Brightness

Module: spectralbridge.brightness.

Direct-module reference; consult the linked workflow for processing context.

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.apply_brightness_correction.

apply_brightness_correction

apply_brightness_correction(cube: ndarray, mask: Optional[ndarray] = None, *, method: Literal['percentile_match', 'linear_regression', 'unit_gain_offset_only'] = 'percentile_match', reference_cube: Optional[ndarray] = None, reference_stats: Optional[Tuple[ndarray, ndarray]] = None, p_lo: float = 5.0, p_hi: float = 95.0, clip_min: float = 0.0, clip_max: float = 1.2, huber_delta: float = 0.1) -> tuple[np.ndarray, dict[str, np.ndarray]]

Apply a per-band brightness correction to hyperspectral/multispectral data.

This normalizes scene brightness under varying illumination (sun angle, terrain shadow) or sensor gain drift. Typically used after ENVI export and before BRDF correction.

Mathematical form

For band b: y_corr[b] = gain[b] * y_raw[b] + offset[b] where gain/offset come from robust percentile matching or regression vs a reference.

Parameters:

Name	Type	Description	Default
cube	ndarray	Array shaped (B, Y, X) or (Y, X, B).	required
mask	ndarray	Boolean mask: True = valid pixel used for stats.	None
method	('percentile_match', 'linear_regression', 'unit_gain_offset_only')	Strategy for estimating per-band gain/offset.	'percentile_match'
reference_cube	ndarray	Reference to match brightness against (required for 'linear_regression').	None
reference_stats	tuple[ndarray, ndarray]	(p_lo, p_hi) per band for reference distribution (each shape (B,)).	None
p_lo	float	Robust percentile bounds, default (5, 95).	5.0
p_hi	float	Robust percentile bounds, default (5, 95).	5.0
clip_min	float	Optional post-correction clipping, default (0.0, 1.2).	0.0
clip_max	float	Optional post-correction clipping, default (0.0, 1.2).	0.0
huber_delta	float	Huber delta for robust regression.	0.1

Returns:

Type	Description
ndarray	Corrected cube with same shape as input.
dict	Metadata with per-band gain/offset and diagnostics.

Examples:

>>> import numpy as np
>>> from spectralbridge import apply_brightness_correction
>>> cube = np.full((2, 4, 4), .2, dtype=np.float32)
>>> corr, meta = apply_brightness_correction(cube)
>>> assert corr.shape == cube.shape

Notes

• NaNs preserved. Bandwise affine transform.
• See also: topo+BRDF correction stage and QA JSON (gain/offset are included there when run).