Skip to content

❓ FAQ

Q: What is TanagerSpec?

A: TanagerSpec (tanagerspec) is a Python package for reading and analysing Planet Tanager-1 hyperspectral HDF5-EOS products. Scenes are held as NumPy arrays with scene.plot, scene.analysis, and scene.convert_to namespaces; use scene.convert_to.xarray() when you need labeled xarray datasets.

Q: How is TanagerSpec different from rasterio, the spectral (SPy) library, or the EnMAP-Box?

A: Those tools each cover one slice of the workflow; TanagerSpec covers the whole slice for Tanager specifically. rasterio reads/writes geospatial rasters but knows nothing about hyperspectral semantics (wavelengths, spectral indices, ML). The spectral (SPy) library handles ENVI cubes and some classification but has no native Tanager HDF5-EOS reader, no curated index catalog, and no GIS-ready export. The EnMAP-Box is a powerful QGIS plugin, but it is GUI-driven and EnMAP-oriented rather than a scriptable Tanager-native Python API. TanagerSpec reads Tanager HDF5-EOS directly (auto-detecting product type), ships 235 published spectral indices plus a custom-index lab, includes dimensionality reduction / clustering / supervised classification, and exports to GeoTIFF, ENVI-BIL, and xarray/NetCDF — all from one NumPy-centered object. It complements rather than replaces these tools: results export cleanly into QGIS, ArcGIS, and ENVI.

Q: How do I install TanagerSpec?

A: See the Installation page for instructions.

Q: What Python versions are supported?

A: Python 3.10 and newer.

Q: How do I plot data?

A: Use scene.plot methods such as scene.plot.rgb() and scene.plot.pixel_spectra(). See the Quick Walkthrough for examples.

Q: How do I contribute?

A: See the Developer Guide for information on setting up a development environment and contributing.

Q: Where can I get help?

A: Please open an issue on the repository.

Q: Why is TanagerSpec a Python workflow rather than a QGIS plugin or desktop GUI?

A: Hyperspectral analysis is inherently iterative and customizable — you chain preprocessing, index selection, machine learning, and export steps in ways that differ for every scene and application. Python workflows are scriptable, reproducible, and composable with the full scientific ecosystem (NumPy, scikit-learn, xarray, Matplotlib). A GUI constrains you to fixed menus and linear sequences; Python lets you remix and automate. Jupyter notebooks also serve as living lab notebooks that document the why behind every analytical choice — something no GUI can do.

Q: Why is TanagerSpec built on NumPy arrays instead of a higher-level abstraction?

A: NumPy is the lingua franca of scientific Python. Every tool you might chain — scikit-learn, SciPy, rasterio, xarray, custom algorithms — speaks NumPy natively. The hyperspectral cube is stored as (bands, rows, cols) so spectral operations vectorize efficiently across the spectral axis. All derived results (index maps, PCA components, cluster labels, classification maps) are plain 2D/3D NumPy arrays, which means the same downstream tools work on all of them. If you need labeled dimensions and coordinates, scene.convert_to.xarray() gives you a fully annotated xarray.Dataset in one call.

Q: Can I still use my results in QGIS, ArcGIS, or ENVI?

A: Yes — TanagerSpec is designed to bridge to GIS workflows, not replace them. scene.convert_to.geotiff() writes a georeferenced multi-band GeoTIFF that opens directly in QGIS, ArcGIS, and ENVI. scene.convert_to.envi_bil() writes native ENVI BIL format with wavelengths embedded in the header. Almost every analysis method also accepts a save_geotiff= argument, so clustering, classification, and index maps can be exported as GIS-ready layers in a single line.

Q: What Tanager-1 product types does TanagerSpec support?

A: TanagerSpec supports four product types: ortho_sr (orthorectified surface reflectance — the most common for mapping), basic_sr (sensor-geometry surface reflectance — for maximum spectral fidelity), ortho_rad (orthorectified radiance), and basic_rad (sensor-geometry radiance). Product type is detected automatically from the HDF5 metadata — the same API works across all types.

Q: Can I analyze radiance products, or do I need surface reflectance?

A: You can load and visualize radiance products, but all analytical features — spectral index calculation, supervised classification, and unsupervised clustering — are designed for surface reflectance (SR). Radiance includes atmospheric interference that makes vegetation indices, burn indices, and similar metrics physically meaningless. The guiding principle is: use radiance for looking; use surface reflectance for deciding.

