Metadata-Version: 2.4
Name: hyperspec-py
Version: 0.5.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: ruff>=0.8 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Fast processing library for hyperspectral imagery, written in Rust
Keywords: hyperspectral,remote-sensing,earth-observation,satellite-imagery,geospatial
Author-email: Brian Kim <brian@hyperstate.co>
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://hyperstate.co
Project-URL: Repository, https://github.com/hyperstateco/hyperspec

# hyperspec

[![Crates.io](https://img.shields.io/crates/v/hyperspec)](https://crates.io/crates/hyperspec)
[![PyPI](https://img.shields.io/pypi/v/hyperspec-py)](https://pypi.org/project/hyperspec-py/)
[![License](https://img.shields.io/crates/l/hyperspec)](LICENSE)

Fast processing library for hyperspectral imagery. Rust core, Python bindings.

Built by [Hyperstate](https://hyperstate.co) — foundation models for Earth intelligence.

## Install

Python:
```bash
pip install hyperspec-py
# or
uv add hyperspec-py
```

Rust:
```bash
cargo add hyperspec
```
or
```toml
[dependencies]
hyperspec = "0.5"
```

## Quickstart

```python
import numpy as np
from hyperspec import SpectralCube, sam, continuum_removal, pca, mnf_denoise

# Create a cube (bands, height, width) with wavelengths in nanometers
data = np.random.rand(200, 100, 100)
wavelengths = np.linspace(400, 2500, 200)

cube = SpectralCube(data, wavelengths)

# --- Spectral analysis ---

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

# Isolate absorption features
cr_cube = continuum_removal(cube)

# Denoise using Minimum Noise Fraction
denoised_cube = mnf_denoise(cube, n_components=20)

# --- Dimensionality reduction ---

# Reduce spectral dimensionality
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)` |

## 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
    └── 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`, `thiserror`
- **Zero system dependencies** — no LAPACK, GDAL, or numba
- **Python 3.12+**, NumPy bindings via PyO3

## Development

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

## License

Apache-2.0

