Drone Translation Registry¶

Module: spectralbridge.drone_translation_registry.

Build and validate versioned production drone-translation registries.

The builder consumes only completed compact bulk outputs. It never opens source rasters, estimates coefficients, or changes the selected production weighting.

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.

packaged_drone_translation_coefficients_path ¶

packaged_drone_translation_coefficients_path() -> Path

Return the packaged production registry or an actionable error.

Audience: advanced.

validate_drone_translation_coefficients ¶

validate_drone_translation_coefficients(payload: Mapping[str, Any]) -> dict[str, Any]

Validate a complete static production coefficient registry.

Audience: public. Also exported as spectralbridge.load_drone_translation_coefficients.

load_drone_translation_coefficients ¶

load_drone_translation_coefficients(path: str | Path | None = None) -> dict[str, Any]

Load the packaged or explicitly supplied static production registry.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path \| None`	Optional coefficient-registry JSON path; None loads the packaged reviewed static registry.	`None`

Returns:

Type	Description
`dict[str, Any]`	Validated versioned registry payload with coefficient records, statuses and provenance.

Raises:

Type	Description
`FileNotFoundError`	If a required source or completed artifact is absent.
`ValueError`	If the supplied options, dimensions, support or provenance violate the input contract.

get_drone_translation_coefficient ¶

get_drone_translation_coefficient(target_sensor: str, target_band: int, *, path: str | Path | None = None) -> dict[str, Any]

Return one unambiguous production target-band coefficient.

Parameters:

Name	Type	Description	Default
`target_sensor`	`str`	Canonical target sensor key present in the reviewed drone coefficient registry.	required
`target_band`	`int`	One-based target sensor band number in the registry; this is not a zero-based array index.	required
`path`	`str \| Path \| None`	Optional coefficient-registry JSON path; None loads the packaged reviewed static registry.	`None`

Returns:

Type	Description
`dict[str, Any]`	Exactly one matching target-band coefficient record, including equation, weighting and status metadata.

Raises:

Type	Description
`KeyError`	If the requested sensor/band does not identify exactly one coefficient.

build_drone_translation_coefficient_registry ¶

build_drone_translation_coefficient_registry(bulk_output: str | Path, output_path: str | Path, *, coefficient_set_version: str = DRONE_TRANSLATION_COEFFICIENT_SET_VERSION, overwrite: bool = False, artifact_paths: Mapping[str, str | Path] | None = None) -> Path

Build a static registry from exact compact bulk result artifacts.

Parameters:

Name	Type	Description	Default
`bulk_output`	`str \| Path`	Root of an existing completed bulk run, containing its manifest and compact model tables.	required
`output_path`	`str \| Path`	Destination JSON registry path; existing files are protected unless overwrite is enabled.	required
`coefficient_set_version`	`str`	Version string embedded in the newly built coefficient set and its provenance.	`DRONE_TRANSLATION_COEFFICIENT_SET_VERSION`
`overwrite`	`bool`	Replace existing requested products; False preserves reusable products or rejects a conflicting destination.	`False`
`artifact_paths`	`Mapping[str, str \| Path] \| None`	Optional mapping overriding known compact bulk artifact paths; unknown keys or mismatched provenance are rejected.	`None`

Returns:

Type	Description
`Path`	Written registry path; coefficients retain compact-source hashes and attention flags.

Raises:

Type	Description
`FileExistsError`	If a protected destination already exists or conflicts with the requested product.
`FileNotFoundError`	If a required source or completed artifact is absent.
`ValueError`	If the supplied options, dimensions, support or provenance violate the input contract.

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
`DRONE_TRANSLATION_REGISTRY_SCHEMA_VERSION`	`1`
`DRONE_TRANSLATION_COEFFICIENT_SET_VERSION`	`'v1'`
`DRONE_TRANSLATION_COEFFICIENT_RESOURCE`	`'drone_translation_coefficients_v1.json'`
`PRODUCTION_TRANSLATION_WEIGHTING`	`'site_balanced'`
`COEFFICIENT_STATUSES`	`frozenset({'validated', 'caution', 'reject'})`
`EXPECTED_TARGET_BANDS`	`{'Landsat_5_TM': (1, 2, 3, 4), 'Landsat_7_ETM+': (1, 2, 3, 4), 'Landsat_8_OLI': (1, 2, 3, 4, 5), 'Landsat_9_OLI-2': (1, 2, 3, 4, 5)}`
`L5_TM_B3_CAUTION`	`'Bulk-derived translation for MicaSense 668 nm -> Landsat 5 TM B3 showed strong site dependence and poor WREF leave-one-site-out transferability. Treat this band as lower-confidence.'`