lunar-toolkit 0.1.0.dev2__py3-none-any.whl

lunar_toolkit/config.py

@@ -0,0 +1,345 @@
+"""Flat YAML run configuration for ``lunar sfs``: load, validate, merge, resolve regions and dump."""
+
+from __future__ import annotations
+
+import dataclasses
+import difflib
+import hashlib
+import json
+import logging
+import os
+import types
+import typing
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+
+from .sfs import SfsConfig
+
+log = logging.getLogger(__name__)
+
+PGDA = "pgda"
+RUNS_DIR_ENV = "LUNAR_RUNS_DIR"
+"""``dem: pgda`` (or no ``dem`` with a ``region``): the region's PGDA LOLA 5 m ``surf`` DEM."""
+
+OPTION_KEYS = ("bundle_adjust_options", "refine_options", "sfs_options")
+FLOW_KEYS = ("projwin", "stereo_convergence", "crop_center")
+
+
+class ConfigError(ValueError):
+    """An invalid configuration: unknown key, wrong type or inconsistent settings."""
+
+
+@dataclass
+class RunConfig:
+    """Everything a ``lunar sfs`` run needs: inputs, region and the :class:`SfsConfig`.
+
+    In YAML the run keys below and the :class:`SfsConfig` fields share one flat
+    mapping.  Relative paths are relative to the current directory.
+
+    Parameters
+    ----------
+    work_dir : Path
+        Run directory; a relative path is taken under *runs_dir*.
+    runs_dir : Path, optional
+        Where relative ``work_dir`` paths live (default: ``$LUNAR_RUNS_DIR``, else the
+        current directory).
+        Working / output directory.
+    dem : str, optional
+        Prior DEM path, or ``"pgda"`` for the region's PGDA LOLA 5 m DEM (the
+        default with a *region*).
+    region : str or int, optional
+        Artemis III region (:func:`lunar_toolkit.reference.get_region`): sets
+        the ``projwin`` (its ROI, or a *crop_km* window), ``region_id`` and the
+        image search AOI.
+    crop_km : float, optional
+        Side of a square window at the region centre (:func:`~lunar_toolkit.reference.crop_window`).
+    crop_center : (lat, lon), optional
+        Centre of that window (default: the ROI centre).
+    aoi : str, optional
+        AOI (GeoJSON / WKT file or WKT) for the image search and, without
+        ``projwin``, the crop.
+    sources : list of str
+        NAC product IDs or ``.IMG`` / ``.cub`` paths (default: search the AOI).
+    from_file : Path, optional
+        Text file of more sources, one per line.
+    max_slew, max_pixel_scale : float, optional
+        Image search cuts (deg, m/px).  No slew cut by default: slewed images give the
+        stereo convergence for registration, and ``max_sfs_slew`` keeps them out of SfS.
+    max_images : int, optional
+        Cap on the searched images before download (stereo pairs + illumination coverage;
+        :func:`lunar_toolkit.sfs.cap_candidates`).
+    pgda_dir : Path, optional
+        Where PGDA files are downloaded (default: the reference cache).
+    data_dir : Path, optional
+        Parquet index directory.
+    checksums : bool
+        MD5 the input files (under 2 GB) in ``provenance.json``.
+    sfs : SfsConfig
+    """
+
+    work_dir: Path = Path("sfs_work")
+    runs_dir: Path | None = None
+    dem: str | None = None
+    region: str | int | None = None
+    crop_km: float | None = None
+    crop_center: tuple[float, float] | None = None
+    aoi: str | None = None
+    sources: list[str] = field(default_factory=list)
+    from_file: Path | None = None
+    max_slew: float | None = None
+    max_pixel_scale: float | None = 1.5
+    max_images: int | None = None
+    pgda_dir: Path | None = None
+    data_dir: Path | None = None
+    checksums: bool = True
+    sfs: SfsConfig = field(default_factory=SfsConfig)
+
+
+def _hints(cls: type) -> dict[str, Any]:
+    names = [f.name for f in dataclasses.fields(cls)]
+    hints = typing.get_type_hints(cls)
+    return {n: hints[n] for n in names if n != "sfs"}
+
+
+RUN_KEYS: dict[str, Any] = _hints(RunConfig)
+SFS_KEYS: dict[str, Any] = _hints(SfsConfig)
+KEYS: dict[str, Any] = {**RUN_KEYS, **SFS_KEYS}
+
+
+def _describe(hint: Any) -> str:
+    if typing.get_origin(hint) in (Union, types.UnionType):
+        return " or ".join(_describe(a) for a in typing.get_args(hint))
+    origin, args = typing.get_origin(hint), typing.get_args(hint)
+    if origin is tuple:
+        return f"list of {len(args)} {_describe(args[0])}s"
+    if origin is list:
+        return f"list of {_describe(args[0])}s"
+    if origin is dict:
+        return "mapping"
+    names = {bool: "boolean", int: "integer", float: "number", str: "string", Path: "path"}
+    return "null" if hint is type(None) else names.get(hint, str(hint))
+
+
+def _coerce(key: str, value: Any, hint: Any) -> Any:
+    origin, args = typing.get_origin(hint), typing.get_args(hint)
+    if hint is Any:
+        return value
+    if origin in (Union, types.UnionType):
+        if value is None and type(None) in args:
+            return None
+        for arm in args:
+            if arm is not type(None):
+                try:
+                    return _coerce(key, value, arm)
+                except ConfigError:
+                    pass
+    elif hint is bool and isinstance(value, bool):
+        return value
+    elif hint is int and isinstance(value, int) and not isinstance(value, bool):
+        return value
+    elif hint is float and isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    elif hint is str and isinstance(value, str):
+        return value
+    elif hint is Path and isinstance(value, (str, Path)):
+        return Path(value)
+    elif origin is tuple and isinstance(value, (list, tuple)) and len(value) == len(args):
+        return tuple(_coerce(key, v, a) for v, a in zip(value, args))
+    elif origin is list and isinstance(value, (list, tuple)):
+        return [_coerce(key, v, args[0]) for v in value]
+    elif origin is dict and isinstance(value, Mapping) and all(isinstance(k, str) for k in value):
+        return {k.replace("-", "_"): v for k, v in value.items()}
+    raise ConfigError(f"{key}: expected {_describe(hint)}, got {value!r}")
+
+
+def from_dict(data: Mapping[str, Any], source: str = "config") -> RunConfig:
+    """A validated :class:`RunConfig` from a flat mapping (keys as in :data:`KEYS`).
+
+    Raises
+    ------
+    ConfigError
+        For unknown keys (with suggestions), wrong types and invalid choices.
+    """
+    if not isinstance(data, Mapping):
+        raise ConfigError(f"{source}: expected a mapping of settings, got {type(data).__name__}")
+    norm = {str(k).replace("-", "_"): v for k, v in data.items()}
+    for key in norm:
+        if key not in KEYS:
+            close = difflib.get_close_matches(key, list(KEYS), n=1)
+            hint = f" (did you mean {close[0]!r}?)" if close else ""
+            raise ConfigError(f"{source}: unknown key {key!r}{hint}")
+    try:
+        values = {k: _coerce(k, v, KEYS[k]) for k, v in norm.items()}
+    except ConfigError as exc:
+        raise ConfigError(f"{source}: {exc}") from None
+    try:
+        sfs = SfsConfig(**{k: v for k, v in values.items() if k in SFS_KEYS})
+    except ValueError as exc:
+        raise ConfigError(f"{source}: {exc}") from None
+    return RunConfig(**{k: v for k, v in values.items() if k in RUN_KEYS}, sfs=sfs)
+
+
+def _plain(value: Any) -> Any:
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, (list, tuple)):
+        return [_plain(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _plain(v) for k, v in value.items()}
+    return value
+
+
+def to_dict(cfg: RunConfig) -> dict[str, Any]:
+    """Flat, YAML / JSON-ready mapping of every setting (run keys first)."""
+    out = {k: _plain(getattr(cfg, k)) for k in RUN_KEYS}
+    out.update({k: _plain(getattr(cfg.sfs, k)) for k in SFS_KEYS})
+    return out
+
+
+def merge(cfg: RunConfig, overrides: Mapping[str, Any], source: str = "overrides") -> RunConfig:
+    """*cfg* with *overrides* applied; option dicts are merged key by key, other values replaced."""
+    data = to_dict(cfg)
+    for key, value in overrides.items():
+        key = key.replace("-", "_")
+        if key in OPTION_KEYS and isinstance(value, Mapping) and isinstance(data.get(key), dict):
+            data[key] = {**data[key], **value}
+        else:
+            data[key] = value
+    return from_dict(data, source)
+
+
+def load_config(path: Path) -> RunConfig:
+    """Read and validate a YAML config (an empty file gives the defaults)."""
+    path = Path(path)
+    try:
+        data = yaml.safe_load(path.read_text())
+    except OSError as exc:
+        raise ConfigError(f"Cannot read config {path}: {exc.strerror or exc}") from None
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML: {exc}") from None
+    return from_dict(data if data is not None else {}, str(path))
+
+
+def dump_config(cfg: RunConfig, path: Path | None = None) -> str:
+    """YAML text of every setting (written to *path* when given)."""
+    from .constants import APP_VERSION
+
+    lines = [f"# lunar sfs configuration (lunar-toolkit {APP_VERSION})\n"]
+    for key, value in to_dict(cfg).items():
+        if key == next(iter(SFS_KEYS)):
+            lines.append("\n# SfS pipeline settings (lunar_toolkit.sfs.SfsConfig)\n")
+        if key in FLOW_KEYS or (isinstance(value, (list, dict)) and not value):
+            flow = yaml.safe_dump(value, default_flow_style=True, width=10**6).strip()
+            lines.append(f"{key}: {flow.removesuffix('...').strip()}\n")
+        else:
+            lines.append(yaml.safe_dump({key: value}, default_flow_style=False, sort_keys=False, width=110))
+    text = "".join(lines)
+    if path is not None:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        Path(path).write_text(text)
+    return text
+
+
+def config_hash(cfg: RunConfig) -> str:
+    """SHA-256 of the settings (canonical JSON of :func:`to_dict`)."""
+    return hashlib.sha256(json.dumps(to_dict(cfg), sort_keys=True).encode()).hexdigest()
+
+
+def pgda_file(region: Any, kind: str, out_dir: Path | None = None, download: bool = True) -> Path:
+    """Local path of a region's PGDA LOLA 5 m raster (``surf``, ``ldec``, ``toterr``, ...).
+
+    Downloaded into ``out_dir/<site>/`` when missing and *download*; otherwise the
+    expected path (``<site>_final_adj_5mpp_<kind>.tif``, ``<site>_final_adj.xyzi``)
+    is returned without touching the network or the disk.
+    """
+    from . import reference as ref
+
+    site = ref._site_name(region)
+    out_dir = Path(out_dir) if out_dir else ref.REFERENCE_CACHE_DIR / "pgda"
+    name = f"{site}_final_adj.xyzi" if kind == "xyzi" else f"{site}_final_adj_5mpp_{kind}.tif"
+    expected = out_dir / site / name
+    if expected.exists() or not download:
+        return expected
+    files = ref.download_pgda(site, [kind], out_dir)[kind]
+    if not files:
+        raise ConfigError(f"PGDA site {site} has no {kind} file")
+    return files[0]
+
+
+def region_id(region: Any) -> str:
+    """Bertone et al. product prefix of a region, e.g. ``A311`` for Malapert Massif."""
+    from . import reference as ref
+
+    return f"A3{ref.get_region(region).id:02d}"
+
+
+def resolve(cfg: RunConfig, download: bool = True) -> RunConfig:
+    """Fill what *region* implies: ``projwin``, ``region_id`` and the PGDA prior DEM.
+
+    An explicit ``projwin`` wins, then ``aoi`` (the crop is computed from it at run
+    time), then a ``crop_km`` window, then the region ROI.  ``dem: pgda`` (or none)
+    is the region's PGDA ``surf`` DEM, downloaded when missing and *download*.
+
+    Raises
+    ------
+    ConfigError
+        For a ``crop_km`` / ``dem: pgda`` without a region, or an unknown region.
+    """
+    from . import reference as ref
+
+    runs_dir = cfg.runs_dir or (Path(os.environ[RUNS_DIR_ENV]) if os.environ.get(RUNS_DIR_ENV) else None)
+    if runs_dir is not None and not Path(cfg.work_dir).is_absolute():
+        cfg = merge(cfg, {"work_dir": str(Path(runs_dir).expanduser() / cfg.work_dir), "runs_dir": None})
+    if cfg.region is None:
+        if cfg.crop_km is not None or cfg.crop_center is not None:
+            raise ConfigError("crop_km / crop_center need a region")
+        if cfg.dem == PGDA:
+            raise ConfigError("dem: pgda needs a region")
+        return cfg
+    try:
+        reg = ref.get_region(cfg.region)
+    except KeyError as exc:
+        raise ConfigError(f"region: {exc.args[0]}") from None
+    changes: dict[str, Any] = {}
+    if cfg.sfs.projwin is None and cfg.aoi is None:
+        if cfg.crop_km is not None:
+            box = ref.crop_window(reg, cfg.crop_km, cfg.crop_center)
+        else:
+            box = reg.roi
+        changes["projwin"] = box.projwin
+    if cfg.sfs.region_id is None:
+        changes["region_id"] = region_id(reg)
+    if cfg.dem in (None, PGDA):
+        try:
+            changes["dem"] = str(pgda_file(reg, "surf", cfg.pgda_dir, download=download))
+        except KeyError as exc:
+            raise ConfigError(f"dem: {exc.args[0]}") from None
+    return merge(cfg, changes, "region") if changes else cfg
+
+
+def search_aoi(cfg: RunConfig) -> str | None:
+    """Image-search AOI: ``aoi``, else the region crop (``projwin`` as lon/lat WKT), else None."""
+    from . import reference as ref
+
+    if cfg.aoi is not None:
+        return cfg.aoi
+    if cfg.region is None or cfg.sfs.projwin is None:
+        return None
+    ulx, uly, lrx, lry = cfg.sfs.projwin
+    return ref.PsBox(ulx, lry, lrx, uly).wkt()
+
+
+def load_sources(cfg: RunConfig) -> list[str]:
+    """``sources`` plus the non-comment lines of ``from_file``."""
+    sources = list(cfg.sources)
+    if cfg.from_file is not None:
+        try:
+            text = Path(cfg.from_file).read_text()
+        except OSError as exc:
+            raise ConfigError(f"from_file: cannot read {cfg.from_file}: {exc.strerror or exc}") from None
+        sources += [s.strip() for s in text.splitlines() if s.strip() and not s.strip().startswith("#")]
+    return sources

lunar_toolkit/constants.py

@@ -0,0 +1,217 @@
+"""App name, data directories, PDS LROC archive URLs, datasets and shared defaults."""
+
+import os
+import re
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+# Application name used for the user data / cache directories and the HTTP
+# User-Agent.  The only place the package name is spelled out at runtime.
+APP_NAME = "lunar_toolkit"
+try:
+    APP_VERSION = version("lunar-toolkit")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    APP_VERSION = "0.0.0"
+
+# PDS archive roots
+# The LROC SOC host (https://pds.lroc.im-ldi.com/data/<DATA_SET_ID>/...) now
+# 302-redirects to the PDS Imaging Node S3 store below.  Dataset directories
+# there are lowercase and drop the "-V1.0" suffix, e.g.
+#   https://pds.lroc.im-ldi.com/data/LRO-L-LROC-2-EDR-V1.0/LROLRC_0066C/INDEX/
+#   → https://pds.mcp.nasa.gov/data/store/img/lunar_reconnaissance_orbiter/
+#       pds4/lroc/lro-l-lroc-2-edr/LROLRC_0066C/INDEX/
+
+LEGACY_PDS_BASE_URL = "https://pds.lroc.im-ldi.com/data/"
+
+PDS_STORE_URL = "https://pds.mcp.nasa.gov/data/store/img/"
+PDS_LROC_PREFIX = "lunar_reconnaissance_orbiter/pds4/lroc/"
+PDS_BASE_URL = PDS_STORE_URL + PDS_LROC_PREFIX
+
+EDR_DATASET = "lro-l-lroc-2-edr/"
+CDR_DATASET = "lro-l-lroc-3-cdr/"
+RDR_DATASET = "lro-l-lroc-5-rdr/"
+
+EDR_BASE_URL = PDS_BASE_URL + EDR_DATASET
+CDR_BASE_URL = PDS_BASE_URL + CDR_DATASET
+RDR_BASE_URL = PDS_BASE_URL + RDR_DATASET
+
+# Fallback releases — the newest volume is auto-discovered from the S3 listing
+# (see cumindex.discover_volumes); these are only used when that fails.
+EDR_LATEST_RELEASE = "LROLRC_0068A/"
+CDR_LATEST_RELEASE = "LROLRC_1068A/"
+RDR_LATEST_RELEASE = "LROLRC_2001/"
+
+INDEX_DIR = "INDEX/"
+
+CUMINDEX_LBL_FILENAME = "CUMINDEX.LBL"
+CUMINDEX_TAB_FILENAME = "CUMINDEX.TAB"
+VOLINDEX_LBL_FILENAME = "INDEX.LBL"
+VOLINDEX_TAB_FILENAME = "INDEX.TAB"
+
+# Dataset registry
+# Each entry drives CumIndex URL construction and the name of the parquet file
+# built by `lunar build-db <key>`.
+
+DATASETS: dict[str, dict] = {
+    "edr": {
+        "label": "EDR — Experiment Data Record (raw NAC/WAC images)",
+        "data_set_id": "LRO-L-LROC-2-EDR-V1.0",
+        "base_url": EDR_BASE_URL,
+        "release": EDR_LATEST_RELEASE,
+        "volume_re": r"LROLRC_0\d{3}[A-Z]?",
+        "index_dir": INDEX_DIR,
+        "lbl_filename": CUMINDEX_LBL_FILENAME,
+        "tab_filename": CUMINDEX_TAB_FILENAME,
+        "parquet": "cumindex_edr.parquet",
+    },
+    "cdr": {
+        "label": "CDR — Calibrated Data Record",
+        "data_set_id": "LRO-L-LROC-3-CDR-V1.0",
+        "base_url": CDR_BASE_URL,
+        "release": CDR_LATEST_RELEASE,
+        "volume_re": r"LROLRC_1\d{3}[A-Z]?",
+        "index_dir": INDEX_DIR,
+        "lbl_filename": CUMINDEX_LBL_FILENAME,
+        "tab_filename": CUMINDEX_TAB_FILENAME,
+        "parquet": "cumindex_cdr.parquet",
+    },
+    "rdr": {
+        "label": "RDR — Reduced Data Record (WAC mosaics, DEMs, etc.)",
+        "data_set_id": "LRO-L-LROC-5-RDR-V1.0",
+        "base_url": RDR_BASE_URL,
+        "release": RDR_LATEST_RELEASE,
+        "volume_re": r"LROLRC_2\d{3}[A-Z]?",
+        "index_dir": INDEX_DIR,
+        "lbl_filename": CUMINDEX_LBL_FILENAME,
+        "tab_filename": CUMINDEX_TAB_FILENAME,
+        "parquet": "cumindex_rdr.parquet",
+    },
+}
+
+# PDS URL helpers
+_LEGACY_DS_RE = re.compile(r"^(LRO-L-LROC-\d-[A-Z]+)-V\d+\.\d+$", re.IGNORECASE)
+
+
+def pds_url_from_file_spec(file_spec: str) -> str:
+    """Map a CUMINDEX ``FILE_SPECIFICATION_NAME`` to a download URL.
+
+    ``LRO-L-LROC-2-EDR-V1.0/LROLRC_0001/DATA/.../M101013931LE.IMG`` →
+    ``<PDS_BASE_URL>lro-l-lroc-2-edr/LROLRC_0001/DATA/.../M101013931LE.IMG``.
+    Paths without a dataset prefix are joined to ``PDS_BASE_URL`` unchanged.
+    """
+    spec = str(file_spec).strip().lstrip("/")
+    head, _, rest = spec.partition("/")
+    m = _LEGACY_DS_RE.match(head)
+    if m and rest:
+        return PDS_BASE_URL + m.group(1).lower() + "/" + rest
+    return PDS_BASE_URL + spec
+
+
+def modernize_pds_url(url: str) -> str:
+    """Rewrite a legacy ``pds.lroc.im-ldi.com/data/`` URL to the PDS store host.
+
+    Other URLs are returned unchanged.  (The legacy host still redirects, but
+    resolving up front saves a round-trip and keeps Range requests simple.)
+    """
+    if url.startswith(LEGACY_PDS_BASE_URL):
+        return pds_url_from_file_spec(url[len(LEGACY_PDS_BASE_URL) :])
+    return url
+
+
+# Data directory resolution
+# Environment variable overriding the data directory.
+DATA_DIR_ENV_VAR = "LUNAR_DATA_DIR"
+
+
+def _user_data_dir(app_name: str = APP_NAME) -> Path:
+    try:
+        from platformdirs import user_data_dir
+
+        return Path(user_data_dir(app_name, appauthor=False))
+    except ImportError:  # pragma: no cover - platformdirs is a declared dependency
+        base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+        return Path(base) / app_name
+
+
+def get_data_dir() -> Path:
+    """Directory where Parquet databases are stored.
+
+    ``LUNAR_DATA_DIR`` if set, else the per-user data directory
+    (``platformdirs.user_data_dir``), e.g. ``~/.local/share/lunar_toolkit``
+    on Linux (honours ``XDG_DATA_HOME``).
+    """
+    env = os.environ.get(DATA_DIR_ENV_VAR)
+    return Path(env) if env else _user_data_dir()
+
+
+def find_parquet(name: str, data_dir: Path | None = None) -> Path:
+    """Path of Parquet database *name* in *data_dir* (default: :func:`get_data_dir`)."""
+    return Path(data_dir or get_data_dir()) / name
+
+
+# User cache (raw TAB / LBL downloads)
+DEFAULT_CACHE_DIR = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / APP_NAME
+
+# Misc
+DEFAULT_PROJECTION = "equirectangular"
+
+# gdal_translate flags for map-projected GeoTIFFs: native values, lossless and tiled
+GEOTIFF_OPTIONS = ["-of", "GTiff", "-co", "COMPRESS=DEFLATE", "-co", "TILED=YES", "-co", "BIGTIFF=IF_SAFER"]
+
+# Mean lunar radius (km) used for polar stereographic footprints and searches
+MOON_RADIUS_KM = 1737.4
+
+# |latitude| above which footprints also get polar stereographic coordinates
+POLAR_LAT_THRESHOLD = 60.0
+
+# Index columns <corner>_LATITUDE / <corner>_LONGITUDE of a footprint, in ring order
+FOOTPRINT_CORNERS = ("UPPER_LEFT", "UPPER_RIGHT", "LOWER_RIGHT", "LOWER_LEFT")
+
+# NAC product IDs: <observation><side L/R><type E = EDR, C = CDR>; the short
+# base form (M1096757719L) omits the type
+NAC_ID_RE = re.compile(r"^([A-Z]\d{9,12})([LR])([EC]?)$", re.IGNORECASE)
+WAC_ID_RE = re.compile(r"^[A-Z]\d{9,12}[CMUV]E$", re.IGNORECASE)
+NAC_PRODUCT_TYPES = {"E": "edr", "C": "cdr"}
+NAC_SUFFIXES = ("LE", "RE", "LC", "RC")
+
+
+def parse_nac_id(product_id: str) -> tuple[str, str, str] | None:
+    """Split a NAC product ID into ``(observation, side, type)``.
+
+    ``"M1096757719LE"`` → ``("M1096757719", "L", "edr")``; a short base ID
+    (``"M1096757719L"``) gets type ``"edr"``.  None for anything else (WAC,
+    ShadowCam, …).
+    """
+    m = NAC_ID_RE.match(str(product_id).strip())
+    if m is None:
+        return None
+    obs, side, kind = m.groups()
+    return obs.upper(), side.upper(), NAC_PRODUCT_TYPES[(kind or "E").upper()]
+
+
+def nac_id(product_id: str, side: str | None = None, product_type: str | None = None) -> str | None:
+    """Full NAC product ID of *product_id*, optionally for another side / type.
+
+    ``nac_id("M1096757719L")`` → ``"M1096757719LE"``;
+    ``nac_id("M1096757719LE", side="R", product_type="cdr")`` → ``"M1096757719RC"``.
+    None when *product_id* is not a NAC ID.
+    """
+    parts = parse_nac_id(product_id)
+    if parts is None:
+        return None
+    obs, own_side, own_type = parts
+    letter = {v: k for k, v in NAC_PRODUCT_TYPES.items()}[(product_type or own_type).lower()]
+    return f"{obs}{(side or own_side).upper()}{letter}"
+
+
+def is_nac_id(product_id: str) -> bool:
+    """True for a full NAC product ID (``LE`` / ``RE`` / ``LC`` / ``RC``)."""
+    m = NAC_ID_RE.match(str(product_id).strip())
+    return bool(m and m.group(3))
+
+
+# SfS pipeline option values (lunar_toolkit.sfs.SfsConfig), here so the CLI stays light
+REGISTRATION_MODES = ("stereo", "residuals", "none")
+SELECTION_METHODS = ("coverage", "kmedoids", "image_subset", "all")
+CAMERA_SOURCES = ("ba", "published")
+SFS_CAMERA_MODELS = ("csm", "isis")