Landsat Flight Validation

Module: spectralbridge.landsat_flight_validation.

Independent seven-band NEON-to-real-Landsat validation, one flight at a time.

Extends existing Landsat transport/identity/scaling helpers. No calibration is fit.

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: advanced.

FlightValidationInput dataclass

FlightValidationInput(flight_id: str, site: str, acquisition_datetime: str, corrected_raster: str, undarkened_raster: str, adjusted_raster: str, synthetic_scale_factor: float, time_provenance: str, source_h5: str | None = None, timezone_verified: bool = False)

Specify existing raw/adjusted synthetic products and an actual Landsat comparison source for one flight.

Audience: advanced.

FlightValidationConfig dataclass

FlightValidationConfig(search_days: int = 16, minimum_valid_coverage: float = 0.9, minimum_pixels: int = 100, bootstraps: int = 499, spatial_block_pixels: int = 10, seed: int = 20261014, rgb_max: float = 0.4)

Configure explicit support, acquisition-time, screening and rendering settings for flight validation.

validate

validate()

Audience: advanced.

candidate_records

candidate_records(items, neon_datetime)

All searched scenes; compatibility and collection are explicit gates.

Audience: advanced.

rank_scene_candidates

rank_scene_candidates(table, minimum_pixels=100)

Temporal -> clear overlap -> compatibility -> coverage -> quality; never error.

Audience: advanced.

load_scene_qa

load_scene_qa(item, bounds_wgs84, cache)

Windowed Collection 2 QA with a 600-m halo for conservative proximity.

Audience: advanced.

load_scene_surface_reflectance

load_scene_surface_reflectance(item, grid, qa, cache)

Read seven real SR assets on their native Landsat window; no TOA route.

Audience: advanced.

compare_flight_to_real_landsat

compare_flight_to_real_landsat(flight, output, *, config=None, items=None, client=None) -> dict

Select one real scene and compare it with a verified seven-band flight.

Parameters:

Name	Type	Description	Default
flight	FlightValidationInput	Source paths, identity, acquisition time and explicit scale/time provenance. Synthetic bands must be ordered coastal/blue/green/red/NIR/SWIR1/SWIR2.	required
output	str or Path	Checkpoint/result directory.	required
config	FlightValidationConfig	Search, coverage and bootstrap settings; defaults include 0.9 whole-footprint valid coverage.	None
items	sequence	Supplied STAC items; None enables discovery.	None
client	object	STAC client for discovery.	None

Returns:

Name	Type	Description
dict	dict	Status/identity/checksummed output manifest. Explicit no-scene and unusable-scene statuses are retained, not fabricated successful fits. Results contain matched arrays, tables, QA and figures in output.

Raises:

Type	Description
ValueError	Source coordinates/scales, metadata or configuration invalid.
OSError	Source/cache/output IO fails. Network/library errors propagate when discovery/download is requested; use optional landsat extra.

Inputs are read in place. Complete valid outputs are reused. Uses actual footprint area, QA_PIXEL/RADSAT, official C2 SR scaling, seven-band joint support and spatial-block uncertainty. One flight is not cross-site evidence.

Audience: advanced.

summarize_flight_validations

summarize_flight_validations(outputs, destination)

Read compact completed results only; equally weight flights, never pixels.