lunar_toolkit.sfs_report

Validation report of an SfS work dir: metrics, figures and HTML (Bertone et al. 2026, Sec. 3).

ReportInputs(work_dir, sfs_dem=None, prior_dem=None, region_id=None, resolution=None, shadow_threshold=None, max_offset_p85=None, ldec=None, toterr=None, slperr=None, ldem_slope=None, lola_points=None, lola_xyzi=None, published_dem=None, slope_edges=SLOPE_EDGES, slope_split=20.0, preview_size=800) dataclass

Files and settings of a report; anything None is discovered or its section skipped.

Parameters:
  • work_dir (Path) –

    An SfsPipeline work directory.

  • sfs_dem (Path, default: None ) –

    Default products/<ROI>_GLDELEV_<RES>.tif (else sfs/run-DEM-final.tif) and dem/prior-<RES>m.tif.

  • prior_dem (Path, default: None ) –

    Default products/<ROI>_GLDELEV_<RES>.tif (else sfs/run-DEM-final.tif) and dem/prior-<RES>m.tif.

  • region_id (optional, default: None ) –

    Product name parts (default: config.yaml, else the work dir name and 5).

  • resolution (optional, default: None ) –

    Product name parts (default: config.yaml, else the work dir name and 5).

  • shadow_threshold (float, default: None ) –

    Default from config.yaml (or the Bertone preset).

  • max_offset_p85 (float, default: None ) –

    Default from config.yaml (or the Bertone preset).

  • ldec (Path, default: None ) –

    PGDA LOLA count, elevation / slope uncertainty and slope rasters.

  • toterr (Path, default: None ) –

    PGDA LOLA count, elevation / slope uncertainty and slope rasters.

  • slperr (Path, default: None ) –

    PGDA LOLA count, elevation / slope uncertainty and slope rasters.

  • ldem_slope (Path, default: None ) –

    PGDA LOLA count, elevation / slope uncertainty and slope rasters.

  • lola_points (Path, default: None ) –

    ASP CSV of LOLA points (lunar_toolkit.reference.write_asp_csv).

  • lola_xyzi (Path, default: None ) –

    PGDA .xyzi point cloud, converted to lola_points when those are not given.

  • published_dem (Path, default: None ) –

    Published Bertone et al. SDEM (<ROI>_GLDELEV_005.tif).

  • slope_edges (sequence of float, default: SLOPE_EDGES ) –

    Slope bins (deg) for the differences vs slope.

  • slope_split (float, default: 20.0 ) –

    Slope (deg) separating the low / high-slope ensemble regimes.

  • preview_size (int, default: 800 ) –

    Longer side (px) of the grid maps and coverage comparisons are drawn on.

from_work_dir(work_dir, **overrides) classmethod

Inputs with defaults read from <work_dir>/config.yaml and the standard paths.

product(code, *suffix)

<work_dir>/products/<ROI>_GLD<code>_<RES>[_suffix].tif.

Histogram(label, edges, counts) dataclass

Counts of values in edges; values beyond the edges go to the outer bins.

Metrics(inputs, summary=dict(), tables=dict(), histograms=dict(), hist2d=dict(), skipped=dict()) dataclass

Everything a report shows: JSON summary, tables and histograms per section.

stats(values)

Count, mean, median, std, NMAD, RMS, range, 5/95th percentiles and the same of |values|.

split_stats(values, ldec=None)

stats of all values and, with a LOLA count raster, of LDEC > 0 / LDEC = 0 pixels.

binned(values, by, edges)

Per bin of by: count, median, quartiles, mean |values| and RMS of values.

normal_summary(z)

How close normalised residuals are to a unit Gaussian: std, NMAD and fractions within 1-3 sigma.

coverage_fractions(solar_bins, valid=None)

Fractions of pixels lit from 0, 1, 2 and >=3 non-redundant Sun directions (and >=1, >=2).

read_ba_reports(prefix)

Per-image bundle-adjustment report of <prefix>-*: residuals before / after and match offsets.

Columns image, initial_mean / initial_median / initial_count, final_* (pixels) and offset_p25 ... offset_p95, offset_count (m). None when none of the reports exist.

ba_summary(table, resolution, max_offset_p85)

Fig. 5 numbers: per-image median residual mean +- std before / after, offset percentiles.

read_convergence(path)

<prefix>-convergence_angles.txt: left, right, p25, p50, p75 (deg), matches.

read_pointmap_residuals(path)

mean_residual column (pixels) of a *_residuals_pointmap.csv (GCP rows included).

removed_images(work_dir)

selection/removed.csv with a cause column (matches, offset, residuals, shadow, other).

selection_table(work_dir)

selection/selection.csv (every kept image; selected as bool), or None.

preview_grid(grid, max_size)

grid coarsened by an integer factor so its longer side is at most max_size.

solar_bins_from_images(paths, azimuths, grid, shadow_threshold, bin_width=30.0)

Non-redundant Sun directions per pixel of grid from mapprojected images (illumination_maps).

sample(array, grid, x, y)

Nearest-pixel values of array on grid at map coordinates; NaN outside.

lola_differences(dem, points_csv, out_prefix, z=None, grid=None)

DEM minus LOLA points (x, y polar stereographic m; diff m).

Uses geodiff (compare_to_points); without ASP, the nearest DEM pixel of each point (z on grid, read when not given).

open_workspace(work_dir)

The work dir's lunar.duckdb Workspace (read-only), or None.

None when there is none or it cannot be opened (e.g. locked by a running pipeline).

metrics(inputs, work=None, sections=None)

All report metrics; sections whose inputs are missing are listed in skipped.

Parameters:
  • inputs (ReportInputs or Path) –

    Inputs, or a work dir (ReportInputs.from_work_dir).

  • work (Path, default: None ) –

    Scratch directory for converted LOLA points and geodiff output (default: <work_dir>/report/work).

  • sections (iterable of str, default: None ) –

    Subset of SECTIONS (default: all).

write_tables(m, out_dir)

tables/<name>.csv for every table, plus metrics.json (summary and histograms).

summary_tables(m)

Table 2-style rows (one per comparison) and the coverage fractions as tables.

hillshade_array(z, res, azimuth=315.0, elevation=45.0)

Lambertian hillshade (0-1) of z with the Sun at azimuth / elevation (deg).

figures(m, out_dir)

PNG figures of every section with data, in <out_dir>/figures; returns name -> path.

write_html(m, figs, out, tables=None)

Self-contained report.html: summary tables, embedded figures, skipped sections.

make_report(inputs, out_dir=None, sections=None)

Metrics, tables, figures and report.html in out_dir (default <work_dir>/report).