Metadata-Version: 2.4
Name: tanagerspec
Version: 1.0.0
Summary: Read, analyze, and export Planet Tanager hyperspectral (imaging spectroscopy) data cubes from a single Python object.
Author-email: Abdelrahman Saleh <a3.re.sa@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://planetlabs.github.io/tanagerspec/
Project-URL: Documentation, https://planetlabs.github.io/tanagerspec/
Project-URL: Repository, https://github.com/planetlabs/tanagerspec
Project-URL: Issues, https://github.com/planetlabs/tanagerspec/issues
Project-URL: Changelog, https://github.com/planetlabs/tanagerspec/blob/main/CHANGELOG.md
Keywords: hyperspectral,remote sensing,imaging spectroscopy,Planet,Tanager,spectral indices,earth observation,geospatial,surface reflectance,HDF5-EOS,GeoTIFF,NDVI,satellite imagery,spectral analysis,raster
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.2.0
Requires-Dist: numpy>=1.22.1; python_version < "3.12"
Requires-Dist: numpy>=1.26; python_version >= "3.12"
Requires-Dist: h5py>=3.10.0
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: rasterio>=1.3.0
Requires-Dist: plotly>=6.7.0
Requires-Dist: requests>=2.32.5
Requires-Dist: pandas>=2.3.3
Requires-Dist: xarray>=2024.2.0
Requires-Dist: netcdf4>=1.7.3
Requires-Dist: nbformat>=5.10.4
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: line-profiler>=4.0.3; extra == "dev"
Requires-Dist: ruff>=0.11.10; extra == "dev"
Requires-Dist: fsspec>=2024.2.0; extra == "dev"
Requires-Dist: ipykernel>=6.29.5; extra == "dev"
Provides-Extra: jupyter
Requires-Dist: jupyterlab>=4.0.3; extra == "jupyter"
Requires-Dist: jupyter-bokeh>=4.0.0; extra == "jupyter"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
Requires-Dist: pillow>=10.0; extra == "docs"
Requires-Dist: cairosvg>=2.7; extra == "docs"
Provides-Extra: all
Requires-Dist: tanagerspec[dev,docs,jupyter]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/logo_dark_mode.png" alt="TanagerSpec" width="500">
</p>
<h1 align="center"></h1>
<h2 align="center">Decoding Planet Tanager's Hyperspectral Cubes: From Spectra to Decisions.</h2>

[![PyPI version](https://img.shields.io/pypi/v/tanagerspec.svg)](https://pypi.org/project/tanagerspec/)
[![Downloads](https://static.pepy.tech/badge/tanagerspec)](https://pepy.tech/project/tanagerspec)
[![PyPI downloads](https://img.shields.io/pypi/dm/tanagerspec.svg)](https://pypi.org/project/tanagerspec/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![Stars](https://img.shields.io/github/stars/planetlabs/tanagerspec?style=social)](https://github.com/planetlabs/tanagerspec)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://planetlabs.github.io/tanagerspec/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20723630.svg)](https://doi.org/10.5281/zenodo.20723630)

**TanagerSpec** is a Python package for hyperspectral analysis of [Tanager](https://docs.planet.com/data/imagery/tanager) data. It brings nearly every essential tool for working with hyperspectral cubes into a single, intuitive, well-organized environment, so you can spend less time wrangling data and more time answering questions.

---

## Installation

Install from PyPI:

```bash
pip install tanagerspec
```

Or install the latest version directly from GitHub:

```bash
pip install git+https://github.com/planetlabs/tanagerspec.git
```

> Requires Python 3.10 or newer.

---

## Quick Start

Two ways to get going immediately:

| | |
|---|---|
| [**Quick Walkthrough**](https://planetlabs.github.io/tanagerspec/start/quick_walkthrough/) | Copy-paste reference for every API call, one concise snippet per capability. |
| [**Full Walkthrough**](https://planetlabs.github.io/tanagerspec/start/full_walkthrough/) | End-to-end interactive demo with extensive details about each API. |

>For a deeper understanding of *why* each step exists and how the tools connect into a real remote-sensing workflow, follow the **[Crash Course](#learn-the-real-potential-of-tanagerspec)** included further down this page.

---

## Why TanagerSpec

A Tanager scene is a **hyperspectral data cube**: a stack of hundreds of images, one per narrow wavelength, where every pixel carries a full **reflectance spectrum**. That richness is exactly what makes it powerful, and exactly what makes it hard to handle.

**TanagerSpec is the workbench, the tools, and the recipe together.** Load a scene once, and every capability is discoverable on a single object through a clean, consistent API.

<img src="docs/assets/TanagerSpec_tools.png" alt="TanagerSpec architecture overview" style="border-radius: 18px;"/>

### Features

**TanagerSpec brings the entire hyperspectral workflow to your fingertips—seamless, expressive, and in a single Python object:**

| 🚀 **Capability**            | ✨ **What it empowers you to do**                                                                                                      |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| 🛰️ **Load & orient**        | Download from Planet's Open Data STAC, inspect HDF5-EOS files, and access live scene metadata with ease,                              |
| 🧹 **Preprocess**            | Apply quality masking, reflectance clipping, band exclusion, and PCA denoising, efficient, in-place, and always re-runnable,           |
| 📊 **Visualize & explore**   | Create RGB composites, band galleries, histograms, interactive pixel finders, spectral signature plots, and animated band sweeps,     |
| 📚 **Spectral indices (200+)| Leverage a built-in catalog spanning vegetation, water, soil, snow, burn, urban, and clouds, compute any published index by name,      |
| 🧪 **Index Creator Lab**     | Design and test your own indices with a guided band-discovery funnel and immediate feedback, spark creativity and science,             |
| 🤖 **Machine learning**      | Perform dimensionality reduction (PCA/ICA/MNF), clustering (KMEANS/GMM), create spectral libraries, and classify (SAM/RF/NN), all in a few lines, |
| 🗺️ **Export & interoperability** | Export directly to GeoTIFF, ENVI-BIL, or xarray/NetCDF, ready for QGIS, ArcGIS, ENVI, or your Python workflow,                  |

### Bank of Indices — 235 indices, 7 domains

<img src="docs/assets/merge_awesome_indices.png" style="border-radius: 18px;">

TanagerSpec ships a curated bank of published spectral indices, adopted from the [Awesome Spectral Indices](https://github.com/awesome-spectral-indices/awesome-spectral-indices) repository. Each index includes its formula, wavelength references, and source citation. You never need to transcribe formulas or search for the right bands—simply call the index by name and TanagerSpec maps it to the closest Tanager wavelengths for you.

**Find the right index.** `IndexCatalog` is an external utility, no need to initialize a `TanagerSpec` object. Use it on its own to search, list, or explore indices before you ever load a cube:

```python
from tanagerspec import IndexCatalog

catalog = IndexCatalog()
catalog.print_domains()                        # List the 7 index domains
catalog.print_indices_by_domain("vegetation")  # List all vegetation indices
catalog.search("water")                        # Search by keyword or index name
catalog.print_index("NDVI")                    # Show formula, wavelengths, and citation
```

**Tip:** You can use `IndexCatalog` wherever you need it, whether you're just exploring the catalog, scripting your own workflows.

---
### The Index Creator Lab — design your own indices
<img src="docs/assets/create_index_tools.png" style="border-radius: 8px;"/>

The 235-index bank covers the literature, but Tanager's contiguous narrow bands let you go further and build indices tuned to *your* target. The Index Creator Lab is a **band-discovery funnel**: start wide across a spectral region, narrow to the most separating pair of wavelengths, then prototype and stress-test a formula, with immediate spatial, statistical, and spectral feedback at every step.

---
## Learn the Real Potential of TanagerSpec

Knowing the tools is only half the story; knowing *when, why, and how to connect them* is what unlocks the real power of TanagerSpec. A quick API walkthrough can show individual functions, but it cannot fully demonstrate the unique design of TanagerSpec: the way its APIs, tools, and workflows are meant to work together as a connected remote-sensing system.

The **[Crash Course](https://planetlabs.github.io/tanagerspec/course/)** included with these docs is designed to bridge that gap. Across **eight hands-on lessons**, it walks a single Tanager scene from raw HDF5-EOS input to interpreted output, teaching through a real remote-sensing question at each step rather than simply touring the API method by method.

By following the course, users learn not just what each tool does, but how the pieces fit together, how preprocessing, visualization, spectral analysis, and interpretation can be combined into a creative and flexible workflow. The goal is to help users understand the design philosophy of TanagerSpec and build the confidence to connect its tools in their own projects later.

| # | Lesson | What you'll learn |
|---|--------|-------------------|
| 1 | [Introduction](https://planetlabs.github.io/tanagerspec/course/00_ts_intro/) | Get an overview of what you will learn throughout the course, including a quick look at the complete workflow for analyzing hyperspectral data.|
| 2 | [Orientation & Initialization](https://planetlabs.github.io/tanagerspec/course/01_ts_orientation/) | Learn how to initialize TanagerSpec for the first time, download a scene, and work with the basic setup steps.|
| 3 | [Preprocessing](https://planetlabs.github.io/tanagerspec/course/02_ts_preprocessing/) | Learn how to use the provided preprocessing features before analyzing the data, including masking, clipping, and denoising with PCA reconstruction when needed.|
| 4 | [Export & Conversion](https://planetlabs.github.io/tanagerspec/course/03_ts_export_conversion/) | Learn how to extend and convert HDF5-EOS files into other formats for external workflows, such as GeoTIFF, ENVI-BIL, and NetCDF using Xarray. |
| 5 | [Visualization & Exploration](https://planetlabs.github.io/tanagerspec/course/04_ts_visualization/) | Explore different ways to visualize hyperspectral data, from RGB composites to extracting and comparing spectral signatures. |
| 6 | [Spectral Indices](https://planetlabs.github.io/tanagerspec/course/05_ts_spectral_indices/) | Query 200+ peer-reviewed indices across seven domains, compute spatial index maps, and diagnose saturation and dynamic-range differences between indices. |
| 7 | [Index Creator Lab](https://planetlabs.github.io/tanagerspec/course/06_ts_index_creator_lab/) | Learn how the Index Creator Lab and its helper tools can assist you in creating your own spectral index or revising and evaluating spectral indices from the literature.  |
| 8 | [Machine Learning](https://planetlabs.github.io/tanagerspec/course/07_ts_machine_learning/) | Apply machine learning techniques to hyperspectral data, including dimensionality reduction, clustering for unsupervised learning, and classification for supervised learning.|

> This crash course is **Module 5** of the broader *[Tanager Hyperspectral Data Analysis course](https://www.planet.com/)*. The full course explores the *why* behind hyperspectral analysis, including the physics of reflectance spectra, radiometry, and the science underlying each step of the workflow. It was designed by **[Abdelrahman Saleh](https://github.com/AbdelrahmanAmr3)**, who also developed this package.

<div align="center">
  <a href="https://github.com/planetlabs/tanager-opendata-edu" target="_blank" rel="noopener">
    <img src="docs/assets/course_logo.png" alt="Tanager: Hyperspectral Data Analysis course" width="450" style="border-radius: 24px; box-shadow: 0 6px 24px rgba(0,0,0,0.15); border: 2px solid #eee;"/>
  </a>
</div>

---
## Which Tanager assets it works with

TanagerSpec is an **analysis** package, and its analytical tools are designed for **surface reflectance (SR)**. SR is the appropriate input for indices, spectral analysis, and machine-learning workflows because atmospheric effects have already been corrected.

TanagerSpec supports both SR delivery types out of the box: **orthorectified (GRID)** products and basic sensor-geometry **(SWATH)** products. The same API works across both: load the scene, and the package adapts automatically to the product type.

**Radiance is supported for visualization and inspection**, RGB composites, band galleries, spectral plots, and quick-look workflows, but it is not intended for analysis. **Use radiance for looking; use surface reflectance for deciding.**

TanagerSpec also handles real-scene gaps gracefully, including `NaN`s, nodata pixels, masked clouds, dropped bands, and invalid reflectance values, so missing data is propagated or skipped rather than silently corrupting results.

---

## Authorship & Acknowledgements

**TanagerSpec** was independently designed and developed by **[Abdelrahman Saleh](http://linkedin.com/in/a3saleh)**, an interdisciplinary PhD researcher at the **University of Manitoba**. The package was developed during his research internship at **[Planet Labs PBC](https://www.planet.com/)**, through the **[Mitacs Accelerate research program](https://www.mitacs.ca/)**, as part of a collaboration between the **[University of Manitoba](https://umanitoba.ca/)** and **Planet Labs PBC**.

The author gratefully acknowledges the valuable technical feedback, review, and support provided by members of the **Tanager team** at **Planet Labs PBC** throughout the development of this package. Special thanks are extended to **Keely Roth**, the author’s mentor at **Planet Labs PBC**, for her guidance, thoughtful review, and constructive feedback during the project.

The author also sincerely thanks **Geert Barentsen**, **Dominic LeDuc**, and **Joe Kington** for their valuable technical input, review of the package materials, and support in developing TanagerSpec.

Finally, the author sincerely thanks **Nasem Badreldin**, the author’s PhD supervisor, for his continued support and encouragement throughout the project.

To learn more about the course author, visit the [Author page](https://planetlabs.github.io/tanagerspec/Author/).

<img src="docs/assets/collaboration_institue.png" style="border-radius: 18px;">

For more about Planet and the Tanager program, see the [Planet Documentation](https://docs.planet.com/data/imagery/tanager) and the [Planet website](https://www.planet.com/).

## Contributing

Found a bug, hit an unexpected result, or have an idea for a missing feature or index? Open an issue on [GitHub Issues](https://github.com/planetlabs/tanagerspec/issues) — bug reports, feature requests, and suggestions for missing indices or workflows are all welcome.

## License

TanagerSpec is released under the [**Apache License 2.0**](https://www.apache.org/licenses/LICENSE-2.0).
