i.hyper.cannabis finds the pixels in a hyperspectral 3D raster that most closely match a user-supplied reference spectrum. For each pixel the module computes a similarity score in [0, 1] (0 = no match, 1 = perfect match) using one or more of 19 spectral-similarity methods drawn from remote sensing, signal analysis, information theory, morphological mathematics, and subpixel-detection theory.
The reference spectrum is automatically resampled onto the sensor wavelength grid via a precomputed WavelengthLUT (linear interpolation; O(n) per pixel, no repeated binary search). Optional preprocessing — continuum removal, normalization, probability-simplex projection — is applied identically to the reference and to every pixel before matching.
The module also exposes a full multi-method consensus pipeline (method=consensus) that runs all 17 base methods simultaneously, calibrates each score map to a true per-pixel probability via an empirical CDF rank transform, down-weights correlated methods using an inter-method diversity analysis, and fuses the result into a single hotspot probability map plus four diagnostic maps (agreement, entropy, conflict, spread).
i.hyper.cannabis is part of the i.hyper module family for hyperspectral data import, atmospheric correction, and analysis in GRASS GIS. Input 3D rasters are produced by i.hyper.import or i.hyper.atcorr.
Comma-separated wavelength:reflectance pairs passed directly as a command option. Colons and semicolons are both accepted as pair separators; pairs may also be whitespace-delimited. Scientific notation is supported. The list is sorted by wavelength before use. At least 2 pairs are required.
# Colon separator, comma list (most common) reference="450:0.04,550:0.11,670:0.05,750:0.40,900:0.45,1650:0.22,2200:0.18" # Semicolon separator reference="450;0.04,550;0.11,670;0.05" # Whitespace-separated list reference="450:0.04 550:0.11 670:0.05" # Scientific notation reference="4.5e2:4.0e-2,5.5e2:1.1e-1,8.0e2:4.0e-1"
Reflectance values should be in [0, 1] (surface reflectance). Values above 2 trigger a warning that the data may be in percent reflectance.
Two columns: wavelength and reflectance. Any row whose first field is non-numeric (header line, comment, blank line) is silently skipped. Pairs are sorted by wavelength before use. At least 2 data rows are required.
With header:
wavelength,reflectance 450,0.04 550,0.11 670,0.05 800,0.42 2200,0.18
Header-less:
450,0.04 550,0.11 670,0.05
With comment lines (non-numeric rows are skipped automatically):
# kaolinite -- USGS Spectral Library 7 # wavelength (nm), reflectance [0-1] wavelength,reflectance 2165,0.22 2195,0.18 2205,0.09 2240,0.21 2320,0.31
Four distinct JSON layouts are accepted:
1. Array of pairs (compact):
[[450, 0.04], [550, 0.11], [670, 0.05], [800, 0.42], [2200, 0.18]]
2. Parallel arrays (ENVI / spectral library style):
{
"wavelengths": [450, 550, 670, 800, 2200],
"reflectances": [0.04, 0.11, 0.05, 0.42, 0.18]
}
Key aliases accepted: "wavelength" or "wl" for the wavelength array; "reflectance" or "r" for the reflectance array.
3. Named list ("data", "spectrum", or "pairs" key):
{"data": [[450, 0.04], [550, 0.11], [670, 0.05]]}
{"spectrum": [[450, 0.04], [550, 0.11], [670, 0.05]]}
{"pairs": [[450, 0.04], [550, 0.11], [670, 0.05]]}
4. Short-key parallel arrays:
{"wl": [450, 550, 670, 800], "r": [0.04, 0.11, 0.05, 0.42]}
All JSON variants are sorted by wavelength before use.
Reference wavelengths must be in the same units as the sensor band metadata (usually nanometres). The following unit strings in band metadata are converted automatically to nm: um / µm / micrometer, m / meter. If your reference file uses µm (e.g., USGS .asc exports), convert before use:
python3 -c "
import csv
for row in csv.reader(open('kaolinite.csv')):
try: print(f'{float(row[0])*1000:.2f},{row[1]}')
except: print(','.join(row))
" > kaolinite_nm.csv
| Key | Name | Category | Description |
|---|---|---|---|
| sam | Spectral Angle Mapper | Geometric | Angle θ between reference vector and pixel vector in n-dimensional reflectance space. Scale-invariant (insensitive to illumination magnitude). sim = 1 − 2θ/π. |
| sid | Spectral Information Divergence | Information theory | Symmetric KL divergence between spectra treated as probability distributions. SID = D(r‖p) + D(p‖r); sim = exp(−SID). Sensitive to subtle energy redistribution between bands. |
| sid_sam | SID × tan(SAM) | Information theory / Geometric | Hybrid measure (Chang 2000): sim = exp(−SID·tan θSAM). Combines probabilistic and angular perspectives; effective when both shape and energy differ between target and background. |
| ed | Euclidean Distance (L2) | Distance | Root-mean-square per-band difference. sim = 1/(1 + ‖r−p‖₂/√n). Use with normalize=vector to remove illumination effects. |
| sad | Spectral Absolute Difference (L1) | Distance | Mean absolute per-band difference; more robust to outlier bands than L2. sim = 1/(1 + mean|ri−pi|). |
| sca | Spectral Correlation Angle (Pearson r) | Statistical | Pearson correlation between reference and pixel spectra mapped to [0, 1]. Captures spectral shape independently of mean level; equivalent to SAM applied to mean-centered spectra. |
| cr_sam | Continuum-Removed SAM | Morphological / Geometric | Upper-convex-hull continuum removal (Clark et al. 1987) applied to both spectra before SAM. Isolates absorption-feature shape, removing broadband albedo and slope. Best for mineral identification. |
| cr_ed | Continuum-Removed Euclidean Distance | Morphological / Distance | Same continuum removal as cr_sam, followed by L2 distance. Useful when absolute band-depth differences are meaningful in addition to angular deviation. |
| gd1 | 1st-Derivative Shape Matching | Signal analysis | Finite-difference first derivative of both spectra, then SAM. Highly sensitive to slope transitions and absorption-edge positions; insensitive to overall level and broadband curvature — analogous to high-pass filtering. |
| gd2 | 2nd-Derivative Shape Matching | Signal analysis | Second finite difference, then SAM. Responds only to local curvature — absorption-band centres and inflection points. Requires well-calibrated data with low noise. |
| xcorr | Normalized Cross-Correlation | Signal analysis | NCC computed at lags [−W, +W] (controlled by shift_window=); maximum over all lags returned. Tolerates small wavelength-calibration offsets. sim = (maxkNCC + 1)/2. |
| dtw | Dynamic Time Warping | Signal analysis | Sakoe-Chiba band DTW in a rolling two-row window (memory-efficient). Finds minimum-cost alignment under a bandwidth constraint of shift_window= bands. Captures non-linear feature stretching. sim = exp(−DTWnorm). |
| ssim | Spectral Structural Similarity Index | Signal analysis | Wang et al. (2004) adapted to 1-D spectra. Decomposes similarity into luminance (mean), contrast (std dev), and structure (covariance) components. sim = (SSIM + 1)/2. |
| jsd | Jensen-Shannon Divergence | Information theory | JSD = (KLD(r‖m) + KLD(p‖m))/2 where m = (r+p)/2. Always well-defined; bounded in [0, ln 2]. sim = exp(−JSD). Recommended with -z. |
| bhatt | Bhattacharyya Coefficient | Statistical | BC = Σ√(piqi) ∈ [0, 1]. Directly a similarity; no further transform needed. Robust to band noise. Recommended with -z. |
| mtf | Matched Tuned Filter | Subpixel detection | Reed-Yu (1990) linear detector: w = Σ−1(d−μ)/(d−μ)TΣ−1(d−μ). Maximises signal-to-background ratio for target d. Requires full cube to compute image covariance Σ. Score percentile-normalised to [0, 1]. |
| cem | Constrained Energy Minimization | Subpixel detection | Chang & Heinz (2000): w = Σ−1d/(dTΣ−1d). Minimises mean output energy subject to unit target response. No explicit background model; effective for small-fraction targets. Score percentile-normalised to [0, 1]. |
| ensemble | Rank-based Ensemble Fusion | Meta-method | Borda-count rank aggregation: pixel ranks within each method are summed and normalised to [0, 1]. Robust to scale differences between methods; reduces sensitivity to any single method's failure mode. |
| consensus | Calibrated Probability Fusion | Meta-method | Four-step pipeline: (1) run all 17 base methods; (2) CDF rank-calibrate each map to a true probability; (3) compute inter-method diversity weights; (4) fuse via the selected fusion_mode. Produces a hotspot probability map plus four diagnostic maps. See the Consensus analysis section. |
When consensus is requested the module executes a four-step pipeline:
p_m(i) = rank(score_m(i)) / N_pixelsThis removes scale bias that would otherwise allow high-range methods (SAM ∈ [0.8, 1.0]) to dominate over low-range methods (ED ∈ [0.0, 0.2]). Calibrated maps are written as {prefix}_cal_{method}.
w_i ∝ 1 / (mean_{j≠i} |r_{ij}| + 0.15)
so that correlated clusters (e.g., SAM + SCA) do not over-count
their shared evidence. Weights are rescaled so that mean(w) = 1.
Print with -v.| Mode | Formula | Characteristics |
|---|---|---|
| rank_product | exp(Σᵢ wᵢ ln pᵢ) | Weighted geometric mean; AND-like; robust (default) |
| fisher | 1 − χ²_sf(−2 Σᵢ wᵢ ln(1−pᵢ), df_eff) | Proper p-value from combined probability test (Fisher 1932) |
| stouffer | Φ(Σᵢ wᵢ Φ⁻¹(pᵢ) / √Σᵢ wᵢ²) | Diversity weights enter exactly via Z-score combination (Stouffer 1949) |
| group_product | geometric mean within groups; arithmetic mean across | AND within geometric/distance/info groups; OR across groups |
| harmonic | 1 / Σᵢ wᵢ/pᵢ | Strictest: all methods must simultaneously agree |
| min | mini pᵢ | Absolute strictest; dominated by the single worst method |
When output_prefix= is set, the following maps are written in addition to the primary output= hotspot probability map:
| Map | Content |
|---|---|
| {prefix}_consensus_agreement | Fraction of methods voting above agreement_threshold [0, 1] |
| {prefix}_consensus_entropy | Normalised Shannon entropy of calibrated scores: 0 = unanimous, 1 = maximal conflict |
| {prefix}_consensus_conflict | Pixels that are simultaneously high-probability AND high-entropy — review these |
| {prefix}_consensus_spread | Standard deviation of calibrated scores per pixel |
| {prefix}_cal_{method} | Rank-calibrated probability for each of the 17 base methods |
| {prefix}_{method} | Raw similarity score for each base method |
The reference spectrum and the sensor wavelength grid will almost always differ in sampling and range. A WavelengthLUT is built once before any pixel processing:
Use -i (info mode) to inspect the coverage report before processing.
| Parameter | Default | Description |
|---|---|---|
| input= | — | Input hyperspectral 3D raster (produced by i.hyper.import or i.hyper.atcorr) |
| output= | — | Output similarity map (FCELL, [0, 1]) |
| reference= | — | Inline wl:r,… spectrum string; mutually exclusive with reference_file= |
| reference_file= | — | Path to CSV or JSON spectrum file; mutually exclusive with reference= |
| method= | sam | Comma-separated list of similarity methods (see table above) |
| fusion_mode= | rank_product | Fusion strategy for method=consensus |
| agreement_threshold= | 0.80 | Calibrated-probability threshold for the per-pixel agreement count (consensus only) |
| output_prefix= | — | Prefix for per-method output maps; enables map caching in consensus |
| resample= | linear | Interpolation for resampling the reference spectrum to the sensor wavelength grid: linear, cubic, pchip |
| normalize= | none | Spectrum normalisation before matching: none, area, max, minmax, vector (see Normalization options) |
| shift_window= | 3 | Maximum band-shift for shift-tolerant methods (xcorr, dtw); 0 disables shifting |
| min_wavelength= | — | Lower wavelength limit (nm); restricts matching to the sensor/reference overlap |
| max_wavelength= | — | Upper wavelength limit (nm); restricts matching to the sensor/reference overlap |
| coordinates= | — | east,north for single-pixel point-mode analysis (requires -p) |
| Flag | Effect |
|---|---|
| -n | Only use bands marked valid=1 in band metadata |
| -i | Info mode: print band coverage and LUT summary, then exit |
| -v | Verbose: per-method scores in point mode; correlation matrix and diversity weights in consensus mode |
| -c | Apply upper-convex-hull continuum removal to both reference and pixel spectra before matching |
| -p | Point mode: extract spectrum at coordinates= and print a ranked per-method score table |
| -z | Normalise both reference and pixel spectra to the probability simplex (sum-to-one) before matching |
| Flag | Effect | Recommended with |
|---|---|---|
| -c | Apply upper-convex-hull continuum removal to every pixel and to the reference before matching. Removes broadband albedo variation, leaving only absorption feature shape. | sam, ed, sca — removes illumination / slope bias |
| -z | Normalise both reference and pixel spectra to the probability simplex (sum-to-one, all values ≥ 0) before matching. | sid, jsd, bhatt — these methods assume probability distributions |
| Option | Transform |
|---|---|
| none | Raw reflectance (default) |
| area | Divide by spectral sum; total power = 1 |
| max | Divide by maximum band value |
| minmax | Map range to [0, 1] |
| vector | Divide by L2 norm; unit vector in spectral space (equivalent to SAM denominator) |
When -p is set together with coordinates=east,north, i.hyper.cannabis extracts the spectrum at the given geographic location and prints a ranked similarity table for every requested method. No raster output is produced. Useful for validation, threshold selection, and understanding method behaviour before running a full-image analysis.
The module expects a 3D raster map with wavelength metadata stored in band-level metadata following the i.hyper standard: wavelength, FWHM, valid, and unit. Such maps are produced by i.hyper.import or i.hyper.atcorr.
All wavelengths must be in the same unit as the sensor metadata (typically nanometres for optical sensors). The module automatically converts µm and m to nm when reading band metadata.
Spectra must be in surface reflectance units (0–1 range). Top-of-atmosphere radiance or raw DN values will produce invalid results.
All output maps are floating-point FCELL rasters in [0, 1]. All maps share a blue → yellow → red colour ramp applied automatically via r.colors (0 = blue, 0.5 = yellow, 1 = red).
Methods sam, sid, ed, sad, sca, jsd, bhatt, ssim, xcorr, gd1, gd2 are fully vectorised over the pixel dimension and are fast even for large images.
Methods mtf and cem compute a full nbands × nbands covariance matrix; fast once built (Tikhonov regularisation prevents singularity).
Method dtw uses a chunked Sakoe-Chiba rolling-window implementation (O(n·W) per pixel) with shift_window= controlling the maximum alignment warp. For large images use a small shift_window (default 3).
Methods cr_sam and cr_ed perform a per-pixel convex-hull computation (Graham scan) and are approximately 10× slower than purely linear methods. For a 1000 × 1000 image with 200 bands, expect several minutes.
Method consensus runs all 17 base methods internally. On the first run this is slow; subsequent runs can reuse cached maps when output_prefix= names already-computed rasters.
When multiple methods are listed in method= and output_prefix= is set, each method's similarity map is written as prefix_method. The primary output= map contains the consensus or ensemble result if either is in the method list, otherwise the first listed method.
Method-specific similarity thresholds vary. As a rough guide for sam: 0.97 (≈5°) is a tight target match, 0.90 (≈26°) is loose. For probabilistic methods (sid, jsd, bhatt), values above 0.8 generally indicate strong similarity. For consensus probability, > 0.7 is a conservative hotspot threshold; > 0.5 is a candidate. Use -p point mode on known target and background pixels to calibrate thresholds for your data.
i.hyper.cannabis input=scene_atcorr output=kaolinite_sam \ reference_file=kaolinite_usgs.csv method=sam
i.hyper.cannabis input=scene_atcorr output=hotspot \ reference_file=target.csv \ method=consensus fusion_mode=group_product \ output_prefix=tgt # Produces: # tgt_consensus — hotspot probability # tgt_consensus_agreement/entropy/conflict/spread — diagnostics # tgt_cal_sam, tgt_cal_sid, ... — 16 calibrated probability maps # tgt_sam, tgt_sid, ... — 17 raw similarity maps
i.hyper.cannabis input=scene_atcorr output=_ \ reference="450:0.04,670:0.05,800:0.42,2200:0.18" \ method=sam,sid,bhatt,dtw,mtf,consensus \ coordinates="452300,4325100" -p -v
i.hyper.cannabis input=scene_atcorr output=best \ reference_file=chlorophyll_a.json \ method=sam,cr_sam,gd1,jsd,bhatt,ensemble \ output_prefix=chl normalize=minmax resample=pchip -c
i.hyper.cannabis input=scene_atcorr output=kaolinite_sub \ reference_file=kaolinite_usgs.csv \ method=cem,mtf,ensemble output_prefix=kaolinite
i.hyper.cannabis input=scene_atcorr output=hotspot_strict \ reference_file=chlorophyll_a.csv \ method=consensus fusion_mode=stouffer \ agreement_threshold=0.90 \ output_prefix=chl_strict
i.hyper.cannabis input=scene_atcorr output=_ \ reference_file=target.csv method=sam -i # Console output (example): # src [400-2500 nm, n=200] -> dst [350-2500 nm, n=242] # overlap [400-2500 nm] # edge-fill risk: 42 dst bands below src range (350-399 nm) # unobservable: 0 src features outside dst range
i.hyper.cannabis input=scene_atcorr output=min_match \ reference_file=kaolinite_usgs.csv method=sam,cr_sam,gd2 \ min_wavelength=1000 max_wavelength=2500 output_prefix=min
Yann Chemin, GRASS Development Team.
Part of the i.hyper module family for VNIR-SWIR hyperspectral data
processing in GRASS GIS.