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).
Eight rock families plus an uncertain class are mapped:
| Class | Label | Key diagnostic features |
|---|---|---|
| 0 | Masked | NDVI > 0.3 (vegetation/water) |
| 1 | Mafic | Fe2+ ~1000 nm, Mg-OH 2320 nm (chlorite), Fe-oxide VNIR |
| 2 | Ultramafic | Strong Mg-OH 2315-2325 nm, Fe2+ 900/1050 nm, absent Al-OH |
| 3 | Felsic | Al-OH dominant 2195-2220 nm, alunite/kaolinite possible |
| 4 | Intermediate | Mixed Fe2+ + Al-OH + Mg-OH (hornblende) |
| 5 | Carbonate sedimentary | CO3 absorption 2340 nm (calcite) / 2320 nm (dolomite) |
| 6 | Siliciclastic sedimentary | Clay Al-OH 2200-2220 nm, Fe-oxide staining |
| 7 | Metamorphic | Mica + chlorite + amphibole, low Fe-oxide |
| 8 | Evaporite/Sulphate | Gypsum 1750 nm, alunite 2270 nm, jarosite VNIR |
| 9 | Uncertain/Mixed | No dominant class above minimum score threshold |
Six ISRM-inspired weathering grades are assessed spectroscopically:
| Grade | Label | Spectral signature |
|---|---|---|
| W0 | Fresh | Primary minerals dominant, Fe2+ intact, no clay/oxide coatings |
| W1 | Slightly weathered | Minor Fe-oxide staining, primary minerals still dominant |
| W2 | Moderately weathered | Strengthening Fe-oxide, incipient kaolinite/chlorite |
| W3 | Highly weathered | Strong Fe-oxide, clay minerals dominant |
| W4 | Completely weathered | Very strong Fe-oxide (laterite), clay-dominant spectrum |
| W5 | Residual soil | Deep laterite/bauxite profile, goethite/hematite at maximum |
Ten hydrothermal and supergene alteration categories support mining and exploration applications:
| Code | Type | Key minerals |
|---|---|---|
| 1 | Unaltered | Primary mineralogy, all indicators low |
| 2 | Propylitic | Chlorite + calcite + epidote |
| 3 | Phyllic | White mica (sericite/muscovite) 2195-2210 nm |
| 4 | Argillic | Kaolinite 2165/2205 nm |
| 5 | Advanced argillic | Alunite + dickite/pyrophyllite |
| 6 | Supergene | Secondary goethite/hematite, low jarosite |
| 7 | AMD active | Jarosite + efflorescent sulphates |
| 8 | AMD mature | Hydrated goethite/schwertmannite |
| 9 | Carbonate alteration | Carbonatization, skarn, calcite veining; CO3 > 0.06, low Al-OH, low Mg-OH |
| 10 | Serpentinization | Serpentine + talc + chlorite (ultramafic); Mg-OH > 0.08, no Al-OH |
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.
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.
| Output | Type | Value range | Meaning |
|---|---|---|---|
| output_family | integer CELL | 0 – 9 | Rock family class |
| output_weathering | integer CELL | 0 – 5 | Weathering grade W0–W5 |
| output_alteration | integer CELL | 1 – 10 | Alteration type code |
| {prefix}_band_depth | float FCELL | 0.0 – ~0.8 | Normalised absorption depth (0 = none) |
| {prefix}_hematite_vnir / fe_oxide_broad | float FCELL | 0.5 – 3.0 | Reflectance ratio (>1 = Fe-oxide present) |
| {prefix}_aloh_position | float FCELL | 0.2 – 5.0 | Al-OH position ratio |
| {prefix}_reactivity_index | float FCELL | 0.66 – 2.11 | AMD reactivity (Tolentino et al. 2025) |
| {prefix}_clay_mixture_index | float FCELL | 1.15 – 4.34 | Clay mixture richness |
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:
| Value | Interpretation |
|---|---|
| 0.00 | No absorption (flat or peaked spectrum) |
| 0.01–0.03 | Trace / below detection |
| 0.03–0.06 | Detectable absorption |
| 0.06–0.15 | Moderate 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.15 | Strong absorption; nearly pure or concentrated mineral surface |
| Indicator | Target (nm) | Bands used (nm) | Mineral target |
|---|---|---|---|
| jarosite_vnir | 430 | 400 / 430 / 470 | Jarosite, AMD sulphates |
| goethite_900 | 900 | 750 / 900 / 1050 | Goethite, Fe-oxide |
| ferrous_1000 | 1000 | 850 / 1000 / 1200 | Pyroxene, olivine (Fe2+) |
| hydroxyl_1400 | 1400 | 1350 / 1400 / 1500 | Hydroxyl overtone |
| water_1900 | 1900 | 1800 / 1900 / 2000 | H2O, hydrated minerals |
| gypsum_1750 | 1750 | 1700 / 1750 / 1800 | Gypsum SO4 |
| aloh_2200 | 2200 | 2100 / 2200 / 2280 | Al-OH (kaolinite, mica, alunite) |
| alunite_2270 | 2270 | 2220 / 2270 / 2310 | Alunite SO4 |
| mgoh_2300 | 2320 | 2250 / 2320 / 2400 | Mg-OH (chlorite, serpentine, talc) |
| carbonate_2340 | 2340 | 2290 / 2340 / 2400 | CO3 (calcite, dolomite) |
Ratio indicators:
| Indicator | Formula | Interpretation |
|---|---|---|
| hematite_vnir | rho630 / rho490 | Fe3+ hematite doublet; >1.2 indicates hematite |
| fe_oxide_broad | rho750 / rho550 | Broad Fe3+ charge-transfer; >1.5 indicates strong Fe-oxide |
| aloh_position | rho2165 / rho2220 | >1.0 = muscovite direction (phyllic); <1.0 = kaolinite direction (argillic) |
Composite indices from Tolentino et al. (2025):
| Index | Formula | Range |
|---|---|---|
| reactivity_index | (rho2210 + rho2395) / (rho2285 + rho2330) | 0.66 – 2.11; > 1.5 = AMD-reactive |
| clay_mixture_index | (rho2168 × rho2224) / rho2198 | 1.15 – 4.34; > 2.0 = clay-rich mixed surface |
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.
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.
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.
# 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
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).