DESCRIPTION

i.hyper.geology performs geological rock family classification, mineralogical range assessment, and weathering grade mapping from hyperspectral imagery imported as 3D raster maps (raster_3d) by i.hyper.import.

The module reads wavelength metadata from hyperspectral 3D raster bands and computes up to 15 spectral indicators from VNIR (400-1000 nm) and SWIR (1000-2500 nm) diagnostic absorption features. These indicators drive three expert-system classifications: rock family (8 classes), weathering grade (W0-W5), and hydrothermal/supergene alteration type (10 categories).

i.hyper.geology is part of the i.hyper module family designed for hyperspectral data import, processing, and analysis in GRASS. It provides a geologically interpretable output suite for mineral exploration, mine-site mapping, lithological survey, and environmental monitoring of acid mine drainage (AMD).

Rock family classification

Eight rock families plus an uncertain class are mapped:

ClassLabelKey diagnostic features
0MaskedNDVI > 0.3 (vegetation/water)
1MaficFe2+ ~1000 nm, Mg-OH 2320 nm (chlorite), Fe-oxide VNIR
2UltramaficStrong Mg-OH 2315-2325 nm, Fe2+ 900/1050 nm, absent Al-OH
3FelsicAl-OH dominant 2195-2220 nm, alunite/kaolinite possible
4IntermediateMixed Fe2+ + Al-OH + Mg-OH (hornblende)
5Carbonate sedimentaryCO3 absorption 2340 nm (calcite) / 2320 nm (dolomite)
6Siliciclastic sedimentaryClay Al-OH 2200-2220 nm, Fe-oxide staining
7MetamorphicMica + chlorite + amphibole, low Fe-oxide
8Evaporite/SulphateGypsum 1750 nm, alunite 2270 nm, jarosite VNIR
9Uncertain/MixedNo dominant class above minimum score threshold

Weathering grade

Six ISRM-inspired weathering grades are assessed spectroscopically:

GradeLabelSpectral signature
W0FreshPrimary minerals dominant, Fe2+ intact, no clay/oxide coatings
W1Slightly weatheredMinor Fe-oxide staining, primary minerals still dominant
W2Moderately weatheredStrengthening Fe-oxide, incipient kaolinite/chlorite
W3Highly weatheredStrong Fe-oxide, clay minerals dominant
W4Completely weatheredVery strong Fe-oxide (laterite), clay-dominant spectrum
W5Residual soilDeep laterite/bauxite profile, goethite/hematite at maximum

Alteration type

Ten hydrothermal and supergene alteration categories support mining and exploration applications:

CodeTypeKey minerals
1UnalteredPrimary mineralogy, all indicators low
2PropyliticChlorite + calcite + epidote
3PhyllicWhite mica (sericite/muscovite) 2195-2210 nm
4ArgillicKaolinite 2165/2205 nm
5Advanced argillicAlunite + dickite/pyrophyllite
6SupergeneSecondary goethite/hematite, low jarosite
7AMD activeJarosite + efflorescent sulphates
8AMD matureHydrated goethite/schwertmannite
9Carbonate alterationCarbonatization, skarn, calcite veining; CO3 > 0.06, low Al-OH, low Mg-OH
10SerpentinizationSerpentine + talc + chlorite (ultramafic); Mg-OH > 0.08, no Al-OH

NOTES

Input requirements

The module expects input data to be a 3D raster map created by i.hyper.import or any 3D raster with wavelength metadata stored in band-level metadata following the i.hyper standard format: wavelength, FWHM, valid, and unit.

Spectra must be in surface reflectance units (0-1 range). Top-of-atmosphere radiance or raw digital numbers will produce invalid results. Apply atmospheric correction (e.g., i.hyper.atcorr) before using this module.

Output map types

Classification maps (output_family, output_weathering, output_alteration) are integer CELL rasters with category labels assigned automatically. Indicator maps ({output_prefix}_{name}, produced with -m) are floating-point FCELL rasters.

