DESCRIPTION

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.

Reference spectrum formats

Inline (reference=)

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.

CSV file (reference_file=)

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

JSON file (reference_file=)

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.

Wavelength units

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

Similarity methods

KeyNameCategoryDescription
samSpectral Angle MapperGeometric Angle θ between reference vector and pixel vector in n-dimensional reflectance space. Scale-invariant (insensitive to illumination magnitude). sim = 1 − 2θ/π.
sidSpectral Information DivergenceInformation 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_samSID × 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.
edEuclidean Distance (L2)Distance Root-mean-square per-band difference. sim = 1/(1 + ‖r−p‖₂/√n). Use with normalize=vector to remove illumination effects.
sadSpectral Absolute Difference (L1)Distance Mean absolute per-band difference; more robust to outlier bands than L2. sim = 1/(1 + mean|ri−pi|).
scaSpectral 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_samContinuum-Removed SAMMorphological / 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_edContinuum-Removed Euclidean DistanceMorphological / Distance Same continuum removal as cr_sam, followed by L2 distance. Useful when absolute band-depth differences are meaningful in addition to angular deviation.
gd11st-Derivative Shape MatchingSignal 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.
gd22nd-Derivative Shape MatchingSignal analysis Second finite difference, then SAM. Responds only to local curvature — absorption-band centres and inflection points. Requires well-calibrated data with low noise.
xcorrNormalized Cross-CorrelationSignal 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.
dtwDynamic Time WarpingSignal 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).
ssimSpectral Structural Similarity IndexSignal 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.
jsdJensen-Shannon DivergenceInformation 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.
bhattBhattacharyya CoefficientStatistical BC = Σ√(piqi) ∈ [0, 1]. Directly a similarity; no further transform needed. Robust to band noise. Recommended with -z.
mtfMatched Tuned FilterSubpixel 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].
cemConstrained Energy MinimizationSubpixel 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].
ensembleRank-based Ensemble FusionMeta-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.
consensusCalibrated Probability FusionMeta-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.

Consensus analysis (method=consensus)

When consensus is requested the module executes a four-step pipeline:

  1. Compute all base methods. All 17 methods (excluding ensemble/consensus) are run against the cube. Already-computed maps identified via output_prefix= are reused.
  2. Empirical CDF calibration. Each score map is rank-transformed to a uniform probability in (0, 1]:
    p_m(i) = rank(score_m(i)) / N_pixels
    This 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}.
  3. Diversity weighting. The full k × k Pearson correlation matrix is built across calibrated maps. Each method receives weight:
    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.
  4. Fusion. Six modes via fusion_mode=:
    ModeFormulaCharacteristics
    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

Consensus output maps

When output_prefix= is set, the following maps are written in addition to the primary output= hotspot probability map:

MapContent
{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

WavelengthLUT

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.

Parameters

ParameterDefaultDescription
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)

Flags

FlagEffect
-nOnly use bands marked valid=1 in band metadata
-iInfo 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

Preprocessing flags

FlagEffectRecommended 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

Normalization options (normalize=)

OptionTransform
noneRaw reflectance (default)
areaDivide by spectral sum; total power = 1
maxDivide by maximum band value
minmaxMap range to [0, 1]
vectorDivide by L2 norm; unit vector in spectral space (equivalent to SAM denominator)

Point mode (-p)

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.

NOTES

Input requirements

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.

Output map types

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).

Performance

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.

Multi-method and ensemble output

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.

Threshold selection

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.

EXAMPLES

Find pixels matching a kaolinite spectrum (SAM)

i.hyper.cannabis input=scene_atcorr output=kaolinite_sam \
  reference_file=kaolinite_usgs.csv method=sam

Full consensus analysis with all methods and diagnostic maps

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

Point inspection: all methods at one location

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

Six methods + ensemble, per-method maps, PCHIP resampling

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

Subpixel mineral detection with CEM and MTF

i.hyper.cannabis input=scene_atcorr output=kaolinite_sub \
  reference_file=kaolinite_usgs.csv \
  method=cem,mtf,ensemble output_prefix=kaolinite

Consensus with Stouffer fusion and strict agreement threshold

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

Check band coverage and LUT diagnostics before processing

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

Restrict matching to SWIR for mineral identification

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

REFERENCES

SEE ALSO

i.hyper.import, i.hyper.atcorr, i.hyper.continuum, i.hyper.spectroscopy, i.hyper.geology, r.mapcalc, r.colors, r.univar, r3.info

AUTHORS

Yann Chemin, GRASS Development Team.
Part of the i.hyper module family for VNIR-SWIR hyperspectral data processing in GRASS GIS.