hyperspec-py 0.6.0

Fast hyperspectral data processing for remote sensing and ML pipelines

hyperspec

Fast hyperspectral data processing for remote sensing and ML pipelines. Rust core with Python bindings.

Built by Hyperstate — foundation models for Earth intelligence.

Why hyperspec?

Hyperspectral imagery produces hundreds of bands per pixel, orders of magnitude more than RGB or multispectral. Most existing tools are slow, have heavy system dependencies, and were not designed for modern ML training pipelines.

hyperspec provides:

• Fast Rust implementations of standard hyperspectral algorithms
• A SpectralCube abstraction that keeps data, wavelengths, and metadata together
• Zarr V3 storage with chunking optimized for ML dataloaders
• Python bindings with zero-copy NumPy interop

Install

Python:

pip install hyperspec-py
# or
uv add hyperspec-py

Rust:

cargo add hyperspec

or

[dependencies]
hyperspec = "0.6"

Quickstart

import numpy as np
from hyperspec import (
    SpectralCube, read_envi, write_zarr, read_zarr_window, zarr_cube_shape,
    sam, continuum_removal, pca, mnf_denoise,
)

# --- I/O ---

# Read ENVI format (AVIRIS-NG, etc.)
cube = read_envi("scene.hdr")

# Process
cr_cube = continuum_removal(cube)
denoised = mnf_denoise(cube, n_components=20)

# Write to Zarr with ML-friendly chunks
write_zarr(cube, "chips.zarr", chunk_shape=(cube.bands(), 256, 256))

# Read a single training tile without loading the full cube
tile = read_zarr_window(
    "chips.zarr",
    bands=(0, cube.bands()),
    rows=(0, 256),
    cols=(0, 256),
)

# Query shape without loading data
bands, lines, samples = zarr_cube_shape("chips.zarr")

# --- Spectral analysis ---

# Compare every pixel to a reference spectrum
reference = cube.spectrum(50, 50)
angles = sam(cube, reference)

# Dimensionality reduction
pca_result = pca(cube, n_components=10)

SpectralCube

Category	Methods
Dimensions	bands, height, width, shape
Data access	data(), wavelengths(), fwhm(), nodata
Pixel access	spectrum(row, col)
Band access	band(index), band_at(nm), band_nearest(nm)
Wavelength lookup	wavelength(index), wavelength_index(nm), nearest_band_index(nm)
Statistics	mean_spectrum()
Subsetting	sel_bands([i, j]), sel_wavelengths(min, max)

I/O

Read

Format	Function	Notes
ENVI	read_envi(path)	BSQ, BIL, BIP; memory-mapped; all numeric types
Zarr V3	read_zarr(path)	Auto-discovers reflectance/wavelengths/fwhm
Zarr V3	read_zarr_with_options(path, ...)	Explicit dataset paths, scale/offset
Zarr V3	read_zarr_window(path, bands, rows, cols)	Windowed reads for ML dataloaders

Write

Format	Function	Notes
ENVI	write_envi(cube, path)	Configurable dtype and interleave
Zarr V3	write_zarr(cube, path)	Gzip compression, ML-friendly chunk_shape

Utilities

Function	Description
zarr_cube_shape(path)	Query (bands, lines, samples) without loading data

Algorithms

Spectral similarity

Operation	Function
Spectral Angle Mapper	sam(cube, reference)

Spectral preprocessing

Operation	Function
Continuum removal	continuum_removal(cube)

Spectral indices

Operation	Function
Normalized difference	normalized_difference(cube, a, b)
Band ratio	band_ratio(cube, a, b)
NDVI	ndvi(cube, nir, red)

Dimensionality reduction

Operation	Function
PCA	pca(cube, n_components)
MNF	mnf(cube, n_components)
MNF denoise	mnf_denoise(cube, n_components)

Spectral utilities

Operation	Function
Resample	resample(cube, target_wl, method)

Architecture

crates/hyperspec/           # Pure Rust library → crates.io
└── src/
    ├── cube.rs             # SpectralCube type
    ├── error.rs            # HyperspecError
    ├── io/
    │   ├── envi.rs         # ENVI read/write (BSQ, BIL, BIP)
    │   └── zarr.rs         # Zarr V3 read/write/window
    └── algorithms/
        ├── sam.rs
        ├── continuum.rs
        ├── indices.rs
        ├── pca.rs
        ├── mnf.rs
        └── resample.rs

pyo3-hyperspec/             # PyO3 bindings → PyPI: hyperspec-py
├── src/lib.rs
└── python/hyperspec/
    └── __init__.py

• Rust 2024 edition, using ndarray, rayon, zarrs, thiserror
• Minimal system dependencies — no LAPACK or GDAL
• Python 3.12+, NumPy bindings via PyO3

Roadmap

• Cloud-native Zarr stores (Azure, GCS, S3)
• More algorithms and utilities

Development

uv venv && source .venv/bin/activate
uv pip install maturin pytest
cargo test
maturin develop
pytest

License

Apache-2.0