Q: Does TanagerSpec handle cloud masks, nodata pixels, and dropped bands?

A: Yes. scene.preprocess() applies the quality masks embedded in the HDF5 file (nodata, cloud, cirrus), setting invalid pixels to NaN. scene.drop_bands() marks noisy wavelength ranges (e.g., water-absorption intervals) as invalid without changing the cube shape. NaNs propagate correctly throughout all subsequent steps — indices, visualization, and ML all skip or handle missing values gracefully.

Q: What preprocessing steps should I apply before analysis?

A: The recommended pipeline is:

  1. scene.preprocess(masking=True, clipping=True) — apply quality masks and clip SR to the physical range [0, 1].
  2. scene.drop_bands([(start_nm, end_nm), …]) — exclude noisy or water-absorption bands.
  3. scene.denoise(n_components=3) — optional PCA reconstruction to suppress sensor noise while retaining >98% of variance.

All three operations work in-place and are safe to re-run. Call scene.info() at any point to see current band status and preprocessing state.

Q: How many spectral indices are included, and how do I find the right one?

A: TanagerSpec ships with 235 published spectral indices covering seven application domains: vegetation (153), water (31), soil (14), urban (11), burn (10), snow (9), and clouds (7). Use IndexCatalog to explore:

from tanagerspec import IndexCatalog
catalog = IndexCatalog()
catalog.print_domains()                         # list all domains
catalog.print_indices_by_domain("vegetation")   # browse a domain
catalog.search(query="chlorophyll", limit=5)    # keyword search
catalog.print_index("NDVI")                     # formula + citation

Then compute on your scene with scene.analysis.calculate_index("NDVI").

Q: Can I build a custom spectral index that isn't in the catalog?

A: Yes — scene.analysis.index_creator_lab() is an interactive workbench for designing two-band indices. You provide target pixel coordinates labeled by class, choose two bands, and supply any formula using those band values. The lab evaluates the formula immediately and shows separability metrics. To discover promising band pairs first, use scene.analysis.compare_band_range() to rank all pairs in a spectral region by contrast metrics.

Q: Can I export all TanagerSpec outputs to files?

A: Yes. Three export pathways are available via scene.convert_to:

  • GeoTIFF: scene.convert_to.geotiff(output_path=…) — multi-band GeoTIFF with georeferencing for ortho products. Pass include_extras=True to also export all companion 2D datasets (masks, illumination rasters) as separate single-band GeoTIFFs.
  • ENVI BIL: scene.convert_to.envi_bil(output_path=…) — ENVI Band-Interleaved-by-Line format with wavelengths in the header. include_extras=True works here too.
  • xarray / NetCDF: scene.convert_to.xarray() returns an in-memory xarray.Dataset; call .to_netcdf("file.nc") on it for long-term archival or Python/R interoperability.

Additionally, most analysis methods accept a save_geotiff= path argument to export results (index maps, cluster labels, classification maps) directly as single-band GeoTIFFs.

Q: What machine learning tools are built into TanagerSpec?

A: Three ML capabilities live under scene.analysis:

  • Dimensionality reduction (dim_reduction(method="PCA")): PCA, ICA, or MNF — reduces hundreds of bands to a compact representation for visualization or as input to classification.
  • Unsupervised clustering (clustering(n_clusters=5, clustering_method="KMEANS")): K-Means or Gaussian Mixture Models, with optional dimensionality-reduction preprocessing. Produces a 2D cluster-label map and optionally exports it as a GeoTIFF.
  • Supervised classification (classify_scene(method="RF")): Spectral Angle Mapper (SAM), Random Forest (RF), and Neural Network (NN). All accept a confidence threshold to mark ambiguous pixels as unclassified and export a GeoTIFF classification map.

Supervised methods require a spectral library built first with scene.build_spectral_library(targets={…}).

Q: Is TanagerSpec memory-efficient for large hyperspectral scenes?

A: Yes. Preprocessing (preprocess, drop_bands, denoise) all mutate the cube in-place rather than making copies, keeping peak memory close to the footprint of the original HDF5 data. The spectral axis is always axis 0 (bands, rows, cols), which makes band-wise vectorized operations efficient with NumPy's memory layout.