OutputTypeValue rangeMeaning
output_familyinteger CELL0 – 9Rock family class
output_weatheringinteger CELL0 – 5Weathering grade W0–W5
output_alterationinteger CELL1 – 10Alteration type code
{prefix}_band_depthfloat FCELL0.0 – ~0.8Normalised absorption depth (0 = none)
{prefix}_hematite_vnir / fe_oxide_broadfloat FCELL0.5 – 3.0Reflectance ratio (>1 = Fe-oxide present)
{prefix}_aloh_positionfloat FCELL0.2 – 5.0Al-OH position ratio
{prefix}_reactivity_indexfloat FCELL0.66 – 2.11AMD reactivity (Tolentino et al. 2025)
{prefix}_clay_mixture_indexfloat FCELL1.15 – 4.34Clay mixture richness

Spectral indicators

The module computes 15 spectral indicators via r.mapcalc. Each indicator targets a specific mineral absorption feature.

Band depth indicators use the normalized band depth formula:

band_depth = max(0, 1 - rho_center / mean(rho_left, rho_right))

The value is 0.0 when there is no absorption at the target wavelength. It increases with absorption strength:

ValueInterpretation
0.00No absorption (flat or peaked spectrum)
0.01–0.03Trace / below detection
0.03–0.06Detectable absorption
0.06–0.15Moderate to strong — classifier thresholds fall in this range (e.g. Al-OH > 0.06 → phyllic/argillic; Mg-OH > 0.08 → serpentinization; CO₃ > 0.06 → carbonate alteration)
> 0.15Strong absorption; nearly pure or concentrated mineral surface
IndicatorTarget (nm)Bands used (nm)Mineral target
jarosite_vnir430400 / 430 / 470Jarosite, AMD sulphates
goethite_900900750 / 900 / 1050Goethite, Fe-oxide
ferrous_10001000850 / 1000 / 1200Pyroxene, olivine (Fe2+)
hydroxyl_140014001350 / 1400 / 1500Hydroxyl overtone
water_190019001800 / 1900 / 2000H2O, hydrated minerals
gypsum_175017501700 / 1750 / 1800Gypsum SO4
aloh_220022002100 / 2200 / 2280Al-OH (kaolinite, mica, alunite)
alunite_227022702220 / 2270 / 2310Alunite SO4
mgoh_230023202250 / 2320 / 2400Mg-OH (chlorite, serpentine, talc)
carbonate_234023402290 / 2340 / 2400CO3 (calcite, dolomite)

Ratio indicators:

IndicatorFormulaInterpretation
hematite_vnirrho630 / rho490Fe3+ hematite doublet; >1.2 indicates hematite
fe_oxide_broadrho750 / rho550Broad Fe3+ charge-transfer; >1.5 indicates strong Fe-oxide
aloh_positionrho2165 / rho2220>1.0 = muscovite direction (phyllic); <1.0 = kaolinite direction (argillic)

Composite indices from Tolentino et al. (2025):

IndexFormulaRange
reactivity_index(rho2210 + rho2395) / (rho2285 + rho2330)0.66 – 2.11; > 1.5 = AMD-reactive
clay_mixture_index(rho2168 × rho2224) / rho21981.15 – 4.34; > 2.0 = clay-rich mixed surface

Classification method

Rock family classification uses a weighted scoring approach. For each of the 8 rock families a score is computed as a weighted linear combination of relevant spectral indicators. The class with the maximum score (minimum threshold 0.15) is assigned. When indicator bands are absent (no band within 25 nm tolerance of the target wavelength), the indicator is set to a neutral constant and does not penalize any class.

Vegetation pixels (NDVI > 0.3, using bands near 678 and 800 nm) are masked to class 0.

The priority order for tie-breaking when scores are equal is: Evaporite/Sulphate > Carbonate > Ultramafic > Mafic > Metamorphic > Felsic > Intermediate > Siliciclastic.

Flags

The -n flag restricts processing to only bands marked as valid (valid=1) in the metadata. This is useful for excluding atmospheric water vapour absorption bands (around 1400 and 1900 nm) if they were flagged during import. Note that flagging the 1400 and 1900 nm water vapour bands will disable the hydroxyl_1400 and water_1900 indicators.

The -i flag prints spectral coverage diagnostics and capability assessment without processing any raster data. Use this first to understand what geological information is accessible from a given sensor dataset.

The -m flag outputs all 15 individual spectral indicator maps using the provided output_prefix. These floating-point maps are useful for threshold tuning, visual inspection, or input to custom classification workflows.

The -v flag prints diagnostic messages listing the exact wavelength of each band used for each indicator computation. Useful for validating sensor-to-wavelength matching.

Band slice extraction

