asp-plot 3.4.0__tar.gz → 3.5.0__tar.gz

{asp_plot-3.4.0 → asp_plot-3.5.0}/.gitignore

@@ -140,7 +140,9 @@ notebooks/**/*.parquet
 notebooks/**/*.csv
 CLAUDE/
 .claude/**
-scripts/
+# Study driver scripts live in a separate repo; scripts is often a symlink to it,
+# which a trailing-slash pattern (directories only) does not match.
+/scripts
 /*.parquet
 reports/regenerate_reports.sh
 # Figure-selections sidecars written next to each report by `asp_report`. These are

{asp_plot-3.4.0 → asp_plot-3.5.0}/AGENTS.md

@@ -52,15 +52,35 @@ To publish a regenerated set:
 
 ```bash
 bash reports/regenerate_reports.sh          # gitignored; needs ~/Desktop/asp-plot-examples
+
+# Switch the Zenodo webhook off for the publish (needs repo admin; see below)
+HOOK=$(gh api repos/uw-cryo/asp_plot/hooks \
+    --jq '.[] | select(.config.url | contains("zenodo.org")) | .id')
+gh api -X PATCH repos/uw-cryo/asp_plot/hooks/$HOOK -F active=false --jq .active
+
 gh release create reports-$(date +%F) \
     reports/*.pdf reports/*_figure_selections.yml reports/regenerate_reports.sh \
     --target main --latest=false \
     --title "Example reports, $(date +%F)" --notes "What changed and why."
+
+# Confirm nothing was delivered for the new release, then switch it back on
+gh api "repos/uw-cryo/asp_plot/hooks/$HOOK/deliveries?per_page=3" \
+    --jq '.[] | "\(.delivered_at) \(.event) \(.action)"'
+gh api -X PATCH repos/uw-cryo/asp_plot/hooks/$HOOK -F active=true --jq .active
 # then bump REPORTS_RELEASE in docs/fetch_example_reports.sh and commit that one line
 ```
 
-Four things matter here:
-
+Five things matter here:
+
+- **Keep the release off Zenodo.** The repository has a Zenodo webhook on
+  `release` events, and Zenodo archives every published release as a version of
+  the software: it cannot tell a reports release from a version release. The
+  `reports-2026-09-18` release was archived that way and, being the newest
+  record, became what the DOI badge in the README resolves to. Switch the
+  webhook off before publishing and back on afterwards, as above; GitHub does
+  not re-send the events it skipped. Always pass `--jq` when reading the hook,
+  because its URL embeds an access token that must not end up in a log or a
+  comment. A published Zenodo record can only be removed by Zenodo support.
 - **Publish the release before pushing the commit** that points at it. The docs
   build uses `curl -f`, so a tag that does not exist yet fails the build.
 - **`--latest=false`**, or the reports release takes the "Latest" badge from the
@@ -69,13 +89,11 @@ Four things matter here:
   hardcode absolute local paths) but they are what makes regeneration
   figure-stable and offline (issue #121), so keeping them with the PDFs they
   produced makes a release self-describing.
-- **Attach `regenerate_reports.sh` as well, for the same reason and one more.**
-  It is gitignored too, which means it is in no clone *and in no backup* — a
-  mirror of this repository contains zero objects for it, because git never
-  tracked it. The release is therefore its only durable copy, and a release that
-  carries the reports, the selections that shaped them, and the commands that
-  produced them can be reproduced by someone who has the example datasets and
-  nothing else.
+- **Attach `regenerate_reports.sh` as well, for the same reason.** It is
+  gitignored too, so no clone of this repository contains it. Attaching it keeps
+  a copy with each set of reports, and a release that carries the reports, the
+  selections that shaped them, and the commands that produced them can be
+  reproduced by someone who has the example datasets and nothing else.
 
 Always regenerate with `--reuse-selections` so pages stay figure-for-figure
 comparable and no SlideRule request is made. Reports are capped at 200 effective
@@ -93,9 +111,9 @@ what keeps the assets small.
 - **There is no "unadjusted" CSM state on disk after a `bundle_adjust` run** — it writes only `*.adjusted_state.json` for the *optimized* cameras, while the originals exist solely as vendor XML. To get the before-camera for `csm_camera_summary_plot()`, re-run with an identity transform: write a 4x4 identity to `identity.txt` and pass `--initial-transform identity.txt --apply-initial-transform-only` with the same images/XMLs into a separate `-o` prefix. That skips iterations, matching, and reports (seconds, not minutes), and the resulting `.adjust` files are exactly zero translation + identity quaternion, so you can verify the cameras really are untouched. Demonstrated in `notebooks/WorldView/worldview_spacenet_ucsd_stereo.ipynb`.
 - **CSM camera *differences* deliberately diverge from ASP's `orbit_plot.py`** (#53): `csm_analysis.read_angles_common_frame()` puts both cameras in one satellite body frame estimated from the *original* ephemeris, instead of estimating a frame per camera from its own positions the way `csm_io.read_angles()` (the ASP mirror) does. A solver perturbs positions *and* resamples the ephemeris finer, and over the resulting ~140 m central-difference baseline a 2 m perturbation tilts a per-camera frame by ~0.8° — which is what made the example figure look full of outliers. Angle diffs are also wrapped to [-180, 180). Don't "re-sync" either back to `read_angles()`; `csm_io.py` stays a verbatim ASP mirror and is not where this belongs.
 - **Airbus DIMAP quaternions are scalar-first** (`Q0` = scalar); they are reordered to the scalar-last `q1..q4` layout the roll/pitch/yaw code expects in `PleiadesMetadata.getAtt_df()`. Don't "fix" the reorder.
-- **The altimetry outlier cut is a 30-NMAD gate plus 3σ; both values are deliberate.** A whole ICESat-2 pass can be cloud (over UCSD one pass was a marine-layer return 150–210 m above ground, 21 % of the sample), which defeats a plain mean ± 3σ cut by inflating σ; the gate removes it. Don't "simplify" the cut to median ± 3 NMAD: on the heavy-tailed residuals a DSM has against ICESat-2 in a city that removes a fifth of the real points and lowers every reported NMAD by a third (`_outlier_mask` in `altimetry_source.py`; the case is described in the benchmark notebook's UCSD section). If a benchmark or report shows an RMSE far above its NMAD, look for a cloud pass in the residual map before touching the DEM.
-- **`asp_plot.sensors.rpc.read_rpc()` refuses any raster that carries a CRS**, on purpose: an RPC describes the raw image grid, and ASP's `mapproject` copies RPC metadata onto its outputs. However, GDAL sometimes writes a lat/lon geotransform from a NITF's corner coordinates when converting it (one of five CORE3D scenes came out that way), and the reader then calls a raw scene "already map-projected". Strip it with `gdal_edit.py -unsetgt -a_srs "" scene.tif`.
-- **SpaceNet CORE3D NITF scenes are JPEG2000, and the ASP 3.8.0-alpha build ships GDAL's JP2OpenJPEG driver as a plugin it never loads**: `gdalinfo` and rasterio both fail with *No JPEG2000 capable driver is available*. `GDAL_DRIVER_PATH=<ASP root>/lib` for one `gdal_translate` to GeoTIFF is enough; the older 3.7.0 build had the driver built in, which is why earlier UCSD runs never hit this.
+- **The altimetry outlier cut is a 30-NMAD gate plus 3σ; both values are deliberate.** A whole ICESat-2 pass can be cloud (over UCSD one pass was a marine-layer return 150–210 m above ground, 21 % of the sample), which defeats a plain mean ± 3σ cut by inflating σ; the gate removes it. Don't "simplify" the cut to median ± 3 NMAD: on the heavy-tailed residuals a DSM has against ICESat-2 in a city that removes a fifth of the real points and lowers every reported NMAD by a third (`_outlier_mask` in `altimetry_source.py`). If a benchmark or report shows an RMSE far above its NMAD, look for a cloud pass in the residual map before touching the DEM.
+- **`asp_plot.sensors.rpc.read_rpc()` refuses any raster that carries a CRS**, on purpose: an RPC describes the raw image grid, and ASP's `mapproject` copies RPC metadata onto its outputs.
+- **SpaceNet CORE3D NITF scenes are JPEG2000, and the ASP 3.8.0-alpha build ships GDAL's JP2OpenJPEG driver as a plugin it never loads**: `gdalinfo` and rasterio both fail with *No JPEG2000 capable driver is available*. `GDAL_DRIVER_PATH=<ASP root>/lib` for one `gdal_translate` to GeoTIFF is enough; the older 3.7.0 build had the driver built in, which is why earlier UCSD runs never hit this. The conda-forge `asp-3.7.0` env on NAS ships it as a plugin too, under `$ASP_ROOT/lib/gdalplugins`.
 - **ASP multiview triangulation of mapprojected images needs `ISISROOT`** (observed with ASP 3.8.0-alpha, non-ISIS `-t pleiades` session): the joint triangulation aborts with an uncatchable `Isis::IException` (`$ISISROOT/IsisPreferences was not found`) that surfaces as a generic "Failed to run"/killed job. Workaround: `export ISISROOT=<ASP install root>` (the release bundles `IsisPreferences` there). Pair runs and raw-image multiview runs are unaffected; full write-up in a PR #155 comment.
 
 ## External Data Sources

{asp_plot-3.4.0 → asp_plot-3.5.0}/ARCHITECTURE.md

@@ -62,6 +62,7 @@ The package is organized by functionality, with each module focused on a specifi
 - 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)
+- `_keep_figures()`: with `--figures-directory`, copies each section's PNG out of `tmp_asp_report_plots/` as `NN_<title-slug>.png` after `compile_report()` has numbered the sections, and before the plots directory is deleted. The title is in the name because figure numbers shift when a section is gated off
 
 **`report_captions.py`** - Caption + description text for the report sections (issue #128)
 - All section captions and the Earth/planetary alignment descriptions as module constants / small builder functions, moved out of the CLI as a data module (verified byte-identical to the pre-refactor strings via AST comparison)
@@ -366,7 +367,7 @@ Docs dependencies are in `pyproject.toml` under `[project.optional-dependencies]
 ## Example Notebooks
 
 Example notebooks demonstrating modular usage are organized by sensor type:
-- `notebooks/WorldView/` - WorldView examples (Earth-based). `worldview_spacenet_ucsd_stereo.ipynb` is the classic two-scene pair example; `worldview_utqiagvik_stereo.ipynb` (excluded from the docs build) and `worldview_uyuni_jitter_plots.ipynb` cover comprehensive modular usage and jitter plots; the two `*_scene_selection.ipynb` notebooks pick which scenes to process with `stereo_geom` before any ASP run. **`worldview_spacenet_benchmark.ipynb` is the scene-combination benchmark (issue #169)**: with `DEMBenchmark` on one ICESat-2 sample per site it scores every combination and flow — at Atlanta 21 DEMs (all ten pairs of the five same-pass scenes, six `dem_mosaic` blends incl. median / convergence-weighted / `VerticalStdDev`-weighted, six multi-view runs incl. two references) then at UCSD 17 DEMs (five multi-date WorldView-3 scenes over a steep crop of Mount Soledad: three multi-view references, ten pairs, four blends) (both sets of runs come from local driver scripts that are not in the repo; the notebook re-scores whatever is on disk). Crop and scene selection for UCSD are done in the notebook from metadata staged next to the data (`ucsd_mvs/selection/`). Its findings, in its two takeaways sections: at the same-pass flat site single-pair accuracy is set by convergence angle; at the steep multi-date site the point estimates depend more on which scene a pair contains than on its geometry, but a paired track bootstrap (#199) separates only the worst DEM from the rest, so those rules are suggested rather than established; at both sites the multi-view reference scene has the largest effect. The Atlanta example (`worldview_spacenet_atlanta_mvs.ipynb`) is a 3-scene same-pass multi-view run (`parallel_stereo --alignment-method affineepipolar` on the `wv_correct`ed `*_corr.tif` images, nadir13 reference) compared against the ASP-docs-recommended alternative: the three pairwise runs merged with `dem_mosaic` (coverage, DEM difference, ICESat-2 residuals). Two crop-window methods keep the ROIs matched: the reference crop window in mapprojected/ground coordinates converts to image pixels via GDAL's inverse RPC transform on the *original* `.tif` (the `wv_correct` `_corr.tif` carries no RPC metadata) — `gdal.Transformer(["METHOD=RPC", "RPC_HEIGHT=<m>"])` + `TransformPoint(1, lon, lat, h)` on the corners; and the `--left-image-crop-win` for a pair whose left image is *not* the reference is derived from the `bundle_adjust` clean match points that fall inside the reference crop window (no RPCs needed at all).
+- `notebooks/WorldView/` - WorldView examples (Earth-based). `worldview_spacenet_ucsd_stereo.ipynb` is the classic two-scene pair example; `worldview_utqiagvik_stereo.ipynb` (excluded from the docs build) and `worldview_uyuni_jitter_plots.ipynb` cover comprehensive modular usage and jitter plots. The Atlanta example (`worldview_spacenet_atlanta_mvs.ipynb`) is a 3-scene same-pass multi-view run (`parallel_stereo --alignment-method affineepipolar` on the `wv_correct`ed `*_corr.tif` images, nadir13 reference) compared against the ASP-docs-recommended alternative: the three pairwise runs merged with `dem_mosaic` (coverage, DEM difference, ICESat-2 residuals). Two crop-window methods keep the ROIs matched: the reference crop window in mapprojected/ground coordinates converts to image pixels via GDAL's inverse RPC transform on the *original* `.tif` (the `wv_correct` `_corr.tif` carries no RPC metadata) — `gdal.Transformer(["METHOD=RPC", "RPC_HEIGHT=<m>"])` + `TransformPoint(1, lon, lat, h)` on the corners; and the `--left-image-crop-win` for a pair whose left image is *not* the reference is derived from the `bundle_adjust` clean match points that fall inside the reference crop window (no RPCs needed at all). Its benchmark cell, six DEMs scored with `DEMBenchmark` on one ICESat-2 sample, is the worked example of `DEMBenchmark`.
 - `notebooks/Pleiades/` - Airbus Pléiades Neo tri-stereo example over Marseille (Earth-based): DIMAP stereo-geometry analysis, bundle adjustment of all three scenes, and a 3-image multi-view stereo run (nadir reference, `--left-image-crop-win` derived from the DIMAP `Dataset_Extent` vertices; the ASP docs discourage MVS in favor of pairwise + `dem_mosaic`, which the notebook cites)
 - `notebooks/ASTER/` - ASTER examples with map-projection and jitter correction (Earth-based)
 - `notebooks/LRO_NAC/` - Lunar Reconnaissance Orbiter Narrow Angle Camera examples (Lunar)

{asp_plot-3.4.0 → asp_plot-3.5.0}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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).
 
+## [Unreleased]
+
+## [3.5.0] - 2026-10-23
+
+In this release:
+
+- `asp_report --figures-directory` keeps a copy of each report figure, named by figure number and title, for use in notebooks and slides.
+- `DEMBenchmark` reuses a translated DEM newer than its inputs instead of rewriting it on every run.
+- Three study notebooks are no longer in the examples.
+- The example reports are regenerated under 3.4.0, and a reports release is kept off Zenodo.
+
+### Added
+- **`asp_report --figures-directory DIR` keeps a copy of each report figure** (`ReportConfig.figures_directory`). The report plots every figure to `tmp_asp_report_plots/` and deletes that directory once the PDF is written, so the only way to show a figure in a notebook or slides was to extract it from the PDF. With the option, each figure is also copied to `DIR` as `NN_<title>.png` (`05_dem_results.png`, `07_icesat_2_atl06_sr_map.png`), where `NN` is its figure number in the PDF. The title is in the name because the numbers shift when a section is skipped. Nothing is kept by default, so existing runs are unchanged.
+
+### Changed
+- **The example reports are regenerated under 3.4.0** and published as [`reports-2026-09-29`](https://github.com/uw-cryo/asp_plot/releases/tag/reports-2026-09-29); the docs build fetches that set. All seven carry the intersection error captions of 3.4.0. `WorldView_Atlanta_MVS` is rebuilt for the first time since the 200 dpi cap, which the fix for deleted `*-L.tif` files ([#202](https://github.com/uw-cryo/asp_plot/issues/202)) made possible, and goes from 22.4 MB to 12.4 MB. Every report was rebuilt with `--reuse-selections`, so each page shows the same altimetry points and clips as before.
+- **A reports release is kept off Zenodo.** Zenodo archives every published GitHub release as a version of the software, and the first reports release had become what the DOI badge resolves to. `AGENTS.md` now has the step that prevents it: the Zenodo webhook is switched off while a reports release is published.
+- **`DEMBenchmark` reuses a translated DEM that is newer than its DEM and its `pc_align` output** instead of rewriting it on every run, so re-scoring from cached `pc_align` runs no longer writes a full-size copy of every DEM. A new copy is written under a temporary name and renamed, so an interrupted run cannot leave a partial file that a later run would reuse.
+
+### Removed
+- **Three study notebooks are no longer examples: `worldview_spacenet_benchmark.ipynb`, `worldview_spacenet_atlanta_stereo_scene_selection.ipynb` and `worldview_spacenet_ucsd_stereo_scene_selection.ipynb`.** Each answered a research question (which scene combination or pair gives the best DEM) rather than showing how to use a feature, and each re-execution added a full new copy of the notebook to the repository's history. `worldview_spacenet_atlanta_mvs.ipynb` remains the worked example of `DEMBenchmark`; `docs/cli/stereo_geom.md` covers assessing the geometry of every pair in a multi-scene delivery; and the UCSD stereo and Atlanta MVS notebooks now say in their text how their pairs were chosen and how the candidates scored (markdown edits only; neither notebook was re-executed).
+
 ## [3.4.0] - 2026-09-29
 
 In this release:

{asp_plot-3.4.0 → asp_plot-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: asp_plot
-Version: 3.4.0
+Version: 3.5.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.4.0 → asp_plot-3.5.0}/asp_plot/cli/asp_report.py

@@ -137,6 +137,12 @@ def _reconstruct_command():
     type=int,
     help="Resolution ceiling for figures embedded in the PDF, applied at the size each figure is placed on the page. Figures are plotted at 220 dpi and then scaled down to the page, so wide multi-panel figures otherwise land at 400+ effective dpi and inflate the file for detail no screen or printer shows. Pass 0 to embed the full-resolution figures.",
 )
+@click.option(
+    "--figures-directory",
+    prompt=False,
+    default=None,
+    help="Directory to keep a copy of each report figure in, as NN_<title>.png (e.g. 05_dem_results.png), where NN is the figure number in the PDF. A relative path is taken from the current directory, not from --directory. Use this to show figures in a notebook or slides without extracting them from the PDF. Files of the same name are overwritten. Default: None, the figures are not kept.",
+)
 def main(
     directory,
     bundle_adjust_prefix,
@@ -156,6 +162,7 @@ def main(
     report_filename,
     report_title,
     figure_max_dpi,
+    figures_directory,
 ):
     """
     Generate a comprehensive report of ASP processing results.
@@ -183,6 +190,7 @@ def main(
         report_filename=report_filename,
         report_title=report_title,
         figure_max_dpi=figure_max_dpi,
+        figures_directory=figures_directory,
         report_command=_reconstruct_command(),
     )
     run_report(config)

{asp_plot-3.4.0 → asp_plot-3.5.0}/asp_plot/dem_benchmark.py

@@ -54,6 +54,7 @@ Examples
 >>> bench.summary_plot(save_dir="atlanta_mvs", fig_fn="dem_benchmark.png")
 """
 
+import glob
 import logging
 import os
 import re
@@ -235,6 +236,14 @@ def _safe_dirname(label):
     return re.sub(r"[^\w.-]+", "_", label).strip("_") or "dem"
 
 
+def _is_newer_than(fn, sources):
+    """True if ``fn`` exists and is at least as new as every existing file in ``sources``."""
+    if not os.path.exists(fn):
+        return False
+    mtime = os.path.getmtime(fn)
+    return all(os.path.getmtime(s) <= mtime for s in sources if os.path.exists(s))
+
+
 def _dh_stats(dh, prefix):
     """median / NMAD / RMSE of a dh series as ``{prefix}_*_m`` keys (NaN when empty)."""
     values = np.asarray(dh, dtype=float)
@@ -363,8 +372,10 @@ class DEMBenchmark:
     directory : str
         Working folder. pc_align products, the pc_align CSV and the translated
         DEM copy for each candidate go under ``<directory>/dem_benchmark/<label>/``.
-        The translated copy is rewritten on every run, so two benchmarks
-        sharing a directory and a label must not run at the same time.
+        The translated copy is reused while it is newer than its DEM and the
+        pc_align output, and otherwise rewritten (under a temporary name, then
+        renamed), so two benchmarks sharing a directory and a label must not
+        run at the same time.
     dems : dict or list
         ``{label: dem_fn}`` (order preserved), or a list of paths /
         ``"label=path"`` strings (see :func:`parse_dem_specs`).
@@ -597,7 +608,8 @@ class DEMBenchmark:
             Also run ``pc_align --compute-translation-only`` per DEM and
             re-score against the translated copy. Default True. Existing
             pc_align outputs under the benchmark folder are reused, so a
-            re-run makes no pc_align call and works offline.
+            re-run makes no pc_align call and works offline; so are translated
+            DEMs newer than their DEM and pc_align output.
         minimum_points : int, optional
             Skip pc_align for a DEM with fewer valid dh points, default 500
             (the report's threshold).
@@ -992,10 +1004,23 @@ class DEMBenchmark:
             )
             return None, None
         stem = os.path.splitext(os.path.basename(dem_fn))[0]
-        aligned_fn = alignment.apply_dem_translation(
-            output_prefix=output_prefix,
-            output_fn=os.path.join(label_dir, f"{stem}_pc_align_translated.tif"),
+        aligned_fn = os.path.join(label_dir, f"{stem}_pc_align_translated.tif")
+        if _is_newer_than(
+            aligned_fn,
+            [dem_fn]
+            + glob.glob(os.path.join(label_dir, "pc_align", f"{prefix_name}-*")),
+        ):
+            print(f"  Reusing translated DEM {aligned_fn}")
+            return report, aligned_fn
+        # Write under a temporary name and rename, so an interrupted run never
+        # leaves a partial copy that the next run would take as current.
+        partial_fn = os.path.join(label_dir, f"{stem}_pc_align_translated.partial.tif")
+        written = alignment.apply_dem_translation(
+            output_prefix=output_prefix, output_fn=partial_fn
         )
+        if written != partial_fn:
+            return report, written
+        os.replace(partial_fn, aligned_fn)
         return report, aligned_fn
 
     def _reference_stats(self, label, dem_fn):

{asp_plot-3.4.0 → asp_plot-3.5.0}/asp_plot/report_pipeline.py

@@ -14,6 +14,7 @@ Captions live in :mod:`asp_plot.report_captions`.
 """
 
 import os
+import re
 import shutil
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
@@ -83,6 +84,9 @@ class ReportConfig:
     # Resolution ceiling for figures embedded in the PDF, applied at the size
     # each figure is placed on the page. See asp_plot.report.FIGURE_MAX_DPI.
     figure_max_dpi: Optional[int] = FIGURE_MAX_DPI
+    # Directory to keep a copy of each report figure in, as NN_<title>.png.
+    # None keeps nothing: the figures are deleted with the plots directory.
+    figures_directory: Optional[str] = None
     # Reconstructed "asp_report --flag ..." string recorded in the report. The
     # CLI builds this from the Click context; non-CLI callers may leave it None.
     report_command: Optional[str] = None
@@ -1052,12 +1056,35 @@ def _write_figure_selections(ctx: ReportContext) -> None:
         print(f"\nCould not write figure selections: {e}\n")
 
 
+def _keep_figures(sections: List[object], figures_directory: str) -> None:
+    """Copy each report figure to ``figures_directory`` as ``NN_<title>.png``.
+
+    ``NN`` is the figure number printed in the PDF and ``<title>`` the page
+    heading in lowercase with runs of other characters replaced by ``_``
+    (e.g. ``05_dem_results.png``), so a figure can be picked by name even when
+    a section is skipped and the numbers shift. Files of the same name are
+    overwritten; nothing else in the directory is touched.
+    """
+    figures_directory = os.path.expanduser(figures_directory)
+    os.makedirs(figures_directory, exist_ok=True)
+    kept = 0
+    for section in sections:
+        if not section.image_path or not os.path.exists(section.image_path):
+            continue
+        slug = re.sub(r"[^a-z0-9]+", "_", section.title.lower()).strip("_")
+        fn = f"{section.figure_number:02}_{slug}.png"
+        shutil.copy2(section.image_path, os.path.join(figures_directory, fn))
+        kept += 1
+    print(f"\nKept {kept} report figures in {figures_directory}\n")
+
+
 def run_report(config: ReportConfig) -> str:
     """Generate the ASP processing report described by ``config``.
 
     Builds the runtime context, iterates the declarative
     :data:`REPORT_SECTIONS` registry to assemble the report body, compiles the
-    PDF, writes the figure-selections sidecar, and cleans up. Returns the path
+    PDF, writes the figure-selections sidecar, keeps a copy of the figures if
+    ``config.figures_directory`` is set, and cleans up. Returns the path
     to the written PDF. Importable and callable without any Click context.
     """
     ctx = _setup_context(config)
@@ -1088,6 +1115,9 @@ def run_report(config: ReportConfig) -> str:
 
     _write_figure_selections(ctx)
 
+    if config.figures_directory:
+        _keep_figures(sections, config.figures_directory)
+
     shutil.rmtree(ctx.plots_directory)
 
     print(f"\n\nReport saved to {ctx.report_pdf_path}\n\n")

{asp_plot-3.4.0 → asp_plot-3.5.0}/pyproject.toml

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