Python API¶

The rsrf package exports its public API from the top-level module. All functions listed here are available via from rsrf import ....

Sensor discovery¶

`list_sensors`¶

list_sensors(root: Path | None = None) -> list[dict[str, Any]]

List all registered sensor representations that have backing canonical artifacts on disk. Returns a list of dictionaries sorted by sensor_unit_id and representation_variant.

from rsrf import list_sensors

sensors = list_sensors()
for s in sensors:
    print(s["sensor_unit_id"], s["representation_variant"], s["content_kind"])

`list_bands`¶

list_bands(
    sensor_unit_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
) -> list[dict[str, Any]]

List band-level registry rows for a sensor representation. When only one representation variant exists for the sensor, representation_variant can be omitted.

from rsrf import list_bands

bands = list_bands("sentinel-2c_msi", "band_average")
for b in bands:
    print(b["band_id"], b.get("band_name"))

`list_planned_sensors`¶

list_planned_sensors(
    root: Path | None = None,
    *,
    catalog_path: Path | None = None,
) -> list[dict[str, Any]]

Return planned sensor entries from the planning catalog as JSON-friendly dictionaries. These are sensors tracked for future ingest that do not yet have canonical artifacts.

`list_sensor_definitions`¶

list_sensor_definitions(
    *,
    representation_variant: str | None = None,
    root: Path | None = None,
) -> list[str]

List registry-backed sensor ids that can be normalized into full SensorDefinition objects.

from rsrf import list_sensor_definitions

sensor_ids = list_sensor_definitions()
print(sensor_ids[:5])

Whole-sensor definitions¶

`get_sensor_definition`¶

get_sensor_definition(
    sensor_id: str,
    *,
    representation_variant: str | None = None,
    root: Path | None = None,
) -> SensorDefinition

Load a registry-backed sensor as a versioned SensorDefinition. When multiple backed variants exist for the same sensor id and no representation_variant is provided, RSRF picks a deterministic default and records the chosen variant in sensor_definition.extensions["rsrf"]["representation_variant"].

from rsrf import get_sensor_definition

sensor_definition = get_sensor_definition("sentinel-2c_msi")
print(sensor_definition.schema_type, sensor_definition.schema_version)
print(sensor_definition.extensions["rsrf"]["representation_variant"])

`sensor_definition_from_dict`¶

sensor_definition_from_dict(payload: Mapping[str, Any]) -> SensorDefinition

Validate and normalize a custom sensor-definition payload into the stable typed model.

`sensor_definition_to_dict`¶

sensor_definition_to_dict(sensor_definition: SensorDefinition) -> dict[str, Any]

Serialize a SensorDefinition back to its stable JSON-facing shape. extensions content is preserved.

`load_sensor_definition`¶

load_sensor_definition(
    source: str | Path,
    *,
    root: Path | None = None,
) -> SensorDefinition

Load and validate a sensor definition from a JSON file.

`dump_sensor_definition`¶

dump_sensor_definition(
    sensor_definition: SensorDefinition,
    destination: str | Path,
) -> None

Write a validated sensor definition to JSON.

`coerce_sensor_definition`¶

coerce_sensor_definition(
    sensor_definition_input: SensorDefinition | Mapping[str, Any] | str | Path,
    *,
    representation_variant: str | None = None,
    root: Path | None = None,
) -> SensorDefinition

Normalize any supported sensor-definition input into a SensorDefinition. Supported forms are:

a SensorDefinition instance
a mapping payload
a JSON file path
a registry sensor id

Band-level response_definition payloads accept sampled arrays plus kind="sampled", or center/FWHM metadata via kind="band_spec" or kind="gaussian", and are validated during coercion.

Loading response definitions¶

`load_response_definition`¶

load_response_definition(
    sensor_unit_id: str,
    band_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
) -> SampledCurve | BandSpec

Load a canonical response definition for a single band. Returns a SampledCurve when the representation is sampled_curve, or a BandSpec when the representation is band_spec. This is the recommended general-purpose loading function.

from rsrf import load_response_definition

response = load_response_definition("sentinel-2c_msi", "B03", "band_average")
print(type(response).__name__)  # SampledCurve

`load_curve`¶

load_curve(
    sensor_unit_id: str,
    band_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
) -> SampledCurve

Load a canonical sampled curve for a band. Raises ValueError if the representation is not sampled_curve.

from rsrf import load_curve

curve = load_curve("sentinel-2c_msi", "B03", "band_average")
print(len(curve.wavelength_nm), "samples")

`load_band_spec`¶

load_band_spec(
    sensor_unit_id: str,
    band_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
) -> BandSpec

Load a canonical band specification for a band. Raises ValueError if the representation is not band_spec.

from rsrf import load_band_spec

spec = load_band_spec("prisma_hsi", "B001", "metadata_band_spec")
print(spec.center_wavelength_nm, spec.fwhm_nm)

`get_metadata`¶

get_metadata(
    sensor_unit_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
) -> dict[str, Any]

Load the canonical metadata.json sidecar for a sensor representation.

from rsrf import get_metadata

meta = get_metadata("sentinel-2c_msi", "band_average")
print(meta["content_kind"], meta["representation_variant"])

`coerce_response_definition`¶

coerce_response_definition(
    response_definition: SampledCurve | BandSpec | Mapping[str, Any] | Callable[[], Any],
    *,
    band_id: str = "custom",
    source_variant: str | None = "custom",
) -> SampledCurve | BandSpec