When 2D band-slice rasters are not pre-created by i.hyper.import (e.g. direct 3D raster imports via r3.in.bin), the module extracts slices on-the-fly using Rast3d_extract_z_slice() from the GRASS raster3d library (libgrass_g3d). The function opens the 3D map with RASTER3D_NO_CACHE and calls Rast3d_get_block() in tile-bulk mode: only tiles covering the target Z level are loaded exactly once from disk, versus one function call per voxel with the default cache-based API. Only the bands required for indicator computation are extracted, not the entire depth dimension of the cube.

Limitations

EXAMPLES

# Basic rock family mapping from EnMAP data
i.hyper.geology input=enmap \
                output_family=enmap_rock_family
# Full geological assessment suite
i.hyper.geology input=prisma \
                output_family=prisma_lithology \
                output_weathering=prisma_weathering \
                output_alteration=prisma_alteration
# Check spectral capabilities before processing
i.hyper.geology input=tanager \
                output_family=dummy \
                -i

# Console output (example):
# ============================================================
# i.hyper.geology - Geological Assessment Capabilities
# ============================================================
# Sensor spectral coverage: 400.0 - 2500.0 nm (400 bands)
#
# Spectral Region Coverage:
#   VNIR Fe-oxide (400-1000 nm):   AVAILABLE - 200 bands
#   NIR Fe2+ (900-1100 nm):         AVAILABLE - 20 bands
#   SWIR OH/H2O (1350-1450 nm):     AVAILABLE - 8 bands
#   SWIR H2O (1800-2000 nm):        AVAILABLE - 18 bands
#   SWIR Al-OH (2100-2300 nm):      AVAILABLE - 36 bands
#   SWIR Mg-OH (2250-2400 nm):      AVAILABLE - 28 bands
#   SWIR CO3 (2290-2400 nm):        AVAILABLE - 20 bands
# Map only valid bands, export mineral indicator maps
i.hyper.geology input=enmap \
                output_family=enmap_lithology \
                output_weathering=enmap_weathering \
                output_alteration=enmap_alteration \
                output_prefix=enmap_minerals \
                -n -m

# This produces maps such as:
#   enmap_minerals_aloh_2200
#   enmap_minerals_mgoh_2300
#   enmap_minerals_carbonate_2340
#   enmap_minerals_goethite_900
#   enmap_minerals_gypsum_1750
#   ... (15 total indicator maps)
# AMD monitoring workflow for mine site
# Step 1: Import drone VNIR-SWIR hyperspectral data
i.hyper.import input=/data/drone_hsi.hdr \
               product=envi \
               output=drone_hsi

# Step 2: Full geological assessment with verbose reporting
i.hyper.geology input=drone_hsi \
                output_family=drone_lithology \
                output_weathering=drone_weathering \
                output_alteration=drone_alteration \
                output_prefix=drone_minerals \
                -n -m -v

# Step 3: Extract AMD-affected areas (alteration class 7 = AMD active)
r.mapcalc expression="amd_mask = if(drone_alteration == 7, 1, null())"

# Step 4: Statistics on AMD extent
r.univar map=amd_mask

# Step 5: Visualize
d.rast map=drone_alteration
d.legend raster=drone_alteration
# Bauxite prospectivity mapping
# High weathering grades (W4-W5) in felsic/intermediate rocks
# indicate bauxite formation potential (Kouzeli et al. 2025)
i.hyper.geology input=satellite_hsi \
                output_family=lithology \
                output_weathering=weathering

r.mapcalc expression="bauxite_prospective = \
    if((weathering == 4 || weathering == 5) && \
       (lithology == 3 || lithology == 4), 1, null())"

r.colors map=bauxite_prospective color=bgyr
# Limit processing to SWIR range for alteration mapping only
i.hyper.geology input=enmap \
                output_family=enmap_family \
                output_alteration=enmap_alteration \
                min_wavelength=1000 \
                max_wavelength=2500

SEE ALSO

i.hyper.import, i.hyper.continuum, i.hyper.indices, i.hyper.albedo, i.hyper.rgb, r.mapcalc, r.colors, r.category, r.univar, r3.info

REFERENCES

AUTHORS

Created for the i.hyper module family

Based on spectral geology methods from Koerting et al. (2024), Tolentino et al. (2025), and Kouzeli et al. (2025).