lunar_toolkit.lroc.nac

LROC NAC images: metadata, download and the ISIS + GDAL processing pipeline.

IndexColumn(column, cast)

Bases: Generic[_V]

Read-only NacImage attribute holding one CUMINDEX column.

The value is converted by cast; None when the column is missing or null.

NacImage(product_id, cumindex=None, _row=None)

A single LROC NAC (or WAC) image identified by its PDS product ID.

Product ID anatomy::

M 1096757719 L E
             │ └── type: E = EDR,  C = CDR
             └──── side: L = left, R = right

Short base IDs (M1096757719L) are automatically normalized to EDR (M1096757719LE). The correct CumIndex dataset is auto-detected from the type suffix, so no manual dataset selection is needed.

Parameters:
  • product_id (str) –

    Full or short NAC/WAC product ID, e.g. "M1524360231LE", "M1524360231L", or "M1524360231LC".

  • cumindex (CumIndex, default: None ) –

    Pre-built CumIndex instance to reuse. If None, one is constructed lazily on first metadata access (dataset auto-detected from suffix).

  • _row (Series, default: None ) –

    Pre-populated metadata row from a bulk CumIndex.get_images() call. Avoids a per-image database round-trip.

side property

"L" for left NAC, "R" for right NAC, None for WAC.

product_type property

"edr" for LE/RE, "cdr" for LC/RC, None for WAC.

edr_id property

Product ID for the EDR version of this observation (e.g. M...LE).

cdr_id property

Product ID for the CDR version of this observation (e.g. M...LC).

pair_id property

Product ID of the stereo sibling (L↔R, same type suffix). None for WAC.

has_pair property

True if the stereo sibling exists in the EDR index (DB check).

pair property

The stereo sibling as a NacImage, or None if not in the index.

slew_angle = IndexColumn('SLEW_ANGLE', float) class-attribute instance-attribute

Off-nadir slew angle (degrees). Equivalent to emission_angle.

pixel_scale = IndexColumn('RESOLUTION', float) class-attribute instance-attribute

Ground-sample distance in metres/pixel.

emission_angle = IndexColumn('EMISSION_ANGLE', float) class-attribute instance-attribute

Off-nadir emission angle (degrees). Same as slew_angle.

solar_distance = IndexColumn('SOLAR_DISTANCE', float) class-attribute instance-attribute

Distance from the Sun in km.

spacecraft_altitude = IndexColumn('SPACECRAFT_ALTITUDE', float) class-attribute instance-attribute

Spacecraft altitude above the lunar surface in km.

target_center_distance = IndexColumn('TARGET_CENTER_DISTANCE', float) class-attribute instance-attribute

Distance from spacecraft to lunar centre in km.

edr_url property

PDS URL for the raw EDR .IMG file.

cdr_url property

PDS URL for the calibrated CDR .IMG file (requires CDR database).

metadata_items()

Return (label, value) pairs for all available metadata fields.

Used by the CLI query command and the GUI — single source of truth for both ordering and human-readable labels.

download_edr(output_dir, force=False)

Download the raw EDR to <output_dir>/<edr_id>.IMG.

download_cdr(output_dir, force=False)

Download the calibrated CDR to <output_dir>/<cdr_id>.IMG (requires the CDR database).

process(output_dir, **kwargs)

Run the ISIS + GDAL pipeline on the EDR, returning the GeoTIFF.

kwargs are NacProcessor options (projection, resolution, web, keep, force).

to_png(output_dir, input_path)

Convert an image (e.g. a GeoTIFF from process) to <output_dir>/<id>.png.

show(input_path)

Display an image file of this product inline (Jupyter / matplotlib).

NacImageCollection(images)

An ordered collection of NacImages with bulk download and processing.

Returned by CumIndex.get_images(). Behaves like a list but also exposes bulk operations that parallelise across images.

from_sources(sources, data_dir=None) classmethod

Build a collection from product IDs or local .IMG paths.

Raw HTTP(S) URLs are skipped — use PdsDownloader for those. Automatically routes LE/RE → EDR index, LC/RC → CDR index. IDs not found in the index are silently excluded.

to_dataframe()

Return a DataFrame with one row per image (all metadata columns).

download_edrs(output_dir, workers=4, force=False)

Download all EDR .IMG files in parallel.

Returns a dict mapping product_id → local Path (or None on failure).

download_cdrs(output_dir, workers=4, force=False)

Download all CDR .IMG files in parallel (requires CDR database).

process(output_dir, workers=4, **kwargs)

Run the ISIS + GDAL pipeline on all EDRs in parallel.

kwargs are NacProcessor options. Returns a dict mapping product_id → GeoTIFF Path (or None on failure).

to_pngs(output_dir, input_paths, workers=4)

Convert a set of TIFs to PNGs via gdal_translate in parallel.

Parameters:
  • output_dir (Path) –
  • input_paths (dict[str, Path]) –

    Mapping of product_id → source TIF path (e.g. from download_cdrs()).

  • workers (int, default: 4 ) –
Returns:
  • dict mapping product_id → PNG Path (or None on failure). –

NacProcessor(output_dir=Path('data'), *, web=True, projection=DEFAULT_PROJECTION, resolution=None, keep=False, force=False)

Download, calibrate and map-project LROC NAC EDRs into GeoTIFFs.

Each image ends up in output_dir as <id>.tif (map-projected I/F, GEOTIFF_OPTIONS). Intermediates (a downloaded <id>.IMG, <id>.cal.echo.cub, <id>.map.cub) are written beside it and removed after success unless keep; after a failure they stay, so a re-run resumes. Steps whose output exists are skipped unless force.

Parameters:
  • output_dir (Path, default: Path('data') ) –

    Where downloads, cubes and GeoTIFFs are written.

  • web (bool, default: True ) –

    Use the USGS SPICE web service in spiceinit.

  • projection (str, default: DEFAULT_PROJECTION ) –

    ISIS projection for mosrange (default: equirectangular).

  • resolution (float, default: None ) –

    Map resolution in m/pixel (default: mosrange's estimate).

  • keep (bool, default: False ) –

    Keep the downloaded EDR and the intermediate cubes.

  • force (bool, default: False ) –

    Redo every step even when its output exists.

process(source)

Process one EDR (local .IMG path or HTTP(S) URL); returns the GeoTIFF.

process_batch(sources, max_workers=4)

Process several images in parallel (None for failures).

to_png(src, dst)

Convert an image to an 8-bit, min/max-scaled PNG with gdal_translate.