Lunar Hyperspectral Mapping

An end-to-end reference workflow for lunar surface mineral/regolith classification from hyperspectral imagery. It compresses high-dimensional spectra with an autoencoder, trains a mineral classifier on the learned latent space, evaluates with spatially separated splits, and exports a georeferenced-ready classification map.

The repository runs on a synthetic 261-band cube shaped to resemble Moon Mineralogy Mapper (M³) spectral data. This keeps the project public and reproducible without redistributing large NASA data products. M³ flew on ISRO's Chandrayaan-1 and measured reflected energy across 430–3000 nm for lunar mineralogical mapping. ISRO mission science · NASA PDS M³ collection

Workflow

hyperspectral cube → mask + spectral normalization → spatial split → autoencoder
                                                              ↓
                         classified mineral/regolith map ← latent classifier ← latent vectors
                                                              ↓
                                               metrics + confusion matrix + model card

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

lunar-map generate-demo --output data/demo_cube.npz
lunar-map train --input data/demo_cube.npz --artifact-dir artifacts
lunar-map predict --input data/demo_cube.npz --artifact-dir artifacts --output data/classification.npz
lunar-map export-features --input data/demo_cube.npz --artifact-dir artifacts --output data/features.npz

predict exports the class map, confidence map, and valid-pixel mask. export-features saves coordinates, autoencoder latent vectors, engineered spectral features, and labels for downstream experimentation. Use lunar-map inspect to review the cube and label balance before training.

Methodology

• Input contract: cube (rows, columns, bands), wavelengths, validity mask, and optional labelled pixels.
• Spectral cleaning: invalid-pixel rejection, bounded within-spectrum interpolation for small gaps, isolated-spike suppression, and a persisted cleaning report.
• Feature engineering: reference reflectance, band ratios, 1/2 µm absorption-depth proxies, and visible/NIR slopes are concatenated with learned embeddings for classification.
• Representation learning: an MLPRegressor autoencoder reconstructs spectra through a configurable bottleneck; its encoder weights provide the latent vector.
• Classification: a calibrated logistic-regression model predicts mineral/regolith classes from learned plus interpretable spectral features.
• Evaluation: block-based spatial split prevents adjacent pixels from leaking between train and test; reports balanced accuracy, macro-F1, confusion matrix, and reconstruction MSE.

The demo labels are simulated classes (highland_anorthosite, mare_basalt, pyroxene_rich, and mature_regolith), and are not scientific labels. Do not report the demo score as a lunar-science result.

Each training run writes model.joblib, metrics.json, and feature_contract.json. The feature contract records expected wavelengths, band count, latent width, and engineered feature names so scoring inputs cannot silently drift.

It also writes MODEL_CARD.md, capturing the data-cleaning outcome, spatial split, evaluation values, and limits of the particular run.

Real M³ data

The PDS collection includes calibrated reflectance products. USGS also provides a small M³ GeoTIFF cube for Montes Apenninus that is useful for experimentation. Download source data separately, record the PDS product IDs and preprocessing choices, then convert the selected raster to the NPZ contract with lunar_mapping.io.save_cube. USGS sample data

For a GeoTIFF product, put the exact band wavelengths and product provenance in a manifest based on configs/source_manifest.example.json, then run:

pip install -e '.[raster]'
lunar-map ingest-geotiff --input source.tif --manifest source_manifest.json --output data/source_cube.npz

For real labels, use published mineral maps or carefully reviewed regions of interest. Validate using geographically disjoint scenes/tiles and report classes, ground-truth provenance, spectral calibration, and uncertainty.

Production notes

This project is an analysis pipeline, not a scientific conclusion. A production or research deployment should use versioned PDS product manifests, raster metadata/coordinate reference systems, a data catalog, experiment tracking, expert-reviewed labels, and independent regional validation.

License

MIT