Drone Translation¶
Module: spectralbridge.drone_translation.
Wavelength-aware application of reviewed bulk translation coefficients.
This module is deliberately downstream of drone correction and downstream of bulk coefficient estimation. It never fits coefficients and never performs spectral convolution.
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.
DroneTranslationBand
dataclass
¶
DroneTranslationBand(translation_pair: str, source_sensor: str, target_sensor: str, coefficient_band_index: int, coefficient_source_band_index: int, native_source_band_index: int, target_band_index: int, source_spectral_identity: str, target_spectral_identity: str, source_wavelength_nm: float, native_source_wavelength_nm: float, target_wavelength_nm: float, target_fwhm_nm: float, slope: float, intercept: float, x_min: float | None, x_max: float | None, x_mean: float | None, r2: float | None, rmse: float | None = None, fitted_correction_percent: float | None = None, flightline_slope_iqr: float | None = None, site_slope_range: float | None = None, worst_loso_r2: float | None = None, worst_loso_rmse: float | None = None, worst_loso_site: str | None = None, attention_flags: tuple[str, ...] = (), coefficient_status: str | None = None, coefficient_warnings: tuple[str, ...] = (), coefficient_set_version: str | None = None)
One validated source-band to target-band affine relationship.
Audience: advanced.
DroneTranslationPlan
dataclass
¶
DroneTranslationPlan(analysis_run_id: str, analysis_level: str, weighting_description: str, source_sensor: str, target_sensor: str, translation_pair: str, coefficient_path: str, coefficient_sha256: str, evidence_boundary: str | None, candidate_status: str | None, bands: tuple[DroneTranslationBand, ...], coefficient_set_version: str | None = None)
Validated coefficients and band mapping for one Landsat target sensor.
Audience: advanced.
load_drone_translation_plans ¶
load_drone_translation_plans(coefficient_path: str | Path | None = None, *, weighting: str = PRODUCTION_TRANSLATION_WEIGHTING, source_wavelengths_nm: Sequence[float] | ndarray, target_sensors: Iterable[str] | None = None, strict: bool = False) -> tuple[DroneTranslationPlan, ...]
Load and scientifically validate bulk coefficients for drone application.
weighting selects the bulk analysis_level and defaults to the fixed
production policy, site_balanced. When coefficient_path is omitted,
the packaged versioned production registry is used. When target_sensors
is omitted, every complete built-in target present in the artifact is
returned; the function never dynamically chooses a sensor or weighting.
Audience: advanced.
translated_output_stem ¶
translated_output_stem(flight_dir: str | Path, flight_stem: str, target_sensor: str) -> Path
Return a precise, sensor-specific Landsat-like translated ENVI stem.
Audience: advanced.
matched_source_output_stem ¶
matched_source_output_stem(flight_dir: str | Path, flight_stem: str, source_sensor: str) -> Path
Return the canonical matched-MicaSense product stem used by bulk.
Audience: advanced.
ensure_matched_source_product ¶
ensure_matched_source_product(corrected_img: str | Path, corrected_hdr: str | Path, *, output_stem: str | Path, plan: DroneTranslationPlan, overwrite: bool = False, chunk_lines: int = 256) -> dict[str, Any]
Persist the plan's wavelength-selected source bands for bulk analysis.
This is a distinct scientific product, not a copy for staging: it is the exact source-side band subset paired with the translated Landsat-like raster by the existing bulk translation registry.
Audience: advanced.
apply_drone_translation ¶
apply_drone_translation(corrected_img: str | Path, corrected_hdr: str | Path, *, output_stem: str | Path, plan: DroneTranslationPlan, overwrite: bool = False, chunk_lines: int = 256) -> dict[str, Any]
Apply one validated affine plan to a corrected native MicaSense ENVI.
Audience: advanced.
coefficient_rows_for_parquet ¶
coefficient_rows_for_parquet(plan: DroneTranslationPlan) -> list[dict[str, Any]]
Return compact band-level provenance records for table enrichment.
Audience: advanced.
enrich_translated_spectral_library ¶
enrich_translated_spectral_library(parquet_path: str | Path, *, plan: DroneTranslationPlan, translation_result: dict[str, Any], source_package_path: str, working_h5_path: str, corrected_micasense_path: str, acquisition_datetime: str | None, overwrite: bool = False) -> Path
Attach constant translation/provenance fields without loading pixel rows.
Explicitly exported constants and type aliases¶
These values describe package metadata, schemas or configuration; they are not observations from a production dataset.
| Name | Source expression |
|---|---|
TRANSLATION_EQUATION |
'target = slope * source + intercept' |
SUPPORTED_WEIGHTINGS |
('pixel_pooled', 'flightline_balanced', 'site_balanced') |