Io Neon

Module: spectralbridge.io.neon.

Helpers for reading NEON reflectance HDF5 products across layout versions.

The new-layout reader was factored from SpectralBridge's HyTools-adapted NeonCube path and then extended for historical schemas, bounded reads, orientation, and reflectance scaling.

HyTools: Hyperspectral image processing library Copyright (C) 2021 University of Wisconsin Authors named in the relevant source notices: Adam Chlus, Zhiwei Ye, Philip Townsend. License: GNU General Public License, version 3 Upstream: https://github.com/EnSpec/hytools Audited revision: 31286d64541791a9815d29443a33726fa4d54031

Modified and extended for SpectralBridge. See LICENSE, NOTICE, and HYTOOLS_PROVENANCE.md.

API glossary · Workflow / scientific context

Signatures and documentation below are collected from the current source. Advanced objects are not newly declared stable by inclusion here.

Audience: public. Also exported as spectralbridge.io.is_pre_2021.

is_pre_2021

is_pre_2021(h5_path: Path) -> bool

Return True when h5_path appears to be a pre-2021 NEON export.

Parameters:

Name	Type	Description	Default
h5_path	Path	Existing NEON reflectance HDF5 file; layout is detected from file metadata rather than assumed from array dimensions.	required

Returns:

Type	Description
bool	Whether a year parsed from the filename is earlier than 2021; False when no year is recognized. This is not the schema resolver.

See Also

spectralbridge.pipelines.pipeline.process_one_flightline : Related source-derived API contract.

Audience: advanced.

reflectance_to_unitless_multiplier

reflectance_to_unitless_multiplier(scale_factor: float) -> float

Return m such that unitless = stored * m.

Accepts both common packaging conventions:

• Multiply style (0.0001): unitless = DN * 0.0001
• NEON / ENVI divisor style (10000): unitless = DN / 10000
• Already unitless (1.0): unitless = DN

The raw attribute is still stored on cubes / ENVI headers for QA; this helper is only for converting between storage units and physical reflectance.

Audience: advanced.

stored_to_unitless

stored_to_unitless(data: ndarray, scale_factor: float) -> np.ndarray

Convert stored reflectance values to unitless reflectance.

Audience: advanced.

unitless_to_stored

unitless_to_stored(data: ndarray, scale_factor: float) -> np.ndarray

Convert unitless reflectance back to the cube's storage scale.

Audience: advanced.

read_neon_reflectance_unitless

read_neon_reflectance_unitless(reflectance_ds: Dataset) -> tuple[np.ndarray, float, float]

Return unitless reflectance scaled by the NEON factor with ignore masked.

Parameters:

Name	Type	Description	Default
reflectance_ds	Dataset	The NEON reflectance dataset (/Reflectance/Reflectance_Data or similar).	required

Returns:

Type	Description
tuple[ndarray, float, float]	(data_unitless, scale_factor, ignore_value) where data_unitless is a float32 array scaled into 0–1 reflectance with ignore values set to NaN. scale_factor is the raw dataset attribute (for example 10000 or 1e-4); conversion to unitless always goes through :func:reflectance_to_unitless_multiplier.

Audience: public. Also exported as spectralbridge.io.peek_neon_raster_shape.

peek_neon_raster_shape

peek_neon_raster_shape(h5_path: Path) -> tuple[int, int]

Return (n_lines, n_samples) without loading the reflectance cube.

Parameters:

Name	Type	Description	Default
h5_path	Path	Existing NEON reflectance HDF5 file; layout is detected from file metadata rather than assumed from array dimensions.	required

Returns:

Type	Description
tuple[int, int]	Number of along-track lines and across-track samples, without loading the reflectance cube.

Raises:

Type	Description
FileNotFoundError	If a required source or completed artifact is absent.
RuntimeError	If required processing or artifact validation cannot complete.

See Also

spectralbridge.pipelines.pipeline.process_one_flightline : Related source-derived API contract.

Audience: public. Also exported as spectralbridge.io.peek_neon_sample_count.

peek_neon_sample_count

peek_neon_sample_count(h5_path: Path) -> int

Return the across-track sample count without loading the reflectance cube.

Parameters:

Name	Type	Description	Default
h5_path	Path	Existing NEON reflectance HDF5 file; layout is detected from file metadata rather than assumed from array dimensions.	required

Returns:

Type	Description
int	Across-track sample count, without loading the reflectance cube.

See Also

spectralbridge.pipelines.pipeline.process_one_flightline : Related source-derived API contract.

Audience: public. Also exported as spectralbridge.io.read_neon_cube.

read_neon_cube

read_neon_cube(h5_path: Path, sample_slice: slice | tuple[int, int] | None = None, line_slice: slice | tuple[int, int] | None = None) -> tuple[np.ndarray, np.ndarray, Dict[str, Any]]

Return (cube, wavelengths, metadata) for h5_path regardless of layout.

Parameters:

Name	Type	Description	Default
h5_path	Path	Existing NEON reflectance HDF5 file; layout is detected from file metadata rather than assumed from array dimensions.	required
sample_slice	slice | tuple[int, int] | None	Optional half-open across-track sample window, supplied as a slice or (start, stop); None reads the full sample axis.	None
line_slice	slice | tuple[int, int] | None	Optional half-open along-track line window, supplied as a slice or (start, stop); None reads the full line axis.	None

Returns:

Type	Description
tuple[ndarray, ndarray, Dict[str, Any]]	Cube shaped (lines, samples, bands), wavelength vector (bands,) in nanometers, and metadata including nodata, scale_factor and spatial/window provenance. Stored reflectance values are retained; use the explicit unitless reader when conversion is required.

Raises:

Type	Description
FileNotFoundError	If a required source or completed artifact is absent.
RuntimeError	If required processing or artifact validation cannot complete.

Notes

sample_slice / line_slice are optional half-open windows on the across-track and along-track axes. When omitted, the full cube is loaded.

See Also

spectralbridge.pipelines.pipeline.process_one_flightline : Related source-derived API contract.