# ENVI Spectral Library & Standard Cubes

> **Status:** Supported (scoped) · **Vendor:** L3Harris / ENVI (formerly Exelis / RSI) · **Extensions:** `.sli` + `.hdr` (spectral library); `.img` / `.dat` + `.hdr` (image cube)

ENVI is the de facto interchange format for hyperspectral remote sensing. A
plain-text `.hdr` header describes a binary payload, which is either a
one-band-per-row spectral library (`.sli`) or a multi-band image cube
(`.img` / `.dat`). nirs4all-formats reads both: spectral libraries become one record
per stored spectrum, and image cubes become one record per pixel (or a single
N-dimensional cube record on request).

## Instruments & software

Written by ENVI and compatible GIS/remote-sensing tools. ENVI spectral
libraries ship with reference collections such as the USGS spectral libraries
(splib06/splib07), while ENVI Standard cubes back airborne and lab hyperspectral
imagers. Committed fixtures include a synthetic little-endian float32 library, a
mini ENVI Standard cube, and the USGS AVIRIS-resampled splib06a / splib07
libraries.

## File structure

- **Header (`.hdr`)** — ASCII key/value lines beginning with `ENVI`, parsed into
  `samples`, `lines`, `bands`, `interleave`, `data type`, `byte order`, optional
  `header offset`, `wavelength = { ... }`, `wavelength units`, `spectra names`
  and (for cubes) `map info`. Brace-wrapped lists may span multiple lines.
- **Binary payload** — resolved from `data file = ...` when present, otherwise
  from the sibling file (`.sli` / `.SLI` for libraries; `.img` / `.IMG` /
  `.dat` / `.DAT` for cubes). Decoded through the shared numeric helper covering
  ENVI `data type` 1, 2, 3, 4, 5, 12, 13, 14, 15 (u8 / i16 / i32 / f32 / f64 /
  u16 / u32 / i64 / u64) in either byte order.
- **Layout constraints** — spectral libraries require `bands == 1` and BSQ
  interleave; ENVI Standard cubes support BSQ, BIL and BIP and resolve the
  interleave into C-order on read.

## What nirs4all-formats extracts

- **Signals** — one `spectrum` signal per record. The signal type is `Unknown`
  (ENVI headers carry no semantic unit field).
- **Axis** — values from `wavelength = { ... }`; the unit/kind follow
  `wavelength units` (`nm`, `um`, `cm-1`); a missing axis falls back to a
  generated index with the `envi_sli_missing_wavelength_axis_generated_index`
  warning.
- **Library records** — one record per `spectra names` entry, with
  `metadata.sample_id` and an `envi` object (dimensions, data type, interleave,
  byte order, wavelength units, sensor type).
- **Cube records** — one record per pixel, `sample_id = pixel_y{row}_x{col}`,
  `pixel_x` / `pixel_y`, and, when `map info` is present, `spatial_x` /
  `spatial_y`, normalized `spatial_unit`, projection, reference pixel/map
  coordinates, pixel sizes, zone, hemisphere and datum.
- **Pixel selection** — cubes accept a half-open `CubeWindow` ROI
  (`--rows START:END --cols START:END`) or an ordered sparse `CubeMask`
  (`--pixel ROW,COL` / `--pixels-file`); original pixel coordinates are
  preserved.
- **Single-record mode** — `ReadOptions::single_record()` / `--single-record`
  emits one N-dimensional record (`dims = ["row", "col", "x"]`) with `row`/`col`
  index coordinates and map-level georeferencing in metadata (rejects a sparse
  mask).
- **Provenance** — header sidecar (role `header`) and binary payload (role
  `binary`), each with SHA-256.

## Variants & support status

| Variant | Status | Notes |
|---|---|---|
| ENVI Spectral Library `.sli` + `.hdr` | Supported | One-band BSQ float/int payloads, either byte order; `spectra names` become records. |
| ENVI Standard cube `.img` / `.dat` + `.hdr` | Supported (scoped) | BSQ/BIL/BIP; per-pixel records, ROI window, sparse mask, or single N-D record. |
| USGS splib06 / splib07 (AVIRIS-resampled) | Supported | Read through both `.hdr` and direct `.sli` entry paths. |
| Legacy `.slb` spectral library | Planned | No fixture yet; low NIRS impact. |
| Specim / HySpex / Headwall / NEON cubes | Planned | Production-scale cube fixtures still wanted. |

## Limitations & known gaps

- `data ignore value` sentinels are preserved as numeric values rather than
  converted to missing values; a masking policy is pending in the shared model.
- Non-zero `header offset` and big-endian payloads are accepted by the decoder
  but not yet exercised by a committed fixture.
- The single-record cube mode rejects sparse masks; use the per-pixel layout for
  arbitrary pixel selection.

## Reference readers

The format is documented by ENVI and supported by Spectral Python (`spectral`),
R `RStoolbox::readSLI()`, `pysptools` and `rasterio`. The nirs4all-formats reader is
clean-room. Conformance output from Spectral Python is planned once the optional
dependency is present in the reverse-engineering environment.

## Samples & validation

Fixtures live under `samples/envi_sli/` (synthetic library `.hdr`/`.sli`, mini
cube `.hdr`/`.img`, USGS splib06a/splib07) and the AVIRIS cube under
`samples/hyperspectral_cubes/`; all are golden-backed. The synthetic library
yields 50 records of 200 points over 1100–2500 nm, first record `y[0] = 0.0367427170`,
last record `y[199] = 0.0608757548`. The mini cube is 48×48 pixels × 32 bands
(first pixel first/last `100`/`3223`; last pixel `152`/`3275`), with UTM `map info`
normalized to `spatial_unit = "m"`. The USGS libraries expose 1365 (splib06a) and
3139 (splib07) records on a 224-point `um` axis (`0.38315..2.5082`). ENVI is a
sidecar-bearing format: `open_path` reads the pair from disk, `open_with_sidecars`
decodes in-memory bytes through a `SidecarResolver`, and `open_bytes` returns
`Error::UnsupportedSidecar`.