GRASS logo

NAME

p.spec.library - Planetary spectral library search — rank mineral matches by SAM angle.
Compares a query spectrum (from a CSV file or extracted as the mean of a GRASS raster group over the current region) against a spectral library directory. Each library entry is a 2-column CSV (wavelength_um, reflectance). Reports top-N matches ranked by Spectral Angle Mapper (SAM) distance. The built-in fallback library contains 28 key planetary minerals extracted from USGS splib07a (olivine, pyroxene, plagioclase, phyllosilicates, carbonates, sulfates, iron oxides, opal).

KEYWORDS

Planetary, Spectral & Mineral Mapping, spectral library, SAM, mineral identification

SYNOPSIS

p.spec.library
p.spec.library --help
p.spec.library [-v] [spectrum=string] [group=name] [wavelengths=string] [library=string] [top=integer] [output=string] [max_angle=float] [--help] [--verbose] [--quiet] [--ui]

Flags:

-v
Verbose: print each library file considered (including skipped)
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

spectrum=string
Input spectrum CSV file (two columns: wavelength_um, reflectance)
Mutually exclusive with group=. One row per band. Lines starting with # are ignored.
group=name
GRASS imagery group to extract mean spectrum from
The mean value per band over the current region is used. Requires wavelengths= to map bands to wavelengths.
wavelengths=string
CSV file with per-band wavelengths in µm (one value per line, for group= mode)
library=string
Path to library directory of 2-column CSVs (wavelength_um, reflectance)
If not given, uses the built-in planetary library (28 mineral spectra from USGS splib07a). A RELAB or USGS splib07a directory can also be given directly; see notes.
top=integer
Number of top matches to report (ranked by SAM angle, ascending)
Default: 10
output=string
Output CSV file for the ranked match table (if not given, prints to stdout)
max_angle=float
Maximum SAM angle in radians to include in results (default π/2 = no filter)
Default: 1.5708

Table of contents

DESCRIPTION

p.spec.library compares a query spectrum against a directory of 2-column wavelength/reflectance CSVs and reports the top-N closest matches ranked by Spectral Angle Mapper (SAM) distance.

The query spectrum can be:

The library is any directory of 2-column CSV files (library=). The built-in planetary library (28 spectra from USGS splib07a; no external download required) is used by default.

Built-in library contents

Class Spectra
Olivine Fo89, Fo51, Fo29, Fo11 (compositional series)
Low-Ca pyroxene Enstatite, Bronzite
High-Ca pyroxene Augite, Diopside
Plagioclase Anorthite, Albite
Smectite / phyllosilicate Nontronite, Montmorillonite, Saponite, Kaolinite, Serpentine, Chlorite, Illite, Muscovite, Talc
Secondary silicate Prehnite, Epidote
Carbonate Calcite
Sulfate Gypsum, Jarosite (Na), Jarosite (K)
Iron oxide Hematite, Goethite
Silica Opal

All BECK-instrument spectra cover 0.2–3.0 µm (≈ 460–478 valid channels); ASD-instrument spectra (serpentine, chlorite, goethite) cover 0.35–2.5 µm (2151 channels). Spectra are resampled to the query's wavelength grid via linear interpolation before SAM computation.

SAM angle

SAM is the arccosine of the normalised dot product of two spectral vectors:

SAM = acos(Σ aᵢbᵢ / (|a|·|b|))

It is invariant to multiplicative (albedo) scaling and gives distances in radians (0 = identical shape). Typical thresholds for mineralogic matching:

Using an external RELAB or USGS splib07a library

Point library= at any directory containing 2-column CSV files. You can convert USGS splib07a ASCII files with the included make_speclib.py script (edit the SPLIB07 path variable at the top). RELAB files (3-column: wavelength, reflectance, stddev) need minor pre-processing — strip the first two header lines and drop the third column.

PARAMETERS

Parameter Default Description
spectrum= Query spectrum CSV (wavelength_um, reflectance)
group= GRASS imagery group to extract mean spectrum from
wavelengths= Per-band wavelength CSV for group= mode (one value per line)
library= built-in Directory of 2-column spectrum CSVs
top= 10 Number of top matches to report
output= CSV file for the ranked match table (default: stdout)
max_angle= π/2 Maximum SAM angle in radians; larger matches are excluded
-v Verbose: print all library entries considered

NOTES

EXAMPLES

Match a mean CRISM spectrum (extracted from the current region of an imported CRISM imagery group) against the built-in library:

p.spec.library group=crism_frt wavelengths=crism_wavelengths.csv top=5

Match a single-pixel spectrum CSV against the built-in library, save results:

p.spec.library spectrum=my_pixel.csv top=10 output=matches.csv

Match against a full USGS splib07a directory (requires local copy):

p.spec.library spectrum=my_pixel.csv \
    library=/path/to/splib07a_minerals_beck/ top=20

SEE ALSO

p.spec.pca, p.spec.class, p.spectral.planet, p.mineral.indices

REFERENCES

SOURCE CODE

Available at: p.spec.library source code (history)

Accessed: Sunday Nov 15 11:06:07 2026


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

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