GRASS logo

NAME

p.matter.bands - Detect planetary matter (minerals, ices, gases, organics, liquids) by absorption-band depth from a body-aware spectral database (UV–LWIR).

KEYWORDS

imagery, spectral, hyperspectral, minerals, planetary, absorption

SYNOPSIS

p.matter.bands
p.matter.bands --help
p.matter.bands [-lqumsixzacvdek] group=name body=string output_prefix=name [wavelengths=string] [matter=string[,string,...]] [db=string] [mode=string] [min_bd=float] [endmembers=name[,name,...]] [sam_library=name[,name,...]] [sam_library_prefix=string] [sam_max_angle=float] [import_library=string] [import_library_name=string] [extract_coords=east,north] [extract_csv=string] [sites=name] [sites_output=name] [temperature=float] [space_weathering=float] [min_abund=float] [atcorr_incidence=name] [atcorr_emission=name] [atcorr_phase=name] [atcorr_model=string] [atcorr_tau=float] [atcorr_wha=float] [min_conf=float] [report=string] [radiometric_noise=float] [reference_prefix=string] [change_sigma=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l
List detectable species for this body/sensor combination (no raster output)
-q
Output per-species confidence raster (__conf) — value = fraction of diagnostic bands covered by the sensor [0,1]
-u
NNLS spectral unmixing mode — output endmember abundance maps instead of band-depth maps (requires endmembers=)
-m
Spectral Angle Mapper (SAM) cross-validation mode — output per-pixel spectral angle maps against sam_library= reference spectra instead of band-depth maps (requires sam_library=)
-s
Spectral cross-check — suppress band-depth pixels whose full spectrum disagrees with the species' reference spectrum (requires sam_library_prefix=)
-i
Import a spectral library CSV (import_library=) as a new reference image group (import_library_name=), resampled onto the current sensor's wavelength grid — does not run detection
-x
Extract the full spectrum at extract_coords= and write it to extract_csv= (same format consumed by import_library=) — does not run detection
-z
Site comparison — add per-species band-depth statistics as attribute columns on a copy of sites= (requires sites= and sites_output=)
-a
Apply Hapke atmospheric correction via p.atcorr.hapke before detection (requires atcorr_incidence=, atcorr_emission=, atcorr_phase=, atcorr_tau=, atcorr_wha=)
-c
Output composite false-colour RGB: R=minerals, G=ices/gases, B=organics (strongest species per type)
-v
Verbose: report band depth statistics for each species map
-d
Multi-temporal change detection — compute __diff against reference_prefix= maps from a previous run
-e
Output per-species uncertainty raster (__unc), propagated analytically from radiometric_noise= through the band-depth formula
-k
Output a dominant-species classification raster (_classification) — category code of the species with highest confidence-weighted band depth at each pixel
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

group=name [required]
Input image group (calibrated reflectance / I/F)
Image group produced by p.in.pds3/p.in.pds4/p.in.isis. Band order must match the wavelengths= CSV row order.
body=string [required]
Target planetary body
Controls which matter types and absorption features are loaded from the database.
Options: mars, moon, mercury, venus, titan, europa, io, enceladus, ceres, asteroid_c_type, asteroid_s_type, asteroid_d_type, comet, pluto, ganymede, callisto, triton, ariel, uranus_moon, generic
mars: Mars surface and atmosphere
moon: Earth's Moon
mercury: Mercury (MESSENGER/BepiColombo)
venus: Venus (surface NIR windows + atmosphere)
titan: Saturn's Titan (VIMS atmospheric windows)
europa: Jupiter's Europa (irradiated icy surface)
io: Jupiter's Io (SO2 frost and sulfur)
enceladus: Saturn's Enceladus (clean H2O ice + plume)
ceres: Dwarf planet Ceres (ammoniated clays)
asteroid_c_type: Carbonaceous (C-type) asteroid (Ryugu/Bennu)
asteroid_s_type: Stony (S-type) asteroid
asteroid_d_type: Dark D-type asteroid / Jupiter Trojan (Lucy targets)
comet: Cometary nucleus and coma
pluto: Pluto / KBO (volatile ices)
ganymede: Jupiter's Ganymede (JUICE/MAJIS 2031)
callisto: Jupiter's Callisto (JUICE/MAJIS 2031)
triton: Neptune's Triton (future orbiter)
ariel: Uranus moon Ariel — strong CO2 ice
uranus_moon: Generic Uranus icy moon (Titania/Oberon/Umbriel)
generic: Generic body — load all database entries
output_prefix=name [required]
Prefix for output band-depth raster maps
One map per detected species: <prefix>_<species_name>. Values are band depth [0, 1]. NULL where data is absent or BD < min_bd.
wavelengths=string
Two-column CSV: wavelength_um,fwhm_um — one row per band in the group
Band centre wavelengths and FWHM in micrometres, ordered to match the group band order (same convention as p.mineral.indices). Required unless the bands carry 'wavelength_um' metadata (set by p.in.isis).
matter=string[,string,...]
Matter type(s) to detect
Options: all, minerals, ices, gases, organics, liquids
Default: all
db=string
Custom band database JSON file
Overrides the built-in $GISBASE/etc/planetary/matter_bands.json. Useful for adding unreleased species or mission-specific calibration data.
mode=string
Input data type
reflectance — standard I/F or reflectance factor (UV–SWIR sensors); emissivity — thermal emissivity derived from calibrated MIR/TIR radiance via Planck inversion (TES, THEMIS, MERTIS, MIRI). The band-depth formula BD = 1 − signal(λ)/continuum(λ) is identical in both modes; this flag tags output maps and skips non-applicable database species.
Options: reflectance, emissivity
Default: reflectance
min_bd=float
Minimum band depth threshold [0.0–1.0]
Output pixels with BD below this value are set to NULL (no detection).
Default: 0.01
endmembers=name[,name,...]
Comma-separated list of endmember spectral library groups for NNLS unmixing (-u)
One image group per endmember. Each group must have the same band count as the input group, in the same wavelength order, with each band a constant raster equal to that endmember's reflectance at the corresponding wavelength. Output: one abundance map [0,1] per endmember group, named <output_prefix>_abund_<group_name>.
sam_library=name[,name,...]
Comma-separated list of full-spectrum library groups for Spectral Angle Mapper (-m)
One image group per reference spectrum, same convention as endmembers=: each group must have the same band count as the input group, in the same wavelength order, with each band a constant raster equal to that reference's value at the corresponding wavelength. Output: one angle map [0,90] degrees per library group, named <output_prefix>_sam_<group_name> (0 = perfect match). If more than one library group is given, also writes <output_prefix>_sam_classification (smallest-angle match per pixel).
sam_library_prefix=string
Prefix for per-species full-spectrum reference groups, for spectral cross-check (-s)
For each detected species, looks for an image group named <sam_library_prefix>_<species_name> (same band count and wavelength order as the input group; one constant-value band per wavelength). If found, the per-pixel Spectral Angle Mapper distance between the full observed spectrum and this reference is computed; pixels above sam_max_angle= are suppressed from the band-depth map. Species without a matching reference group are processed normally (no cross-check applied). Requires -s.
sam_max_angle=float
Maximum SAM angle in degrees for spectral cross-check confirmation (-s)
Pixels whose full-spectrum SAM angle to the species' reference (sam_library_prefix=) exceeds this threshold are treated as spectrally inconsistent and suppressed from the band-depth output, even if the absorption-band depth alone exceeded min_bd.
Default: 30.0
import_library=string
Two-column CSV (wavelength_um,value) of a reference spectrum to import (-i)
A plain spectral-library file — one row per sample, "wavelength_um,value" (comments with # and blank lines are ignored). Resampled by linear interpolation onto the current group's sensor wavelength grid (extrapolation clamps to the nearest library endpoint) and written as a new image group of constant-value bands, ready for use as endmembers=, sam_library=, or sam_library_prefix=. Requires -i and import_library_name=.
import_library_name=string
Name for the new reference image group created from import_library= (-i)
extract_coords=east,north
Easting,northing of a pixel whose spectrum to extract (-x)
Coordinates
extract_csv=string
Output path for the extracted spectrum CSV (-x)
Written in the same two-column "wavelength_um,value" format consumed by import_library= — one row per band of the input group, value = the pixel value at extract_coords=. NULL pixels are written as "nan". Requires -x and extract_coords=.
sites=name
Vector map of candidate sites/zones (points or areas) for site comparison (-z)
Or data source for direct OGR access
sites_output=name
Output vector — a copy of sites= with per-species band-depth statistics added as attribute columns (-z)
Points get one "<species>_bd" column per detected species (v.what.rast); areas get "<species>_average", "<species>_minimum", "<species>_maximum" columns (v.rast.stats). Requires -z and sites=.
temperature=float
Scene temperature in Kelvin — shifts ice band centers before matching
Corrects temperature-dependent wavelength shifts in volatile ice bands (H2O, N2, CH4, CO, CO2). Critical for Europa (80–130 K), Enceladus (80 K), Pluto (40 K), Triton (36 K). Refs: Mastrapa et al. 2008; Quirico & Schmitt 1997.
space_weathering=float
Space weathering Is/FeO factor [0.0 = disabled]
NPFe nanophase iron correction: BD_corr = BD / (1 − α × Is/FeO). Body-specific α from database (Moon 0.40, Mercury 0.35, S-type 0.30). Hapke 2001; Clark et al. 2002.
Default: 0.0
min_abund=float
Minimum endmember abundance threshold for NNLS output [0.0–1.0]
Default: 0.01
atcorr_incidence=name
Per-pixel incidence angle map (°) from p.phocube [--atcorr]
Name of input raster map
atcorr_emission=name
Per-pixel emission angle map (°) from p.phocube [--atcorr]
Name of input raster map
atcorr_phase=name
Per-pixel phase angle map (°) from p.phocube [--atcorr]
Name of input raster map
atcorr_model=string
Hapke scattering model for atmospheric correction [--atcorr]
Options: Isotropic1, Isotropic2, Anisotropic1, Anisotropic2
Default: Isotropic2
atcorr_tau=float
Atmospheric optical depth τ [--atcorr]
atcorr_wha=float
Hapke single-scattering albedo wha [--atcorr]
min_conf=float
Minimum band-concordance confidence [0.0–1.0, default 0.0]
Species whose matched-band fraction (n_bands_in_sensor / n_diagnostic_bands) falls below this value are suppressed. E.g. min_conf=0.5 requires at least half the diagnostic bands to be covered. Use with -q to also write confidence rasters.
Default: 0.0
report=string
Path for JSON detection report
Write a structured JSON summary of all detections (species, confidence, mean/max BD, n_bands) to this file. Written after all species are processed.
radiometric_noise=float
1-sigma relative radiometric noise [0.0 = disabled]
Fractional 1-sigma uncertainty on each input reflectance/emissivity sample (e.g. 0.02 = two percent). Propagated analytically through the band-depth formula to produce per-species uncertainty. Use with -e to write uncertainty rasters.
Default: 0.0
reference_prefix=string
Output prefix from a previous run, for multi-temporal change detection (-d)
For each detected species, looks for <reference_prefix>_<species_name> (and, if present, <reference_prefix>_<species_name>_unc) and computes <output_prefix>_<species_name>_diff = BD_now - BD_reference. Requires -d.
change_sigma=float
Significance threshold (combined-sigma units) for change detection (-d)
When uncertainty rasters are available for both epochs (radiometric_noise= used in both runs), pixels with |diff| / sqrt(sigma_now^2 + sigma_ref^2) >= change_sigma are written to <prefix>_<species>_diff_sig.
Default: 2.0

Table of contents

p.matter.bands — Planetary matter detection from absorption bands

DESCRIPTION

p.matter.bands detects and maps surface/atmospheric matter (minerals, ices, gases, organics, liquids) in any planetary hyperspectral or multispectral image group by computing absorption-band depth maps from a science-backed band database covering UV through LWIR (0.1–100 µm).

The module is sensor-agnostic and body-aware: given a target body (body=), it queries the built-in band database ($GISBASE/etc/planetary/matter_bands.json) for all species detectable on that body, filters to those whose diagnostic absorption bands fall within the sensor's wavelength coverage, and computes one per-species band-depth raster.

Key concepts

Absorption band depth — following Clark & Roush (1984):

BD = 1 - R_center / R_continuum

where R_continuum is the linear continuum interpolated from the left and right shoulders. A value of 0 means no absorption; 1 means total absorption. The continuum is removed first (following Sunshine et al. 1990, p_spectra library) before depth computation, making results comparable across sensors and illumination conditions.

Body-aware filtering — the band database encodes which matter types are plausible on each planetary body based on geochemical constraints and published detection. For example, NH4-bearing phyllosilicates are listed only for Ceres and the outer C-type asteroids, not for the Moon.

Sensor-coverage gating — each species entry carries detection_range_um (min/max wavelength needed to detect it). If the image group does not cover this range, the species is silently skipped and listed in the coverage-gap report.


SITUATION REPORT — EXISTING SPECTRAL MODULES

The following spectral/mineral analysis modules already exist in the addons. p.matter.bands extends this stack to broader wavelength coverage and all planetary body types.

Module Role Body / sensor scope Wavelength
p.mineral.indices CRISM-derived Mars indices (OLINDEX, LCPINDEX, HCPINDEX, D2300, BD1900, BD3000) Mars / CRISM, OMEGA 1.0–3.5 µm
p.spectral.planet Generic band-ratio, NDI, SAM, band-depth, continuum-removal operations Any / any multispectral User-defined
p.bandnorm Spectral band normalisation (illumination removal) Any Any
p_spectra (lib) Core C library: band depth, SAM, continuum-removal, high-pass, divfilter (library) (library)
p.photomet Photometric correction (Lambert–Hapke models) Any rocky/icy body (broadband)
p.atcorr.hapke Atmospheric correction via Hapke RT Atmosphered bodies (broadband)
p.albedo I/F → geometric/normal albedo conversion Any (broadband)
p.phocube Per-pixel geometry backplanes (i, e, g angles) Any (broadband)
p.cubenorm / p.dstripe Detector gain/stripe removal (pre-processing) Any push-broom Any

Gap addressed by p.matter.bands:


PLANETARY BODY APPLICABILITY

Band detection ranges by body type

Body class       UV(0.1-0.4) VIS(0.4-0.7) NIR(0.7-1µm) SWIR(1-2.5) MIR(2.5-5) TIR(5-25µm) FIR(>25µm)
──────────────── ─────────── ──────────── ─────────── ──────────── ────────── ─────────── ──────────
Rocky/basaltic   SO2,graphit Fe-oxides    olivine,Px   phyllosil.  carbonate  silicate-8  carbonate-11
 (Mars,Moon,Merc          SO2,s-allot  feldsp.glass  sulfates    organics   emiss.      emiss.
  Venus surface)                      TiO2/FeO      ices(ov.t.)  H2O ice
Ice worlds       SO2(Io)     S-allot(Io) H2O-ice(ov) H2O,CO2,N2  H2O,CO2,   SO2 fund.  H2O fund.
 (Europa,Encela              (UV broad)   CH4,SO2-1st CH4,CO,NH3  SO2,CH4    H2O2,CO2
  Io,Titan,Pluto)                         band         ice        fund.
Gas/ice giants   UV hazes    CH4 atm     CH4,NH3      CH4,NH3    NH3,H2S    NH3 fund.  H2 CIA
 (Jupiter,Saturn             H2 Rayleigh  rings-min.  PH3,GeH4   PH3,AsH3   CH4 fund.
  Uranus,Neptune)
Moons (rocky)    space-weath Fe-oxides    olivine,Px   phyllosil. carbonate  silicate-8  emiss.
 (like Moon)     SO2(Io exc)              glass,TiO2   ices(ov.t.) ice fund.
Asteroids (C)    UV slope    0.7µm drop  olivine,Px   hydrated   3µm OH     emiss.
                             Fe/Fe-OH                 silicate   organics
Asteroids (S)    UV          Fe-oxides   olivine(1µm)  Px(1.85µm) —
Comets                       dark org.   org+ice-ov.  ice combs  organics   H2O,CO2    H2O rot.
                                                                  C-H 3.4
KBOs / TNOs                  tholins     CH4,N2,CO-ov CH4,N2,CO  —          CH4 fund.
Exoplanet atm   UV,ozone    aerosols    CH4,H2O      CO2,H2O    CO2,CH4    CO2 bending
 (transmission)             hazes        absorption   CO,HCN     CH4 fund.

Body-specific matter matrix

Mars — well-studied; CRISM/OMEGA data-rich

Moon — space-weathered mafics; polar ice

Mercury — low-FeO, sulfur-rich, graphite-bearing

Venus surface — NIR atmospheric windows only

Titan — organic-dominated; hydrocarbon lakes; H2O bedrock

Europa — irradiated icy ocean world

Io — SO2-dominated; sulfur allotropes; active volcanism

Enceladus — clean H2O ice; plume organics

Ceres — ammoniated phyllosilicates; carbonates; water ice

C-type asteroids (Bennu, Ryugu, Pallas…)

S-type asteroids (Itokawa, Eros…)

Comets (67P, Halley, future dynamically new comets)

Pluto / KBOs — volatile ices + tholins


MODULE DESIGN: p.matter.bands

Parameters

p.matter.bands group=<name> body=<name> output_prefix=<name>
    [matter=<types>] [db=<path>] [min_bd=<0.0-1.0>]
    [-l] [-c] [-v]
Parameter Type Description
group required GRASS image group with wavelength metadata (set by p.in.isis / p.in.pds3 / p.in.pds4)
body required Planetary body: mars, moon, mercury, venus, titan, europa, io, enceladus, ceres, asteroid_c_type, asteroid_s_type, comet, pluto, generic
output_prefix required Prefix for output raster maps (one per detected species)
matter optional Comma-separated subset: minerals, ices, gases, organics, liquids. Default: all
db optional Path to custom band database JSON (overrides built-in matter_bands.json)
min_bd optional Minimum band depth to report (0.0–1.0, default 0.01). Pixels below this threshold are set to NULL.
-l flag List detectable species for the body/sensor combination; do not process rasters
-c flag Output composite false-colour RGB: R=mineral, G=ice, B=organic (strongest species per type)
-v flag Verbose: print band depth statistics per species

Output maps

For each detectable species:

<output_prefix>_<species_name>   DCELL raster, band depth [0.0, 1.0]
                                 NULL where image data is invalid or BD < min_bd

If -c: <output_prefix>_composite_RGB (three-band group: R/G/B)

Processing chain

                ┌──────────────────────────────────────────────────────┐
                │  p.matter.bands                                       │
                │                                                       │
  GRASS image   │  1. Read wavelength metadata from group              │
  group         │     (p_spectra_def from planetary.json band history) │
  (calibrated   │                                                       │
   I/F rasters) │  2. Load matter_bands.json for target body          │
        │       │                                                       │
        ▼       │  3. Gate: filter species to those within sensor       │
  band_list[]   │     wavelength range (detection_range_um)            │
                │                                                       │
                │  4. For each qualifying species:                      │
                │     a. p_spectra_continuum_remove(left, right)        │
                │     b. p_spectra_band_depth(left, center, right)      │
                │     c. Multi-band composite score if species has      │
                │        multiple absorption features                    │
                │     d. Write output raster                            │
                │                                                       │
                │  5. Coverage-gap report: species skipped + reason    │
                │                                                       │
                │  6. Optional: composite RGB (-c flag)                │
                └──────────────────────────────────────────────────────┘

Band-depth computation (per species)

For species with N absorption bands b₁…bₙ:

BD_total = 0
weight_sum = 0
for each band bᵢ:
    if sensor covers bᵢ.center ± tolerance:
        BD_i = band_depth(R[left_i], R[center_i], R[right_i])
        w_i  = diagnostic_weight[bᵢ]   # from database; primary feature = 1.0
        BD_total  += BD_i * w_i
        weight_sum += w_i
BD_species = BD_total / weight_sum if weight_sum > 0 else NULL

Multi-band confirmation raises confidence; single-band detections are flagged with lower confidence.


IMPLEMENTATION PLAN

Phase 1 — Foundation (this PR)

1.1 Band database (data/matter_bands.json)

1.2 C library extension (libs/p_spectra/)

1.3 Module skeleton (planetary/p.matter.bands/)

Phase 2 — Wavelength range extension ✓ COMPLETE

2.1 UV support (0.1–0.4 µm) ✓

2.2 MIR support (5–30 µm) ✓

2.3 LWIR/FIR (30–100 µm) ✓

Phase 3 — Body database expansion ✓ COMPLETE

New bodies added (6):

Body Key species Driver mission
ganymede H2O ice, CO2 ice, MgSO4 hydrate salt, SO2 trace (UV), dark organics JUICE/MAJIS 2031
callisto H2O ice, CO2 ice (dominant), dark C-rich lag JUICE/MAJIS 2031
triton N2 ice (2.148 µm), CH4 ice (6 bands), CO ice, CO2 ice, H2O ice, tholins future orbiter (Decadal)
ariel CO2 ice (very strong, trailing), H2O ice, NH3 hydrate, dark material Uranus Orbiter (Decadal)
uranus_moon H2O ice, CO2 ice, NH3 hydrate, dark organics (Titania/Oberon/Umbriel) Uranus Orbiter (Decadal)
asteroid_d_type Organic reddening slope, aliphatic + aromatic C-H, OH phyllosilicates Lucy ongoing

Expanded existing bodies:

Database totals after Phase 3: 19 bodies, 123 species, wavelength range 0.18–200 µm

Phase 5 — Confidence and quality outputs ✓ COMPLETE

5.1 Per-species confidence raster (-q)

5.2 Minimum confidence filter (min_conf=)

5.3 JSON detection report (report=)

5.4 Confidence-weighted composite (-c)

Phase 6 — Classification and uncertainty propagation ✓ COMPLETE

6.1 Dominant-species classification map (-k)

6.2 Radiometric uncertainty propagation (-e, radiometric_noise=)

Phase 7 — Multi-temporal change detection ✓ COMPLETE

7.1 Band-depth difference map (-d, reference_prefix=)

7.2 Statistical significance flagging (change_sigma=)

Phase 8 — Spectral Angle Mapper cross-validation ✓ COMPLETE

8.1 Per-pixel SAM angle maps (-m, sam_library=)

8.2 Best-match classification (<prefix>_sam_classification)

Phase 9 — Per-species spectral cross-check ✓ COMPLETE

9.1 Full-spectrum confirmation (-s, sam_library_prefix=, sam_max_angle=)

Phase 10 — Spectral library import ✓ COMPLETE

10.1 Build reference groups from plain spectral-library files (-i, import_library=, import_library_name=)

Phase 11 — Spectrum extraction ✓ COMPLETE

11.1 Pull a real pixel's spectrum out of the scene (-x, extract_coords=, extract_csv=)

Phase 12 — Band-read cache and site comparison ✓ COMPLETE

12.1 Band-read cache (internal optimization)

12.2 Site comparison as a GRASS vector (-z, sites=, sites_output=)

Phase 4 — Advanced detection modes ✓ COMPLETE

4.1 Spectral unmixing integration

4.2 Band shape analysis (temperature correction)

4.3 Space weathering correction

4.4 Atmospheric correction pipeline integration


DATABASE SCIENCE REFERENCES

The following peer-reviewed publications back every absorption band entry in data/matter_bands.json. Only ISI/Scopus-indexed journals are used.

Spectral laboratory foundations

Ref Relevance
Clark, R.N. & Roush, T.L. (1984). Reflectance spectroscopy: Quantitative analysis techniques for remote sensing applications. J. Geophys. Res. 89(B7):6329–6340. doi:10.1029/JB089iB07p06329 Band depth formula used by p_spectra library
Clark, R.N. et al. (1990). High spectral resolution reflectance spectroscopy of minerals. J. Geophys. Res. 95(B8):12653–12680. doi:10.1029/JB095iB08p12653 Primary spectral library: phyllosilicates, sulfates, carbonates, feldspar
Burns, R.G. (1993). Mineralogical Applications of Crystal Field Theory (2nd ed.). Cambridge. doi:10.1017/CBO9780511524899 Electronic transition theory for olivine and pyroxene
Adams, J.B. (1974). Visible and near-infrared diffuse reflectance spectra of pyroxenes. J. Geophys. Res. 79(32):4829–4836. doi:10.1029/JB079i032p04829 Pyroxene Band I/II parameters
Sunshine, J.M. & Pieters, C.M. (1993). Estimating modal abundances from spectra of natural and laboratory pyroxene mixtures using the modified Gaussian model. J. Geophys. Res. 98(E5):9075–9087. doi:10.1029/93JE00638 Olivine deconvolution

Water ice and volatiles

Ref Relevance
Clark, R.N. (1981). The spectral reflectance of water-mineral mixtures at low temperatures. J. Geophys. Res. 86(B4):3087–3096. doi:10.1029/JB086iB04p03087 H2O ice band positions
Clark, R.N. et al. (1986). Spectral reflectance of frost as a function of grain size and areal distribution. J. Geophys. Res. 91(B14):D233–D240. doi:10.1029/JD091iD02p0D233 H2O/CO2/SO2 ice bands
Quirico, E. & Schmitt, B. (1997). Near-infrared spectroscopy of simple hydrocarbons and carbon oxides diluted in solid N2 and as pure ices. Icarus 127(2):354–378. doi:10.1006/icar.1997.5710 N2, CO, CO2 volatile ice bands
Grundy, W.M. & Schmitt, B. (1998). The temperature-dependent near-infrared absorption spectrum of hexagonal H2O ice. J. Geophys. Res. 103(E11):25809–25822. doi:10.1029/98JE00738 Temperature-dependent ice bands

Mars mineralogy

Ref Relevance
Pelkey, S.M. et al. (2007). CRISM multispectral summary products: Parameterizing mineral diversity on Mars from reflectance. J. Geophys. Res. 112(E8):E08S14. doi:10.1029/2006JE002831 CRISM index definitions
Viviano-Beck, C.E. et al. (2014). Revised CRISM spectral parameters and summary products based on the currently detected mineral diversity on Mars. J. Geophys. Res. Planets 119(6):1403–1431. doi:10.1002/2014JE004627 Updated Mars mineral indices
Ehlmann, B.L. & Edwards, C.S. (2014). Mineralogy of the Martian surface. Annu. Rev. Earth Planet. Sci. 42:291–315. doi:10.1146/annurev-earth-060313-055024 Comprehensive Mars mineralogy review
Carter, J. et al. (2013). Hydrous minerals on Mars as seen by the CRISM and OMEGA imaging spectrometers: Updated global view. J. Geophys. Res. Planets 118(4):831–858. doi:10.1029/2012JE004145 Phyllosilicate global mapping
Gendrin, A. et al. (2005). Sulfates in Martian layered terrains: The OMEGA/Mars Express view. Science 307:1587–1591. doi:10.1126/science.1109087 Sulfate detection (kieserite/gypsum)

Outer solar system ices and organics

Ref Relevance
McCord, T.B. et al. (1998). Salts on Europa's surface detected by Galileo's NIMS spectrometer. Science 280:1242–1245. doi:10.1126/science.280.5367.1242 Europa non-ice material detection
Carlson, R.W. et al. (1999). Hydrogen peroxide on the surface of Europa. Science 286:97–99. doi:10.1126/science.286.5437.97 Europa H2O2 at 3.5 µm
Trumbo, S.K. et al. (2019). Sodium chloride on the surface of Europa. Sci. Adv. 5(6):eaaw7123. doi:10.1126/sciadv.aaw7123 NaCl color centres on Europa
Smythe, W.D. et al. (1995). Absorption bands in the spectrum of Io and Io's atmosphere detected by the NIMS. Icarus 111(1):79–105. doi:10.1006/icar.1994.1138 Io SO2 frost band assignments
Khare, B.N. et al. (1984). Optical constants of organic tholins produced in a simulated Titanian atmosphere. Icarus 60(1):127–137. doi:10.1016/0019-1035(84)90195-X Tholin UV-VIS optical constants
Capaccioni, F. et al. (2015). The organic-rich surface of comet 67P/Churyumov-Gerasimenko as seen by VIRTIS/Rosetta. Science 347(6220):aaa0628. doi:10.1126/science.aaa0628 Cometary organic-rich 3.2 µm feature
De Sanctis, M.C. et al. (2015). Ammoniated phyllosilicates with a likely outer Solar System origin on (1) Ceres. Nature 528:241–244. doi:10.1038/nature14334 Ceres NH4 diagnostic band at 3.06 µm

Asteroids and small bodies

Ref Relevance
Kitazato, K. et al. (2019). The surface composition of asteroid 162173 Ryugu from Hayabusa2 near-infrared spectroscopy. Science 364:272–275. doi:10.1126/science.aav7432 C-type 2.72/2.94 µm hydration
Hamilton, V.E. et al. (2019). Evidence for widespread hydrated minerals on asteroid (101955) Bennu. Nature Astron. 3:332–340. doi:10.1038/s41550-019-0894-3 Bennu hydrated silicates
Yabuta, H. et al. (2023). Macromolecular organic matter in samples of the asteroid (162173) Ryugu. Science 379(6634):eabn9471. doi:10.1126/science.abn9471 Ryugu organic matter (3.4 µm C-H)

ADDING CUSTOM SPECIES TO THE LOCAL DATABASE

On the first p.in.* import in a GRASS session, p_meta automatically copies $GISBASE/etc/planetary/matter_bands.json to your current mapset:

$GISDBASE/$LOCATION/$MAPSET/Misc/matter_bands.json

p.matter.bands checks this mapset-local copy first. You can edit it freely to add unpublished species, mission-specific calibration data, or absorption features from a paper that post-dates the system install — without touching the system-wide file and without root access.

Step 1 — locate (or seed) the local file

# After any p.in.* import the file is already there.
# To seed it manually before the first import:
MISC_DIR=$(g.gisenv get=GISDBASE)/$(g.gisenv get=LOCATION_NAME)/$(g.gisenv get=MAPSET)/Misc
mkdir -p "$MISC_DIR"
cp "$GISBASE/etc/planetary/matter_bands.json" "$MISC_DIR/matter_bands.json"

Step 2 — understand the schema

A minimal species entry inside one body's matter-type array:

{
  "name": "example_sulfate",
  "display_name": "Example Sulfate",
  "formula": "CaSO4·2H2O",
  "detection_range_um": [1.4, 2.5],
  "absorption_bands": [
    {
      "center": 1.45,
      "left":   1.35,
      "right":  1.55,
      "type":   "H2O combination",
      "sensors": ["CRISM", "OMEGA"]
    },
    {
      "center": 1.75,
      "left":   1.65,
      "right":  1.85,
      "type":   "S-O overtone",
      "sensors": ["CRISM"]
    },
    {
      "center": 2.21,
      "left":   2.10,
      "right":  2.35,
      "type":   "H2O+SO4 combination",
      "sensors": ["CRISM", "OMEGA"]
    }
  ],
  "refs": [
    {
      "cite": "Author et al. (2024) Planet. Sci. J. X:Y",
      "doi":  "10.3847/PSJ/XXXXX"
    }
  ]
}

Required fields: name (unique within the body), absorption_bands[] with at least center, left, right (all in µm).
Optional: display_name, formula, detection_range_um (inferred from band extremes if absent), sensors[], refs[].

Step 3 — insert the new entry

Open the file in any editor and append to the appropriate array. Example adding a Mars mineral (abbreviated JSON showing insertion point):

{
  "bodies": {
    "mars": {
      "minerals": [
        { ... existing species ... },
        {
          "name": "mg_perchlorate_hexahydrate",
          "display_name": "Mg-perchlorate hexahydrate",
          "formula": "Mg(ClO4)2·6H2O",
          "detection_range_um": [1.4, 3.5],
          "absorption_bands": [
            {
              "center": 1.47,
              "left":   1.35,
              "right":  1.60,
              "type":   "H2O combination band",
              "sensors": ["CRISM", "MRO-CRISM"]
            },
            {
              "center": 1.98,
              "left":   1.85,
              "right":  2.10,
              "type":   "H2O combination band",
              "sensors": ["CRISM"]
            },
            {
              "center": 2.14,
              "left":   2.05,
              "right":  2.25,
              "type":   "Cl-O overtone + H2O",
              "sensors": ["CRISM"]
            }
          ],
          "refs": [
            {
              "cite": "Hanley et al. (2015) GRL 42:687–694",
              "doi":  "10.1002/2014GL062403"
            }
          ]
        }
      ]
    }
  }
}

Step 4 — validate the JSON

python3 -m json.tool "$MISC_DIR/matter_bands.json" > /dev/null && echo "JSON valid"

Step 5 — verify the module sees the new species

p.matter.bands -l group=<your_group> body=mars matter=minerals \
    wavelengths=<your_wavelengths.csv>

The new species appears in the Detectable list if the sensor range covers its detection_range_um. If it appears under Out of sensor range, the sensor does not cover the required wavelengths — the entry is correct but the data cannot detect it.

Step 6 — run the detection

p.matter.bands group=crism_scene body=mars matter=minerals \
    output_prefix=my_mars wavelengths=crism_wavelengths.csv \
    min_bd=0.02 -v

The new species produces a map my_mars_mg_perchlorate_hexahydrate with band depth values in [0, 1].

Notes on the wavelengths= CSV

One row per band in the image group, matching band order:

# wavelength_um, fwhm_um
1.0020, 0.0065
1.0085, 0.0065
1.0150, 0.0065
...

FWHM is used only for display and documentation; it does not affect band depth computation.


USAGE EXAMPLES

List detectable species for Europa given NIMS-range data

p.matter.bands -l group=europa_nims body=europa

Output:

Europa — sensor coverage 0.70–5.20 µm (NIMS)
Detectable (8):  water_ice_crystalline, hydrated_sulfuric_acid, epsomite,
                 so2_surface, co2_surface, hydrogen_peroxide, sodium_chloride*
Skipped (1):     sodium_chloride [needs UV < 0.50 µm; not covered]
* single-feature detection only

Map minerals on Mars from CRISM FRT

# Import and pre-process CRISM product (existing modules)
p.in.pds3 input=FRT00003E12_07_IF166L_TRR3.img output=crism
p.atcorr.hapke input=crism output=crism_corr tau=0.3 omega=0.92 g=0.3

# Map all mineral species
p.matter.bands group=crism_corr body=mars matter=minerals \
    output_prefix=mars_FRT3E12 min_bd=0.02 -vc

Output maps:

mars_FRT3E12_olivine            (BD at 1.05 µm)
mars_FRT3E12_low_ca_pyroxene    (BD composite 0.92+1.85 µm)
mars_FRT3E12_high_ca_pyroxene   (BD composite 1.00+2.30 µm)
mars_FRT3E12_smectite_montmorillonite  (BD composite 1.41+1.91+2.21 µm)
mars_FRT3E12_nontronite         (BD composite 1.41+1.91+2.29 µm)
mars_FRT3E12_gypsum             (BD composite 1.45+1.75+1.95+2.22 µm)
... (13 more mineral maps)
mars_FRT3E12_composite_RGB      (R=olivine, G=smectite, B=hematite)

Map Titan surface organics from Cassini VIMS

p.in.pds3 input=v1722289127_1_vis.qub output=vims_vis band=96
# (import all bands, build group)
p.matter.bands group=vims_titan body=titan matter=organics,liquids \
    output_prefix=titan_vims -c

Detect ices on Pluto from LEISA

p.matter.bands group=leisa_pluto body=pluto matter=ices \
    output_prefix=pluto_nh min_bd=0.05 -lv

Full pipeline — HiRISE colour over Mawrth Vallis clay outcrops (Mars)

Mawrth Vallis (≈22–24°N, 341–344°E) is one of the mineralogically richest phyllosilicate terrains on Mars, hosting Fe/Mg smectites (nontronite, Fe-smectite) overlain by Al-phyllosilicates (montmorillonite, kaolinite), all diagnostic of prolonged aqueous alteration in the Noachian (Loizeau et al. 2010; Bishop et al. 2008). HiRISE Enhanced Colour images (three bands: BG, RED, NIR) provide 25 cm/pixel morphological context and allow detection of Fe-oxide signatures; phyllosilicate absorption bands at 1.4, 1.9 and 2.2 µm lie beyond HiRISE's wavelength range but are mapped simultaneously by CRISM (see note at end).

# ── 0. One-time: create a Mars geographic GRASS location ─────────────────────
# IAU Mars 2000 geographic CRS (lat/lon in degrees, body radius 3396.19 km)
grass -c EPSG:49900 ~/grassdata/mars

# ── 1. Set the working region to Mawrth Vallis clay outcrop centre ───────────
# The main Fe/Mg smectite exposure described in Bishop et al. (2008)
# is centred near 23.6°N, 342.8°E; 0.5° box at 1 arcsec resolution.
g.region n=23.85 s=23.35 e=343.05 w=342.55 res=0:00:01

# ── 2. List available HiRISE Enhanced Colour products in this region ─────────
p.in.archive -l search="HiRISE Enhanced Color Mawrth" limit=20

# ── 3. Import the three HiRISE colour bands ───────────────────────────────────
# HiRISE Enhanced Colour products expose three bands on Astropedia STAC:
#   Band 1 — BG  (Blue-Green, ~400–600 nm, centre 500 nm)
#   Band 2 — RED (Red,        ~550–850 nm, centre 700 nm)
#   Band 3 — NIR (Near-IR,   ~750–1000 nm, centre 875 nm)
# (McEwen et al. 2007 SSR 129:369; Delamere et al. 2010 SSR 150:477)
#
# Using observation PSP_002074_2025 (2006-12-04, 23.6°N 342.8°E,
# centred on the main Fe/Mg smectite terrace).
p.in.archive search="PSP_002074_2025" band=1 output=mawrth_bg  --overwrite
p.in.archive search="PSP_002074_2025" band=2 output=mawrth_red --overwrite
p.in.archive search="PSP_002074_2025" band=3 output=mawrth_nir --overwrite

# ── 4. Build an image group ───────────────────────────────────────────────────
i.group group=mawrth_hirise input=mawrth_bg,mawrth_red,mawrth_nir

# ── 5. Create the HiRISE wavelength CSV ──────────────────────────────────────
# Two-column format: wavelength_um, fwhm_um  (one row per band in group order)
cat > hirise_wavelengths.csv << 'EOF'
# HiRISE Enhanced Colour filter wavelengths (McEwen et al. 2007)
# wavelength_um, fwhm_um
0.500, 0.200
0.700, 0.300
0.875, 0.125
EOF

# ── 6. Check what is detectable at HiRISE wavelengths ───────────────────────
# Expect: Fe-oxide (hematite broad ~0.53/0.86 µm) within range.
# Expect: all phyllosilicates (1.4, 1.9, 2.2 µm) OUT of range — HiRISE
# cannot detect them; those entries appear under "Out of sensor range".
p.matter.bands -lv \
    group=mawrth_hirise \
    body=mars \
    output_prefix=mawrth \
    wavelengths=hirise_wavelengths.csv

# Example output:
#   Body: mars | Bands: 3 | Sensor: 0.5000–0.8750 µm
#   Detectable (2):
#     hematite           minerals   0.5330 µm, 0.8600 µm
#     goethite           minerals   0.5300 µm, 0.6600 µm
#   Out of sensor range (14):
#     olivine            needs 0.8000–2.5000 µm
#     low_ca_pyroxene    needs 0.9000–2.0000 µm
#     smectite_fe_mg     needs 1.3500–2.5000 µm
#     nontronite         needs 1.3500–2.5000 µm
#     montmorillonite    needs 1.3500–2.5000 µm
#     ... (9 more)

# ── 7. Compute Fe-oxide band depth maps ─────────────────────────────────────
p.matter.bands \
    group=mawrth_hirise \
    body=mars \
    matter=minerals \
    output_prefix=mawrth \
    wavelengths=hirise_wavelengths.csv \
    min_bd=0.02 \
    -vc

# Output maps:
#   mawrth_hematite   — BD composite 0.53 + 0.86 µm [DCELL, 0–1]
#   mawrth_goethite   — BD composite 0.53 + 0.66 µm [DCELL, 0–1]
#   mawrth_composite_RGB — R=hematite, G=0, B=0

# ── 8. Display ────────────────────────────────────────────────────────────────
r.colors map=mawrth_hematite color=reds
d.mon start=wx0
d.rast mawrth_hematite
d.rast mawrth_red  # true-colour context underneath

Interpreting the output — high mawrth_hematite band depth (~0.05–0.25) marks the grey hematite-rich cap that conformably overlies the phyllosilicate sequence visible in CRISM data (Loizeau et al. 2010). The phyllosilicate layers underneath are spatially co-located but require CRISM wavelength coverage for detection.

For complete clay mapping — co-register with CRISM TRDR:

# CRISM covers 0.36–3.92 µm in 544 bands — detects all phyllosilicate features
# Fetch a CRISM Full Resolution Targeted Reduced Data Record over the same area
p.in.archive search="CRISM FRT Mawrth" limit=5

# Import (example product FRT00003BFB_07_IF166L_TRRU)
p.in.pds3 \
    input=FRT00003BFB_07_IF166L_TRRU.img \
    output=mawrth_crism

# Build CRISM group and wavelength CSV from the label
# (CRISM BandBin centres extracted from .lbl with grep/awk)
awk '/BAND_BIN_CENTER/{found=1} found{print; if(/}/) exit}' \
    FRT00003BFB_07_IF166L_TRRU.lbl \
    | grep -oP '[0-9]+\.[0-9]+' \
    | awk '{print $1 ", 0.0065"}' > crism_wavelengths.csv

# Detect all Mars minerals + ices from CRISM
p.matter.bands \
    group=mawrth_crism \
    body=mars \
    matter=minerals,ices \
    output_prefix=mawrth_crism \
    wavelengths=crism_wavelengths.csv \
    min_bd=0.02 \
    -vc
# → mawrth_crism_nontronite, mawrth_crism_montmorillonite,
#   mawrth_crism_smectite_fe_mg, mawrth_crism_kaolinite …

# Co-register HiRISE Fe-oxide map with CRISM clay map for combined analysis
r.resamp.interp input=mawrth_hematite output=mawrth_hematite_crism_res \
    method=bilinear

References for this example:

Full pipeline — CRISM TRDR over Mawrth Vallis clay outcrops (Mars)

Mawrth Vallis (≈22–24°N, 341–344°E) is the best-studied phyllosilicate terrain on Mars and a former Mars 2020 landing-site candidate. The stratigraphic sequence — Fe/Mg smectites (nontronite, Fe-saponite) at depth, overlain by Al-phyllosilicates (montmorillonite, kaolinite) — is uniquely complete and fully accessible to orbital spectroscopy (Bishop et al. 2008; Loizeau et al. 2010; Carter et al. 2015).

The four orbital instruments that detect minerals on the Martian surface are:

CRISM TRDR (Targeted Reduced Data Record) provides the best spatial resolution for clay-unit mapping and is the standard reference dataset for Mawrth Vallis. The IR (S-detector) channel covers 1.00–3.92 µm in 438 bands, resolving all phyllosilicate absorption features.

# ── 0. One-time: GRASS location on Mars geographic CRS (IAU 2015) ────────────
grass -c EPSG:49900 ~/grassdata/mars

# ── 1. Set region to the main Mawrth Vallis clay terrace ─────────────────────
# Bishop et al. (2008) Science Fig. 1 centre: 23.6°N, 342.8°E
# 0.2° box encloses the Fe/Mg → Al phyllosilicate sequence
g.region n=23.70 s=23.50 e=342.90 w=342.70 res=0:00:02

# ── 2. List CRISM targeted products intersecting this region ─────────────────
p.in.archive -lr \
    opus="instrument=MRO CRISM,target=Mars" \
    output=dummy limit=15

# ── 3. Find and import a CRISM IR TRDR ───────────────────────────────────────
# Two complementary resources identify suitable CRISM tiles for Mawrth Vallis:
#
#   • rsidea.whu.edu.cn/Martian_mineral_detection.htm — WHU group CRISM
#     mineral-detection dataset (31-class MICA-based classification; ISPRS
#     J. Photogramm. Remote Sens. 2024, doi:10.1016/j.isprsjprs.2024.03587).
#     The dataset lists CRISM FRT tiles and their mineral content; filter for
#     tiles intersecting 22–24°N, 341–344°E and showing phyllosilicate classes.
#
#   • OPUS browser (opus.pds-rings.seti.org) — search by instrument
#     MRO CRISM, target Mars, lon 342.55–342.95, lat 23.35–23.85 to list all
#     CRISM observations with footprint, emission angle, and solar longitude.
#     Prefer low emission angle (<10°) and low dust opacity (Ls < 180° for
#     northern autumn when dust loading is minimal).
#
# CRISM TRDR PDS naming convention:
#   FRT<8-hex-obsid>_07_IF<mode><channel>_TRR3
#   channel S = IR detector (1.0–3.92 µm, 438 bands)
#   channel L = VNIR detector (0.36–1.05 µm, 107 bands)
#
# Well-documented tiles over the Mawrth Vallis clay terrace:
#   FRT00003BFB  2006-11-02  23.6°N 342.8°E  — primary phyllosilicate exposure
#   FRT0000CBCE  2009-03-15  23.5°N 343.0°E  — northern terrace margin
#   FRT0000ABD6  2008-08-22  23.7°N 342.6°E  — cross-section through Al/Fe units

# List IR TRDR products that intersect the working region (OPUS search):
p.in.archive -lr \
    opus="instrument=MRO+CRISM,target=Mars" \
    output=dummy limit=20

# Import the chosen IR tile.
# p.in.archive downloads the .img cube + .lbl from OPUS and dispatches to
# p.in.pds3, which imports each band as a separate raster: mawrth_crism_ir.1 …
CRISM_TILE="mro-crism-frt00003bfb_07_if166s_trr3"   # set to chosen tile OPUS ID
p.in.archive \
    opus_id="${CRISM_TILE}" \
    output=mawrth_crism_ir \
    --overwrite

# ── 4. Build the image group ──────────────────────────────────────────────────
# All 438 S-detector bands in wavelength order (p.in.pds3 preserves band order)
BAND_MAPS=$(g.list type=raster pattern="mawrth_crism_ir.*" \
    separator=comma mapset=.)
i.group group=mawrth_crism input="${BAND_MAPS}"

# ── 5. Extract CRISM IR wavelengths from the PDS3 label ──────────────────────
# BAND_BIN_CENTER in the TRDR .lbl lists centre wavelengths in nm.
# The one-liner below extracts them and converts to µm for the CSV.
python3 - << 'PYEOF'
import re, os

lbl = "FRT00003BFB_07_IR166S_TRR3.LBL"
wl_nm = [float(x) for x in
         re.findall(r"[\d.]+", "".join(
             open(lbl).read().split("BAND_BIN_CENTER")[1].split(")")[0]
             .split("(")[1:]))]
with open("crism_ir_wavelengths.csv", "w") as f:
    f.write("# CRISM S-detector wavelengths (Murchie et al. 2007 JGR)\n")
    f.write("# wavelength_um, fwhm_um\n")
    for wl in wl_nm:
        f.write(f"{wl/1000.0:.6f}, 0.00650\n")
print(f"Wrote {len(wl_nm)} bands: {wl_nm[0]/1000:.4f}–{wl_nm[-1]/1000:.4f} µm")
PYEOF
# → Wrote 438 bands: 1.0020–3.9192 µm

# ── 6. Verify detectable species ─────────────────────────────────────────────
p.matter.bands -lv \
    group=mawrth_crism \
    body=mars \
    output_prefix=mawrth \
    wavelengths=crism_ir_wavelengths.csv

# Expected output (representative):
#   Body: mars | Bands: 438 | Sensor: 1.0020–3.9192 µm
#   Detectable (14):
#     olivine              minerals  1.0500 µm
#     low_ca_pyroxene      minerals  0.9200+1.8500 µm
#     high_ca_pyroxene     minerals  1.0000+2.3000 µm
#     smectite_fe_mg       minerals  1.4100+1.9100+2.2900 µm   ← nontronite
#     nontronite           minerals  1.4100+1.9100+2.2900 µm   ← primary target
#     montmorillonite      minerals  1.4100+1.9100+2.2100 µm   ← Al-phyllosil.
#     kaolinite            minerals  1.4100+1.9100+2.2100 µm
#     chlorite             minerals  2.2500+2.3300 µm
#     serpentine           minerals  2.3200+2.5200 µm
#     gypsum               minerals  1.4500+1.7500+1.9500 µm
#     jarosite             minerals  0.4300+0.9000 µm
#     hematite             minerals  0.5330+0.8600 µm
#     h2o_ice              ices      1.5000+2.0200 µm
#     co2_ice              ices      1.4300+2.0100 µm
#   Out of range (2): perchlorate_hydrate, ...

# ── 7. Map all Mars minerals and ices ────────────────────────────────────────
p.matter.bands \
    group=mawrth_crism \
    body=mars \
    matter=minerals,ices \
    output_prefix=mawrth \
    wavelengths=crism_ir_wavelengths.csv \
    min_bd=0.02 \
    -vc

# Output maps (one per detected species):
#   mawrth_nontronite           BD composite 1.41 + 1.91 + 2.29 µm
#   mawrth_montmorillonite      BD composite 1.41 + 1.91 + 2.21 µm
#   mawrth_kaolinite            BD composite 1.41 + 1.91 + 2.21 µm
#   mawrth_smectite_fe_mg       BD composite 1.41 + 1.91 + 2.29 µm
#   mawrth_chlorite             BD composite 2.25 + 2.33 µm
#   mawrth_serpentine           BD composite 2.32 + 2.52 µm
#   mawrth_low_ca_pyroxene      BD composite 0.92 + 1.85 µm
#   mawrth_olivine              BD 1.05 µm
#   mawrth_hematite             BD composite 0.53 + 0.86 µm
#   mawrth_gypsum               BD composite 1.45 + 1.75 + 1.95 µm
#   mawrth_h2o_ice              BD composite 1.50 + 2.02 µm
#   mawrth_composite_RGB        i.group: R=nontronite, G=montmorillonite, B=olivine

# ── 8. Colour tables and display ─────────────────────────────────────────────
r.colors map=mawrth_nontronite      color=reds
r.colors map=mawrth_montmorillonite color=blues
r.colors map=mawrth_kaolinite       color=greens

d.mon start=wx0 resolution=1
d.rast mawrth_composite_RGB
# Red pixels  → nontronite (Fe/Mg smectite layer, lower stratigraphic unit)
# Blue pixels → montmorillonite (Al-phyllosilicate cap, upper unit)
# Mixed areas → transition zone; cross-reference with HRSC/HiRISE DTM

# ── 9. Extract stratigraphy transect ─────────────────────────────────────────
# Profile through the phyllosilicate terrace (N–S transect at 342.80°E)
r.profile \
    input=mawrth_nontronite,mawrth_montmorillonite,mawrth_kaolinite \
    coordinates="342.80,23.70,342.80,23.50" \
    output=mawrth_clay_transect.csv

Interpreting the result — the stratigraphic trend expected from Bishop et al. (2008) and Loizeau et al. (2010): nontronite (2.29 µm) band depth peaks in the lower terrace unit (Noachian, pre-3.7 Ga); montmorillonite/kaolinite (2.21 µm) band depth peaks in the overlying 10–200 m cap. The mawrth_composite_RGB map reproduces this as a red-to-blue vertical gradient across the terrace edge.

References:


PRE-PROCESSING CHAIN (required before p.matter.bands)

Raw PDS data
    │
    ▼
p.in.pds3 / p.in.pds4 / p.in.isis  ← import, sets wavelength metadata
    │
    ▼ (if needed)
p.specpix                            ← clean special pixel values
p.dstripe / p.cubenorm               ← remove detector artifacts
    │
    ▼ (always)
p.albedo                             ← convert I/F → geometric albedo
    │
    ▼ (if atmosphere)
p.atcorr.hapke                       ← remove atmospheric contribution
    │
    ▼ (optional for photometric uniformity)
p.phocube → p.photomet               ← normalise incidence/emission
    │
    ▼
p.matter.bands                       ← absorption band detection maps

SEE ALSO

AUTHOR

Yann Chemin

STATUS

Phases 1–12 complete.

Phase 1: band database (data/matter_bands.json), C library extension (p_spectra_bd_multi, p_spectra_apply_row_bd_multi), Python module (p.matter.bands.py), and auto-install via p_meta_install_matter_bands().

Phase 2: wavelength range extended to 0.18–200 µm. UV coverage (15 band entries across 8 bodies); MIR emissivity mode (mode=emissivity) with 38 band features for TES/THEMIS/MERTIS/JWST-MIRI sensors; LWIR/FIR cometary H2O rotational lines (Herschel/PACS, HIFI, ALMA).

Phase 3: 6 new bodies (ganymede, callisto, triton, ariel, uranus_moon, asteroid_d_type) + expansion of Europa, Titan, Venus. Database now holds 123 species across 19 bodies, wavelength range 0.18–200 µm. Testsuite has 46 tests across three test classes (Phase 1: 11, Phase 2: 15, Phase 3: 20).

Phase 4: advanced detection modes — NNLS spectral unmixing (-u endmembers=, one full-spectrum image group per endmember); temperature-dependent ice band-center correction (temperature=); space weathering correction (space_weathering=, body-specific α from body_meta in the database); Hapke atmospheric correction pre-step (-a atcorr_*=). Phase 4 adds 13 testsuite tests (class TestPmatterbandsPhase4; total: 59 tests).

Phase 5: confidence & quality outputs — per-species band-concordance confidence raster (-q, value = n_bands_matched / n_diagnostic_bands); minimum confidence filter (min_conf=, default 0.0) to suppress under-constrained detections; structured JSON detection report (report=) listing per-species confidence, mean/max BD, n_matched/n_total, and skipped-species reasons; composite RGB channel selection upgraded from mean-BD to confidence × mean-BD weighting. Phase 5 adds 11 testsuite tests (class TestPmatterbandsPhase5; total: 70 tests).

Phase 6: classification and uncertainty propagation — dominant-species classification raster (-k, <prefix>_classification, category code of the highest confidence-weighted BD species per pixel, with r.category labels); radiometric uncertainty propagation (radiometric_noise= + -e, analytic first-order error propagation through the band-depth formula, written as <prefix>_<species>_unc); JSON report gains a mean_uncertainty field. Phase 6 adds 10 testsuite tests (class TestPmatterbandsPhase6; total: 80 tests).

Phase 7: multi-temporal change detection — band-depth difference map (-d, reference_prefix=, <prefix>_<species>_diff = BD_now − BD_reference, diverging colour table); statistical significance flagging (change_sigma=, default 2.0σ) using combined uncertainty from both epochs when available, written to <prefix>_<species>_diff_sig; JSON report gains mean_diff, max_abs_diff, n_significant_change_pixels. Phase 7 adds 10 testsuite tests (class TestPmatterbandsPhase7; total: 90 tests).

Phase 8: Spectral Angle Mapper cross-validation — standalone full-spectrum matching mode (-m, sam_library=, one full-spectrum reference group per library entry, same convention as endmembers=); per-reference angle maps <prefix>_sam_<group_name> in degrees [0,90] (color=byr); best-match classification <prefix>_sam_classification when multiple libraries are given (reuses the Phase 6.1 classification mechanism). Mirrors p_spectra_sam() from the C library as a pure-numpy implementation. Phase 8 adds 8 testsuite tests (class TestPmatterbandsPhase8; total: 98 tests).

Phase 9: per-species spectral cross-check — integrates Phase 8's SAM angle computation into the core detection loop (-s, sam_library_prefix=, sam_max_angle= default 30°), following the same <prefix>_<species_name> lookup convention as Phase 7's reference_prefix=; suppresses band-depth pixels whose full spectrum disagrees with the species' reference beyond the threshold; graceful no-op (warn, not fatal) when no reference group exists or its band count mismatches. JSON report gains sam_angle_deg and sam_confirmed_fraction. Verified the underlying p_spectra_sam() / p_spectra_apply_row_sam() C implementation (libs/p_spectra/) is complete, correct, and already OpenMP-parallel at the row level (6565/6565 C unit-test assertions pass); BLAS/LAPACK/GSL/OpenCL were evaluated and not adopted — vector lengths (tens to low hundreds of bands) are too small for them to offer a measurable gain over the existing per-pixel OpenMP parallelism. Phase 9 adds 7 testsuite tests (class TestPmatterbandsPhase9; total: 105 tests).

Phase 10: spectral library import — standalone mode (-i, import_library=, import_library_name=) that linearly interpolates a plain two-column spectral-library CSV onto the current group's sensor wavelength grid and writes a ready-to-use reference image group (one constant-value band per wavelength via r.mapcalc), for direct reuse as endmembers=, sam_library=, or sam_library_prefix=. Fixed a latent bug where the "no species found" early exit could abort standalone modes (-u, -m, -i) before they ever ran, for body/matter combinations with zero matching species. Phase 10 adds 8 testsuite tests (class TestPmatterbandsPhase10; total: 113 tests).

Phase 11: spectrum extraction — standalone mode (-x, extract_coords=, extract_csv=) that reads every band's value at a map coordinate via r.what and writes it in the same wavelength_um,value CSV format Phase 10 consumes, NULL pixels as nan; round-trips into -i import_library= to build endmember/SAM references directly from the scene under analysis. Found and fixed a parsing bug during implementation: r.what's pipe-output has a variable number of leading fields before the per-map values, so parsing now anchors from the right instead of a fixed offset. Phase 11 adds 8 testsuite tests (class TestPmatterbandsPhase11, including an extract→import round-trip check; total: 121 tests).

Phase 12: band-read cache + site comparison. _read_band() now caches each raster's pixel array per process, eliminating redundant r.out.bin round-trips across species that share diagnostic/continuum bands and across repeated full-spectrum reads in the SAM cross-check; verified safe (no consumer mutates the returned array) and white-box tested via direct module import. Site comparison (-z, sites=, sites_output=) writes per-species band-depth statistics as new attribute columns on a fresh copy of a sites vector — <species>_bd for points (v.what.rast), <species>_average/ minimum/maximum for areas (v.rast.stats) — auto-detecting point vs. area via v.info -t. Phase 12 adds 11 testsuite tests across two classes (TestPmatterbandsPhase12Cache: 5, TestPmatterbandsPhase12Sites: 6; total: 132 tests).

Also fixed in this phase set: the .deb package never installed or linked $GISBASE/etc/planetary/matter_bands.json (debian/rules, grass-planetary-addons.postinst/.prerm), so any p.matter.bands run without db= explicitly set would fail on a packaged install — this affected real usage, not just tests.

SOURCE CODE

Available at: p.matter.bands source code (history)

Accessed: Sunday Nov 15 11:06:02 2026


Main index | Paint index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual