RSRF 0.0.1__py3-none-any.whl

rsrf/__init__.py

@@ -0,0 +1,88 @@
+"""Bootstrap package for the spectral response function repository."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .api import get_metadata, list_bands, list_sensors, load_band_spec, load_curve, load_response_definition
+from .manifests import iter_source_manifest_paths, manifest_path, resolve_manifest_path
+from .planning import list_planned_sensors, register_planned_sensor_catalog
+from .qa import validate_sensor, write_validation_artifacts
+from .realize import realize_curve
+from .visualization import export_docs_visualization_assets
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+
+
+def _metadata_version_from_path(metadata_path: Path) -> str | None:
+    if not metadata_path.exists():
+        return None
+    for line in metadata_path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("Version: "):
+            return line.split("Version: ", 1)[1].strip()
+    return None
+
+
+def _pyproject_version(pyproject_path: Path) -> str | None:
+    if not pyproject_path.exists():
+        return None
+
+    in_project_block = False
+    for raw_line in pyproject_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if line.startswith("["):
+            in_project_block = line == "[project]"
+            continue
+        if in_project_block and line.startswith("version = "):
+            version_literal = line.split("=", 1)[1].strip()
+            if version_literal.startswith('"') and version_literal.endswith('"'):
+                return version_literal[1:-1]
+    return None
+
+
+def _local_distribution_version() -> str | None:
+    repo_version = _pyproject_version(PACKAGE_ROOT.parent.parent / "pyproject.toml")
+    if repo_version:
+        return repo_version
+
+    candidates = [PACKAGE_ROOT.parent / "RSRF.egg-info" / "PKG-INFO"]
+    candidates.extend(sorted(PACKAGE_ROOT.parent.glob("RSRF-*.dist-info/METADATA")))
+    for candidate in candidates:
+        local_version = _metadata_version_from_path(candidate)
+        if local_version:
+            return local_version
+    return None
+
+
+_local_version = _local_distribution_version()
+if _local_version:
+    __version__ = _local_version
+else:
+    __version__ = "0.0.1"
+    for _distribution_name in ("RSRF", "spectral-response-function"):
+        try:
+            __version__ = version(_distribution_name)
+            break
+        except PackageNotFoundError:
+            continue
+
+__all__ = [
+    "PACKAGE_ROOT",
+    "__version__",
+    "export_docs_visualization_assets",
+    "get_metadata",
+    "iter_source_manifest_paths",
+    "list_bands",
+    "list_planned_sensors",
+    "list_sensors",
+    "load_band_spec",
+    "load_curve",
+    "load_response_definition",
+    "manifest_path",
+    "realize_curve",
+    "resolve_manifest_path",
+    "register_planned_sensor_catalog",
+    "validate_sensor",
+    "write_validation_artifacts",
+]

rsrf/__main__.py

@@ -0,0 +1,7 @@
+"""Module entrypoint for ``python -m rsrf``."""
+
+from .commands.app import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rsrf/api.py

@@ -0,0 +1,272 @@
+"""Read API for registry-backed spectral response data."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .io import read_json
+from .models import BandSpec, ContentKind, SampledCurve
+from .registry import read_registry_table, representation_variant_dir
+
+
+def list_sensors(root: Path | None = None) -> list[dict[str, Any]]:
+    """List registered sensor representations."""
+
+    frame = _available_sensor_rows(root)
+    frame = frame.sort_values(["sensor_unit_id", "representation_variant"])
+    return frame.to_dict(orient="records")
+
+
+def list_bands(
+    sensor_unit_id: str,
+    representation_variant: str | None = None,
+    *,
+    root: Path | None = None,
+) -> list[dict[str, Any]]:
+    """List bands for a sensor representation."""
+
+    sensor_row = _resolve_sensor_variant(
+        sensor_unit_id,
+        representation_variant,
+        root=root,
+    )
+    resolved_variant = str(sensor_row["representation_variant"])
+    frame = read_registry_table(root, "bands")
+    frame = frame[
+        (frame["sensor_unit_id"] == sensor_unit_id)
+        & (frame["representation_variant"] == resolved_variant)
+    ]
+    if "band_index" in frame.columns:
+        frame = frame.sort_values(["band_index", "band_id"], na_position="last")
+    return frame.to_dict(orient="records")
+
+
+def get_metadata(
+    sensor_unit_id: str,
+    representation_variant: str | None = None,
+    *,
+    root: Path | None = None,
+) -> dict[str, Any]:
+    """Load the canonical metadata sidecar for a sensor representation."""
+
+    sensor_row = _resolve_sensor_variant(
+        sensor_unit_id,
+        representation_variant,
+        root=root,
+    )
+    metadata_path = (
+        _representation_dir(root, sensor_row)
+        / "metadata.json"
+    )
+    return read_json(metadata_path)
+
+
+def 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."""
+
+    sensor_row = _resolve_sensor_variant(
+        sensor_unit_id,
+        representation_variant,
+        root=root,
+    )
+    resolved_variant = str(sensor_row["representation_variant"])
+    content_kind = ContentKind(str(sensor_row["content_kind"]))
+    if content_kind != ContentKind.SAMPLED_CURVE:
+        raise ValueError(
+            f"{sensor_unit_id}/{resolved_variant} is {content_kind.value}, not sampled_curve"
+        )
+
+    curves_path = (
+        _representation_dir(root, sensor_row)
+        / "curves.parquet"
+    )
+    frame = _read_parquet(curves_path)
+    frame = frame[
+        (frame["sensor_unit_id"] == sensor_unit_id)
+        & (frame["representation_variant"] == resolved_variant)
+        & (frame["band_id"] == band_id)
+    ]
+    if frame.empty:
+        raise KeyError(f"curve not found for {sensor_unit_id}/{resolved_variant}/{band_id}")
+    frame = frame.sort_values("wavelength_nm")
+    return SampledCurve(
+        band_id=band_id,
+        wavelength_nm=frame["wavelength_nm"].to_numpy(),
+        response=frame["response"].to_numpy(),
+        source_variant=resolved_variant,
+    )
+
+
+def 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."""
+
+    sensor_row = _resolve_sensor_variant(
+        sensor_unit_id,
+        representation_variant,
+        root=root,
+    )
+    resolved_variant = str(sensor_row["representation_variant"])
+    content_kind = ContentKind(str(sensor_row["content_kind"]))
+    if content_kind != ContentKind.BAND_SPEC:
+        raise ValueError(f"{sensor_unit_id}/{resolved_variant} is not a band_spec representation")
+
+    band_specs_path = (
+        _representation_dir(root, sensor_row)
+        / "band_specs.parquet"
+    )
+    frame = _read_parquet(band_specs_path)
+    frame = frame[
+        (frame["sensor_unit_id"] == sensor_unit_id)
+        & (frame["representation_variant"] == resolved_variant)
+        & (frame["band_id"] == band_id)
+    ]
+    if frame.empty:
+        raise KeyError(f"band spec not found for {sensor_unit_id}/{resolved_variant}/{band_id}")
+    row = frame.iloc[0]
+    band_registry_row = _lookup_band_registry_row(
+        sensor_unit_id,
+        band_id,
+        resolved_variant,
+        root=root,
+    )
+    shape_param_json = row["shape_param_json"]
+    return BandSpec(
+        band_id=str(row["band_id"]),
+        center_wavelength_nm=float(row["center_wavelength_nm"]),
+        fwhm_nm=float(row["fwhm_nm"]),
+        band_index=None if _is_nullish(row["band_index"]) else int(row["band_index"]),
+        band_name=(
+            str(band_registry_row["band_name"])
+            if band_registry_row is not None and not _is_nullish(band_registry_row["band_name"])
+            else str(row["band_id"])
+        ),
+        band_status="nominal" if _is_nullish(row["band_status"]) else str(row["band_status"]),
+        published_shape_type=str(row["published_shape_type"]),
+        shape_param_json=(
+            {}
+            if _is_nullish(shape_param_json) or not shape_param_json
+            else json.loads(shape_param_json)
+        ),
+    )
+
+
+def load_response_definition(
+    sensor_unit_id: str,
+    band_id: str,
+    representation_variant: str | None = None,
+    *,
+    root: Path | None = None,
+) -> SampledCurve | BandSpec:
+    """Load either a sampled curve or a canonical band spec for a band."""
+
+    sensor_row = _resolve_sensor_variant(
+        sensor_unit_id,
+        representation_variant,
+        root=root,
+    )
+    resolved_variant = str(sensor_row["representation_variant"])
+    content_kind = ContentKind(str(sensor_row["content_kind"]))
+    if content_kind == ContentKind.SAMPLED_CURVE:
+        return load_curve(sensor_unit_id, band_id, resolved_variant, root=root)
+    if content_kind == ContentKind.BAND_SPEC:
+        return load_band_spec(sensor_unit_id, band_id, resolved_variant, root=root)
+    raise NotImplementedError(f"content_kind not supported: {content_kind.value}")
+
+
+def _resolve_sensor_variant(
+    sensor_unit_id: str,
+    representation_variant: str | None,
+    *,
+    root: Path | None = None,
+) -> Any:
+    sensors = _available_sensor_rows(root)
+    frame = sensors[sensors["sensor_unit_id"] == sensor_unit_id]
+    if representation_variant is not None:
+        frame = frame[frame["representation_variant"] == representation_variant]
+    if frame.empty:
+        raise KeyError(f"sensor representation not found: {sensor_unit_id}/{representation_variant}")
+    if len(frame) > 1:
+        raise ValueError(
+            f"multiple representations found for {sensor_unit_id}; representation_variant is required"
+        )
+    return frame.iloc[0]
+
+
+def _lookup_band_registry_row(
+    sensor_unit_id: str,
+    band_id: str,
+    representation_variant: str,
+    *,
+    root: Path | None = None,
+):
+    frame = read_registry_table(root, "bands")
+    frame = frame[
+        (frame["sensor_unit_id"] == sensor_unit_id)
+        & (frame["representation_variant"] == representation_variant)
+        & (frame["band_id"] == band_id)
+    ]
+    if frame.empty:
+        return None
+    if "band_index" in frame.columns:
+        frame = frame.sort_values(["band_index", "band_id"], na_position="last")
+    return frame.iloc[0]
+
+
+def _available_sensor_rows(root: Path | None):
+    frame = read_registry_table(root, "sensors")
+    mask = frame.apply(_row_has_backing_artifact, axis=1, root=root)
+    return frame[mask].copy()
+
+
+def _row_has_backing_artifact(row, *, root: Path | None) -> bool:
+    content_kind = ContentKind(str(row["content_kind"]))
+    artifact_name = _primary_artifact_name(content_kind)
+    if artifact_name is None:
+        return False
+    artifact_path = _representation_dir(root, row) / artifact_name
+    return artifact_path.exists()
+
+
+def _representation_dir(root: Path | None, row) -> Path:
+    return representation_variant_dir(
+        root,
+        sensor_unit_id=str(row["sensor_unit_id"]),
+        representation_variant=str(row["representation_variant"]),
+        content_kind=str(row["content_kind"]),
+        realization_kind=str(row.get("realization_kind", "none")),
+    )
+
+
+def _primary_artifact_name(content_kind: ContentKind) -> str | None:
+    if content_kind == ContentKind.SAMPLED_CURVE:
+        return "curves.parquet"
+    if content_kind == ContentKind.BAND_SPEC:
+        return "band_specs.parquet"
+    return None
+
+
+def _is_nullish(value: Any) -> bool:
+    return value is None or value != value
+
+
+def _read_parquet(path: Path):
+    try:
+        import pandas as pd
+    except ImportError as exc:
+        raise RuntimeError("pandas is required for read API operations") from exc
+
+    return pd.read_parquet(path)

rsrf/band_specs.py

@@ -0,0 +1,47 @@
+"""Helpers for metadata-only band specifications."""
+
+from __future__ import annotations
+
+from .models import BandSpec
+
+
+def default_band_id(band_index: int) -> str:
+    """Build a stable band identifier for unnamed hyperspectral bands."""
+
+    if band_index < 0:
+        raise ValueError("band_index must be non-negative")
+    return f"B{band_index:03d}"
+
+
+def build_band_spec(
+    center_wavelength_nm: float,
+    fwhm_nm: float,
+    *,
+    band_index: int | None = None,
+    band_id: str | None = None,
+    band_name: str | None = None,
+    band_status: str = "nominal",
+    published_shape_type: str = "unknown",
+) -> BandSpec:
+    """Create a bootstrap band specification."""
+
+    if center_wavelength_nm <= 0:
+        raise ValueError("center_wavelength_nm must be positive")
+    if fwhm_nm <= 0:
+        raise ValueError("fwhm_nm must be positive")
+
+    resolved_band_id = band_id
+    if resolved_band_id is None:
+        if band_index is None:
+            raise ValueError("band_id or band_index must be provided")
+        resolved_band_id = default_band_id(band_index)
+
+    return BandSpec(
+        band_id=resolved_band_id,
+        center_wavelength_nm=center_wavelength_nm,
+        fwhm_nm=fwhm_nm,
+        band_index=band_index,
+        band_name=band_name,
+        band_status=band_status,
+        published_shape_type=published_shape_type,
+    )

