asp-plot 2.2.0__tar.gz → 3.1.0__tar.gz

{asp_plot-2.2.0 → asp_plot-3.1.0}/AGENTS.md

@@ -54,7 +54,7 @@ sphinx-autobuild docs docs/_build/html --open-browser   # or sphinx-build for a
 ## External Data Sources
 
 - **ICESat-2 ATL06-SR** (Earth): requested through the SlideRule API; results cached as parquet next to the report.
-- **LOLA (Moon) / MOLA (Mars)**: async queries to the ODE GDS REST API via the `request_planetary_altimetry` CLI — the user gets a download link by email, then passes the CSV to `asp_report --altimetry_csv`. Coordinates are east-positive 0–360 longitude, planetocentric latitude.
+- **LOLA (Moon) / MOLA (Mars)**: async queries to the ODE GDS REST API via the `request_planetary_altimetry` CLI — the user gets a download link by email, then passes the CSV to `asp_report --altimetry-csv`. Coordinates are east-positive 0–360 longitude, planetocentric latitude.
 
 ## Testing
 
@@ -76,7 +76,7 @@ The rest is automated: `release.yml` detects the version bump, creates a GitHub
 ASP output files follow specific naming patterns (find them with the `glob_file()` utility):
 - DEMs: `*-DEM.tif` or `*_dem.tif`
 - Disparity: `*-F.tif`
-- Match files: `*.match`
+- Match files: `*.match` (binary) or `*__*.txt` (plain text, from ASP >= 3.7.0 `--matches-as-txt`; binary preferred when both exist)
 - Bundle adjust residuals: `*-initial_residuals_pointmap.csv`, `*-final_residuals_pointmap.csv`
 - Log files: `*log-bundle_adjust*.txt`, `*log-stereo*.txt`, `*log-point2dem*.txt`
 

{asp_plot-2.2.0 → asp_plot-3.1.0}/ARCHITECTURE.md

@@ -42,24 +42,24 @@ The package is organized by functionality, with each module focused on a specifi
 - `pixel_window_to_bbox()` / `bbox_to_pixel_offset()`: convert a detailed-hillshade clip between a DEM-CRS map bbox and a top-left pixel offset. `bbox_to_pixel_offset` uses `rowcol(..., op=round)` (round-to-nearest, **not** floor) so a replayed clip doesn't drift by a pixel from floating-point error
 - `reproject_bbox(bbox, src_crs, dst_crs)`: reprojects a clip bbox between CRSs (via `rasterio.warp.transform_bounds`) so clip reuse works across stereo variants in different projections (e.g. MOC non-mapproj Stereographic vs mapproj Sinusoidal). `plot_detailed_hillshade(clip_windows_crs=...)` passes the manifest's `dem_crs`; reprojection is a no-op when CRSs match
 - Deliberately imports nothing from `report.py` / `fpdf`, so it is safe to use from notebooks
-- The `asp_report` CLI always writes `<report_stem>_figure_selections.yml` next to the report; `--reuse_selections PATH` replays a prior run's choices
+- The `asp_report` CLI always writes `<report_stem>_figure_selections.yml` next to the report; `--reuse-selections PATH` replays a prior run's choices
 
 **`report.py`** - PDF report generation using fpdf2
 - `ReportSection`: Dataclass representing a report figure (title, image path, caption)
-- `AlignmentReportPage`: Dataclass for the pc_align + ICESat-2 alignment workflow (title, parameters dict, 1-row stats dict, description paragraph, status message, optional figure + caption). Rendered alongside `ReportSection` by `compile_report()`. Body text blocks are left-aligned (not justified) to avoid word-spacing gaps on long lines. Long pc_align column names (`north_shift`, `east_shift`, `down_shift`, `translation_magnitude`) are displayed as `N_shift`, `E_shift`, `D_shift`, `|T|` via `_ALIGNMENT_STATS_DISPLAY_LABELS` so the 10-column horizontal stats row fits in the page width.
+- `AlignmentReportPage`: Dataclass for the pc_align + altimetry alignment workflow (title, parameters dict, flat stats dict from `pc_align_report()`, description paragraph, status message, optional figure + caption). Rendered alongside `ReportSection` by `compile_report()`. Body text blocks are left-aligned (not justified) to avoid word-spacing gaps on long lines. `_add_alignment_stats_tables()` splits the flat stats dict (`_split_alignment_stats()`) into two side-by-side tables: "Error Statistics (m)" with one row per `<stat>_beg`/`<stat>_end` pair and Before / After / Change columns (row labels via `_ALIGNMENT_STAT_LABELS`, Change from `_fmt_pct_change()`), and "Translation (m)" with one row per remaining key (`north_shift` → `North`, … `translation_magnitude` → `Magnitude |T|` via `_ALIGNMENT_TRANSLATION_LABELS`). Either table takes the full width when the other is empty.
 - `ReportMetadata`: Dataclass for DEM metadata displayed on the title page (dimensions, GSD, CRS, nodata %, elevation range, DEM filename, reference DEM, acquisition dates). The "Acquisition Date(s)" row is added to the summary table only when `acquisition_dates` is non-empty.
 - `ASPReportPDF`: FPDF subclass with custom header/footer and page numbers
 - `compile_report()`: Assembles title page, Processing Parameters (page 2), figure sections with captions, and any trailing alignment pages into a PDF. Accepts optional `report_command` string to record the CLI invocation. Figures are automatically scaled to fit page dimensions, preventing overflow/cutoff. `sections` is a mixed list of `ReportSection | AlignmentReportPage`; dispatch is by `isinstance` check.
 - `_add_processing_parameters_page()`: helper that renders the runtime summary table plus the bundle_adjust / stereo / point2dem / report commands on page 2 (moved from the trailing page as of v1.13.0). Also renders the reconstructed `mapproject` command(s) (from the optional `mapproject` list key; see `mapproject.py`) with a "reconstructed from output metadata" note.
 - `_fmt_sig()`: formats a number compactly — 2 decimals for |x| < 10, 1 decimal for 10 ≤ |x| < 100, 0 decimals above, "n/a" for non-finite. Used for alignment stats.
 - Title page displays: processing date, ASP version (from logs), asp_plot version (from package metadata)
