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

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

@@ -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-3.0.0 → asp_plot-3.1.0}/ARCHITECTURE.md

@@ -46,7 +46,7 @@ The package is organized by functionality, with each module focused on a specifi
 
 **`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.
@@ -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
 

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

@@ -5,6 +5,15 @@ 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: asp_plot
-Version: 3.0.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

{asp_plot-3.0.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-3.0.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-3.0.0 → asp_plot-3.1.0}/asp_plot/report.py

@@ -53,9 +53,10 @@ class AlignmentReportPage:
         to skip.
     stats_row : dict
         Single-row alignment statistics (e.g. p16_beg/p50_beg/... from
-        ``pc_align_report``). Rendered as a horizontal 1-row table with
-        column headers. Values are formatted to two significant figures.
-        Use an empty dict to skip.
+        ``pc_align_report``). Rendered as two side-by-side tables: one
+        row per error statistic (Before / After / Change) and one row per
+        translation component. Values are formatted to two significant
+        figures. Use an empty dict to skip.
     description : str
         Long-form explanation of pc_align and the meaning of each column in
         the parameters and stats tables. Rendered between the stats table
@@ -325,7 +326,7 @@ def _render_alignment_report_page(pdf, page):
         pdf.ln(3)
 
     if page.stats_row:
-        _add_alignment_stats_row_table(pdf, page.stats_row)
+        _add_alignment_stats_tables(pdf, page.stats_row)
         pdf.ln(3)
 
     if page.description:
@@ -391,21 +392,70 @@ def _add_alignment_parameters_table(pdf, parameters):
         pdf.cell(col_w, 6, str(val), border=1, new_x="LMARGIN", new_y="NEXT")
 
 
-_ALIGNMENT_STATS_DISPLAY_LABELS = {
-    "north_shift": "N_shift",
-    "east_shift": "E_shift",
-    "down_shift": "D_shift",
-    "translation_magnitude": "|T|",
+# Row labels for the error-statistics table, keyed by the pc_align_report()
+# stat name (the part of the key before _beg/_end).
+_ALIGNMENT_STAT_LABELS = {
+    "median": "Median",
+    "nmad": "NMAD",
+    "rmse": "RMSE",
+    "mean": "Mean",
+    "stddev": "StdDev",
+    "p16": "p16",
+    "p50": "p50",
+    "p84": "p84",
 }
 
+# Row labels for the translation table.
+_ALIGNMENT_TRANSLATION_LABELS = {
+    "north_shift": "North",
+    "east_shift": "East",
+    "down_shift": "Down",
+    "translation_magnitude": "Magnitude |T|",
+}
+
+
+def _split_alignment_stats(stats_row):
+    """Split a flat pc_align_report() row into the two alignment tables.
+
+    Returns ``(stats, translation)``: ``stats`` is a list of
+    ``(label, before, after)`` for every ``<stat>_beg`` key that has a
+    matching ``<stat>_end``; ``translation`` is a list of ``(label, value)``
+    for everything else, in row order.
+    """
+    stats, translation, consumed = [], [], set()
+    for key, val in stats_row.items():
+        if key.endswith("_beg") and f"{key[:-4]}_end" in stats_row:
+            stat = key[:-4]
+            stats.append(
+                (_ALIGNMENT_STAT_LABELS.get(stat, stat), val, stats_row[f"{stat}_end"])
+            )
+            consumed.update({key, f"{stat}_end"})
+    for key, val in stats_row.items():
+        if key not in consumed:
+            translation.append((_ALIGNMENT_TRANSLATION_LABELS.get(key, key), val))
+    return stats, translation
+
+
+def _fmt_pct_change(before, after):
+    """Percent change from before to after (negative = improvement)."""
+    try:
+        b, a = float(before), float(after)
+    except (TypeError, ValueError):
+        return "n/a"
+    if not (math.isfinite(b) and math.isfinite(a)) or b == 0:
+        return "n/a"
+    return f"{(a - b) / b * 100:+.1f}%"
+
 
-def _add_alignment_stats_row_table(pdf, stats_row):
-    """Render a single-row horizontal alignment stats table.
+def _add_alignment_stats_tables(pdf, stats_row):
+    """Render the alignment statistics as two side-by-side tables.
 
-    Each key becomes a column header; the corresponding value becomes the
-    single data row (formatted to two significant figures). Long pc_align
-    field names are shortened via ``_ALIGNMENT_STATS_DISPLAY_LABELS`` so the
-    headers fit inside the table columns.
+    Left, "Error Statistics (m)": one row per statistic with Before /
+    After / Change columns. Right, "Translation (m)": one row per
+    component of the applied translation. Both come from the flat
+    ``pc_align_report()`` row via ``_split_alignment_stats``; the number
+    of statistic rows follows what the log provided (Median/NMAD/RMSE for
+    ASP >= 3.7.0, p16/p50/p84 before that).
 
     Parameters
     ----------
@@ -413,28 +463,70 @@ def _add_alignment_stats_row_table(pdf, stats_row):
     stats_row : dict
         Ordered dict-like of ``{column_name: value}``.
     """
-    pdf.set_font("Helvetica", "B", 11)
-    pdf.cell(0, 8, "Alignment Statistics (m)", new_x="LMARGIN", new_y="NEXT")
-    pdf.ln(1)
-
-    keys = list(stats_row.keys())
-    if not keys:
+    stats, translation = _split_alignment_stats(stats_row)
+    if not stats and not translation:
         return
 
     usable_w = pdf.w - pdf.l_margin - pdf.r_margin
-    col_w = usable_w / len(keys)
-
-    pdf.set_font("Helvetica", "B", 7)
-    pdf.set_fill_color(220, 220, 220)
-    for k in keys:
-        label = _ALIGNMENT_STATS_DISPLAY_LABELS.get(k, str(k))
-        pdf.cell(col_w, 6, label, border=1, fill=True, align="C")
-    pdf.ln(6)
+    gap = 8
+    if stats and translation:
+        left_w = (usable_w - gap) * 0.6
+        right_w = usable_w - gap - left_w
+    else:  # a lone table takes the full width
+        left_w = right_w = usable_w
+    row_h = 6
+    x_left, y_top = pdf.l_margin, pdf.get_y()
+    x_right = pdf.l_margin + left_w + gap if stats else pdf.l_margin
+
+    def header(x, y, widths, labels):
+        pdf.set_xy(x, y)
+        pdf.set_font("Helvetica", "B", 9)
+        pdf.set_fill_color(220, 220, 220)
+        for w, label in zip(widths, labels):
+            pdf.cell(w, row_h, label, border=1, fill=True, align="C")
+
+    def body_row(x, y, widths, values):
+        pdf.set_xy(x, y)
+        pdf.set_font("Helvetica", "", 9)
+        for i, (w, val) in enumerate(zip(widths, values)):
+            pdf.cell(w, row_h, val, border=1, align="L" if i == 0 else "C")
 
-    pdf.set_font("Helvetica", "", 8)
-    for k in keys:
-        pdf.cell(col_w, 6, _fmt_sig(stats_row[k]), border=1, align="C")
-    pdf.ln(6)
+    bottoms = []
+    if stats:
+        pdf.set_xy(x_left, y_top)
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.cell(left_w, 6, "Error Statistics (m)", new_x="LMARGIN", new_y="NEXT")
+        widths = [left_w * 0.31, left_w * 0.23, left_w * 0.23, left_w * 0.23]
+        y = y_top + 6
+        header(x_left, y, widths, ["Statistic", "Before", "After", "Change"])
+        for label, before, after in stats:
+            y += row_h
+            body_row(
+                x_left,
+                y,
+                widths,
+                [
+                    label,
+                    _fmt_sig(before),
+                    _fmt_sig(after),
+                    _fmt_pct_change(before, after),
+                ],
+            )
+        bottoms.append(y + row_h)
+
+    if translation:
+        pdf.set_xy(x_right, y_top)
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.cell(right_w, 6, "Translation (m)", new_x="LMARGIN", new_y="NEXT")
+        widths = [right_w * 0.6, right_w * 0.4]
+        y = y_top + 6
+        header(x_right, y, widths, ["Component", "Value"])
+        for label, val in translation:
+            y += row_h
+            body_row(x_right, y, widths, [label, _fmt_sig(val)])
+        bottoms.append(y + row_h)
+
+    pdf.set_xy(pdf.l_margin, max(bottoms))
 
 
 def _render_command_block(pdf, label, cmd):

{asp_plot-3.0.0 → asp_plot-3.1.0}/asp_plot/report_captions.py

@@ -103,17 +103,25 @@ EARTH_ALIGNMENT_DESCRIPTION = (
     "magnitude (as a fraction of the DEM GSD) required to "
     "write out an aligned DEM.\n"
     "  - improvement_threshold_pct: minimum percentage "
-    "reduction in p50 required to keep the aligned DEM on "
+    "reduction in the median residual required to keep the aligned DEM on "
     "disk; below this, the aligned DEM is removed.\n\n"
-    "Alignment Statistics (above, in meters):\n"
-    "  - p16_beg / p50_beg / p84_beg: 16th / 50th / 84th "
-    "percentile of the DEM-vs-ICESat absolute height "
-    "residuals before alignment.\n"
-    "  - p16_end / p50_end / p84_end: same percentiles "
-    "after alignment.\n"
-    "  - N_shift / E_shift / D_shift: north / east / down "
-    "components of the applied translation vector.\n"
-    "  - |T|: magnitude of the translation vector."
+    "Error Statistics (above, in meters): each row is one "
+    "statistic of the DEM-vs-ICESat absolute height residuals, "
+    "Before and After alignment; Change is the percent change "
+    "from Before to After, so negative is an improvement.\n"
+    "  - Median: median residual.\n"
+    "  - NMAD: normalized median absolute deviation; a robust "
+    "spread, insensitive to outliers.\n"
+    "  - RMSE: root-mean-square residual; outlier-sensitive, so "
+    "a large RMSE next to a small NMAD flags a tail of gross "
+    "errors rather than a broad misfit.\n"
+    "  - p16 / p50 / p84: shown instead of the above when the "
+    "pc_align log predates ASP 3.7.0 (which added the Median / "
+    "NMAD / RMSE summary): 16th / 50th / 84th percentile of the "
+    "residuals; p50 is the median.\n\n"
+    "Translation (above, in meters): the applied translation "
+    "vector as North / East / Down components and its "
+    "magnitude |T|. Positive Down means the DEM was too high."
 )
 
 
@@ -167,15 +175,24 @@ def planetary_alignment_description(instrument):
         f"magnitude (as a fraction of the DEM GSD) required "
         f"to write out an aligned DEM.\n"
         f"  - improvement_threshold_pct: minimum percentage "
-        f"reduction in p50 required to keep the aligned DEM "
+        f"reduction in the median residual required to keep the aligned DEM "
         f"on disk; below this, the aligned DEM is removed.\n\n"
-        f"Alignment Statistics (above, in meters):\n"
-        f"  - p16_beg / p50_beg / p84_beg: 16th / 50th / 84th "
-        f"percentile of the DEM-vs-{instrument} absolute "
-        f"height residuals before alignment.\n"
-        f"  - p16_end / p50_end / p84_end: same percentiles "
-        f"after alignment.\n"
-        f"  - N_shift / E_shift / D_shift: north / east / down "
-        f"components of the applied translation vector.\n"
-        f"  - |T|: magnitude of the translation vector."
+        f"Error Statistics (above, in meters): each row is one "
+        f"statistic of the DEM-vs-{instrument} absolute height "
+        f"residuals, Before and After alignment; Change is the "
+        f"percent change from Before to After, so negative is an "
+        f"improvement.\n"
+        f"  - Median: median residual.\n"
+        f"  - NMAD: normalized median absolute deviation; a robust "
+        f"spread, insensitive to outliers.\n"
+        f"  - RMSE: root-mean-square residual; outlier-sensitive, so "
+        f"a large RMSE next to a small NMAD flags a tail of gross "
+        f"errors rather than a broad misfit.\n"
+        f"  - p16 / p50 / p84: shown instead of the above when the "
+        f"pc_align log predates ASP 3.7.0 (which added the Median / "
+        f"NMAD / RMSE summary): 16th / 50th / 84th percentile of the "
+        f"residuals; p50 is the median.\n\n"
+        f"Translation (above, in meters): the applied translation "
+        f"vector as North / East / Down components and its "
+        f"magnitude |T|. Positive Down means the DEM was too high."
     )

{asp_plot-3.0.0 → asp_plot-3.1.0}/asp_plot/report_pipeline.py

@@ -380,8 +380,27 @@ def _build_detailed_hillshade(ctx: ReportContext) -> List[object]:
     ]
 
 
+# Which pc_align_report() error statistics the alignment report page shows.
+# ASP >= 3.7.0 logs carry a Mean/StdDev/RMSE/Median/NMAD summary, and the
+# page shows Median/NMAD/RMSE from it (mean/stddev tell the same outlier
+# story RMSE does). Older logs only have the 16/50/84 percentiles, so the
+# page falls back to those -- their absence is the ASP-version signal, no
+# version sniffing needed. Everything parsed stays in alignment_report_df.
+_ALIGNMENT_STATS_PAGE_NEW = ("median", "nmad", "rmse")
+_ALIGNMENT_STATS_PAGE_OLD = ("p16", "p50", "p84")
+_ALIGNMENT_STATS_PAGE_HIDDEN = ("mean", "stddev")
+
+
 def _stats_row_from_result(align_result) -> dict:
-    """First row of the alignment report dataframe, minus the 'key' column."""
+    """First row of the alignment report dataframe, reduced to the columns
+    the alignment page shows, minus the 'key' column.
+
+    Columns are the before-alignment error stats, the same after
+    alignment, then the N-E-D translation and its magnitude. If any of the ASP >= 3.7.0
+    ``median_*``/``nmad_*``/``rmse_*`` columns are present the percentile
+    columns are dropped; otherwise (ASP < 3.7.0 log) the percentiles are
+    shown as before. ``mean_*``/``stddev_*`` never appear on the page.
+    """
     stats_row: dict = {}
     if (
         align_result.alignment_report_df is not None
@@ -389,7 +408,23 @@ def _stats_row_from_result(align_result) -> dict:
     ):
         row = align_result.alignment_report_df.iloc[0].to_dict()
         row.pop("key", None)
-        stats_row = row
+        has_new = any(k.split("_")[0] in _ALIGNMENT_STATS_PAGE_NEW for k in row)
+        shown = _ALIGNMENT_STATS_PAGE_NEW if has_new else _ALIGNMENT_STATS_PAGE_OLD
+        hidden = _ALIGNMENT_STATS_PAGE_HIDDEN + (
+            _ALIGNMENT_STATS_PAGE_OLD if has_new else ()
+        )
+        # Error stats first (before, then after alignment, in the order the
+        # tuples list them), then whatever else the row carries -- the
+        # translation columns -- in dataframe order.
+        ordered = [f"{stat}_{when}" for when in ("beg", "end") for stat in shown]
+        stats_row = {k: row[k] for k in ordered if k in row}
+        stats_row.update(
+            {
+                k: v
+                for k, v in row.items()
+                if k not in stats_row and k.split("_")[0] not in hidden
+            }
+        )
     return stats_row
 
 

{asp_plot-3.0.0 → asp_plot-3.1.0}/asp_plot/stereo.py

@@ -96,9 +96,10 @@ class StereoFiles:
     align_left_fn, align_right_fn : str or None
         Alignment transform text files.
     match_point_fn : str or None
-        Match-point file (the non-``-disp-`` one when several exist); None when
-        the directory has none at the top level (e.g. a multi-view run, whose
-        match files live in the ``run-pair*/`` subdirectories).
+        Match-point file, binary ``.match`` or plain-text ``.txt`` (the
+        non-``-disp-`` one when several exist); None when the directory has
+        none at the top level (e.g. a multi-view run, whose match files live
+        in the ``run-pair*/`` subdirectories).
     left_vwip_fn, right_vwip_fn : str or None
         Per-image raw interest point files (``.vwip``) for the left and right
         images; either may be None (they are intermediates that ASP runs
@@ -263,15 +264,65 @@ class StereoFiles:
     def _find_match_file(directory, quiet=False):
         """The directory's match file, or None.
 
+        ASP writes matches either as binary ``<A>__<B>.match`` or, when run
+        with ``--matches-as-txt`` (ASP >= 3.7.0), as plain-text
+        ``<A>__<B>.txt`` (issue #147); both are candidates. The ``.txt`` glob
+        is anchored on the ``__`` image-name separator, and a candidate must
+        also open with a match row (:meth:`_opens_with_match_row`), so the
+        logs and alignment matrices sharing that extension are never picked
+        up -- not even when the run prefix itself contains ``__``.
+
         There may be multiple match files if stereo was run with
         ``--num-matches-from-disparity``; in that case, filter out the match
         file with ``-disp-`` in the filename. Candidates are sorted so the
-        choice is deterministic (glob order is filesystem-dependent).
+        choice is deterministic (glob order is filesystem-dependent), binary
+        ahead of text. The two coexist only when a binary run's matches were
+        converted for inspection (same points either way) or a
+        ``--matches-as-txt`` re-run left an older ``.match`` behind; a run
+        reads one format and ignores the other, so the directory cannot say
+        which was used, and preferring binary keeps the choice every
+        pre-existing layout made.
         """
-        match_files = glob_file(directory, "*.match", all_files=True, quiet=quiet)
-        non_disp = sorted(f for f in (match_files or []) if "-disp-" not in f)
+        candidates = glob_file(directory, "*.match", all_files=True, quiet=True) or []
+        candidates += [
+            f
+            for f in glob_file(directory, "*__*.txt", all_files=True, quiet=True) or []
+            if StereoFiles._opens_with_match_row(f)
+        ]
+        non_disp = sorted(
+            (f for f in candidates if "-disp-" not in f),
+            key=lambda f: (not f.endswith(".match"), f),
+        )
+        if not non_disp and not quiet:
+            logger.warning(
+                f"Could not find a match file (*.match or *__*.txt) in {directory}. Some plots may be missing."
+            )
         return non_disp[0] if non_disp else None
 
+    @staticmethod
+    def _opens_with_match_row(path):
+        """Whether a text file's first non-blank line is a plain-text match
+        row: six numeric fields (``x1 y1 unc1 x2 y2 unc2``).
+
+        With a run prefix containing ``__`` (``-o my__run``), the run's logs
+        (``my__run-log-stereo_corr-*.txt``) and alignment matrices
+        (``my__run-align-L.txt``, three fields per row) match the
+        ``*__*.txt`` discovery glob too, and the alignment matrix even sorts
+        ahead of the real match file; neither opens with six numbers. An
+        empty file -- a run that found no matches -- is accepted.
+        """
+        with open(path, errors="replace") as f:
+            fields = next((line.split() for line in f if line.strip()), None)
+        if fields is None:
+            return True
+        if len(fields) != 6:
+            return False
+        try:
+            [float(v) for v in fields]
+        except ValueError:
+            return False
+        return True
+
     @staticmethod
     def _find_vwip_files(directory, match_point_fn):
         """The directory's left and right ``.vwip`` files, or None for each.
@@ -531,13 +582,51 @@ class StereoPlotter(Plotter):
         iprec.extend(desc)
         return iprec
 
+    @staticmethod
+    def _is_text_match_file(match_point_fn):
+        """Whether a match file is ASP's plain-text format rather than binary.
+
+        ASP itself goes by extension (``.txt`` with ``--matches-as-txt``,
+        ``.match`` otherwise), but the bytes are unambiguous and survive a
+        renamed file: the binary format opens with two little-endian uint64
+        interest point counts, whose upper bytes are NUL, while the text
+        format is digits, spaces and newlines throughout (issue #147).
+        """
+        with open(match_point_fn, "rb") as match_file:
+            return b"\x00" not in match_file.read(16)
+
+    @staticmethod
+    def _read_text_match_file(match_point_fn):
+        """Read an ASP plain-text match file into an x1/y1/x2/y2 DataFrame.
+
+        The format (ASP >= 3.7.0; written by ``--matches-as-txt`` runs and
+        ``ipmatch --binary-to-txt``) is one match per line, six
+        space-separated floats::
+
+            x1 y1 unc1 x2 y2 unc2
+
+        pixel coordinates (column, row from 0) in the first and second image
+        and a per-point uncertainty in pixels that bundle adjustment weights
+        by. The uncertainties are dropped so the result has the same columns
+        as a binary match file's; an empty file (no matches) yields an empty
+        DataFrame.
+        """
+        df = pd.read_csv(
+            match_point_fn,
+            sep=r"\s+",
+            header=None,
+            names=["x1", "y1", "unc1", "x2", "y2", "unc2"],
+        )
+        return df[["x1", "y1", "x2", "y2"]]
+
     def get_match_point_df(self, match_point_fn=None):
         """
-        Convert a binary match file to a DataFrame of match points.
+        Read a match file into a DataFrame of match points.
 
-        Reads the binary match file produced by ASP stereo processing
-        and converts it to a DataFrame containing matched interest points
-        from the left and right images.
+        Reads the match file produced by ASP stereo processing -- the binary
+        ``.match`` format or the plain-text format ASP writes with
+        ``--matches-as-txt`` (issue #147) -- and converts it to a DataFrame
+        containing matched interest points from the left and right images.
 
         Parameters
         ----------
@@ -554,16 +643,23 @@ class StereoPlotter(Plotter):
 
         Notes
         -----
-        This method converts the binary match file to a CSV file with the
-        same base name but '.csv' extension, then reads that CSV file into
-        a DataFrame. If the CSV file already exists, it is read directly.
+        The format is detected from the file's bytes rather than its
+        extension (:meth:`_is_text_match_file`). A binary match file is
+        converted to a CSV file with the same base name but '.csv' extension,
+        then that CSV file is read into a DataFrame; if the CSV file already
+        exists, it is read directly. A plain-text match file is read directly
+        and never consults that cache, so a stale CSV left by an earlier
+        binary run next to it cannot shadow it.
         """
         if match_point_fn is None:
             match_point_fn = self.match_point_fn
-        out_csv = (
-            os.path.splitext(match_point_fn)[0] + ".csv" if match_point_fn else None
-        )
-        if match_point_fn and not os.path.exists(out_csv):
+        if not match_point_fn:
+            return None
+        if self._is_text_match_file(match_point_fn):
+            return self._read_text_match_file(match_point_fn)
+
+        out_csv = os.path.splitext(match_point_fn)[0] + ".csv"
+        if not os.path.exists(out_csv):
             with (
                 open(match_point_fn, "rb") as match_file,
                 open(out_csv, "w") as out,
@@ -580,11 +676,7 @@ class StereoPlotter(Plotter):
                         )
                     )
 
-        return (
-            pd.read_csv(out_csv, delimiter=r"\s+")
-            if out_csv and os.path.exists(out_csv)
-            else None
-        )
+        return pd.read_csv(out_csv, sep=r"\s+")
 
     def get_vwip_df(self, vwip_fn):
         """

{asp_plot-3.0.0 → asp_plot-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "asp_plot"
-version = "3.0.0"
+version = "3.1.0"
 license = {text = "BSD-3-Clause"}
 authors = [
   { name="Ben Purinton", email="purinton@uw.edu" },