lunar_toolkit.config

Flat YAML run configuration for lunar sfs: load, validate, merge, resolve regions and dump.

RUNS_DIR_ENV = 'LUNAR_RUNS_DIR' module-attribute

dem: pgda (or no dem with a region): the region's PGDA LOLA 5 m surf DEM.

ConfigError

Bases: ValueError

An invalid configuration: unknown key, wrong type or inconsistent settings.

RunConfig(work_dir=Path('sfs_work'), runs_dir=None, dem=None, region=None, crop_km=None, crop_center=None, aoi=None, sources=list(), from_file=None, max_slew=None, max_pixel_scale=1.5, max_images=None, pgda_dir=None, data_dir=None, checksums=True, sfs=SfsConfig()) dataclass

Everything a lunar sfs run needs: inputs, region and the SfsConfig.

In YAML the run keys below and the SfsConfig fields share one flat mapping. Relative paths are relative to the current directory.

Parameters:
  • work_dir (Path, default: Path('sfs_work') ) –

    Run directory; a relative path is taken under runs_dir.

  • runs_dir (Path, default: None ) –

    Where relative work_dir paths live (default: $LUNAR_RUNS_DIR, else the current directory). Working / output directory.

  • dem (str, default: None ) –

    Prior DEM path, or "pgda" for the region's PGDA LOLA 5 m DEM (the default with a region).

  • region (str or int, default: None ) –

    Artemis III region (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, default: None ) –

    Side of a square window at the region centre (crop_window).

  • crop_center ((lat, lon), default: None ) –

    Centre of that window (default: the ROI centre).

  • aoi (str, default: None ) –

    AOI (GeoJSON / WKT file or WKT) for the image search and, without projwin, the crop.

  • sources (list of str, default: list() ) –

    NAC product IDs or .IMG / .cub paths (default: search the AOI).

  • from_file (Path, default: None ) –

    Text file of more sources, one per line.

  • max_slew (float, default: None ) –

    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_pixel_scale (float, default: None ) –

    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, default: None ) –

    Cap on the searched images before download (stereo pairs + illumination coverage; lunar_toolkit.sfs.cap_candidates).

  • pgda_dir (Path, default: None ) –

    Where PGDA files are downloaded (default: the reference cache).

  • data_dir (Path, default: None ) –

    Parquet index directory.

  • checksums (bool, default: True ) –

    MD5 the input files (under 2 GB) in provenance.json.

  • sfs (SfsConfig, default: SfsConfig() ) –

from_dict(data, source='config')

A validated RunConfig from a flat mapping (keys as in KEYS).

Raises:
  • ConfigError –

    For unknown keys (with suggestions), wrong types and invalid choices.

to_dict(cfg)

Flat, YAML / JSON-ready mapping of every setting (run keys first).

merge(cfg, overrides, source='overrides')

cfg with overrides applied; option dicts are merged key by key, other values replaced.

load_config(path)

Read and validate a YAML config (an empty file gives the defaults).

dump_config(cfg, path=None)

YAML text of every setting (written to path when given).

config_hash(cfg)

SHA-256 of the settings (canonical JSON of to_dict).

pgda_file(region, kind, out_dir=None, download=True)

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.

region_id(region)

Bertone et al. product prefix of a region, e.g. A311 for Malapert Massif.

resolve(cfg, download=True)

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.

search_aoi(cfg)

Image-search AOI: aoi, else the region crop (projwin as lon/lat WKT), else None.

load_sources(cfg)

sources plus the non-comment lines of from_file.