TanagerSpec is a Python package for hyperspectral analysis of Tanager satellite 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.
Install from PyPI:
pip install tanagerspecOr install the latest version directly from GitHub:
pip install git+https://github.com/planetlabs/tanagerspec.gitRequires Python 3.10 or newer.
Two ways to get going immediately:
| Quick Walkthrough | Copy-paste reference for every API call, one concise snippet per capability. |
| 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 included further down this page.
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.
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, |
TanagerSpec ships a curated bank of published spectral indices, adopted from the 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:
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 citationTip: You can use IndexCatalog wherever you need it, whether you're just exploring the catalog, scripting your own workflows.
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.
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 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 | 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 | Learn how to initialize TanagerSpec for the first time, download a scene, and work with the basic setup steps. |
| 3 | 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 | 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 | Explore different ways to visualize hyperspectral data, from RGB composites to extracting and comparing spectral signatures. |
| 6 | 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 | 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 | 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. 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, who also developed this package.
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 NaNs, nodata pixels, masked clouds, dropped bands, and invalid reflectance values, so missing data is propagated or skipped rather than silently corrupting results.
TanagerSpec was independently designed and developed by Abdelrahman Saleh, an interdisciplinary PhD researcher at the University of Manitoba. The package was developed during his research internship at Planet Labs PBC, through the Mitacs Accelerate research program, as part of a collaboration between the University of Manitoba 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.
For more about Planet and the Tanager program, see the Planet Documentation and the Planet website.
Found a bug, hit an unexpected result, or have an idea for a missing feature or index? Open an issue on GitHub Issues — bug reports, feature requests, and suggestions for missing indices or workflows are all welcome.
TanagerSpec is released under the Apache License 2.0.