-- Page order: title + DEM summary → Processing Parameters → diagnostic figures → (if `--pc_align` ran) alignment report page + aligned-DEM figures.
+- Page order: title + DEM summary → Processing Parameters → diagnostic figures → (if the `pc_align` step ran) alignment report page + aligned-DEM figures.
 - `report.py` is fed declaratively by `report_pipeline.py`; it was **not** rewritten in #128.
 
 **`report_pipeline.py`** - Declarative report pipeline behind the `asp_report` CLI (issue #128)
 - `ReportConfig`: dataclass packing the ~18 CLI options into one Click-free object (field names/defaults mirror the options one-for-one, guarded by a test)
 - `run_report(config)`: importable/callable from notebooks and tests with no Click context; returns the written PDF path
-- A declarative section registry (`REPORT_SECTIONS`) of `ReportSpec`s replaces the old inline plot-and-append wall: each spec pairs an `enabled(ctx)` predicate with a `build(ctx)` function returning the sections to append. `--plot_geometry` / `--plot_altimetry` / `--pc_align` gating are predicates; figure numbering comes from a per-run counter on the shared `ReportContext`, so section order and numbering are data, not source-line position. The alignment "Page B/C/D" follow-ups are one spec emitting several sections
+- A declarative section registry (`REPORT_SECTIONS`) of `ReportSpec`s replaces the old inline plot-and-append wall: each spec pairs an `enabled(ctx)` predicate with a `build(ctx)` function returning the sections to append. `--no-geometry` / `--no-altimetry` / `--no-pc-align` gating are predicates; figure numbering comes from a per-run counter on the shared `ReportContext`, so section order and numbering are data, not source-line position. The alignment "Page B/C/D" follow-ups are one spec emitting several sections
 - Section builders: `_build_input_scenes`, `_build_stereo_geometry`, `_build_match_points`, `_build_bundle_adjust`, `_build_disparity`, `_build_dem_results`, `_build_detailed_hillshade`, `_build_altimetry` (→ `_build_altimetry_earth` / `_build_altimetry_planetary`)
 - `_numbered_sections()`: shared helper turning a plotter's saved-filename list into one `ReportSection` per figure (first gets the caption, continuations are titled "... (continued)") — used by the scenes/geometry/match/disparity builders, whose plotters save one figure per pair on multi-view runs (issue #160)
 
@@ -109,6 +109,7 @@ The package is organized by functionality, with each module focused on a specifi
 - Detects map-projection status via `Raster.transform` check
 - For non-mapprojected scenes: match points are overlaid on images using alignment transform matrices (`run-align-{L,R}.txt` loaded via `np.loadtxt`), and disparity plots use pixel-unit scalebar instead of GSD-based. Exception: when the match file is named for the aligned images themselves (`run-L__R.match`, older ASP raw-image runs that write `.exr` alignment matrices), the coordinates are already aligned — detected via `_ip_on_aligned_images()` (match stem's left name == L image stem) — and are only rescaled
 - **Raw interest point overlay** (issue #8): `StereoFiles` also discovers the per-image `.vwip` files (named after the images the match file pairs — `<A>__<B>.match` ↔ `<A>.vwip`/`<prefix>-<B>.vwip` — derived from the match stem, with a `*-L.vwip`/`*-R.vwip` glob fallback when no match file exists; either side may be absent). `get_vwip_df()` parses the binary format (a uint64 count then the same interest point records as `.match`); `plot_match_points()` underlays them in blue beneath the red matches through the same per-side coordinate transform (layers denser than 10,000 points are thinned by seeded random sampling for display; titles report true counts), renders interest-points-only when the match file is missing, and falls back to the previous matches-only figure when the `.vwip` files are gone
+- **Plain-text match files** (issue #147): ASP >= 3.7.0 writes `<A>__<B>.txt` (one `x1 y1 unc1 x2 y2 unc2` line per match) *instead of* `.match` when run with `--matches-as-txt`, so `StereoFiles._find_match_file()` globs both `*.match` and `*__*.txt` (the `__` anchor plus a first-row check — six numeric fields, `_opens_with_match_row()` — keeps logs and alignment matrices out even when the run prefix itself contains `__`), preferring binary when both coexist. `get_match_point_df()` detects the format from the bytes (`_is_text_match_file()`: the binary header's uint64 counts contain NULs, text never does — so a renamed file still parses) and routes text through `_read_text_match_file()` — read directly, uncertainties dropped, never via the `.csv` cache a binary conversion leaves behind — while the binary path keeps its CSV conversion. `.vwip` files stay binary-only: stereo never writes text ones (`ipfind --binary-to-txt` is a manual conversion)
 - **Multi-view aware** (issue #160): `StereoFiles` resolves each `<prefix>-pairN/` subdirectory into a `PairStereoFiles` (field names mirror the top-level attributes so the per-figure helpers consume either, duck-typed); `plot_match_points()` / `plot_disparity()` render one figure per pair (`<stem>_pairN.png`) and return the saved filename list — `[fig_fn]` for a standard run — mirroring the `stereo_geom_plot()` N-scene contract
 - Detects the imagery rights-holder via the `attribution` attribute (`detect_satellite_attribution`); adds the copyright overlay to optical imagery in `plot_match_points()` and `plot_detailed_hillshade()`
 - `plot_detailed_hillshade()` auto-selects three subset clips from intersection-error variance (low/medium/high) via `_auto_hillshade_clip_offsets()`. Accepts `clip_windows` (DEM-CRS bboxes) + `clip_windows_crs` to pin/replay clips for run-to-run comparison (issue #121); records the boxes it drew on `self.detailed_hillshade_clips`. Out-of-bounds pinned boxes warn and fall back to auto.
@@ -180,7 +181,7 @@ The package is organized by functionality, with each module focused on a specifi
 - `pc_align_dem_to_atl06sr()`: ICESat-2 path, csv-format `1:lon 2:lat 3:height_above_datum`
 - `pc_align_dem_to_planetary_csv(planetary_csv, body, ...)`: MOLA/LOLA path. Uses csv-format `1:lon 2:lat 3:radius_m` and `--datum D_MARS`/`D_MOON` (per ASAP-Stereo's CTX cookbook). Default `max_displacement=500` m
 - Both public methods keep their signatures/validation/errors and delegate to a shared `_run_pc_align(csv, csv_format, max_displacement, datum=...)` (#127); generated argv is byte-identical to before, with `--datum` emitted only on the planetary path
-- `pc_align_report()`: Extracts begin/end percentiles + N-E-D translation from the pc_align log
+- `pc_align_report()`: Extracts begin/end percentiles, the ASP >= 3.7.0 Mean/StdDev/RMSE/Median/NMAD summary (keys absent for older logs), and the N-E-D translation from the pc_align log; the report page shows Median/NMAD/RMSE + translation when the log has them, else the percentiles (`report_pipeline._stats_row_from_result()`)
 - `apply_dem_translation()`: Applies pc_align's Cartesian translation to the DEM (geotransform shift + scalar add to pixel values, no resampling). Picks the right body-centered geocentric source CRS via the module-level `_GEOCENTRIC_PROJ` dict — Earth uses EPSG:4978, Mars/Moon use PROJ strings (`+proj=geocent +R=...`) because PROJ refuses to convert across celestial bodies
 - Used by `Altimetry` class for DEM-to-altimetry alignment on Earth, Mars, and Moon
 
@@ -218,28 +219,27 @@ All CLI tools are in `asp_plot/cli/` and use Click for argument parsing:
 **`asp_report.py`** - Main CLI tool (`asp_report` command)
 - Generates comprehensive PDF reports of ASP processing
 - A **thin Click wrapper** (issue #128): parses the ~18 options into a `ReportConfig` and calls `report_pipeline.run_report(config)`. All orchestration lives in `report_pipeline.py` (see the module structure section); the CLI file itself is now just option definitions + the `ReportConfig` build
-- Accepts directories for stereo and bundle_adjust outputs
+- Accepts a directory for stereo outputs and a directory or ASP-style prefix for bundle_adjust outputs; trailing slashes are tolerated (issue #60)
 - Options for reference DEMs, ICESat-2 comparisons, basemaps
 - Report section order: Input Scenes → Stereo Geometry → Match Points → Bundle Adjust panels (Log/Linear Residuals, Map-Projected Residuals, Geodiff) → Disparity → DEM Results → Detailed Hillshade → Altimetry panels. Disparity follows Bundle Adjust (not Hillshade) and DEM Results precedes Hillshade, so the title page → inputs → per-step diagnostics → final DEM products narrative reads top-down.
 - Title-page `ReportMetadata` is populated here; `get_acquisition_dates()` is called with the main directory plus stereo/BA subdirs as `extra_dirs` so the Acquisition Date(s) row appears on both raw-input layouts (WV XMLs at top level) and layouts where XMLs live one level deep.
 - `--directory`: Root ASP processing directory (default: `./`)
-- `--stereo_directory`: Stereo output subdirectory (default: `stereo`)
-- `--bundle_adjust_directory`: Optional BA directory
-- `--dem_filename`: Custom DEM filename (default: auto-detect `*-DEM.tif`)
-- `--dem_gsd`: Custom DEM ground sample distance
-- `--map_crs`: Projection as `EPSG:XXXX` (default: auto-detect from DEM, fallback `EPSG:4326`)
-- `--reference_dem`: Reference DEM path (auto-detected from logs if not supplied)
-- `--add_basemap`: Add Esri WorldImagery basemaps (default: True, requires internet)
-- `--plot_altimetry`: Plot altimetry comparisons (default: True). Auto-detects planetary body from DEM CRS: Earth → ICESat-2 (requires internet), Moon → LOLA, Mars → MOLA. For planetary DEMs, requires `--altimetry_csv`. Replaces the deprecated `--plot_icesat` flag.
-- `--plot_icesat`: Deprecated alias for `--plot_altimetry`. Prints deprecation warning if used.
-- `--altimetry_csv`: Path to a LOLA/MOLA CSV from the ODE GDS API. **Mars: must be the `*_pts_csv.csv` (not `*_topo_csv.csv`) — the loader requires the `PLANET_RAD` column to avoid the oblate-areoid offset.** Moon accepts either the `*_topo_simple_csv.csv` (results=u) or the `*_pts_csv.csv` (results=p). Obtained via the `request_planetary_altimetry` CLI tool.
-- `--pc_align`: If True (default) and `--plot_altimetry` is True, runs `pc_align` against the reference altimetry (ICESat-2 for Earth, MOLA for Mars, LOLA for Moon) after the existing altimetry plots and appends an alignment report. **Earth success path**: adds four pages (alignment report page, pre/post landcover histogram, aligned profile, aligned best/worst segments). **Planetary success path**: adds three pages (alignment report page, pre/post mapview, pre/post histogram). `insufficient_points` and `no_improvement` outcomes emit a single alignment report page on either branch. Disabled automatically when `--plot_altimetry` / `--plot_icesat` is False.
-- `--plot_geometry`: Plot stereo geometry (default: True; disable for planetary missions)
-- `--subset_km`: Hillshade subset size in km (default: 1.0)
-- `--atl06sr_time_range`: Time range for ICESat-2 ATL06-SR requests. `"all"` (default) for full mission, `"auto"` for scene metadata ±1 year, `"START,END"` for a custom range, or a single date (buffered by ±1 year).
-- `--reuse_selections`: Path to a `*_figure_selections.yml` from a prior run. Replays that run's ICESat-2 points (parquet), profile track, best/worst segments, and detailed-hillshade clips so re-processing runs (e.g. mapproj vs non-mapproj) are directly comparable (issue #121). Every run always writes `<report_stem>_figure_selections.yml` next to the report (the `regenerate_reports.sh` paired variants use this to reuse each other). Generated sidecars are gitignored (they hardcode absolute local paths); a sanitized example is in `docs/cli/asp_report.md`.
-- `--report_filename`: PDF report filename or path. A bare filename saves in the stereo directory; a path (e.g. `reports/report.pdf`) is used as-is. Default is auto-generated as `asp_report_<report_title>_<UTC timestamp>.pdf`
-- `--report_title`: Custom report title (default: directory name)
+- `--stereo-directory`: Stereo output subdirectory (default: `stereo`)
+- `--bundle-adjust-prefix`: Optional BA output location — either a directory (`ba`) or an ASP-style output prefix (`ba/run`, as passed to stereo/mapproject); a prefix narrows file globs to that run's outputs
+- `--dem-filename`: Custom DEM filename (default: auto-detect `*-DEM.tif`)
+- `--dem-gsd`: Custom DEM ground sample distance
+- `--map-crs`: Projection as `EPSG:XXXX` (default: auto-detect from DEM, fallback `EPSG:4326`)
+- `--reference-dem`: Reference DEM path (auto-detected from logs if not supplied)
+- `--no-basemap`: Skip the Esri WorldImagery basemaps added by default (which require internet)
+- `--no-altimetry`: Skip the altimetry comparisons plotted by default. Auto-detects planetary body from DEM CRS: Earth → ICESat-2 (requires internet), Moon → LOLA, Mars → MOLA. For planetary DEMs, requires `--altimetry-csv`.
+- `--altimetry-csv`: Path to a LOLA/MOLA CSV from the ODE GDS API. **Mars: must be the `*_pts_csv.csv` (not `*_topo_csv.csv`) — the loader requires the `PLANET_RAD` column to avoid the oblate-areoid offset.** Moon accepts either the `*_topo_simple_csv.csv` (results=u) or the `*_pts_csv.csv` (results=p). Obtained via the `request_planetary_altimetry` CLI tool.
+- `--no-pc-align`: Skips the `pc_align` step; by default (when altimetry is on) the report runs `pc_align` against the reference altimetry (ICESat-2 for Earth, MOLA for Mars, LOLA for Moon) after the existing altimetry plots and appends an alignment report. **Earth success path**: adds four pages (alignment report page, pre/post landcover histogram, aligned profile, aligned best/worst segments). **Planetary success path**: adds three pages (alignment report page, pre/post mapview, pre/post histogram). `insufficient_points` and `no_improvement` outcomes emit a single alignment report page on either branch. Skipped automatically when `--no-altimetry` is set.
+- `--no-geometry`: Skip the stereo geometry plots drawn by default (used for planetary missions)
+- `--subset-km`: Hillshade subset size in km (default: 1.0)
+- `--atl06sr-time-range`: Time range for ICESat-2 ATL06-SR requests. `"all"` (default) for full mission, `"auto"` for scene metadata ±1 year, `"START,END"` for a custom range, or a single date (buffered by ±1 year).
+- `--reuse-selections`: Path to a `*_figure_selections.yml` from a prior run. Replays that run's ICESat-2 points (parquet), profile track, best/worst segments, and detailed-hillshade clips so re-processing runs (e.g. mapproj vs non-mapproj) are directly comparable (issue #121). Every run always writes `<report_stem>_figure_selections.yml` next to the report (the `regenerate_reports.sh` paired variants use this to reuse each other). Generated sidecars are gitignored (they hardcode absolute local paths); a sanitized example is in `docs/cli/asp_report.md`.
+- `--report-filename`: PDF report filename or path. A bare filename saves in the stereo directory; a path (e.g. `reports/report.pdf`) is used as-is. Default is auto-generated as `asp_report_<report_title>_<UTC timestamp>.pdf`
+- `--report-title`: Custom report title (default: directory name)
 
 **`csm_camera_plot.py`** - CSM camera comparison tool (`csm_camera_plot` command)
 - Wrapper for `csm_camera.py` functions
@@ -253,7 +253,7 @@ All CLI tools are in `asp_plot/cli/` and use Click for argument parsing:
 - `--email`: Email for notification when query finishes (required)
 - `--channels`: LOLA detector channels (Moon only, default `tffff` = channel 1 only)
 - Saves request metadata as `altimetry_request_info.yml` alongside the DEM
-- Workflow: submit query → receive email → download/unzip → pass `*_pts_csv.csv` (Mars) or `*_topo_simple_csv.csv`/`*_pts_csv.csv` (Moon) to `asp_report --altimetry_csv`
+- Workflow: submit query → receive email → download/unzip → pass `*_pts_csv.csv` (Mars) or `*_topo_simple_csv.csv`/`*_pts_csv.csv` (Moon) to `asp_report --altimetry-csv`
 
 **`stereo_geom.py`** - Stereo geometry visualization tool (`stereo_geom` command)
 - Wrapper for `StereoGeometryPlotter`
@@ -265,7 +265,7 @@ All CLI tools are in `asp_plot/cli/` and use Click for argument parsing:
 **`gallery.py`** - DEM gallery tool (`gallery` command)
 - Wrapper for `GalleryPlotter`; lays out many DEMs as a grid sharing one color scale
 - `--directory` + `--pattern` (supports recursive `**` for subdirectories) or an explicit list of `FILES` (files take precedence)
-- `--hillshade/--no-hillshade`, `--cmap`, `--downsample`, `--max_filesize_mb`, `--title`, `--output_directory/--output_filename`
+- `--no-hillshade`, `--cmap`, `--downsample`, `--max-filesize-mb`, `--title`, `--output-directory/--output-filename`
 - Saves `<dirname>_gallery.png` into the input directory by default
 
 ## Documentation Website
@@ -307,7 +307,7 @@ docs/
 - **`html_extra_path`** is used to serve `notebooks/figures/` at the correct relative path for notebook `<img src>` references.
 - **`docs/` is excluded from sdist** in `pyproject.toml` so docs never ship in the PyPI/conda package.
 - **Changelog** uses `{include} ../CHANGELOG.md` so there's one source of truth.
-- **Selective notebook exclusion**: `.readthedocs.yaml`'s `pre_build` copies every `notebooks/**/*.ipynb` into `docs/examples/notebooks/`, but specific notebooks can be dropped from the build by listing them in `exclude_patterns` in `docs/conf.py` (e.g., `worldview_utqiagvik_stereo.ipynb`). Inter-notebook links in the WorldView examples use fully-qualified `https://asp-plot.readthedocs.io/en/latest/...` URLs so they resolve both on RTD and in raw notebook previews. Report-link convention: each notebook's "Full Report Generation" section ends with a `#### See the resulting [report](https://asp-plot.readthedocs.io/en/latest/_static/reports/<filename>.pdf).` line that links directly to the PDF served from `_static/reports/`. The `<filename>` must match what the cell's `!asp_report --report_filename` writes (so the URL on RTD actually resolves).
+- **Selective notebook exclusion**: `.readthedocs.yaml`'s `pre_build` copies every `notebooks/**/*.ipynb` into `docs/examples/notebooks/`, but specific notebooks can be dropped from the build by listing them in `exclude_patterns` in `docs/conf.py` (e.g., `worldview_utqiagvik_stereo.ipynb`). Inter-notebook links in the WorldView examples use fully-qualified `https://asp-plot.readthedocs.io/en/latest/...` URLs so they resolve both on RTD and in raw notebook previews. Report-link convention: each notebook's "Full Report Generation" section ends with a `#### See the resulting [report](https://asp-plot.readthedocs.io/en/latest/_static/reports/<filename>.pdf).` line that links directly to the PDF served from `_static/reports/`. The `<filename>` must match what the cell's `!asp_report --report-filename` writes (so the URL on RTD actually resolves).
 
 ### Dependencies
 
@@ -337,7 +337,7 @@ Docs dependencies are in `pyproject.toml` under `[project.optional-dependencies]
 
 **ODE GDS REST API**: Base URL `https://oderest.rsl.wustl.edu/livegds`. Queries are submitted via `gds_query_async()` in async mode. The `request_planetary_altimetry` CLI submits the query and the user downloads results via email link. Coordinates use east-positive 0-360 longitude and planetocentric latitude.
 
-**Basemaps**: Uses `contextily` to fetch Esri WorldImagery tiles (requires internet). Can be disabled with `--add_basemap False`. Automatically skipped for planetary (non-Earth) DEMs.
+**Basemaps**: Uses `contextily` to fetch Esri WorldImagery tiles (requires internet). Can be disabled with `--no-basemap`. Automatically skipped for planetary (non-Earth) DEMs.
 
 ## Example Notebooks
 

{asp_plot-2.2.0 → asp_plot-3.1.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-08-27
+
+A compatibility release for two things ASP 3.7.0 changed in the files the report reads. `pc_align` now writes Mean/StdDev/RMSE/Median/NMAD error statistics to its log, and the alignment page shows Median, NMAD and RMSE before and after alignment in place of the 16/50/84 percentiles ([#146](https://github.com/uw-cryo/asp_plot/issues/146)); older logs keep the percentiles, with no version sniffing. And a `parallel_stereo`/`bundle_adjust` run made with `--matches-as-txt` writes plain-text match files instead of binary `.match`, which previously left the match-point page with a "missing match file" placeholder — both formats are now discovered and parsed into the same DataFrame ([#147](https://github.com/uw-cryo/asp_plot/issues/147)). No new dependencies and no entry-point changes.
+
+### Added
+- **`pc_align_report()` parses the error statistics ASP 3.7.0 added to the `pc_align` log** (issue [#146](https://github.com/uw-cryo/asp_plot/issues/146)): the `Input stats (meters):` / `Output stats (meters):` lines become `mean_beg/end`, `stddev_beg/end`, `rmse_beg/end`, `median_beg/end`, `nmad_beg/end` alongside the existing percentiles and translation, and flow into `Altimetry.alignment_report_df`. The alignment report page (ICESat-2 and LOLA/MOLA) now shows `Median`, `NMAD` and `RMSE` before/after alignment in place of the 16/50/84 percentiles, with the column description updated; `mean`/`stddev` stay in the dataframe only. Logs from ASP < 3.7.0 parse exactly as before, without the new keys, and the page keeps showing the percentiles for them — no version sniffing, the absence of the new stats is the signal. The seven committed example reports in `reports/` are regenerated with the new page.
+- **The `pc_align` log parser is now regression-tested** against real logs from both generations — the existing 2024-11 fixtures and a new ASP 3.8.0-alpha LOLA log (`tests/test_data/pc_align/pc_align_lola-log-pc_align.txt`) — which also confirmed the percentile and translation lines we key off are unchanged in 3.8.0.
+- **Plain-text ASP match files are discovered and parsed** (issue [#147](https://github.com/uw-cryo/asp_plot/issues/147)). ASP 3.7.0 added a text match-file format (`<prefix>-<A>__<B>.txt`, one `x1 y1 unc1 x2 y2 unc2` line per match), and `parallel_stereo`/`bundle_adjust --matches-as-txt` write it *instead of* `.match` — so a stereo directory produced with that switch previously got the "missing match file" placeholder on the match-point page. `StereoFiles` now also looks for `*__*.txt` (anchored on the `__` image-name separator and required to open with a six-field match row, so logs and alignment matrices are never mistaken for it — even with a run prefix like `my__run`), `StereoPlotter.get_match_point_df()` reads either format into the same `x1/y1/x2/y2` DataFrame, and the `.vwip` interest-point pairing works off the text stem too. The format is detected from the file's bytes (the binary header has NUL bytes; text never does), not the extension, so a renamed file still parses; when both forms coexist the binary file is preferred, as before; text files are read directly, never through the `.csv` cache a binary conversion leaves behind. A text twin of the raw-image fixture, converted with `ipmatch --binary-to-txt` (ASP 3.8.0-alpha), is committed so the two readers are checked against each other. `.vwip` files remain binary-only — stereo never writes text ones.
+
+## [3.0.0] - 2026-08-24
+
+A breaking standardization of the command-line interfaces ([#60](https://github.com/uw-cryo/asp_plot/issues/60)), done deliberately as a clean break — no aliases, no deprecation period — while the user base is small. Every multi-word option across the five CLIs (`asp_report`, `stereo_geom`, `csm_camera_plot`, `gallery`, `request_planetary_altimetry`) moves from underscores to the hyphenated style ASP itself uses (`--stereo_directory` → `--stereo-directory`), booleans become single switches for the non-default behavior (`--add_basemap False` → `--no-basemap`), and `--bundle_adjust_directory` becomes `--bundle-adjust-prefix`, matching both the name and the semantics of ASP's own option. The Python API is unchanged.
+
+A major version because every existing `asp_report`/`stereo_geom`/`csm_camera_plot`/`gallery` invocation with a multi-word or boolean option needs editing. **Upgrade:** re-spell the flags per the entries below — the `--help` of each command lists the new names, and the committed example reports and notebooks show them in use. No new dependencies and no entry-point changes.
+
+### Changed
+- **All CLI options are hyphenated** (issue [#60](https://github.com/uw-cryo/asp_plot/issues/60)). One-for-one renames: `--stereo-directory`, `--dem-filename`, `--dem-gsd`, `--map-crs`, `--reference-dem`, `--altimetry-csv`, `--subset-km`, `--atl06sr-time-range`, `--reuse-selections`, `--report-filename`, `--report-title` (asp_report); `--output-directory`, `--output-filename` (stereo_geom, gallery); `--max-filesize-mb` (gallery); `--original-cameras`, `--optimized-cameras`, `--map-crs`, `--upper-magnitude-percentile` (csm_camera_plot). Single-word options are untouched. The command recorded on the report's final page is emitted with the new spellings, so it stays re-runnable.
+- **Boolean options are now single switches for the non-default behavior**, in the Unix idiom: where the default is on, only the negative switch exists — `--no-basemap`, `--no-altimetry`, `--no-pc-align`, `--no-geometry` (asp_report), `--no-basemap` (stereo_geom), `--no-trim` (csm_camera_plot), `--no-hillshade` (gallery, replacing the `--hillshade/--no-hillshade` pair) — and where the default is off, only the positive one — `--shared-scales`, `--log-scale-positions`, `--log-scale-angles`, `--add-basemap` (csm_camera_plot). Where you passed `--add_basemap False`, pass `--no-basemap`; the verb-y `plot`/`add` prefixes are dropped from the switch names.
+- **`--bundle_adjust_directory` is now `--bundle-adjust-prefix`**, and accepts either the containing directory (`ba`, the previous behavior) or the same ASP-style output prefix passed to `stereo`/`mapproject` (`ba/run`). A prefix narrows the residuals/log file search to that run's outputs, so several bundle-adjust runs can share a directory. Internally, `ReportConfig.bundle_adjust_directory` is renamed to `bundle_adjust_prefix`.
+- **`csm_camera_plot` options are harmonized with the other CLIs and ASP's `orbit_plot.py`**: `--save_dir` → `--output-directory`, `--fig_fn` → `--output-filename`, `--figsize` → `--figure-size`. The `csm_camera_summary_plot()` Python keyword arguments are unchanged.
+- **Trailing slashes on directory options are stripped centrally** (`--directory`, `--stereo-directory`, `--bundle-adjust-prefix`), closing the last thread of issue [#60](https://github.com/uw-cryo/asp_plot/issues/60); the dg_mosaic `r100` concern from the same issue was resolved earlier by the sensor readers, which treat `*.r100.xml`/`*.r50.xml` as regenerable intermediates.
+
+### Removed
+- **The deprecated `--plot_icesat` alias** (deprecated in favor of `--plot_altimetry` in 1.10.0) is gone; altimetry is on by default and `--no-altimetry` disables it.
+
 ## [2.2.0] - 2026-08-18
 
 A correctness release for the CSM camera comparison, and a new diagnostic layer under the match points.

{asp_plot-2.2.0 → asp_plot-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: asp_plot
-Version: 2.2.0
+Version: 3.1.0
 Summary: Package for plotting outputs Ames Stereo Pipeline processing
 Project-URL: Homepage, https://github.com/uw-cryo/asp_plot
 Project-URL: Documentation, https://asp-plot.readthedocs.io
@@ -74,7 +74,7 @@ See the [installation guide](https://asp-plot.readthedocs.io/en/latest/installat
 Generate a PDF report from an ASP processing directory:
 
 ```
-asp_report --directory ./ --stereo_directory stereo
+asp_report --directory ./ --stereo-directory stereo
 ```
 
 See the [CLI documentation](https://asp-plot.readthedocs.io/en/latest/cli/index.html) for all options and additional tools (`stereo_geom`, `csm_camera_plot`).

{asp_plot-2.2.0 → asp_plot-3.1.0}/README.md

@@ -30,7 +30,7 @@ See the [installation guide](https://asp-plot.readthedocs.io/en/latest/installat
 Generate a PDF report from an ASP processing directory:
 
 ```
-asp_report --directory ./ --stereo_directory stereo
+asp_report --directory ./ --stereo-directory stereo
 ```
 
 See the [CLI documentation](https://asp-plot.readthedocs.io/en/latest/cli/index.html) for all options and additional tools (`stereo_geom`, `csm_camera_plot`).

{asp_plot-2.2.0 → asp_plot-3.1.0}/asp_plot/alignment.py

@@ -17,6 +17,43 @@ logging.basicConfig(level=logging.WARNING)
 logger = logging.getLogger(__name__)
 
 
+# Labels ASP >= 3.7.0 prints on the "Input stats (meters):" / "Output stats
+# (meters):" pc_align log lines, mapped to the keys pc_align_report() uses.
+_PC_ALIGN_STATS_FIELDS = {
+    "Mean": "mean",
+    "StdDev": "stddev",
+    "RMSE": "rmse",
+    "Median": "median",
+    "NMAD": "nmad",
+}
+
+
+def _parse_pc_align_stats_line(line, suffix):
+    """Parse one ``Input/Output stats (meters):`` pc_align log line.
+
+    Parameters
+    ----------
+    line : str
+        e.g. ``"... Input stats (meters): Mean: 71.4632, StdDev: 134.758,
+        RMSE: 152.535, Median: 5.71217, NMAD: 3.20963"``
+    suffix : str
+        ``"beg"`` for the Input line, ``"end"`` for the Output line.
+
+    Returns
+    -------
+    dict
+        ``{"mean_<suffix>": float, "stddev_<suffix>": float, ...}`` for every
+        label found on the line; labels that are missing are left out rather
+        than raising, so a future change to the line degrades gracefully.
+    """
+    parsed = {}
+    for label, key in _PC_ALIGN_STATS_FIELDS.items():
+        match = re.search(rf"{label}: (-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)", line)
+        if match:
+            parsed[f"{key}_{suffix}"] = float(match.group(1))
+    return parsed
+
+
 class Alignment:
     """
     Perform DEM alignment using point cloud alignment techniques.
@@ -274,11 +311,22 @@ class Alignment:
         dict
             Dictionary containing alignment metrics:
             - p16_beg, p50_beg, p84_beg: Error percentiles before alignment
+            - mean_beg, stddev_beg, rmse_beg, median_beg, nmad_beg: Error
+              statistics before alignment (ASP >= 3.7.0 only; absent from
+              the dict when the log predates them)
             - p16_end, p50_end, p84_end: Error percentiles after alignment
+            - mean_end, stddev_end, rmse_end, median_end, nmad_end: Error
+              statistics after alignment (ASP >= 3.7.0 only)
             - north_shift, east_shift, down_shift: Translation vector components
               in North-East-Down (NED) coordinate frame, in meters
             - translation_magnitude: Magnitude of translation vector
 
+        All errors are the absolute point-to-point (or point-to-plane)
+        distances pc_align reports, in meters. ``median_*`` duplicates
+        ``p50_*``; ``nmad_*`` is the robust spread and ``rmse_*`` the
+        outlier-sensitive one, so a large RMSE alongside a small NMAD flags
+        a tail of gross errors rather than a broad misfit.
+
         Notes
         -----
         This method expects the log file to contain specific keyword patterns
@@ -317,6 +365,11 @@ class Alignment:
                     "p84_end": float(values[2]),
                 }
                 report = report | percentile_dict
+            # ASP >= 3.7.0 adds a one-line summary after each percentile line
+            if "Input stats (meters):" in line:
+                report = report | _parse_pc_align_stats_line(line, "beg")
+            if "Output stats (meters):" in line:
+                report = report | _parse_pc_align_stats_line(line, "end")
             if "Translation vector (North-East-Down, meters):" in line:
                 ned_shift = np.genfromtxt(
                     [line.split("Vector3")[1][1:-2]], delimiter=","

{asp_plot-2.2.0 → asp_plot-3.1.0}/asp_plot/altimetry.py

@@ -59,10 +59,10 @@ class AlignmentResult:
         One of:
           - ``"insufficient_points"``: not enough ATL06-SR points for
             pc_align to run (the aligned DEM is removed if one was written).
-          - ``"no_improvement"``: pc_align ran but p50 did not improve
+          - ``"no_improvement"``: pc_align ran but the median (p50) did not improve
             toward 0 by more than the ``improvement_threshold_pct``; the
             aligned DEM has been removed.
-          - ``"success"``: p50 improved by more than the threshold; the
+          - ``"success"``: the median (p50) improved by more than the threshold; the
             aligned DEM is retained and ``Altimetry.aligned_dem_fn`` points
             to it.
     alignment_report_df : pandas.DataFrame
@@ -729,11 +729,11 @@ class Altimetry:
             reason = (
                 f"Translation magnitude is below {min_translation_threshold*100:.0f}% "
                 "of the DEM GSD, so no aligned DEM was written despite a "
-                f"{improvement_repr} p50 reduction."
+                f"{improvement_repr} median reduction."
             )
         else:
             reason = (
-                f"p50 {p50_beg:.2f} m -> {p50_end:.2f} m, "
+                f"median {p50_beg:.2f} m -> {p50_end:.2f} m, "
                 f"{improvement_repr} <= {improvement_threshold_pct:.1f}% "
                 "threshold. Aligned DEM removed."
             )
@@ -795,7 +795,7 @@ class Altimetry:
             ``--max-displacement`` for pc_align, in meters. Default 500
             (ASAP-Stereo's CTX cookbook recommendation).
         improvement_threshold_pct : float, optional
-            Minimum p50 reduction (%) required to keep the aligned DEM.
+            Minimum median (p50) reduction (%) required to keep the aligned DEM.
         min_translation_threshold : float, optional
             Minimum translation magnitude as a fraction of the DEM GSD.
         minimum_points : int, optional
@@ -897,11 +897,11 @@ class Altimetry:
             reason = (
                 f"Translation magnitude is below {min_translation_threshold*100:.0f}% "
                 f"of the DEM GSD ({gsd:.2f} m), so no aligned DEM was "
-                f"written despite a {improvement_repr} p50 reduction."
+                f"written despite a {improvement_repr} median reduction."
             )
         else:
             reason = (
-                f"p50 {p50_beg:.2f} m -> {p50_end:.2f} m, "
+                f"median {p50_beg:.2f} m -> {p50_end:.2f} m, "
                 f"{improvement_repr} <= {improvement_threshold_pct:.1f}% "
                 "threshold."
             )
@@ -1034,7 +1034,7 @@ class Altimetry:
             aligned_dem_fn=self.aligned_dem_fn,
             improvement_pct=improvement_pct,
             message=(
-                f"p50 improved from {p50_beg:.2f} m -> {p50_end:.2f} m "
+                f"Median improved from {p50_beg:.2f} m -> {p50_end:.2f} m "
                 f"({improvement_pct:.1f}% reduction). Aligned DEM written to "
                 f"{self.aligned_dem_fn}."
             ),

{asp_plot-2.2.0 → asp_plot-3.1.0}/asp_plot/bundle_adjust.py

@@ -41,7 +41,7 @@ class ReadBundleAdjustFiles:
     >>> mapproj_gdf = ba_reader.get_mapproj_residuals_gdf()
     """
 
-    def __init__(self, directory, bundle_adjust_directory):
+    def __init__(self, directory, bundle_adjust_directory, stem=None):
         """
         Initialize the ReadBundleAdjustFiles object.
 
@@ -51,10 +51,15 @@ class ReadBundleAdjustFiles:
             Root directory of ASP processing
         bundle_adjust_directory : str
             Subdirectory containing bundle adjustment outputs
+        stem : str, optional
+            Run stem of an ASP output prefix (the ``run`` in ``ba/run``).
+            When given, file globs are narrowed to that run's outputs;
+            otherwise any run in the directory matches.
         """
         self.directory = os.path.expanduser(directory)
         self.bundle_adjust_directory = bundle_adjust_directory
         self.full_directory = os.path.join(self.directory, bundle_adjust_directory)
+        self.stem_glob = stem if stem else "*"
 
     def get_csv_paths(self, geodiff_files=False):
         """
@@ -86,8 +91,8 @@ class ReadBundleAdjustFiles:
         will attempt to generate them using the geodiff ASP tool.
         """
         filenames = [
-            "*-initial_residuals_pointmap.csv",
-            "*-final_residuals_pointmap.csv",
+            f"{self.stem_glob}-initial_residuals_pointmap.csv",
+            f"{self.stem_glob}-final_residuals_pointmap.csv",
         ]
 
         if geodiff_files:
@@ -371,7 +376,9 @@ class ReadBundleAdjustFiles:
         the distance between matched interest points in the map-projected
         images after bundle adjustment.
         """
-        path = glob_file(self.full_directory, "*-mapproj_match_offsets.txt")
+        path = glob_file(
+            self.full_directory, f"{self.stem_glob}-mapproj_match_offsets.txt"
+        )
         if path is None:
             raise ValueError("\n\nMapProj Residuals TXT file not found.\n\n")
 
@@ -411,7 +418,9 @@ class ReadBundleAdjustFiles:
         the bundle adjustment residuals propagate to uncertainty in
         triangulation. This is an estimate of the final DEM error.
         """
-        path = glob_file(self.full_directory, "*-triangulation_uncertainty.txt")
+        path = glob_file(
+            self.full_directory, f"{self.stem_glob}-triangulation_uncertainty.txt"
+        )
         if path is None:
             raise ValueError("\n\nTriangulation Uncertainty TXT file not found.\n\n")