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

{asp_plot-2.1.0 → asp_plot-2.2.0}/.github/workflows/claude-code-review.yml

@@ -34,6 +34,6 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }} --comment'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options

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

@@ -46,6 +46,8 @@ sphinx-autobuild docs docs/_build/html --open-browser   # or sphinx-build for a
 - **ASP's `mapproject` writes no log file**; its command is reconstructed from output GeoTIFF metadata (`mapproject.py`), not parsed from logs like the other tools.
 - **Attribution vs sensor naming is deliberate**: copyright/attribution names the rights-holder (`detect_satellite_attribution()` → `"Vantor"` or `"Airbus DS"`), while readers in the `asp_plot/sensors/` package are named for the satellite family (WorldView, Pleiades). Don't reconcile them into one name (#137).
 - **Package vs CLI naming is a deliberate split** (v2.0.0, #165): the *package* is `asp_plot` (`import asp_plot`, `pip install asp-plot`), the report *command* is `asp_report` (`asp_plot/cli/asp_report.py`). There is no `asp_plot` console script and no alias — don't "fix" either name to match the other. The other four CLIs (`stereo_geom`, `csm_camera_plot`, `request_planetary_altimetry`, `gallery`) are unprefixed and unchanged.
+- **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.
 - **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.
 

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

@@ -77,8 +77,8 @@ The package is organized by functionality, with each module focused on a specifi
 - Used by report generation to document processing settings
 
 **`mapproject.py`** - Reconstruct `mapproject` commands from output GeoTIFF metadata (issue #96)
-- ASP's `mapproject` writes **no log file** (unlike `bundle_adjust`/`stereo`/`point2dem`), so `asp_log.py` has nothing to parse for the mapprojection step. Instead of requiring a new ASP `--log` flag, the command is reconstructed **from the output data alone**: ASP stamps `INPUT_IMAGE_FILE` / `CAMERA_FILE` / `DEM_FILE` / `CAMERA_MODEL_TYPE` / `BUNDLE_ADJUST_PREFIX` into each mapprojected GeoTIFF header, and the raster's own CRS / resolution / bounds give `--t_srs` / `--tr` / `--t_projwin`
-- `reconstruct_mapproject_command(raster_path)`: returns the `mapproject ...` string, or `None` if the ASP mapproject tag signature (`REQUIRED_TAGS` = `INPUT_IMAGE_FILE` + `CAMERA_FILE` + `DEM_FILE`, all read back during reconstruction) is absent. Reuses the `utils.Raster` wrapper (free `NotGeoreferencedWarning` suppression + `get_epsg_code()` with the compound-CRS 2D fallback + `get_gsd()`/bounds) rather than re-opening with raw rasterio. `--t_srs` is `EPSG:XXXX` when an EPSG code exists (incl. the 2D fallback), else the quoted PROJ string (custom planetary/local frames, e.g. jitter stereographic); a malformed CRS returns `None` and logs instead of crashing the report. `_format_coord` renders coordinates to 12 significant figures, positionally — clean for large UTM northings *and* full-precision for degree-scale geographic `--tr`, with no scientific notation or float-repr noise. The reconstruction is faithful but **not byte-for-byte re-runnable** (session is the resolved `-t`, an input `--mpp` shows as the resolved `--tr`, output reads the actual filename) — the report flags this with a one-line note
+- ASP's `mapproject` writes **no log file** (unlike `bundle_adjust`/`stereo`/`point2dem`), so `asp_log.py` has nothing to parse for the mapprojection step. Instead of requiring a new ASP `--log` flag, the command is reconstructed **from the output data alone**: ASP stamps `INPUT_IMAGE_FILE` / `CAMERA_FILE` / `DEM_FILE` / `CAMERA_MODEL_TYPE` / `BUNDLE_ADJUST_PREFIX` into each mapprojected GeoTIFF header, and the raster's own CRS / resolution / bounds give `--t_srs` / `--tr` / `--t_projwin` (the bounds shifted half a pixel NW to ASP's pixel-edge convention, #148)
+- `reconstruct_mapproject_command(raster_path)`: returns the `mapproject ...` string, or `None` if the ASP mapproject tag signature (`REQUIRED_TAGS` = `INPUT_IMAGE_FILE` + `CAMERA_FILE` + `DEM_FILE`, all read back during reconstruction) is absent. Reuses the `utils.Raster` wrapper (free `NotGeoreferencedWarning` suppression + `get_epsg_code()` with the compound-CRS 2D fallback + `get_gsd()`/bounds) rather than re-opening with raw rasterio. `--t_srs` is `EPSG:XXXX` when an EPSG code exists (incl. the 2D fallback), else the quoted PROJ string (custom planetary/local frames, e.g. jitter stereographic); a malformed CRS returns `None` and logs instead of crashing the report. `_format_coord` renders coordinates to 12 significant figures, positionally — clean for large UTM northings *and* full-precision for degree-scale geographic `--tr`, with no scientific notation or float-repr noise. The reconstruction is faithful but **not byte-for-byte re-runnable** (session is the resolved `-t`, an input `--mpp` shows as the resolved `--tr`, output reads the actual filename) — the report flags this with a one-line note. It **is grid-exact on ASP >= 3.7.0** (#148): `--t_projwin` is emitted as ASP's pixel-edge box — the GDAL bounds shifted half a pixel NW (`x − tr/2`, `y + tr/2`) — because ASP snaps a projwin by an edge→center conversion plus round-to-nearest, and the raw GDAL bounds of an ASP output (post `PixelIsPoint` shift) land exactly on the rounding tie, drifting the re-run grid one pixel east. The shifted box survives the snap unchanged; re-runs were verified bit-identical. Pre-3.7.0 ASP subtracts one grid size from the projwin maximum, so nothing round-trips there (and the GeoTIFF records no ASP version to adapt to)
 - `find_mapproject_commands(directories, stereo_command=None)`: scans dirs (processing root, BA dir, stereo dir) for all `*.tif`/`*.tiff` and keeps those carrying the tag signature — **identity is decided by the file's own metadata, never by filename**, so there is no naming-convention dependency (reading a GeoTIFF header is cheap; the `NotGeoreferencedWarning` from raw non-georef inputs is silenced). Dedupes by the reconstructed command string (identical scene reached via two dirs collapses; distinct left/right both show). When `stereo_command` is given, a discovered output is kept only if its filename appears in that command — this scopes the result to the run being reported, so a non-mapprojected run sharing a parent dir with mapprojected scenes (the `stereo/` + `stereo_no_mapproj/` layout) does **not** spuriously list a mapproject step. It's a whole-token basename membership test (the output basename must equal one of the stereo command's argument basenames — not a raw substring, so `run.tif` can't match `prun.tif`), not positional parsing. `ProcessingParameters.get_mapproject_commands(stereo_command)` passes the parsed stereo command; `report.py` renders the results under "Mapproject Command(s)" on the Processing Parameters page (via the module-level `_render_command_block` helper, shared with the bundle_adjust/stereo/point2dem commands)
 
 **`sensors/`** - Sensor-specific scene metadata readers (issue #25; split from a single `sensors.py` into a package as groundwork for the sensor expansion in issue #168)
@@ -107,7 +107,8 @@ The package is organized by functionality, with each module focused on a specifi
 - Creates difference maps with reference DEMs
 - Supports both map-projected and raw (non-georeferenced) imagery
 - 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
+- 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
 - **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.
@@ -129,11 +130,15 @@ The package is organized by functionality, with each module focused on a specifi
 
 **`csm_analysis.py`** - asp_plot-specific analysis built on `csm_io`
 - `get_orbit_plot_gdf()`: turns an original/optimized camera pair into the position- and orientation-difference GeoDataFrame consumed by the plotting layer
+- `read_angles_common_frame()`: the asp_plot replacement for `csm_io.read_angles()` when *differencing* two cameras (#53). ASP's `orbit_plot.py` estimates the satellite body frame per camera, from a central difference of that camera's own ephemeris; a solver both perturbs the positions and resamples the ephemeris finer, and over a ~140 m central-difference baseline a 2 m perturbation tilts that frame by ~0.8° (mostly into pitch), which swamps the orientation change being measured. Both cameras are instead put in one frame, estimated from the original ephemeris and resampled onto the optimized camera's grid. Falls back to `read_angles()` for single-sample (frame) cameras, which give no baseline to estimate a frame from
+- `wrap_angle_diff()`: wraps angle differences into [-180, 180), so a camera pointing near ±180° in yaw (ASTER's backward-looking 3B band, say) does not report a ~360° change across the Euler branch cut
 - `reproject_ecef()`, `poly_fit()`
 
 **`csm_camera.py`** - Plotting layer for CSM camera optimization / jitter results
 - Compares original vs optimized CSM camera models (from bundle_adjust/jitter_solve); analyzes position/orientation differences along the trajectory. Currently supports linescan cameras (e.g., WorldView)
 - `csm_camera_summary_plot()`: the near-verbatim cam1/cam2 halves (~210 duplicated lines) collapsed into a single `_plot_camera()` called once per camera (`_apply_frame_xaxis()` for the shared linescan tick logic). Figure output verified unchanged by golden line-content characterization tests
+- Map colorbar limits come from `_magnitude_limits()` **per camera**; `shared_scales=True` widens them to the union across both cameras. Camera 1's scale is not imposed on camera 2 — two cameras in one solver run often differ by more than their own spread, which flattened camera 2's track to one saturated color
+- Two layout rules exist because matplotlib puts a y-axis scale/offset label in each top corner: the `"Camera N"` panel label is **centered** (right-aligned collided with the twin axis's offset), and `_no_offset_colorbar_ticks()` strips the colorbars' *additive* offset (a `1e-8+1.786e-4` string overlapped the adjacent map panel's `1e6` northing offset). Both are pinned by tests in `TestColorbarScaling` / `TestPanelTitlePlacement`
 - Re-exports the moved `csm_io`/`csm_analysis` symbols for backward compatibility with notebooks and downstream imports
 
 **Altimetry** — the 3800-line `Altimetry` god-class was split (issues #130, #140) into a thin coordinator plus a source/plotter/base layer. The public API and the `asp_plot.altimetry` re-exports are preserved by delegation, so `report_pipeline.py`, the CLI, and notebooks are unchanged.

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

@@ -5,6 +5,30 @@ 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).
 
+## [2.2.0] - 2026-08-18
+
+A correctness release for the CSM camera comparison, and a new diagnostic layer under the match points.
+
+`csm_camera_summary_plot()` measured each camera's roll/pitch/yaw against a satellite body frame estimated separately for that camera — correct when plotting one camera, which is what ASP's `orbit_plot.py` does, but wrong for a *difference* between two ([#53](https://github.com/uw-cryo/asp_plot/issues/53)). `bundle_adjust` and `jitter_solve` both resample the ephemeris finer, and over the ~140 m central-difference baseline that leaves, a 2 m position change tilts the frame by ~0.8° — swamping the orientation change being plotted. Both cameras now share one frame, estimated from the original ephemeris, and the committed Salar de Uyuni pair's reported pitch change drops from 0.73° (ranging −3.4° to +3.6°) to 2.6e-06°, which finally says what that run did: it moved positions by ±2 m and left the orientations alone. The figure that looked full of outliers was the frame moving, not the data.
+
+The same figure gains a `bundle_adjust` counterpart to that `jitter_solve` example, in the UCSD WorldView notebook, so the two solvers' signatures can be compared directly — and putting a second, much smaller correction next to the first exposed two readability bugs: camera 2 was drawn on camera 1's colorbar limits, and panel labels overprinted matplotlib's axis offset text.
+
+Separately, the match point figure now underlays ASP's raw per-image interest points (`.vwip`) beneath the matches ([#8](https://github.com/uw-cryo/asp_plot/issues/8)), so a sparse match set can be traced to poor matching versus nothing detected to match; and reconstructed `mapproject` commands re-run grid-identically on ASP >= 3.7.0 instead of drifting a pixel east per run ([#148](https://github.com/uw-cryo/asp_plot/issues/148)).
+
+A minor version: everything is additive, with no API changes and no new dependencies.
+
+### Added
+- **A `bundle_adjust` camera-comparison example in the UCSD WorldView notebook.** The only committed `csm_camera_summary_plot()` example was a `jitter_solve` run, whose per-segment corrections oscillate along the image. `notebooks/WorldView/worldview_spacenet_ucsd_stereo.ipynb` now also compares the original and adjusted cameras from its own `bundle_adjust` run, which solves one rigid translation and rotation per camera and so produces the opposite signature: smooth, nearly flat panels with a sub-metre position offset (0.4 m north on camera 1, 0.9 m up on camera 2, matching `ba/run-camera_offsets.txt`) and a constant orientation change of ~1e-4°. Having both makes the two solvers' signatures directly comparable, and the notebook says what it means if either shows up looking like the other. Because `bundle_adjust` writes CSM state only for the *optimized* cameras, the notebook also documents how to produce the unadjusted one: re-run with a 4x4 identity `--initial-transform` and `--apply-initial-transform-only`.
+- **Raw per-image interest points (`.vwip`) are overlaid on the match point figure** ([#8](https://github.com/uw-cryo/asp_plot/issues/8)). When the `.vwip` files ASP writes during interest point matching are present in the stereo directory (including per-pair in multi-view runs), the match point figure underlays them in blue beneath the red matches, with per-image counts in the panel titles — so sparse matches can be traced to either poor matching or areas with no detected interest points at all (limited texture, clouds, water). If matching failed outright and there is no match file, the raw interest points are still shown on their own. Either side's file may be absent (they are intermediates some runs clean up), in which case the figure degrades to exactly what it showed before. Layers denser than 10,000 points are thinned by seeded random sampling for display — dense runs (~100k interest points) would otherwise saturate the panels into solid color and bloat the figure — while the panel titles always report the true counts.
+
+### Fixed
+- **Each camera's map colorbar now covers that camera's own range.** `csm_camera_summary_plot()` computed colorbar limits from camera 1 and imposed them on camera 2. Two cameras in one solver run routinely differ by more than their own spread — in the new UCSD example `bundle_adjust` moves one camera 0.432–0.454 m and the other 0.885–0.917 m — so camera 2's entire track rendered as a single saturated color with no visible spatial pattern. Limits are now per camera; passing `shared_scales=True` (which already unified the line-panel y-axes) additionally puts both cameras on one common colorbar spanning the union of their ranges, for when comparing magnitudes directly is the point.
+- **Panel labels and axis offset text no longer overprint each other.** matplotlib parks a y-axis scale/offset label in each top corner of an axes, and the angle panels have two of them — the left axis's and the twin axis's — so the right-aligned `"Camera N"` title rendered on top of the twin's (`+1.669e2`), producing unreadable overstruck glyphs. The label is now centered. Separately, over a narrow range of small values a colorbar emits a combined scale-and-offset string (`1e-8+1.786e-4`) wide enough to overlap the neighbouring map panel's northing offset (`1e6`); the colorbars now drop the additive offset, leaving a short multiplier (`1e-4`) and moving the significant digits into the tick labels, where they are easier to read anyway.
+- **CSM camera angle differences no longer report a rotation the camera never underwent** ([#53](https://github.com/uw-cryo/asp_plot/issues/53)). `csm_camera_summary_plot()` compared roll/pitch/yaw computed against a satellite body frame estimated *separately for each camera*, as ASP's `orbit_plot.py` does — a central difference of that camera's own ephemeris. That is fine for plotting one camera, but it corrupts a difference between two: `bundle_adjust` and `jitter_solve` both perturb the positions and resample the ephemeris to a finer spacing, and at WorldView's ~7 km/s a 0.01 s spacing leaves only a ~140 m central-difference baseline, so a 2 m radial perturbation tilts the estimated frame by ~0.8° — orders of magnitude more than the orientation change being measured, landing almost entirely in pitch. Both cameras are now expressed in one frame, estimated from the original (unperturbed) ephemeris and resampled onto the optimized camera's sample grid, so the plotted difference is the true relative rotation between the two camera models. On the committed Salar de Uyuni `jitter_solve` pair this drops the reported pitch change from 0.73° ± (range −3.4° to +3.6°) to 2.6e-06°, revealing what that run actually did: it moved the camera positions by roughly ±2 m and left the orientations untouched. This is what made the example figure look like it was full of outliers.
+- **Angle differences are wrapped at ±180°** ([#53](https://github.com/uw-cryo/asp_plot/issues/53)). Euler angles are recovered on a branch cut, so a camera pointing near ±180° in yaw — a backward-looking sensor such as ASTER's 3B band — had samples straddling the cut reported as ~360° changes instead of the fraction of a degree they really were. Original angle series are also unwrapped before being resampled onto the optimized camera's grid, so a series crossing the cut is no longer interpolated through zero.
+- **The match point figure no longer raises for raw-image runs whose interest points were found on the aligned images** ([#8](https://github.com/uw-cryo/asp_plot/issues/8)). Older ASP versions name the match file for the aligned images (`run-L__R.match`) and write the alignment matrices as `.exr` rather than `.txt`; those match coordinates are already in aligned space, so plotting now detects this from the match filename (left name == the L image) and just rescales instead of demanding `*-align-{L,R}.txt` and failing with `FileNotFoundError`.
+- **Reconstructed `mapproject` commands now re-run grid-identically on ASP >= 3.7.0** ([#148](https://github.com/uw-cryo/asp_plot/issues/148)). The `--t_projwin` reconstructed from an output GeoTIFF's bounds did not round-trip: ASP snaps a given projwin by converting pixel edges to centers and rounding to the nearest grid multiple, and the bounds GDAL reports for an ASP output (after its `PixelIsPoint` half-pixel shift) land exactly on the rounding tie — re-running the reconstructed command drifted the grid one pixel east per run (and at fractional grid sizes, float noise could grow/shrink the raster by a pixel per edge). The reconstruction now emits ASP's own pixel-edge box — the bounds shifted half a pixel NW (`x − tr/2`, `y + tr/2`) — which survives ASP's snap unchanged; re-runs were verified bit-identical (grid, extent, and pixel values) at both whole and fractional grid sizes. On pre-3.7.0 ASP, which subtracted one grid size from the projwin maximum, no projwin choice can round-trip; the report's explanatory note now states the version assumption.
+
 ## [2.1.0] - 2026-07-30
 
 `asp_plot` now reads the same satellite camera metadata the Stereo Pipeline itself does ([#168](https://github.com/uw-cryo/asp_plot/issues/168)). Where 2.0.0 added Airbus Pléiades, this release finishes the job: the rest of the DIMAP v2 family (Pléiades 1A/1B attitude, SPOT 6/7, PeruSat-1), DIMAP v1 (SPOT 5, ALOS PRISM), ASTER, and RPC-only products (Cartosat-1, Deimos, anything ASP runs with `-t rpc`). The one gap left is ASP's `pinhole`/`opticalbar` sessions — historical aerial and declassified film, which carry no satellite geometry to plot.

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: asp_plot
-Version: 2.1.0
+Version: 2.2.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-2.1.0 → asp_plot-2.2.0}/asp_plot/csm_analysis.py

@@ -4,8 +4,13 @@ position- and orientation-difference GeoDataFrame consumed by the plotting
 layer (``csm_camera.py``).
 
 This module owns the asp_plot-specific analysis (``get_orbit_plot_gdf``,
-``reproject_ecef``, ``poly_fit``) and builds on the ASP-mirrored readers in
-``csm_io.py``.
+``read_angles_common_frame``, ``wrap_angle_diff``, ``reproject_ecef``,
+``poly_fit``) and builds on the ASP-mirrored readers in ``csm_io.py``.
+
+``read_angles_common_frame`` is a deliberate divergence from ASP's
+``orbit_plot.py``: differencing two cameras requires them to share one reference
+frame, and ASP estimates a separate frame per camera from that camera's own
+ephemeris. See its docstring and issue #53.
 """
 
 import geopandas as gpd
@@ -15,14 +20,129 @@ from pyproj import Transformer
 from shapely.geometry import Point
 
 from asp_plot.csm_io import (
+    estim_satellite_orientation,
     getTimeAtLine,
     isLinescan,
     read_angles,
     read_csm_cam,
     read_positions_rotations,
+    roll_pitch_yaw,
 )
 
 
+def _resample(values, n_out):
+    """Resample an (n_in, k) array onto ``n_out`` samples spanning the same range."""
+    values = np.asarray(values, dtype=float)
+    n_in = values.shape[0]
+    if n_in == n_out:
+        return values
+    x_out = np.linspace(0, 1, n_out)
+    x_in = np.linspace(0, 1, n_in)
+    return np.column_stack(
+        [np.interp(x_out, x_in, values[:, i]) for i in range(values.shape[1])]
+    )
+
+
+def wrap_angle_diff(angles):
+    """
+    Wrap angle differences in degrees into the [-180, 180) range.
+
+    Parameters
+    ----------
+    angles : array-like
+        Angle differences in degrees
+
+    Returns
+    -------
+    numpy.ndarray
+        The same differences, wrapped into [-180, 180)
+
+    Notes
+    -----
+    Euler angles are recovered on a branch cut, so a camera whose yaw sits near
+    +/-180 degrees (a backward-looking sensor such as ASTER's 3B band, for
+    example) can have adjacent samples reported as +179.9 and -179.9. Without
+    wrapping, an orientation change of 0.2 degrees is plotted as ~360 degrees.
+    """
+    return (np.asarray(angles, dtype=float) + 180.0) % 360.0 - 180.0
+
+
+def read_angles_common_frame(original_camera, optimized_camera):
+    """
+    Read roll/pitch/yaw for a camera pair using a single shared reference frame.
+
+    Parameters
+    ----------
+    original_camera : str
+        Path to the original camera file
+    optimized_camera : str
+        Path to the optimized camera file
+
+    Returns
+    -------
+    tuple of numpy.ndarray
+        ``(original_angles, optimized_angles)``, each of shape (n, 3) holding
+        roll, pitch and yaw in degrees
+
+    Notes
+    -----
+    ASP's ``orbit_plot.py`` (mirrored in ``csm_io.read_angles()``) estimates the
+    satellite body frame separately for each camera, from a central difference
+    of that camera's own ephemeris. That is fine when plotting one camera, but
+    it corrupts a *difference* between two cameras: ``bundle_adjust`` and
+    ``jitter_solve`` both perturb the positions and usually resample the
+    ephemeris to a finer spacing, and a small position perturbation over a short
+    baseline tilts the estimated along-track axis a lot. At WorldView's ~7 km/s
+    and a 0.01 s sample spacing the baseline is only ~140 m, so a 2 m radial
+    perturbation swings the estimated frame by ~0.8 degrees -- orders of
+    magnitude more than the orientation change actually being measured, and it
+    lands almost entirely in pitch.
+
+    Here both cameras are instead expressed in one frame, estimated from the
+    original (unperturbed) ephemeris and resampled onto the optimized camera's
+    sample grid. The reported angle difference is then the true relative
+    rotation between the two camera models, not a difference of two different
+    reference frames.
+    """
+    original_positions, original_rotations = read_positions_rotations([original_camera])
+    optimized_positions, optimized_rotations = read_positions_rotations(
+        [optimized_camera]
+    )
+    original_positions = np.array(original_positions, dtype=float)
+
+    # A single-sample (frame) camera gives no baseline to estimate a satellite
+    # frame from, so fall back to ASP's behavior. Guard on *both* cameras: a
+    # one-sample optimized camera would collapse the resample below to a single
+    # point, which has the same zero-length tangent vector problem. Neither path
+    # produces usable angles for a frame camera -- ASP's own
+    # estim_satellite_orientation divides by zero there too -- so this only
+    # keeps the two cameras treated alike.
+    if len(original_positions) < 2 or len(optimized_rotations) < 2:
+        original_angles, optimized_angles = read_angles(
+            [original_camera], [optimized_camera], []
+        )
+        return np.array(original_angles), np.array(optimized_angles)
+
+    original_ref_rotations = estim_satellite_orientation(original_positions)
+    optimized_ref_rotations = estim_satellite_orientation(
+        _resample(original_positions, len(optimized_rotations))
+    )
+
+    original_angles = np.array(
+        [
+            roll_pitch_yaw(original_rotations[i], original_ref_rotations[i])
+            for i in range(len(original_rotations))
+        ]
+    )
+    optimized_angles = np.array(
+        [
+            roll_pitch_yaw(optimized_rotations[i], optimized_ref_rotations[i])
+            for i in range(len(optimized_rotations))
+        ]
+    )
+    return original_angles, optimized_angles
+
+
 def reproject_ecef(positions, to_epsg=4326):
     """
     Reproject ECEF coordinates to a specified EPSG coordinate system.
@@ -79,12 +199,13 @@ def get_orbit_plot_gdf(original_camera, optimized_camera, map_crs=None, trim=Tru
     cameras, it optionally trims the data to only include samples corresponding
     to the actual image lines.
     """
-    # orbit_plot.py method to get angles in NED
-    # https://github.com/NeoGeographyToolkit/StereoPipeline/blob/master/src/asp/Tools/orbit_plot.py#L412
-    # This method already calls read_positions_rotations below, but it
-    # doesn't return the positions and rotations we want for plotting
-    original_rotation_angles, optimized_rotation_angles = read_angles(
-        [original_camera], [optimized_camera], []
+    # Roll/pitch/yaw for both cameras, expressed in a single satellite frame
+    # estimated from the original ephemeris. This follows orbit_plot.py's
+    # read_angles() (mirrored in csm_io) but shares one reference frame between
+    # the two cameras, so the difference below is not contaminated by the
+    # frame itself moving. See read_angles_common_frame() for why.
+    original_rotation_angles, optimized_rotation_angles = read_angles_common_frame(
+        original_camera, optimized_camera
     )
 
     # orbit_plot.py method to get positions and rotations
@@ -142,28 +263,26 @@ def get_orbit_plot_gdf(original_camera, optimized_camera, map_crs=None, trim=Tru
     optimized_pitch = np.array([r[1] for r in optimized_rotation_angles])
     optimized_yaw = np.array([r[2] for r in optimized_rotation_angles])
 
-    # Interpolate original angles if lengths don't match
+    # Interpolate original angles if lengths don't match. Unwrap first so a
+    # series straddling the +/-180 branch cut is not averaged through zero,
+    # then wrap the result back into [-180, 180).
     if len(original_roll) != len(optimized_roll):
-        original_roll = np.interp(
-            np.linspace(0, 1, len(optimized_roll)),
-            np.linspace(0, 1, len(original_roll)),
-            original_roll,
-        )
-        original_pitch = np.interp(
-            np.linspace(0, 1, len(optimized_pitch)),
-            np.linspace(0, 1, len(original_pitch)),
-            original_pitch,
-        )
-        original_yaw = np.interp(
-            np.linspace(0, 1, len(optimized_yaw)),
-            np.linspace(0, 1, len(original_yaw)),
-            original_yaw,
+        original_angles = _resample(
+            np.unwrap(
+                np.column_stack([original_roll, original_pitch, original_yaw]),
+                period=360.0,
+                axis=0,
+            ),
+            len(optimized_roll),
         )
+        original_roll, original_pitch, original_yaw = wrap_angle_diff(original_angles).T
 
-    # We are interested in the difference between the original and optimized angles
-    roll_diff = original_roll - optimized_roll
-    pitch_diff = original_pitch - optimized_pitch
-    yaw_diff = original_yaw - optimized_yaw
+    # We are interested in the difference between the original and optimized
+    # angles. Wrap the differences so a camera pointing near +/-180 degrees in
+    # yaw does not report a ~360 degree change across the branch cut.
+    roll_diff = wrap_angle_diff(original_roll - optimized_roll)
+    pitch_diff = wrap_angle_diff(original_pitch - optimized_pitch)
+    yaw_diff = wrap_angle_diff(original_yaw - optimized_yaw)
 
     # Also get angular diff magnitude
     angular_diff_magnitudes = np.sqrt(roll_diff**2 + pitch_diff**2 + yaw_diff**2)

{asp_plot-2.1.0 → asp_plot-2.2.0}/asp_plot/csm_camera.py

@@ -15,11 +15,14 @@ import numpy as np
 from matplotlib import pyplot as plt
 from matplotlib.cm import ScalarMappable
 from matplotlib.colors import Normalize
+from matplotlib.ticker import ScalarFormatter
 
 from asp_plot.csm_analysis import (  # noqa: F401  (re-exported for back-compat)
     get_orbit_plot_gdf,
     poly_fit,
+    read_angles_common_frame,
     reproject_ecef,
+    wrap_angle_diff,
 )
 from asp_plot.csm_io import (  # noqa: F401  (re-exported for back-compat)
     ASP_TO_CSM_SHIFT,
@@ -124,6 +127,60 @@ def _apply_frame_xaxis(ax, gdf, frame):
         ax.set_xlabel("Position Sample", fontsize=9)
 
 
+def _no_offset_colorbar_ticks(cbar):
+    """
+    Stop a colorbar from labelling its ticks with an additive offset.
+
+    Parameters
+    ----------
+    cbar : matplotlib.colorbar.Colorbar
+        The colorbar to reformat
+
+    Notes
+    -----
+    Over a narrow range of small values -- angle changes of 1.7860e-4 to
+    1.7870e-4 degrees, say -- matplotlib labels the ticks 0.5, 1.0, 1.5 and
+    parks a combined scale-and-offset string ("1e-8+1.786e-4") above the
+    colorbar, where it collides with the adjacent map panel's own northing
+    offset ("1e6"). Dropping the additive offset leaves a bare multiplier
+    ("1e-4"), which is both short enough to clear the neighbour and easier to
+    read: the ticks then carry the significant digits themselves.
+    """
+    formatter = ScalarFormatter(useOffset=False)
+    formatter.set_powerlimits((-3, 4))
+    cbar.ax.yaxis.set_major_formatter(formatter)
+
+
+def _magnitude_limits(magnitudes, upper_magnitude_percentile):
+    """
+    Colorbar limits for one camera's difference magnitudes.
+
+    Parameters
+    ----------
+    magnitudes : pandas.Series
+        A ``position_diff_magnitude`` or ``angular_diff_magnitude`` column
+    upper_magnitude_percentile : int
+        Percentile used for the upper limit
+
+    Returns
+    -------
+    tuple of float
+        ``(vmin, vmax)``, or ``(0, 0)`` when nothing changed
+
+    Notes
+    -----
+    Exact zeros are excluded before taking percentiles, and an all-zero column
+    (a camera the solver left untouched) returns ``(0, 0)`` rather than raising
+    on the empty percentile (issue #54).
+    """
+    values = magnitudes[magnitudes > 0]
+    try:
+        vmin, vmax = np.percentile(values, [0, upper_magnitude_percentile])
+    except IndexError:
+        vmin, vmax = 0, 0
+    return vmin, vmax
+
+
 def _plot_camera(
     pos_row,
     ang_row,
@@ -203,6 +260,7 @@ def _plot_camera(
     )
     cbar1.set_label("Diff Magnitude (m)", fontsize=9)
     cbar1.ax.tick_params(labelsize=9)
+    _no_offset_colorbar_ticks(cbar1)
 
     # Angle-magnitude mapview plot
     ax = ang_row[0]
@@ -228,6 +286,7 @@ def _plot_camera(
     )
     cbar2.set_label("Diff Magnitude (°)", fontsize=9)
     cbar2.ax.tick_params(labelsize=9)
+    _no_offset_colorbar_ticks(cbar2)
 
     frame = np.arange(gdf.shape[0])
 
@@ -263,7 +322,11 @@ def _plot_camera(
     for ax in [ax1, ax2, ax3]:
         ax.set_xlim(frame.min(), frame.max())
         ax.hlines(0, frame.min(), frame.max(), color="k", linestyle="-", lw=0.5)
-        ax.set_title(cam_label, loc="right", fontsize=10, y=0.98)
+        # Centered, not right-aligned: matplotlib parks a y-axis offset/scale
+        # label ("1e-5", "+1.669e2") in each top corner, and the angle panels
+        # have two of them -- the left axis's at top left and the twin axis's
+        # at top right -- so a right-aligned title renders on top of the latter.
+        ax.set_title(cam_label, loc="center", fontsize=10)
         _apply_frame_xaxis(ax, gdf, frame)
         ax.set_ylabel("Original $-$ Optimized (m)", fontsize=9)
         if shared_scales:
@@ -310,7 +373,11 @@ def _plot_camera(
     for ax, ax_r in [(ax1, ax1_r), (ax2, ax2_r), (ax3, ax3_r)]:
         ax.set_xlim(frame.min(), frame.max())
         ax.hlines(0, frame.min(), frame.max(), color="k", linestyle="-", lw=0.5)
-        ax.set_title(cam_label, loc="right", fontsize=10, y=0.98)
+        # Centered, not right-aligned: matplotlib parks a y-axis offset/scale
+        # label ("1e-5", "+1.669e2") in each top corner, and the angle panels
+        # have two of them -- the left axis's at top left and the twin axis's
+        # at top right -- so a right-aligned title renders on top of the latter.
+        ax.set_title(cam_label, loc="center", fontsize=10)
         _apply_frame_xaxis(ax, gdf, frame)
         ax.set_ylabel("Original $-$ Optimized (°)", fontsize=9)
         if shared_scales:
@@ -408,28 +475,38 @@ def csm_camera_summary_plot(
         )
         add_basemap = False
 
-    # Calculate colorbar ranges from camera 1; camera 2 reuses the same scale.
-    position_values = gdf_cam1.position_diff_magnitude[
-        gdf_cam1.position_diff_magnitude > 0
-    ]
-    angular_values = gdf_cam1.angular_diff_magnitude[
-        gdf_cam1.angular_diff_magnitude > 0
-    ]
-    # When position or angular changes are all zero, the percentile calculation will fail
-    # https://github.com/uw-cryo/asp_plot/issues/54
-    try:
-        cam1_position_vmin, cam1_position_vmax = np.percentile(
-            position_values, [0, upper_magnitude_percentile]
+    # Colorbar ranges are per camera by default. Two cameras in one run can
+    # differ by more than their own spread -- bundle_adjust might move one by
+    # 0.44 m and the other by 0.90 m -- and forcing the second onto the first's
+    # scale paints its whole track a single saturated color, hiding any spatial
+    # pattern. shared_scales puts both on one scale when the point is to compare
+    # their magnitudes directly.
+    cam1_position_vmin, cam1_position_vmax = _magnitude_limits(
+        gdf_cam1.position_diff_magnitude, upper_magnitude_percentile
+    )
+    cam1_angular_vmin, cam1_angular_vmax = _magnitude_limits(
+        gdf_cam1.angular_diff_magnitude, upper_magnitude_percentile
+    )
+    if cam2_list:
+        cam2_position_vmin, cam2_position_vmax = _magnitude_limits(
+            gdf_cam2.position_diff_magnitude, upper_magnitude_percentile
         )
-    except IndexError:
-        cam1_position_vmin, cam1_position_vmax = 0, 0
-
-    try:
-        cam1_angular_vmin, cam1_angular_vmax = np.percentile(
-            angular_values, [0, upper_magnitude_percentile]
+        cam2_angular_vmin, cam2_angular_vmax = _magnitude_limits(
+            gdf_cam2.angular_diff_magnitude, upper_magnitude_percentile
         )
-    except IndexError:
-        cam1_angular_vmin, cam1_angular_vmax = 0, 0
+        if shared_scales:
+            cam1_position_vmin = cam2_position_vmin = min(
+                cam1_position_vmin, cam2_position_vmin
+            )
+            cam1_position_vmax = cam2_position_vmax = max(
+                cam1_position_vmax, cam2_position_vmax
+            )
+            cam1_angular_vmin = cam2_angular_vmin = min(
+                cam1_angular_vmin, cam2_angular_vmin
+            )
+            cam1_angular_vmax = cam2_angular_vmax = max(
+                cam1_angular_vmax, cam2_angular_vmax
+            )
 
     if upper_magnitude_percentile == 100:
         extend = "neither"
@@ -467,10 +544,10 @@ def csm_camera_summary_plot(
             gdf_cam2,
             cam2_name,
             "Camera 2",
-            cam1_position_vmin,
-            cam1_position_vmax,
-            cam1_angular_vmin,
-            cam1_angular_vmax,
+            cam2_position_vmin,
+            cam2_position_vmax,
+            cam2_angular_vmin,
+            cam2_angular_vmax,
             extend,
             add_basemap,
             shared_scales,

{asp_plot-2.1.0 → asp_plot-2.2.0}/asp_plot/mapproject.py

@@ -15,13 +15,28 @@ ASP ``--log`` flag required. The fields written by ASP are:
 - ``BUNDLE_ADJUST_PREFIX`` -- the ``--bundle-adjust-prefix`` (``"NONE"`` if unset)
 
 combined with the raster's own CRS (``--t_srs``), resolution (``--tr``), and
-bounds (``--t_projwin``).
+bounds (``--t_projwin``, shifted half a pixel NW to ASP's pixel-edge
+convention -- see below).
 
 The reconstruction is faithful but *not* byte-for-byte re-runnable: the session
 type is the resolved value (not necessarily what the user typed), an input
 ``--mpp`` shows up resolved as ``--tr``, and the output name is read from the
 file itself. Callers that surface this to users (e.g. the PDF report) should say
 so. See ``reconstruct_mapproject_command`` for the exact argv order.
+
+The emitted ``--t_projwin`` is, however, *grid-exact*: re-running the
+reconstructed command with ASP >= 3.7.0 reproduces the output's grid, extent,
+and pixel values identically (verified empirically for #148). That requires
+emitting ASP's pixel-edge box -- the GDAL-reported bounds shifted half a pixel
+NW -- because ASP snaps a given projwin via an edge-to-center conversion plus
+round-to-nearest, and the raw GDAL bounds of an ASP output land exactly on the
+rounding tie (drifting the grid one pixel east per re-run). Two version caveats:
+ASP < 3.7.0 instead subtracts one grid size from the projwin maximum, so no
+projwin choice round-trips there (worst case: a one-pixel extent difference,
+identical pixel values on the shared grid); and the outputs of pre-3.7.0
+explicit-``--t_projwin`` runs may sit on a grid phase that a modern re-run snaps
+up to half a pixel. The output GeoTIFF records no ASP version, so the
+reconstruction targets current semantics unconditionally.
 """
 
 import glob
@@ -96,6 +111,11 @@ def reconstruct_mapproject_command(raster_path):
     ``--t_srs`` is emitted as ``EPSG:XXXX`` when the CRS has an exact EPSG code,
     otherwise as the PROJ string (quoted), so custom planetary/local projections
     (e.g. the stereographic frames used in jitter solving) still round-trip.
+
+    ``--t_projwin`` is the raster's bounds shifted half a pixel NW (x - tr/2,
+    y + tr/2): ASP's pixel-edge box, which re-runs grid-identically on
+    ASP >= 3.7.0 instead of drifting one pixel east (#148; see the module
+    docstring for the full convention story and pre-3.7.0 caveats).
     """
     # Reuse the package Raster wrapper: it suppresses the NotGeoreferencedWarning
     # that the raw (non-georef) input scenes raise during discovery, and it owns
@@ -122,14 +142,26 @@ def reconstruct_mapproject_command(raster_path):
         if t_srs:
             parts += ["--t_srs", t_srs]
 
-        parts += ["--tr", _format_coord(raster.get_gsd())]
+        gsd = raster.get_gsd()
+        parts += ["--tr", _format_coord(gsd)]
+        # Emit --t_projwin as ASP's pixel-EDGE box (pixel centers +- tr/2), not
+        # the GDAL-reported bounds. ASP snaps a given projwin by converting
+        # edges to centers (+ tr/2) and rounding to the nearest grid multiple;
+        # the bounds GDAL reports for an ASP output (after its PixelIsPoint
+        # half-pixel shift) land exactly on that rounding tie, so re-running
+        # with them drifts the grid one pixel east per run (and float noise at
+        # fractional grid sizes can flip individual edges either way). Shifting
+        # the window half a pixel NW yields the box ASP itself passes to its
+        # mapproject_single tiles; it survives the snap unchanged, and the
+        # re-run grid is identical (#148, ASP >= 3.7.0 -- see module docstring).
+        half = gsd / 2
         bounds = raster.ds.bounds
         parts += [
             "--t_projwin",
-            _format_coord(bounds.left),
-            _format_coord(bounds.bottom),
-            _format_coord(bounds.right),
-            _format_coord(bounds.top),
+            _format_coord(bounds.left - half),
+            _format_coord(bounds.bottom + half),
+            _format_coord(bounds.right - half),
+            _format_coord(bounds.top + half),
         ]
 
         ba_prefix = tags.get("BUNDLE_ADJUST_PREFIX")

{asp_plot-2.1.0 → asp_plot-2.2.0}/asp_plot/report.py

@@ -493,7 +493,8 @@ def _add_processing_parameters_page(pdf, params, report_command):
             0,
             4,
             "Reconstructed from output GeoTIFF metadata (mapproject writes no "
-            "log file); session type and grid size are the resolved values.",
+            "log file); session type and grid size are the resolved values. "
+            "Re-running reproduces the output grid exactly with ASP >= 3.7.0.",
             new_x="LMARGIN",
             new_y="NEXT",
         )

{asp_plot-2.1.0 → asp_plot-2.2.0}/asp_plot/report_captions.py

@@ -17,7 +17,7 @@ INPUT_SCENES = "Left and right input scenes used for stereo processing. Non-mapp
 
 STEREO_GEOMETRY = "Stereo acquisition geometry skyplot and map view showing satellite viewing angles and scene footprints."
 
-MATCH_POINTS = "Interest point matches between left and right images. These are produced by stereo_corr during its initial interest point matching step, which is used to set the search windows for subsequent dense correlation (not the dense correlation matches themselves)."
+MATCH_POINTS = "Interest point matches between left and right images (red), overlaid on the raw interest points detected on each image individually (blue, when the .vwip files are present in the stereo directory). These are produced by stereo_corr during its initial interest point matching step, which is used to set the search windows for subsequent dense correlation (not the dense correlation matches themselves). Comparing the raw interest points against the matches shows whether sparse matching traces back to poor matching or to areas with no detected interest points at all (e.g., limited texture, clouds, water). Some ASP configurations only write a .vwip file for the left image (the right image's interest points are detected on a temporary aligned image and not saved), in which case only matches are shown on the right."
 
 BUNDLE_RESIDUALS_LOG = (
     "Initial and final bundle adjustment residuals on a logarithmic scale."

{asp_plot-2.1.0 → asp_plot-2.2.0}/asp_plot/stereo.py

@@ -29,6 +29,17 @@ from asp_plot.utils import (
 logging.basicConfig(level=logging.WARNING)
 logger = logging.getLogger(__name__)
 
+# Overlay colors for the match point figure, chosen to stand out against the
+# grayscale images.
+INTEREST_POINT_COLOR = "deepskyblue"
+MATCH_POINT_COLOR = "r"
+# At most this many markers are drawn per overlay layer: dense runs (e.g.
+# ~100k interest points) saturate the panels into solid color otherwise.
+# Layers are thinned by seeded random sampling, which preserves the spatial
+# coverage the figure exists to show; panel titles always report the true
+# counts.
+MAX_POINTS_DRAWN = 10000
+
 
 @dataclass
 class PairStereoFiles:
@@ -49,6 +60,8 @@ class PairStereoFiles:
     align_left_fn: Optional[str]
     align_right_fn: Optional[str]
     match_point_fn: Optional[str]
+    left_vwip_fn: Optional[str]
+    right_vwip_fn: Optional[str]
     disparity_sub_fn: Optional[str]
     disparity_fn: Optional[str]
 
@@ -86,6 +99,10 @@ class StereoFiles:
         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).
+    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
+        sometimes clean up, and some runs keep only the left file).
     disparity_sub_fn, disparity_fn : str or None
         Sub-sampled and full disparity map paths.
     pairs : list of PairStereoFiles
@@ -179,6 +196,9 @@ class StereoFiles:
         )
 
         self.match_point_fn = self._find_match_file(self.full_directory, quiet=quiet)
+        self.left_vwip_fn, self.right_vwip_fn = self._find_vwip_files(
+            self.full_directory, self.match_point_fn
+        )
 
         self.disparity_sub_fn = glob_file(
             self.full_directory, "*-D_sub.tif", quiet=quiet
@@ -187,22 +207,29 @@ class StereoFiles:
         # and rescaling below.
         self.disparity_fn = glob_file(self.full_directory, "*-D.tif", quiet=quiet)
 
-        self.pairs = [
-            PairStereoFiles(
-                number=number,
-                directory=pair_directory,
-                label=describe_pair(number, pair_directory),
-                left_image_fn=glob_file(pair_directory, "*-L.tif"),
-                left_image_sub_fn=glob_file(pair_directory, "*-L_sub.tif"),
-                right_image_sub_fn=glob_file(pair_directory, "*-R_sub.tif"),
-                align_left_fn=glob_file(pair_directory, "*-align-L.txt"),
-                align_right_fn=glob_file(pair_directory, "*-align-R.txt"),
-                match_point_fn=self._find_match_file(pair_directory),
-                disparity_sub_fn=glob_file(pair_directory, "*-D_sub.tif"),
-                disparity_fn=glob_file(pair_directory, "*-D.tif"),
+        self.pairs = []
+        for number, pair_directory in pair_directories:
+            match_point_fn = self._find_match_file(pair_directory)
+            left_vwip_fn, right_vwip_fn = self._find_vwip_files(
+                pair_directory, match_point_fn
+            )
+            self.pairs.append(
+                PairStereoFiles(
+                    number=number,
+                    directory=pair_directory,
+                    label=describe_pair(number, pair_directory),
+                    left_image_fn=glob_file(pair_directory, "*-L.tif"),
+                    left_image_sub_fn=glob_file(pair_directory, "*-L_sub.tif"),
+                    right_image_sub_fn=glob_file(pair_directory, "*-R_sub.tif"),
+                    align_left_fn=glob_file(pair_directory, "*-align-L.txt"),
+                    align_right_fn=glob_file(pair_directory, "*-align-R.txt"),
+                    match_point_fn=match_point_fn,
+                    left_vwip_fn=left_vwip_fn,
+                    right_vwip_fn=right_vwip_fn,
+                    disparity_sub_fn=glob_file(pair_directory, "*-D_sub.tif"),
+                    disparity_fn=glob_file(pair_directory, "*-D.tif"),
+                )
             )
-            for number, pair_directory in pair_directories
-        ]
 
         self.dem_gsd = dem_gsd
 
@@ -238,12 +265,59 @@ class StereoFiles:
 
         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.
+        file with ``-disp-`` in the filename. Candidates are sorted so the
+        choice is deterministic (glob order is filesystem-dependent).
         """
         match_files = glob_file(directory, "*.match", all_files=True, quiet=quiet)
-        non_disp = [f for f in (match_files or []) if "-disp-" not in f]
+        non_disp = sorted(f for f in (match_files or []) if "-disp-" not in f)
         return non_disp[0] if non_disp else None
 
+    @staticmethod
+    def _find_vwip_files(directory, match_point_fn):
+        """The directory's left and right ``.vwip`` files, or None for each.
+
+        ASP writes the per-image raw interest points next to the match file
+        that pairs them: ``<A>__<B>.match`` sits alongside ``<A>.vwip`` and
+        ``<prefix>-<B>.vwip`` (``A``/``B`` are ``L``/``R`` when interest
+        points were found on the aligned images, the input image basenames
+        otherwise). Either side may be absent — they are intermediates that
+        some runs clean up or only partially keep — so lookups are quiet.
+        """
+        vwip_files = sorted(
+            glob_file(directory, "*.vwip", all_files=True, quiet=True) or []
+        )
+
+        def stem(fn):
+            return os.path.splitext(os.path.basename(fn))[0]
+
+        if match_point_fn:
+            match_stem = stem(match_point_fn)
+            left = next(
+                (f for f in vwip_files if match_stem.startswith(stem(f) + "__")),
+                None,
+            )
+            right_name = (
+                match_stem[len(stem(left)) + 2 :]
+                if left
+                else match_stem.rsplit("__", 1)[-1]
+            )
+            right = next(
+                (f for f in vwip_files if f != left and stem(f).endswith(right_name)),
+                None,
+            )
+            return left, right
+
+        # No match file (e.g. interest point matching itself failed): fall
+        # back to the aligned-image naming. Vwips named after the input
+        # images are deliberately NOT picked up here: without a match file
+        # there is nothing to say which image is left vs right, nor whether
+        # the align transform applies, so guessing could plot the points on
+        # the wrong panel or in the wrong coordinate space.
+        return (
+            glob_file(directory, "*-L.vwip", quiet=True),
+            glob_file(directory, "*-R.vwip", quiet=True),
+        )
+
 
 class StereoPlotter(Plotter):
     """
@@ -374,6 +448,14 @@ class StereoPlotter(Plotter):
     def match_point_fn(self):
         return self.files.match_point_fn
 
+    @property
+    def left_vwip_fn(self):
+        return self.files.left_vwip_fn
+
+    @property
+    def right_vwip_fn(self):
+        return self.files.right_vwip_fn
+
     @property
     def disparity_sub_fn(self):
         return self.files.disparity_sub_fn
@@ -504,56 +586,136 @@ class StereoPlotter(Plotter):
             else None
         )
 
+    def get_vwip_df(self, vwip_fn):
+        """
+        Read a per-image raw interest point file (``.vwip``) into a DataFrame.
+
+        These are the interest points ASP detects on each image before
+        matching them across the pair; the ``.match`` file keeps only the
+        subset that matched. Comparing the two shows whether sparse matches
+        come from poor matching or from areas with no interest points at all
+        (limited texture, clouds, water).
+
+        Parameters
+        ----------
+        vwip_fn : str or None
+            Path to the ``.vwip`` file.
+
+        Returns
+        -------
+        pandas.DataFrame or None
+            DataFrame with columns 'x' and 'y' of the interest point
+            coordinates, or None if the file is missing.
+
+        Notes
+        -----
+        The file is a single uint64 interest point count followed by the same
+        binary interest point records as the ``.match`` file (issue #8).
+        """
+        if not vwip_fn or not os.path.exists(vwip_fn):
+            return None
+        with open(vwip_fn, "rb") as vwip_file:
+            (size,) = np.frombuffer(vwip_file.read(8), dtype=np.uint64)
+            ip = [self.read_ip_record(vwip_file) for _ in range(int(size))]
+        return pd.DataFrame({"x": [r[0] for r in ip], "y": [r[1] for r in ip]})
+
+    @staticmethod
+    def _thin_for_display(df):
+        """Subsample a point DataFrame down to :data:`MAX_POINTS_DRAWN` rows
+        for plotting (see the constant's rationale); returns it unchanged
+        when already under the cap. Sampling is seeded (deterministic) and
+        random rather than strided, because striding a gridded interest
+        point layout produces moiré artifacts."""
+        if len(df) <= MAX_POINTS_DRAWN:
+            return df
+        return df.sample(n=MAX_POINTS_DRAWN, random_state=0).sort_index()
+
+    @staticmethod
+    def _ip_on_aligned_images(files):
+        """Whether interest points were found on the aligned L/R images
+        rather than on the input images.
+
+        ASP names the match file after the images interest points were found
+        on: when the left name in ``<A>__<B>.match`` is the L image itself
+        (e.g. ``run-L__R.match``, as older ASP versions wrote for raw inputs),
+        the coordinates are already in aligned space and must not go through
+        the alignment matrices again. With no match file at all, the only
+        ``.vwip`` files discovered are ``*-L.vwip``/``*-R.vwip`` (see
+        :meth:`StereoFiles._find_vwip_files`), which are aligned-space too.
+        """
+
+        def stem(fn):
+            return os.path.splitext(os.path.basename(fn))[0]
+
+        if not files.match_point_fn:
+            return True
+        if not files.left_image_fn:
+            return False
+        left_name = stem(files.match_point_fn).split("__")[0]
+        return left_name == stem(files.left_image_fn)
+
     def _plot_match_points_figure(self, files, title, save_dir=None, fig_fn=None):
         """One two-panel match-point figure for a :class:`StereoFiles` or
         :class:`PairStereoFiles` (duck-typed) set of products."""
         match_point_df = self.get_match_point_df(files.match_point_fn)
+        left_vwip_df = self.get_vwip_df(files.left_vwip_fn)
+        right_vwip_df = self.get_vwip_df(files.right_vwip_fn)
 
         fig, axa = plt.subplots(1, 2, figsize=(10, 5))
 
-        if (
-            files.left_image_fn
-            and files.left_image_sub_fn
-            and files.right_image_sub_fn
-            and match_point_df is not None
-        ):
+        have_images = (
+            files.left_image_fn and files.left_image_sub_fn and files.right_image_sub_fn
+        )
+        have_points = (
+            match_point_df is not None
+            or left_vwip_df is not None
+            or right_vwip_df is not None
+        )
+        if have_images and have_points:
+            # Both the match file and the .vwip files hold coordinates in the
+            # space of the images interest points were found on, so one
+            # transform per side maps either onto the sub-sampled images.
             if self.orthos:
                 full_gsd = Raster(files.left_image_fn).get_gsd()
                 sub_gsd = Raster(files.left_image_sub_fn).get_gsd()
                 rescale_factor = sub_gsd / full_gsd
-                left_x = match_point_df["x1"] / rescale_factor
-                left_y = match_point_df["y1"] / rescale_factor
-                right_x = match_point_df["x2"] / rescale_factor
-                right_y = match_point_df["y2"] / rescale_factor
-            else:
-                if not files.align_left_fn or not files.align_right_fn:
-                    raise FileNotFoundError(
-                        "Alignment matrix files (*-align-{L,R}.txt) not found. "
-                        "These are required to overlay match points on non-mapprojected images."
-                    )
 
+                def to_sub(x, y, side):
+                    return x / rescale_factor, y / rescale_factor
+
+            else:
                 full_width = Raster(files.left_image_fn).ds.width
                 sub_width = Raster(files.left_image_sub_fn).ds.width
                 rescale_factor = full_width / sub_width
 
-                # Transform match points from original to aligned coordinate space
-                align_L = np.loadtxt(files.align_left_fn)
-                align_R = np.loadtxt(files.align_right_fn)
+                if self._ip_on_aligned_images(files):
+                    # Interest points were found on the aligned images
+                    # themselves (the match file is named for L, e.g.
+                    # <prefix>-L__R.match, as older ASP wrote for raw
+                    # inputs), so their coordinates are already in aligned
+                    # space and only need rescaling.
+                    def to_sub(x, y, side):
+                        return x / rescale_factor, y / rescale_factor
 
-                n = len(match_point_df)
-                ones = np.ones(n)
-
-                left_pts = np.vstack([match_point_df["x1"], match_point_df["y1"], ones])
-                left_aligned = align_L @ left_pts
-                left_x = left_aligned[0] / rescale_factor
-                left_y = left_aligned[1] / rescale_factor
+                else:
+                    if not files.align_left_fn or not files.align_right_fn:
+                        raise FileNotFoundError(
+                            "Alignment matrix files (*-align-{L,R}.txt) not found. "
+                            "These are required to overlay match points on non-mapprojected images."
+                        )
 
-                right_pts = np.vstack(
-                    [match_point_df["x2"], match_point_df["y2"], ones]
-                )
-                right_aligned = align_R @ right_pts
-                right_x = right_aligned[0] / rescale_factor
-                right_y = right_aligned[1] / rescale_factor
+                    # Transform points from original to aligned coordinate space
+                    align = {
+                        "left": np.loadtxt(files.align_left_fn),
+                        "right": np.loadtxt(files.align_right_fn),
+                    }
+
+                    def to_sub(x, y, side):
+                        aligned = align[side] @ np.vstack([x, y, np.ones(len(x))])
+                        return (
+                            aligned[0] / rescale_factor,
+                            aligned[1] / rescale_factor,
+                        )
 
             left_image = Raster(files.left_image_sub_fn).read_array()
             right_image = Raster(files.right_image_sub_fn).read_array()
@@ -571,28 +733,52 @@ class StereoPlotter(Plotter):
                 add_cbar=False,
                 copyright=True,
             )
-            axa[0].set_title(f"Left (n={match_point_df.shape[0]})")
-            axa[1].set_title("Right")
-
-            axa[0].scatter(
-                left_x,
-                left_y,
-                color="r",
-                marker="o",
-                facecolor="none",
-                s=1,
-            )
-            axa[0].set_aspect("equal")
-
-            axa[1].scatter(
-                right_x,
-                right_y,
-                color="r",
-                marker="o",
-                facecolor="none",
-                s=1,
-            )
-            axa[1].set_aspect("equal")
+
+            for ax, side, vwip_df, name in (
+                (axa[0], "left", left_vwip_df, "Left"),
+                (axa[1], "right", right_vwip_df, "Right"),
+            ):
+                counts = []
+                if vwip_df is not None:
+                    thinned = self._thin_for_display(vwip_df)
+                    x, y = to_sub(thinned["x"], thinned["y"], side)
+                    ax.scatter(
+                        x,
+                        y,
+                        color=INTEREST_POINT_COLOR,
+                        marker="o",
+                        facecolor="none",
+                        s=1,
+                        label="Interest points",
+                    )
+                    counts.append(f"{vwip_df.shape[0]:,} ip")
+                if match_point_df is not None:
+                    thinned = self._thin_for_display(match_point_df)
+                    x, y = to_sub(
+                        thinned["x1" if side == "left" else "x2"],
+                        thinned["y1" if side == "left" else "y2"],
+                        side,
+                    )
+                    ax.scatter(
+                        x,
+                        y,
+                        color=MATCH_POINT_COLOR,
+                        marker="o",
+                        facecolor="none",
+                        s=1,
+                        label="Matches",
+                    )
+                    counts.append(f"{match_point_df.shape[0]:,} matches")
+                ax.set_title(
+                    f"{name} ({', '.join(counts)})" if counts else name,
+                    fontsize=10,
+                )
+                ax.set_aspect("equal")
+
+            if match_point_df is not None and (
+                left_vwip_df is not None or right_vwip_df is not None
+            ):
+                axa[0].legend(loc="best", fontsize=7, markerscale=4)
         else:
             self.plot_missing(axa[0])
             self.plot_missing(axa[1])
@@ -606,8 +792,15 @@ class StereoPlotter(Plotter):
 
         Creates a figure with two subplots showing the left and right
         subsampled images with match points overlaid as small red circles.
-        For mapprojected scenes, match points are rescaled using the GSD ratio.
-        For non-mapprojected scenes, match points are transformed from original
+        When the per-image raw interest point files (``.vwip``) are present,
+        they are underlaid as small blue circles, so sparse matches can be
+        traced to either poor matching or areas with no detected interest
+        points at all (issue #8); if the match file is missing entirely, the
+        raw interest points are still shown on their own. Layers denser than
+        :data:`MAX_POINTS_DRAWN` are thinned by seeded random sampling for
+        display (the panel titles always report the true counts).
+        For mapprojected scenes, points are rescaled using the GSD ratio.
+        For non-mapprojected scenes, points are transformed from original
         to aligned coordinate space using the alignment matrices, then rescaled
         to the subsampled image dimensions.
 

{asp_plot-2.1.0 → asp_plot-2.2.0}/pyproject.toml

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