asp-plot 1.18.0__tar.gz → 1.19.0__tar.gz

{asp_plot-1.18.0 → asp_plot-1.19.0}/AGENTS.md

@@ -110,8 +110,8 @@ The package is organized by functionality, with each module focused on a specifi
 - Coordinate utilities: `get_utm_epsg()` for determining UTM EPSG from lon/lat, `get_planetary_bounds()` for DEM bounds in planetocentric 0-360 lon/lat
 - Planetary body detection: `detect_planetary_body(dem_fn)` returns `"earth"`, `"moon"`, or `"mars"` by inspecting CRS WKT DATUM/ELLIPSOID fields
 - Subprocess utilities: `run_subprocess_command()`
-- Vantor/copyright utilities:
-  - `detect_vantor_satellite(directory)`: Checks XML files for WorldView SATIDs (WV01/WV02/WV03)
+- Vantor/copyright utilities (an **attribution** concern — named for the rights-holder — kept deliberately distinct from sensor/reader **identity**, the WorldView-named abstraction in `sensors.py`; #137):
+  - `detect_vantor_satellite(directory)`: True when an XML camera file's `SATID` matches `VANTOR_SATID_PREFIXES` — any DigitalGlobe→Maxar→Vantor-owned satellite, i.e. the WorldView family (`WV*`, incl. Legion `WVLG`), GeoEye (`GE*`), QuickBird (`QB*`), IKONOS (`IK*`) — not just WorldView. Gates the `© Vantor` overlay via `Plotter.is_vantor`
   - `add_copyright_overlay(ax)`: Adds "© Vantor {year}" text overlay to bottom-right of matplotlib axes
 - Scene metadata: `get_acquisition_dates(directory, extra_dirs=None)` reads `FIRSTLINETIME` from WorldView/Maxar XMLs and parses the capture timestamp from `AST_L1A_...` file/directory names. Returns a sorted, deduplicated list of `"YYYY-MM-DD HH:MM:SS UTC"` strings; empty if nothing is found. Used by the CLI to populate `ReportMetadata.acquisition_dates`.
 
@@ -160,16 +160,16 @@ The package is organized by functionality, with each module focused on a specifi
 - `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.py`** - Sensor-specific scene metadata readers (issue #25)
-- `SensorMetadata` ABC defining the reader interface (`detect` + `get_scene_dicts`) and the sensor-agnostic scene-dict schema, mirroring the `bodies.py` registry pattern so adding ASTER/HiRISE/etc. is a new subclass with no change to the geometry code
-- `WorldViewMetadata(SensorMetadata)`: the WorldView/Maxar XML logic (file discovery, `dg_mosaic` tiling, per-scene extraction, ephemeris/attitude/footprint) moved verbatim out of the parser. Named after the satellite family rather than the (twice-renamed: DigitalGlobe → Maxar → Vantor) company; the same format also covers GeoEye-1/QuickBird/IKONOS
-- `SENSORS` registry + `sensor_for_directory()` detection
+- `SensorMetadata` ABC defining the reader interface (`detect` + `detect_files` + `get_scene_dicts`) and the sensor-agnostic scene-dict schema, mirroring the `bodies.py` registry pattern so adding ASTER/HiRISE/etc. is a new subclass with no change to the geometry code
+- `WorldViewMetadata(SensorMetadata)`: the WorldView/Maxar XML logic (file discovery, `dg_mosaic` tiling, per-scene extraction, ephemeris/attitude/footprint) moved verbatim out of the parser. Named after the satellite family rather than the (twice-renamed: DigitalGlobe → Maxar → Vantor) company; the same format also covers GeoEye-1/QuickBird/IKONOS. Constructible from either a `directory=` (recursive discovery) or an explicit `image_list=` (already-resolved XML paths); non-camera files (`README.XML`, ortho) are filtered out either way
+- `SENSORS` registry + two detection entry points: `sensor_for_directory()` (scans a directory) and `sensor_for_inputs()` (accepts a mixed list of files/dirs/globs). The latter routes through `resolve_xml_inputs()`, which expands directories (recursively), globs, and plain paths into a deduped, sorted XML list — this is what lets `stereo_geom *.XML` / explicit files / a delivery dir all work without a fixed structure
 
 **`stereopair_metadata_parser.py`** - `StereopairMetadataParser` class
-- Now a **sensor-agnostic orchestrator** (issue #25): detects a reader via `sensor_for_directory()`, delegates scene discovery/extraction to it, and keeps only the pair-level geometry
+- Now a **sensor-agnostic orchestrator** (issue #25): detects a reader via `sensor_for_directory()` (from `directory=`) or `sensor_for_inputs()` (from a mixed `inputs=` list of files/dirs/globs), delegates scene discovery/extraction to it, and keeps only the pair-level geometry
 - Computes stereo geometry metrics: convergence angle, base-to-height ratio, bisector elevation, asymmetry
 - Provides spatial utilities: `get_pair_utm_epsg()`, `get_intersection_bounds()`, `get_scene_bounds()`
 - `get_catid_dicts()` returns dictionaries per catalog ID with ephemeris, attitude, and geometry data (sourced from the sensor reader)
-- Currently supports pairs; N-scene support is planned
+- **N-scene aware** (issue #73): `get_pair_dict()` is the exact-two-scene entry point (raises otherwise); `get_pair_dicts()` returns one pair dict per N-choose-2 combination so >2 scenes can be assessed pairwise. `get_pair_map_projection()` falls back to the footprint union when a pair does not overlap, and `get_pair_intersection()` tolerates a `None` intersection (non-overlapping pairs report `intersection_area = None`)
 
 **`stereo.py`** - `StereoPlotter` class (inherits from `Plotter`)
 - Visualizes ASP stereo processing results
@@ -321,6 +321,8 @@ All CLI tools are in `asp_plot/cli/` and use Click for argument parsing:
 - Wrapper for `StereoGeometryPlotter`
 - Creates skyplot and map view from XML camera files
 - Supports multiple XMLs with automatic mosaicking
+- Accepts positional `INPUTS` (any mix of XML files, directories, and globs — e.g. `stereo_geom *.XML`); falls back to `--directory` when no positional inputs are given. Both paths funnel into the same plotter (`inputs=` vs `directory=`)
+- **N-scene output** (issue #73): two scenes → one `<name>_stereo_geom.png` (unchanged). More than two → one color-coded overview figure (`_overview.png`) plus one figure per pair (`_<catidA>_<catidB>.png`, or `_pairN.png` if a CATID is missing), each with full pairwise stats. `dg_geom_plot()` dispatches on scene count and returns the list of saved filenames; `StereoGeometryPlotter` adds `_render_pair`/`_render_overview`. Map views keep the full (autoscaled) extent so all satellite ephemeris tracks are visible (off-nadir scenes have tracks tens to hundreds of km from the footprints), with tracks drawn on top of the semi-transparent footprints; `_add_basemap_safe` falls back to a coarse zoom so the wide-extent basemap fetch doesn't fail on contextily's negative auto-zoom
 
 **`gallery.py`** - DEM gallery tool (`gallery` command)
 - Wrapper for `GalleryPlotter`; lays out many DEMs as a grid sharing one color scale

{asp_plot-1.18.0 → asp_plot-1.19.0}/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [1.19.0] - 2026-06-30
+
+### Added
+- **`stereo_geom` makes pre-ASP stereo geometry plots straight from satellite XMLs** ([#73](https://github.com/uw-cryo/asp_plot/issues/73)). You can now assess candidate stereo geometry (skyplot + footprint/ephemeris map + convergence/B:H/BIE/asymmetry stats) *before* running ASP, directly from the delivered camera XMLs, without a tidy directory layout. Delivered across three pieces:
+  - **Robust, structure-agnostic XML discovery** ([#150](https://github.com/uw-cryo/asp_plot/issues/150)). Camera XMLs are found recursively (they routinely sit three or four directories deep), decoys like `README.XML` and ortho sidecars are ignored, and scenes are grouped by the CATID read from the file *contents* — never assumed to be in the filename. Tiled deliveries are mosaicked per CATID via `dg_mosaic`.
+  - **Flexible CLI inputs** ([#152](https://github.com/uw-cryo/asp_plot/issues/152)). `stereo_geom` takes positional `INPUTS` that may be any mix of XML files, directories, and glob patterns — `stereo_geom *.XML`, `stereo_geom a.xml b.xml`, `stereo_geom delivery_dir/` — searched recursively. The original `--directory` flag is retained as the fallback, so existing usage is unchanged. New `resolve_xml_inputs()` / `sensor_for_inputs()` / `SensorMetadata.detect_files()` plumbing and a `WorldViewMetadata(image_list=...)` constructor back this, with `inputs=` threaded through `StereopairMetadataParser` and `StereoGeometryPlotter`.
+  - **N-scene multi-view assessment.** `stereo_geom` is no longer limited to a pair. Given more than two scenes it writes one color-coded **overview** figure (all satellite positions on the skyplot, all footprints/ephemeris on the map) plus **one figure per pair** for every N-choose-2 combination, each titled with that pair's full stereo stats — the multi-view use case from the issue (e.g. the Utqiagvik scenes). Two-scene output is unchanged. Pairs whose footprints do not overlap are still plotted, with intersection-dependent stats shown as `N/A`. The parser gains `get_pair_dicts()` (all combinations), `get_scenes_centroid_projection()`, and `get_pair_map_projection()`; `get_pair_dict()` is now the exact-two-scene entry point.
+
+### Fixed
+- **Stereo-geometry map basemap no longer errors/hangs on wide extents** ([#73](https://github.com/uw-cryo/asp_plot/issues/73)). The map intentionally shows the full satellite ephemeris tracks, which (for off-nadir scenes) sit tens to hundreds of kilometers from the ground footprints, so the extent is necessarily wide. At that extent `contextily`'s auto-zoom resolves to an invalid (negative) level, which previously produced a slow, failing tile request that could appear to hang. The basemap fetch now falls back to a coarse continental zoom (`_add_basemap_safe`) when the auto-zoom fails, so the map keeps its full track-revealing extent and still gets a basemap. The satellite tracks are also drawn on top of the (semi-transparent) footprints so they are not buried.
+- **Non-overlapping footprints no longer crash intersection handling.** `get_pair_intersection()` computed the local-projection area before checking whether the two footprints actually intersect, raising on a `None` intersection. This was unreachable in the two-scene path (always overlapping) but is common among the pairs of an N-scene set; the area calculation is now skipped when there is no overlap.
+
+## [1.18.1] - 2026-06-26
+
+### Fixed
+- **`© Vantor` attribution now covers all Vantor-owned satellites, not just WorldView** ([#137](https://github.com/uw-cryo/asp_plot/issues/137)). The copyright-overlay check (`detect_vantor_satellite`) matched only `SATID` values starting with `WV`, so GeoEye-1 (`GE01`), QuickBird (`QB02`), and IKONOS scenes — all owned by the same rights-holder (DigitalGlobe → Maxar → Vantor) — were silently left un-attributed. Detection now matches a `VANTOR_SATID_PREFIXES` whitelist (`WV` incl. WorldView Legion `WVLG`, `GE`, `QB`, `IK`). This clarifies that `is_vantor` / `detect_vantor_satellite` are an **attribution** concern (named for the company), intentionally distinct from sensor/reader **identity** (the WorldView-named abstraction in `sensors.py`); the two names are documented as deliberately different so they aren't reconciled into one.
+
 ## [1.18.0] - 2026-06-25
 
 ### Added

{asp_plot-1.18.0 → asp_plot-1.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asp_plot
-Version: 1.18.0
+Version: 1.19.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-1.18.0 → asp_plot-1.19.0}/asp_plot/altimetry_plots.py

@@ -363,6 +363,18 @@ class AltimetryPlotter:
 
         x_bounds = []
         y_bounds = []
+        # CRS to reproject every panel into. This is independent of whether a
+        # basemap is drawn: a basemap is only fetched when the caller passes
+        # contextily kwargs (e.g. source=...). Previously this CRS was injected
+        # into ``ctx_kwargs``, which made the ``if ctx_kwargs`` basemap guard
+        # below always true and forced a tile download on every call (a network
+        # hang in offline/CI runs).
+        if map_crs:
+            crs = map_crs
+        elif ctx_kwargs:
+            crs = ctx_kwargs.get("crs", "EPSG:4326")
+        else:
+            crs = "EPSG:4326"
         for ax, time_stamp in zip(axes, time_stamps):
             key_to_plot = f"{key}{time_stamp}"
 
@@ -379,13 +391,6 @@ class AltimetryPlotter:
                 continue
 
             atl06sr = filtered[key_to_plot]
-            if map_crs:
-                crs = map_crs
-                ctx_kwargs["crs"] = map_crs
-            elif ctx_kwargs:
-                crs = ctx_kwargs["crs"]
-            else:
-                crs = "EPSG:4326"
             atl06sr_sorted = atl06sr.sort_values(by="h_mean").to_crs(crs)
             bounds = atl06sr_sorted.total_bounds
             x_bounds.extend([bounds[0], bounds[2]])
@@ -424,6 +429,7 @@ class AltimetryPlotter:
                 min(y_bounds) - padding * y_range, max(y_bounds) + padding * y_range
             )
             if ctx_kwargs:
+                ctx_kwargs.setdefault("crs", crs)
                 ctx.add_basemap(ax=ax, **ctx_kwargs)
 
         suptitle = f"{title}"

asp_plot-1.19.0/asp_plot/cli/stereo_geom.py

@@ -0,0 +1,104 @@
+import os
+
+import click
+
+from asp_plot.stereo_geometry import StereoGeometryPlotter
+
+
+@click.command()
+@click.argument("inputs", nargs=-1, type=click.Path())
+@click.option(
+    "--directory",
+    default=None,
+    help=(
+        "Directory containing XML files for stereo geometry analysis. "
+        "Used when no positional INPUTS are given. Default: current directory."
+    ),
+)
+@click.option(
+    "--add_basemap",
+    prompt=False,
+    default=True,
+    help="If True, add a basemap to the figures, which requires internet connection. Default: True.",
+)
+@click.option(
+    "--output_directory",
+    prompt=False,
+    default=None,
+    help="Directory to save the output plot. Default: Input directory.",
+)
+@click.option(
+    "--output_filename",
+    prompt=False,
+    default=None,
+    help=(
+        "Filename for the output plot. Default: Directory name with "
+        "_stereo_geom.png suffix. With more than two scenes this is the stem for "
+        "the per-pair and overview figures."
+    ),
+)
+def main(
+    inputs,
+    directory,
+    add_basemap,
+    output_directory,
+    output_filename,
+):
+    """
+    Generate stereo geometry plots for WorldView XML files.
+
+    This tool creates a skyplot and map visualization of the satellite positions
+    and ground footprints. INPUTS may be any mix of XML files, directories, and
+    glob patterns and need not follow a fixed directory structure, e.g.:
+
+        stereo_geom *.XML
+
+        stereo_geom scene1.xml scene2.xml
+
+        stereo_geom my_delivery_dir/
+
+    If no INPUTS are given, --directory is used (default: current directory).
+    """
+    # Positional INPUTS take precedence; otherwise fall back to --directory.
+    if inputs:
+        inputs = [os.path.expanduser(i) for i in inputs]
+        plotter = StereoGeometryPlotter(inputs=inputs, add_basemap=add_basemap)
+        source_desc = " ".join(inputs)
+        # Base directory for default output paths (resolved by the parser).
+        base_directory = plotter.directory
+    else:
+        base_directory = os.path.expanduser(directory or "./")
+        plotter = StereoGeometryPlotter(
+            directory=base_directory, add_basemap=add_basemap
+        )
+        source_desc = base_directory
+
+    print(f"\nProcessing stereo geometry for XML files in {source_desc}\n")
+
+    # Derive default output directory/filename from the base directory.
+    dir_name = os.path.split(base_directory.rstrip("/\\"))[-1]
+    if output_directory is None:
+        output_directory = base_directory
+    else:
+        output_directory = os.path.expanduser(output_directory)
+    if output_filename is None:
+        output_filename = f"{dir_name}_stereo_geom.png"
+
+    os.makedirs(output_directory, exist_ok=True)
+
+    saved = plotter.dg_geom_plot(save_dir=output_directory, fig_fn=output_filename)
+
+    if saved:
+        if len(saved) == 1:
+            print(
+                f"\nStereo geometry plot saved to {os.path.join(output_directory, saved[0])}\n"
+            )
+        else:
+            print(f"\nStereo geometry plots saved ({len(saved)}):")
+            for fn in saved:
+                print(f"  {os.path.join(output_directory, fn)}")
+            print()
+
+
+if __name__ == "__main__":
+    main()

{asp_plot-1.18.0 → asp_plot-1.19.0}/asp_plot/scenes.py

@@ -26,7 +26,8 @@ class SceneFiles:
     full_stereo_directory : str
         Full path to the stereo directory.
     is_vantor : bool
-        Whether the source imagery is from a Vantor (WorldView) satellite.
+        Whether the source imagery is from a Vantor-owned satellite (WorldView
+        family, GeoEye, QuickBird, etc.); gates the "© Vantor" copyright overlay.
     left_scene_sub_fn, right_scene_sub_fn : str or None
         Paths to the left/right sub-sampled scene files.
     """