Metadata-Version: 2.4
Name: speclib
Version: 1.0.0
Summary: Federated spectral signature library with Kentucky-focused collections
Project-URL: Homepage, https://github.com/chrislyonsKY/speclib
Project-URL: Documentation, https://chrislyonsKY.github.io/speclib/
Project-URL: Repository, https://github.com/chrislyonsKY/speclib
Project-URL: Issues, https://github.com/chrislyonsKY/speclib/issues
Author-email: Chris Lyons <chris.lyons@ky.gov>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: USGS,hyperspectral,minerals,reflectance,remote-sensing,spectral-library,spectroscopy,vegetation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: h5py>=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pyarrow>=15.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.12
Provides-Extra: all
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: netcdf4>=1.6; extra == 'all'
Requires-Dist: pre-commit>=3.6; extra == 'all'
Requires-Dist: pytest-cov>=4.1; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.3; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
Requires-Dist: zensical; extra == 'all'
Provides-Extra: dev
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: docs
Requires-Dist: zensical; extra == 'docs'
Provides-Extra: emit
Requires-Dist: netcdf4>=1.6; extra == 'emit'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: jinja2>=3.1; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'server'
Description-Content-Type: text/markdown

# speclib

![License](https://img.shields.io/badge/license-GPL--3.0-blue)
![Python](https://img.shields.io/badge/python-3.11%2B-informational)
![Status](https://img.shields.io/badge/status-1.0.0-green)
[![CI](https://github.com/chrislyonsKY/speclib/actions/workflows/ci.yml/badge.svg)](https://github.com/chrislyonsKY/speclib/actions/workflows/ci.yml)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://zenodo.org/doi/10.5281/zenodo.XXXXXXX)
[![codecov](https://codecov.io/gh/chrislyonsKY/speclib/graph/badge.svg)](https://codecov.io/gh/chrislyonsKY/speclib)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/f45422a205bb46ff9955f01622d2d6ab)](https://app.codacy.com/gh/chrislyonsKY/speclib/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
![NumPy](https://img.shields.io/badge/numpy-%E2%89%A51.26-013243?logo=numpy)
![HDF5](https://img.shields.io/badge/HDF5-h5py%20%E2%89%A53.10-blue)
![Parquet](https://img.shields.io/badge/parquet-pyarrow%20%E2%89%A515.0-blue)
![D3.js](https://img.shields.io/badge/D3.js-v7-f9a03c?logo=d3.js)

> Federated spectral signature library with Kentucky-focused collections

## Overview

speclib aggregates reflectance spectra from major public spectral libraries into a unified, searchable platform. It provides a Python package for researchers, a static web viewer for discovery, and an optional self-hosted API for power users.

The library federates spectra from **USGS Spectral Library v7**, **ECOSTRESS**, **ASTER/JPL**, and **EMIT L2B**, with a dedicated Kentucky chapter seeded with invasive species spectral data from Lyons et al. (2024).

## Features

- **Federated ingestion** from USGS splib07, ECOSTRESS, ASTER/JPL, and EMIT L2B
- **Dual storage** — HDF5 archival backend + Parquet query layer
- **Export to** .esl (Esri), .sli (ENVI), SPECPR binary, ASCII, JSON
- **Spectral resampling** to Landsat, Sentinel-2, AVIRIS, EMIT, and custom sensors
- **Static web viewer** on GitHub Pages with D3.js interactive spectral plots
- **Optional FastAPI server** with REST API and Jinja templates
- **Kentucky chapter** with invasive species, mineral, and reclamation spectra

## Getting Started

### Prerequisites

- Python 3.11+
- pip

### Installation

```bash
pip install speclib
```

With optional dependencies:

```bash
pip install speclib[server]    # FastAPI server
pip install speclib[emit]      # EMIT L2B support (netCDF4)
pip install speclib[all]       # Everything including dev tools
```

### Quick Start

```python
from speclib import SpectralLibrary

# Load the library from an HDF5 archive
lib = SpectralLibrary.from_hdf5("speclib_archive.h5")

# Search for quartz spectra
results = lib.search("quartz", category="MINERAL")

# Plot a spectrum
results[0].plot()

# Export to Esri Spectral Library format
results[0].export("quartz.esl", format="esl")

# Resample to Landsat 8 OLI bands
resampled = results[0].resample("L8_OLI")
```

### CLI

```bash
speclib ingest usgs --config data/upstream/usgs_splib07.yaml
speclib search "honeysuckle" --category KY_INVASIVE
speclib export usgs_mineral_quartz_a1b2c3d4 --format sli --output quartz.sli
speclib build
speclib serve
```

## Web Viewer

Browse the spectral library at: **https://chrislyonsKY.github.io/speclib/**

## Data Sources

| Source | License | Description |
|--------|---------|-------------|
| USGS Spectral Library v7 | US Public Domain | Minerals, rocks, soils, vegetation, manmade materials |
| ECOSTRESS Spectral Library | CC0 / Public Domain | Minerals, vegetation, soils, water, manmade |
| ASTER/JPL Spectral Library | NASA Open Data | Minerals, rocks, soils |
| EMIT L2B | NASA Open Data | Spaceborne mineral identification spectra |
| Kentucky Field Data | CC-BY-4.0 | Invasive species spectra (Lyons et al. 2024) |

## Citation

```bibtex
@software{lyons2026speclib,
  author = {Lyons, Chris},
  title = {speclib: Federated Spectral Signature Library},
  year = {2026},
  url = {https://github.com/chrislyonsKY/speclib},
  doi = {10.5281/zenodo.XXXXXXX},
  license = {GPL-3.0}
}
```

> **Note:** Replace `XXXXXXX` with the actual Zenodo DOI after the first release is archived.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

## License

GPL-3.0-only — see [LICENSE](LICENSE) for details.
