Metadata-Version: 2.4
Name: spectral-library
Version: 0.2.0
Summary: Spectral library build, preparation, and retrieval-based mapping toolkit.
Author: Marc Yin
Maintainer: Marc Yin
License-Expression: MIT
Project-URL: Homepage, https://github.com/MarcYin/spectral_library
Project-URL: Repository, https://github.com/MarcYin/spectral_library
Project-URL: Documentation, https://marcyin.github.io/spectral_library/
Project-URL: Issues, https://github.com/MarcYin/spectral_library/issues
Project-URL: Changelog, https://github.com/MarcYin/spectral_library/blob/main/CHANGELOG.md
Keywords: hyperspectral,multispectral,reflectance,remote-sensing,spectral-library,spectral-mapping
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=1.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.14; extra == "docs"
Provides-Extra: knn
Requires-Dist: scipy>=1.11.0; extra == "knn"
Provides-Extra: knn-faiss
Requires-Dist: faiss-cpu>=1.8.0; extra == "knn-faiss"
Provides-Extra: knn-pynndescent
Requires-Dist: pynndescent>=0.5.13; extra == "knn-pynndescent"
Provides-Extra: knn-scann
Requires-Dist: scann>=1.4.2; (platform_system == "Linux" and platform_machine == "x86_64") and extra == "knn-scann"
Provides-Extra: knn-all
Requires-Dist: scipy>=1.11.0; extra == "knn-all"
Requires-Dist: faiss-cpu>=1.8.0; extra == "knn-all"
Requires-Dist: pynndescent>=0.5.13; extra == "knn-all"
Requires-Dist: scann>=1.4.2; (platform_system == "Linux" and platform_machine == "x86_64") and extra == "knn-all"
Provides-Extra: internal-build
Requires-Dist: matplotlib>=3.8.0; extra == "internal-build"
Requires-Dist: netCDF4>=1.7.0; extra == "internal-build"
Requires-Dist: openpyxl>=3.1.0; extra == "internal-build"
Requires-Dist: rdata>=0.11.0; extra == "internal-build"
Provides-Extra: accel
Requires-Dist: whitsmooth-rust>=0.1.3; extra == "accel"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: coverage>=7.6.0; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Requires-Dist: matplotlib>=3.8.0; extra == "dev"
Requires-Dist: netCDF4>=1.7.0; extra == "dev"
Requires-Dist: openpyxl>=3.1.0; extra == "dev"
Requires-Dist: pymdown-extensions>=10.14; extra == "dev"
Requires-Dist: rdata>=0.11.0; extra == "dev"
Requires-Dist: scipy>=1.11.0; extra == "dev"
Requires-Dist: whitsmooth-rust>=0.1.3; extra == "dev"
Dynamic: license-file

# Spectral Library

`spectral-library` is a Python package and CLI for:

1. preparing row-aligned runtime artifacts from a SIAC spectral-library export,
2. mapping source-sensor reflectance to target sensors,
3. reconstructing VNIR, SWIR, or full hyperspectral outputs with retrieval-based
   spectral mapping.

The public names are:

- distribution: `spectral-library`
- import package: `spectral_library`
- CLI: `spectral-library`
- license: `MIT` for repository software and repository-authored docs

## Start Here

- published docs site:
  [https://marcyin.github.io/spectral_library/](https://marcyin.github.io/spectral_library/)
- overview:
  [`docs/index.md`](docs/index.md)
- getting started:
  [`docs/mapping_quickstart.md`](docs/mapping_quickstart.md)
- mathematical foundations:
  [`docs/theory.md`](docs/theory.md)
- official sensor examples:
  [`docs/official_sensor_examples.md`](docs/official_sensor_examples.md)
- public CLI reference:
  [`docs/cli_reference.md`](docs/cli_reference.md)
- public Python API reference:
  [`docs/python_api_reference.md`](docs/python_api_reference.md)
- prepared-runtime contract:
  [`docs/prepared_runtime_contract.md`](docs/prepared_runtime_contract.md)
- internal maintainer docs:
  [`docs/internal_overview.md`](docs/internal_overview.md)

## Install

Install from this repository in a Python `3.9+` environment:

```bash
python3 -m pip install .
```

Supported Python versions in CI are `3.9`, `3.10`, `3.11`, and `3.12`.

The same documentation set is published to GitHub Pages from this repository.

For the retained internal normalization and QA commands, install the optional
internal-build dependencies:

```bash
python3 -m pip install ".[internal-build]"
```

This extra is also required if you want to regenerate the bundled official
sensor example assets with `scripts/build_official_mapping_examples.py`.

For the static documentation site and GitHub Pages build path, install:

```bash
python3 -m pip install ".[docs]"
```

The published docs site is built with MkDocs from [mkdocs.yml](mkdocs.yml).

For the optional SciPy `cKDTree` shortlist backend, install:

```bash
python3 -m pip install ".[knn]"
```

Additional optional ANN backends are available with:

```bash
python3 -m pip install ".[knn-faiss]"
python3 -m pip install ".[knn-pynndescent]"
python3 -m pip install ".[knn-scann]"
```

## Minimal Example

Prepare a mapping runtime:

```bash
spectral-library prepare-mapping-library \
  --siac-root build/siac_library \
  --srf-root path/to/srfs \
  --source-sensor SENSOR_A \
  --knn-index-backend faiss \
  --output-root build/mapping_runtime
```

Validate it:

```bash
spectral-library validate-prepared-library \
  --prepared-root build/mapping_runtime
```

Map one reflectance sample:

```bash
spectral-library map-reflectance \
  --prepared-root build/mapping_runtime \
  --source-sensor SENSOR_A \
  --target-sensor SENSOR_B \
  --input path/to/query.csv \
  --output-mode target_sensor \
  --output path/to/mapped.csv
```

Map many samples from one CSV:

```bash
spectral-library map-reflectance-batch \
  --prepared-root build/mapping_runtime \
  --source-sensor SENSOR_A \
  --target-sensor SENSOR_B \
  --input path/to/query_batch.csv \
  --output-mode target_sensor \
  --output path/to/mapped_batch.csv
```

The detailed quickstart, supported CSV layouts, Python API examples, SRF JSON
schema, and prepared-runtime contract are documented in
[`docs/mapping_quickstart.md`](docs/mapping_quickstart.md).

For larger prepared runtimes, the repository also ships
[`scripts/run_full_library_benchmarks.py`](scripts/run_full_library_benchmarks.py)
plus the scheduled/manual GitHub Actions workflow
[`full-library-benchmarks.yml`](.github/workflows/full-library-benchmarks.yml).
Use `--max-test-rows` to keep held-out benchmark runs bounded on large
prepared libraries.

For reproducible cross-sensor examples built from official MODIS, Sentinel-2A,
Landsat 8, and Landsat 9 response functions, see
[`docs/official_sensor_examples.md`](docs/official_sensor_examples.md) and the
bundled example assets in
[`examples/official_mapping`](examples/official_mapping/README.md). Those
official examples expect the previously composed full SIAC library recorded in
the example manifest, rather than a vendored mini runtime.
