Configuration & Constants¶

TanagerSpec has a number of configuration-like values — nodata sentinels, default percentile stretches, figure DPI, colormap names, projection offsets, clustering hyperparameters, and RGB band presets. The numeric and tunable ones now live in a single module, src/tanagerspec/config.py. This page describes what that module holds, how to reference it, and which values deliberately stay inline, so behavior stays consistent across modules.

Where constants live¶

All shared numeric/tunable constants live in one place:

# src/tanagerspec/config.py

Modules import the module as a namespace and reference values through it — never re-typing the literal:

from tanagerspec import config

scale = np.maximum(p_high - p_low, config.STRETCH_EPSILON)
img[img == config.NODATA_VALUE] = np.nan

This from tanagerspec import config / config.NAME pattern is used uniformly across io/, process/, viz/, analysis/, and converters/. A new constant is just added as a module-level value in config.py — there is no export list to keep in sync. Do not use from tanagerspec.config import *; always go through the config namespace.

The earlier analysis/constants.py module has been removed; NODATA_VALUE and MASKED_BAND_VALUE now live in config.py alongside the rest.

Guidance for contributors¶

Prefer a named constant over an inline literal. If a value already has a name (for example NODATA_VALUE), import config and use config.NODATA_VALUE rather than re-typing -9999.
Keep tunable defaults as keyword arguments, but source their default from config rather than a bare literal (for example p_min: float = config.ROBUST_PERCENTILES[0]).
Add new shared constants to config.py when a value is repeated across modules, then import it everywhere it is used.
Treat format specs as constants, not tunables. HDF5 path substrings, ENVI header fields, and xarray dimension/coordinate names describe a file format and should not be changed casually. These stay in their own modules (see Values that stay inline).
Leave genuinely one-off styling inline. A figure size or colormap used in a single plot does not need to be centralized; only values that are repeated across modules belong in config.py.

Constants in `config.py`¶

The tables below mirror config.py, grouped by the same sections used in the module.

Radiometric / sentinel values¶

Constant	Value	Meaning
`NODATA_VALUE`	`-9999`	Integer nodata/missing-pixel sentinel for raw and integer data.
`DEFAULT_FILL_VALUE`	`-9999.0`	Float fallback fill value used when a product declares no `_FillValue`.
`MASKED_BAND_VALUE`	`-9998.0`	Marker for masked-band columns in classifier training tables.
`UINT8_NODATA`	`255`	Nodata value written for `uint8` GeoTIFF outputs.

Numerical-safety constants¶

Constant	Value	Meaning
`DENOMINATOR_EPSILON`	`1e-12`	Floor added to denominators to avoid division by zero (e.g. normalized indices).
`STRETCH_EPSILON`	`1e-8`	Minimum span used when scaling a display stretch to `[0, 1]`.
`SMALL_PADDING`	`1e-6`	Generic small positive padding for color limits and degenerate ranges.

Display / stretch defaults¶

Constant	Value	Meaning
`ROBUST_PERCENTILES`	`(2.0, 98.0)`	Default lower/upper percentiles for robust contrast stretching.
`TARGET_BRIGHTNESS`	`0.5`	Target mean brightness used when computing automatic gamma.
`DEFAULT_GAMMA`	`1.0`	Gamma fallback when an automatic value cannot be computed.

Projection (UTM)¶

Constant	Value	Meaning
`UTM_EPSG_NORTH_BASE`	`32600`	EPSG base for northern-hemisphere UTM zones (add the zone number).
`UTM_EPSG_SOUTH_BASE`	`32700`	EPSG base for southern-hemisphere UTM zones (add the zone number).
`UTM_ZONE_MIN`	`1`	Lowest valid UTM zone number.
`UTM_ZONE_MAX`	`60`	Highest valid UTM zone number.

Machine-learning / algorithm defaults¶