rsrf/cli.py

@@ -0,0 +1,6 @@
+"""Compatibility wrapper for the CLI entrypoint."""
+
+from .commands.app import main
+from .commands.parser import build_parser
+
+__all__ = ["build_parser", "main"]

rsrf/commands/__init__.py

@@ -0,0 +1,6 @@
+"""CLI application package."""
+
+from .app import main
+from .parser import build_parser
+
+__all__ = ["build_parser", "main"]

rsrf/commands/app.py

@@ -0,0 +1,49 @@
+"""Application entrypoint for the ``rsrf`` CLI."""
+
+from __future__ import annotations
+
+from typing import Callable, Sequence
+
+from .handlers import (
+    handle_export_validation,
+    handle_list_bands,
+    handle_list_planned_sensors,
+    handle_list_sensors,
+    handle_register_manifest,
+    handle_register_planned_sensors,
+    handle_show_layout,
+    handle_show_metadata,
+    handle_show_registry_rows,
+    handle_show_response,
+    handle_validate_manifest,
+    handle_validate_sensor,
+)
+from .parser import build_parser
+
+COMMAND_HANDLERS: dict[str, Callable[..., int]] = {
+    "show-layout": handle_show_layout,
+    "list-sensors": handle_list_sensors,
+    "list-planned-sensors": handle_list_planned_sensors,
+    "list-bands": handle_list_bands,
+    "show-metadata": handle_show_metadata,
+    "show-response": handle_show_response,
+    "validate-sensor": handle_validate_sensor,
+    "export-validation": handle_export_validation,
+    "validate-manifest": handle_validate_manifest,
+    "show-registry-rows": handle_show_registry_rows,
+    "register-manifest": handle_register_manifest,
+    "register-planned-sensors": handle_register_planned_sensors,
+}
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI."""
+
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    handler = COMMAND_HANDLERS.get(args.command)
+    if handler is None:
+        parser.print_help()
+        return 0
+    return handler(args)

rsrf/commands/handlers.py

@@ -0,0 +1,213 @@
+"""Command handlers for the ``rsrf`` CLI."""
+
+from __future__ import annotations
+
+from argparse import Namespace
+from pathlib import Path
+
+from ..api import get_metadata, list_bands, list_sensors, load_response_definition
+from ..models import ManifestSummary, ManifestValidationError
+from ..planning import list_planned_sensors, register_planned_sensor_catalog
+from ..qa import validate_sensor, write_validation_artifacts
+from ..registry import build_repo_layout, manifest_registry_rows, register_manifest
+from ..validate import parse_manifest_file
+from .render import (
+    exception_message,
+    print_json,
+    print_manifest_errors,
+    summarize_response_definition,
+)
+
+
+def handle_show_layout(args: Namespace) -> int:
+    layout = build_repo_layout(args.root)
+    entries = {
+        "root": layout.root,
+        "package_root": layout.package_root,
+        "registry_root": layout.registry_root,
+        "canonical_root": layout.canonical_root,
+        "realized_root": layout.realized_root,
+        "common_grid_root": layout.common_grid_root,
+        "source_manifests_root": layout.source_manifests_root,
+        "official_source_manifests_root": layout.official_source_manifests_root,
+        "planning_source_manifests_root": layout.planning_source_manifests_root,
+        "template_source_manifests_root": layout.template_source_manifests_root,
+        "ingest_scripts_root": layout.ingest_scripts_root,
+        "tests_root": layout.tests_root,
+    }
+    for label, path in entries.items():
+        print(f"{label}: {path}")
+    return 0
+
+
+def handle_list_sensors(args: Namespace) -> int:
+    try:
+        sensors = list_sensors(root=args.root)
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
+        print(exception_message(exc))
+        return 1
+    return print_json(sensors)
+
+
+def handle_list_planned_sensors(args: Namespace) -> int:
+    try:
+        sensors = list_planned_sensors(root=args.root, catalog_path=args.catalog_path)
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
+        print(exception_message(exc))
+        return 1
+    return print_json(sensors)
+
+
+def handle_list_bands(args: Namespace) -> int:
+    try:
+        bands = list_bands(
+            args.sensor_unit_id,
+            args.representation_variant,
+            root=args.root,
+        )
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
+        print(exception_message(exc))
+        return 1
+    return print_json(bands)
+
+
+def handle_show_metadata(args: Namespace) -> int:
+    try:
+        metadata = get_metadata(
+            args.sensor_unit_id,
+            args.representation_variant,
+            root=args.root,
+        )
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
+        print(exception_message(exc))
+        return 1
+    return print_json(metadata)
+
+
+def handle_show_response(args: Namespace) -> int:
+    try:
+        metadata = get_metadata(
+            args.sensor_unit_id,
+            args.representation_variant,
+            root=args.root,
+        )
+        resolved_variant = str(metadata["representation_variant"])
+        response_definition = load_response_definition(
+            args.sensor_unit_id,
+            args.band_id,
+            resolved_variant,
+            root=args.root,
+        )
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
+        print(exception_message(exc))
+        return 1
+
+    payload = summarize_response_definition(
+        args.sensor_unit_id,
+        resolved_variant,
+        response_definition,
+    )
+    return print_json(payload)
+
+
+def handle_validate_sensor(args: Namespace) -> int:
+    try:
+        report = validate_sensor(
+            args.sensor_unit_id,
+            args.representation_variant,
+            root=args.root,
+        )
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError, NotImplementedError) as exc:
+        print(exception_message(exc))
+        return 1
+    print_json(report)
+    return 0 if report.get("passed") else 1
+
+
+def handle_export_validation(args: Namespace) -> int:
+    try:
+        written = write_validation_artifacts(
+            args.sensor_unit_id,
+            args.representation_variant,
+            root=args.root,
+            output_dir=args.output_dir,
+        )
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError, NotImplementedError) as exc:
+        print(exception_message(exc))
+        return 1
+    for label, path in written.items():
+        print(f"{label}: {path}")
+    return 0
+
+
+def handle_validate_manifest(args: Namespace) -> int:
+    manifest_path = Path(args.manifest_path)
+    try:
+        manifest = parse_manifest_file(manifest_path, root=args.root)
+    except ManifestValidationError as exc:
+        return print_manifest_errors(manifest_path, exc.errors)
+
+    summary = ManifestSummary.from_manifest(manifest)
+    print(
+        "Manifest OK: "
+        f"{summary.sensor_unit_id} "
+        f"[{summary.representation_variant}] "
+        f"{summary.content_kind} "
+        f"(tier {summary.source_tier})"
+    )
+    return 0
+
+
+def handle_show_registry_rows(args: Namespace) -> int:
+    manifest_path = Path(args.manifest_path)
+    try:
+        manifest = parse_manifest_file(manifest_path, root=args.root)
+    except ManifestValidationError as exc:
+        return print_manifest_errors(manifest_path, exc.errors)
+
+    rows = manifest_registry_rows(manifest)
+    for table_name, table_rows in rows.items():
+        print(f"[{table_name}]")
+        if not table_rows:
+            print("[]")
+            continue
+        for row in table_rows:
+            print_json(dict(row))
+    return 0
+
+
+def handle_register_manifest(args: Namespace) -> int:
+    manifest_path = Path(args.manifest_path)
+    try:
+        manifest = parse_manifest_file(manifest_path, root=args.root)
+    except ManifestValidationError as exc:
+        return print_manifest_errors(manifest_path, exc.errors)
+
+    try:
+        written = register_manifest(args.root, manifest)
+    except RuntimeError as exc:
+        print(str(exc))
+        return 1
+
+    if not written:
+        print("No registry rows were written.")
+        return 0
+
+    for table_name, path in written.items():
+        print(f"{table_name}: {path}")
+    return 0
+
+
+def handle_register_planned_sensors(args: Namespace) -> int:
+    try:
+        written = register_planned_sensor_catalog(root=args.root, catalog_path=args.catalog_path)
+    except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
+        print(exception_message(exc))
+        return 1
+
+    if written is None:
+        print("No planned sensor rows were written.")
+        return 0
+
+    print(f"sensors: {written}")
+    return 0