Skip to content

Conventions

These conventions describe how TanagerSpec represents hyperspectral data in memory and how optional xarray export aligns with broader geospatial workflows.

In-memory cube (primary)

  • Axis order: (bands, rows, cols) — spectral dimension is axis 0.
  • Type: numpy.ndarray on TanagerSpec.dataset.
  • Wavelengths: nanometers on TanagerSpec.wavelengths (from CubeMetadata).
  • Valid bands: boolean mask on TanagerSpec.good_bands; updated by product metadata and by drop_bands() without changing cube shape.
  • Ortho geometry: grid_info provides CRS and affine transform when the product is orthorectified.

Processing methods (preprocess, drop_bands, denoise) mutate the scene in place. Child namespaces (plot, analysis, convert_to) always read the current parent state.

xarray export (optional)

Use scene.convert_to.xarray() when you need labeled dimensions, masks as data variables, and compatibility with the xarray ecosystem:

ds = scene.convert_to.xarray()
# ds contains the main reflectance/radiance cube, wavelengths, masks, and grid metadata when available

When documenting or building on exported datasets, prefer the following naming patterns (aligned with common hyperspectral and CF practice):

Dimension names

  • Non-ortho cubes: crosstrack, alongtrack, wavelength (or band-indexed equivalents from the converter).
  • Ortho cubes (UTM): easting, northing, wavelength.
  • Spectra: wavelength.

Variable names (snake_case, singular)

  • Bottom-of-atmosphere surface reflectance: reflectance
  • Top-of-atmosphere reflectance: toa_reflectance
  • Top-of-atmosphere radiance: radiance
  • Sensor angles: sensor_zenith, sensor_azimuth
  • Sun angles: sun_zenith, sun_azimuth

Derived products (spectral indices, PCA components, cluster labels) may use a band dimension instead of wavelength when the result is no longer per input wavelength.

Coordinates and attributes

  • fwhm, elevation where applicable
  • instrument and other metadata as attributes
  • Time: pandas.Timestamp in a time coordinate when present

Units

  • Wavelengths and FWHM: nanometers (nm)
  • Radiance: W/m²/sr/μm (consistent with Sentinel-2, Landsat, and Planet products)
  • Angles: degrees

Metadata should follow CF conventions where possible on exported xarray objects.

API surface

  • Users: TanagerSpec.from_file(), scene methods, and scene.plot / scene.analysis / scene.convert_to namespaces (see API Reference).
  • Contributors: backend modules under viz/, analysis/, converters/, and process/; see Source layout.
  • Public utilities: IndexCatalog, inspect_hdf, download_scene from the top-level tanagerspec package.

Dependencies

Core workflows use NumPy, h5py, and matplotlib (and optional plotly for interactive maps). xarray is used for in-memory dataset views and interoperability; raster export uses rasterio where georeferencing is available. See pyproject.toml for the full dependency set.