GRASS logo

NAME

p.spec.class - Spectral classification of multi-band planetary rasters.
Two modes: 'kmeans' performs unsupervised k-means++ clustering and writes a geologic unit integer raster; 'sam' performs supervised Spectral Angle Mapper classification against a reference spectrum CSV and writes a binary match raster (1 = match, 0 = no match, NULL = invalid pixel). Reads bands named input.1, input.2, ...

KEYWORDS

Planetary, Spectral & Mineral Mapping, classification, k-means, SAM, geologic mapping

SYNOPSIS

p.spec.class
p.spec.class --help
p.spec.class input=string output=name mode=string [k=integer] [iterations=integer] [seed=integer] [spectrum=string] [threshold=float] [stats=string] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

--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:

input=string [required]
Base name of input band rasters (input.1, input.2, ...)
output=name [required]
Name for output raster map
mode=string [required]
Classification mode: kmeans (unsupervised) or sam (supervised)
Options: kmeans, sam
k=integer
[kmeans] Number of spectral classes
Default: 5
iterations=integer
[kmeans] Maximum k-means iterations
Default: 100
seed=integer
[kmeans] Random seed (0 = use system time)
Default: 0
spectrum=string
[sam] Reference spectrum CSV (one reflectance value per line)
threshold=float
[sam] SAM angle threshold in radians (default 0.1 ≈ 5.7°)
Default: 0.1
stats=string
Output CSV: class centroids (kmeans) or SAM angle stats (sam)

Table of contents

DESCRIPTION

p.spec.class classifies multi-band planetary rasters spectrally in two modes:

kmeans — unsupervised spectral clustering

Groups pixels into k spectrally homogeneous classes using the k-means++ algorithm (Arthur & Vassilvitskii 2007). k-means++ uses distance-weighted probabilistic seeding to avoid the degenerate cluster initialisation that naive random seeding often produces.

Output is an integer raster where each pixel value is its class label (1 … k). Pixels where any band is NULL are set to NULL in the output. Optionally writes the centroid spectrum for each class to a CSV file (stats=), enabling post-hoc spectral identification of the classes.

Typical workflow for geologic unit mapping:

1. Import a calibrated CRISM/OMEGA/M3 cube via p.in.archive
2. Optionally run p.spec.pca to denoise (use first N PCs as input)
3. Run p.spec.class mode=kmeans k=8 to produce a unit raster
4. Inspect class centroids in stats CSV; label each class geologically
5. Use v.what.rast or r.category to attach geologic names to classes

sam — supervised Spectral Angle Mapper classification

Compares each pixel's spectrum to a single reference spectrum supplied as a CSV file (one reflectance value per line, one band per line). Pixels whose SAM angle ≤ threshold radians are assigned value 1 (match); all others are 0. NULL pixels remain NULL.

The default threshold of 0.1 rad (≈ 5.7°) is a commonly used starting point for mineralogic matching; tighten to 0.05 rad for higher purity, relax to 0.15–0.2 rad for higher completeness.

PARAMETERS

Parameter Default Description
input= required Base name of input bands (input.1, .2, …)
output= required Output raster (integer class labels)
mode= required kmeans or sam
k= 5 [kmeans] Number of spectral classes (2–255)
iterations= 100 [kmeans] Maximum k-means iterations
seed= 0 [kmeans] Random seed (0 = system time)
spectrum= [sam] Reference spectrum CSV file
threshold= 0.1 [sam] SAM angle threshold (radians)
stats= Output CSV: centroids (kmeans) or match stats (sam)

NOTES

EXAMPLES

8-class unsupervised classification of CRISM PCs 1–10:

p.spec.class input=crism_pc output=crism_units mode=kmeans k=8 \
    stats=crism_centroids.csv seed=42

SAM match against a laboratory olivine spectrum at 5.7° threshold:

p.spec.class input=crism_frt output=crism_olivine_match \
    mode=sam spectrum=olivine_lab.csv threshold=0.1

REFERENCES

SEE ALSO

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

SOURCE CODE

Available at: p.spec.class 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