Normalize a runtime response-definition input into the package's native dataclasses. Supported forms are:

a SampledCurve or BandSpec instance
a mapping with wavelength_nm and response
a mapping with wavelength and relative_spectral_response
a mapping with center_wavelength_nm and fwhm_nm
a zero-argument callable returning one of the above

Center+FWHM inputs are normalized to a BandSpec. Helpers that need sampled responses, such as convolution utilities, realize them as Gaussian curves.

from rsrf import coerce_response_definition

curve = coerce_response_definition(
    {
        "band_id": "custom_blue",
        "wavelength_nm": [450.0, 455.0, 460.0],
        "response": [0.1, 1.0, 0.1],
    }
)

spec = coerce_response_definition(
    lambda: {
        "band_id": "custom_nir",
        "center_wavelength_nm": 842.0,
        "fwhm_nm": 20.0,
    }
)

Validation¶

`validate_sensor`¶

validate_sensor(
    sensor_unit_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
) -> dict[str, Any]

Validate a sensor representation and return a structured QA report. Dispatches to content-kind-specific validators for sampled_curve and band_spec representations.

`validate_sampled_curve_inventory`¶

validate_sampled_curve_inventory(
    *,
    root: Path | None = None,
) -> dict[str, Any]

Validate every sampled_curve representation in the repository and return an aggregate report.

`write_validation_artifacts`¶

write_validation_artifacts(
    sensor_unit_id: str,
    representation_variant: str | None = None,
    *,
    root: Path | None = None,
    output_dir: Path | None = None,
) -> dict[str, Path]

Run validation and write a validation_report.json and overview.png for a sensor representation. The output directory defaults to docs/sensor-notes/<sensor>/<variant>/.

Manifests¶

`resolve_manifest_path`¶

resolve_manifest_path(
    path_or_name: str | Path,
    root: Path | None = None,
) -> Path

Resolve a manifest from an explicit path or a library filename. The resolution order is:

Absolute path (used as-is)
Relative path resolved from CWD (validated to be within the repo)
Relative to the repository root
Searched in the official, planning, and template manifest directories

Raises FileNotFoundError if no manifest is found.

`manifest_path`¶

manifest_path(
    root: Path | None,
    filename: str,
    *,
    manifest_group: str = "official",
) -> Path

Return the canonical filesystem path for a manifest in the requested group. Valid groups are "official", "planning", and "templates".

`iter_source_manifest_paths`¶

iter_source_manifest_paths(
    root: Path | None = None,
    *,
    include_templates: bool = False,
    include_planning: bool = False,
) -> tuple[Path, ...]

Return all checked-in manifest JSON files in stable sorted order. By default only official manifests are included.

`register_planned_sensor_catalog`¶

register_planned_sensor_catalog(
    root: Path | None = None,
    *,
    catalog_path: Path | None = None,
) -> Path | None

Replace the planned slice of the sensor registry with entries from the planning catalog. Returns the path to the updated sensors.parquet, or None if no changes were needed.

Curve realization¶

`realize_curve`¶

realize_curve(
    band_spec: BandSpec,
    *,
    profile_type: str = "gaussian",
    grid_policy: GridPolicy | None = None,
    normalization: str | None = "peak_1.0",
    source_variant: str | None = None,
) -> SampledCurve

Realize a sampled curve from a BandSpec by synthesizing response samples from the center wavelength and FWHM. Currently supports gaussian profile type with peak_1.0 normalization and adaptive_per_band grid policies.

from rsrf import load_band_spec, realize_curve

spec = load_band_spec("prisma_hsi", "B001", "metadata_band_spec")
curve = realize_curve(spec)
print(len(curve.wavelength_nm), "samples")

Documentation site¶

`prepare_docs_site`¶

prepare_docs_site(
    root: Path | None = None,
    *,
    refresh_visualization_data: bool = True,
) -> dict[str, Path]

Render generated docs files, sync versioned JS/CSS visualization bundles, and optionally refresh the visualization data assets. Returns a dictionary of output paths.

`export_docs_visualization_assets`¶

export_docs_visualization_assets(
    root: Path | None = None,
    *,
    output_dir: Path | None = None,
    sensor_keys: Iterable[tuple[str, str]] | None = None,
) -> dict[str, Path]

Export interactive documentation visualization assets (JSON sensor data files) for the MkDocs site.

Common parameters¶

All repository-aware functions accept an optional root parameter:

Parameter	Type	Description
`root`	`Path \\| None`	Override root path. When `None`, resolved via `RSRF_ROOT`, repository auto-discovery from CWD, or the cached GitHub release snapshot for the installed version.

Data classes¶

The loading functions return frozen dataclass instances. See the Data Model page for field-level documentation of BandSpec, SampledCurve, and the ContentKind enum.

Python API¶

Sensor discovery¶

list_sensors¶

list_bands¶

list_planned_sensors¶

list_sensor_definitions¶

Whole-sensor definitions¶

get_sensor_definition¶

sensor_definition_from_dict¶

sensor_definition_to_dict¶

load_sensor_definition¶

dump_sensor_definition¶

coerce_sensor_definition¶

Loading response definitions¶

load_response_definition¶

load_curve¶

load_band_spec¶

get_metadata¶

coerce_response_definition¶