Constant	Value	Meaning
`RANDOM_STATE`	`31`	Seed for supervised classifiers (RandomForest, MLP).
`CLUSTERING_RANDOM_STATE`	`95`	Seed for unsupervised clustering (KMeans, GaussianMixture); kept distinct from `RANDOM_STATE` to preserve historical reproducibility.
`RF_N_ESTIMATORS`	`100`	Default number of trees for the RandomForest classifier.
`MLP_MAX_ITER`	`500`	Default maximum iterations for the MLP classifier.
`KMEANS_MAX_ITER`	`300`	Default maximum iterations for KMeans.
`KMEANS_N_INIT`	`20`	Default number of KMeans initializations.
`GMM_MAX_ITER`	`200`	Default maximum iterations for the Gaussian mixture.
`GMM_N_INIT`	`5`	Default number of Gaussian-mixture initializations.
`GMM_REG_COVAR`	`1e-6`	Covariance regularization added to the diagonal for the Gaussian mixture.
`PCA_N_COMPONENTS`	`3`	Default number of PCA / dimensionality-reduction components.
`ICA_MAX_ITER`	`1000`	Default maximum iterations for FastICA.
`CONVERGENCE_TOL`	`1e-4`	Default convergence tolerance for iterative reductions.
`N_JOBS`	`-1`	Default parallelism for estimators that accept `n_jobs` (-1 = all cores).
`SAM_THRESHOLD`	`0.15`	Default Spectral Angle Mapper threshold, in radians.

Units¶

Constant	Value	Meaning
`DEFAULT_SPECTRAL_UNITS`	`"nm"`	Default units for wavelength and FWHM metadata.

Spectral presets¶

DEFAULT_RGB_PRESET is "true_color"; DEFAULT_WAVELENGTH_RANGE is "red".

PRESET_BANDS — named RGB composites mapped to (red_nm, green_nm, blue_nm) target wavelengths:

Preset	(R, G, B) nm
`true_color`	(680, 550, 470)
`false_color_nir`	(850, 680, 550)
`false_color_swir`	(1600, 850, 680)
`false_color_urban`	(2200, 1600, 550)

PRESET_WAVELENGTH_RANGES — named wavelength intervals (nm) for band-range exploration:

Range	(min, max) nm
`coastal`	(400, 450)
`blue`	(450, 495)
`green`	(495, 570)
`yellow`	(570, 590)
`orange`	(590, 620)
`red`	(620, 700)
`red_edge`	(700, 750)
`nir`	(750, 900)
`visible`	(400, 700)

Plotting defaults¶

Constant	Value	Meaning
`SAVE_DPI`	`300`	DPI used when saving figures to PNG.
`FIGSIZE_SQUARE`	`(8, 8)`	Square figure size, in inches.
`FIGSIZE_DEFAULT`	`(10, 8)`	Default figure size, in inches.
`FIGSIZE_WIDE`	`(14, 5)`	Wide figure size, in inches.
`FIGSIZE_PANEL`	`(22, 7)`	Multi-panel figure size, in inches.
`FIGSIZE_BAND_STATUS`	`(12, 3)`	Band-status strip figure size, in inches.
`CMAP_INDEX`	`"RdYlGn"`	Default colormap for spectral-index maps.
`CMAP_BACKGROUND`	`"gray"`	Colormap for grayscale background context layers.
`CMAP_DIVERGING`	`"RdBu_r"`	Diverging colormap for difference maps centered on zero.
`CMAP_SEQUENTIAL`	`"viridis"`	General sequential colormap.
`CMAP_CORRELATION`	`"jet"`	Colormap for band-correlation matrices.
`CMAP_BAND_STATUS`	`"nipy_spectral"`	Colormap for band-status (good/bad band) displays.

Values that stay inline¶

Some configuration-like values are not in config.py by design: they describe a file format or are genuinely single-use. Do not move these into config.py — they live next to the code that owns them.

HDF5 product detection — path substrings (SWATHS, GRIDS, surface_reflectance, toa_radiance), the StructMetadata.0 location, and the regexes used to parse band counts, dimensions, data types, and zone codes — in io/tanager_loader.py and io/tanager_grid.py. The 0.5 pixel-center offset used when building coordinates also lives in io/tanager_grid.py.
Export / converter format specs — ENVI dtype codes and header literals (interleave = bil, byte order, file type, datum, units), GeoTIFF driver settings (GTiff, lzw compression, tiling), and the xarray dimension/coordinate/attribute names — in converters/envi_converter.py, converters/tiff_converter.py, and converters/xarray_converter.py.
Spectral-region boundaries — the VIS / NIR / SWIR boundaries used by the band-status plot (VIS 380–750, NIR 750–1400, SWIR 1400–2500 nm) — in viz/plot_band_status.py.
One-off plotting defaults — animation FPS (5) and the ROI window size (5) — in viz/animate_bands.py and viz/plot_pixel_variability.py.
Resource paths and catalog fields — the indices JSON filename (tanager_indices.json), the data/indices_bank/ resource path, and the catalog JSON field names (name, application_domain, bands, reference) — in analysis/indices/catalog.py and utils/index_catalog.py.