asp-plot 1.13.0__tar.gz → 1.14.1__tar.gz

{asp_plot-1.13.0 → asp_plot-1.14.1}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.14.1] - 2026-06-05
+
+### Fixed
+- **`Raster.get_epsg_code()` returned `None` for compound / 3D-promoted CRSs** (e.g. `"EPSG:32610+EPSG:4979"`, as written by [stereopipeline-quickstart's `fetch_cop_dem.py`](https://github.com/uw-cryo/stereopipeline-quickstart/blob/main/scripts/fetch_cop_dem.py) to assert ellipsoid heights on the COP30 DEM). PROJ represents such a CRS as a UTM CRS "promoted to 3D" with no exact EPSG match, so `rasterio`'s `to_epsg()` yields `None` and downstream `f"EPSG:{epsg}"` strings crash (e.g. passing the DEM as `dem_fn` to `Altimetry`, or `Raster.get_bounds(latlon=True)`). Now falls back to the EPSG code of the horizontal (2D) component via `pyproj`'s `CRS.to_2d()`.
+
+## [1.14.0] - 2026-04-28
+
+### Added
+- **Automatic `pc_align` step in the planetary altimetry block** ([#119](https://github.com/uw-cryo/asp_plot/pull/119)). The existing `--pc_align` CLI flag now also runs against MOLA (Mars) and LOLA (Moon) — previously Earth/ICESat-2 only. Mirrors the Earth pipeline: a single alignment-report page on `insufficient_points` / `no_improvement`, plus a pre/post mapview and pre/post histogram on `success`.
+- **`Altimetry.align_and_evaluate_planetary(...)`**: planetary sibling of `align_and_evaluate`. Returns the same `AlignmentResult` dataclass; defaults `max_displacement=500` m (per ASAP-Stereo's CTX cookbook) and `minimum_points=20` (planetary tracks are sparse).
+- **`Alignment.pc_align_dem_to_planetary_csv(...)`**: invokes ASP `pc_align` with `--csv-format '1:lon 2:lat 3:radius_m'` and `--datum D_MARS`/`D_MOON` (aligned with the [ASP `next_steps` documentation on MOLA alignment](https://stereopipeline.readthedocs.io/en/latest/next_steps.html)).
+- **`Altimetry.to_csv_for_pc_align_planetary()`**: writes `lon, lat, radius_m` from `self.planetary_points` to drive `pc_align`.
+- **`plot_aligned` kwarg** on `Altimetry.mapview_plot_planetary_to_dem` and `Altimetry.histogram_planetary_to_dem`: pre/post panels share color/bin scales when an aligned DEM is available.
+- **Module-level constants** `MARS_IAU_SPHERE_RADIUS = 3_396_190.0` and `MOON_IAU_SPHERE_RADIUS = 1_737_400.0` so callers can reconstruct ASP-style "height above sphere" without magic numbers.
+
+### Changed
+- **MOLA loader switched to `PLANET_RAD`**. `_load_mola_csv()` now reads the absolute planetary radius from the ODE GDS `*_pts_csv.csv` and computes `height = PLANET_RAD - 3,396,190` (IAU 2000 Mars sphere). The `*_topo_csv.csv` (TOPOGRAPHY only) is **rejected** with an explanatory error: TOPOGRAPHY is referenced to the **oblate** MOLA areoid while ASP DEMs use the **spherical** IAU 2000 datum, so dh from TOPOGRAPHY carries a latitude-dependent offset of up to ~10 km that `pc_align` cannot remove. Verified on the MOC NA tutorial scene at lat 34°N: signed median dh dropped from +6,000 m (TOPOGRAPHY path) → +99.74 m (PLANET_RAD path) → +3.13 m (after `pc_align`). Reference: [MOLA PEDR Software Interface Specification (PDS Geosciences)](https://pds-geosciences.wustl.edu/mgs/mgs-m-mola-3-pedr-l1a-v1/mgsl_21xx/document/pedrsis.pdf).
+- **LOLA loader prefers `Pt_Radius` (km) when available**. The Point per Row LOLA RDR CSV (`results=p`) carries `Pt_Radius` in **kilometers**; the simple Topography CSV (`results=u`) carries Topography in meters. `_load_lola_csv()` auto-detects km by magnitude (< 10 000) and converts to meters, then writes both `height` (m above the IAU 1737.4 km lunar sphere) and `radius_m` to `self.planetary_points`. The Moon is essentially spherical (~1.4 km equatorial-vs-polar variation), so either CSV gives the same dh to ~1 m. Reference: [ODE GDS REST V2.0 manual](https://oderest.rsl.wustl.edu/GDS_REST_V2.0.pdf).
+- **`Alignment.apply_dem_translation()` is body-aware**. Picks a body-centered geocentric "ECEF-equivalent" CRS from a new module-level `_GEOCENTRIC_PROJ` dict — Earth uses `EPSG:4978`; Mars/Moon use PROJ strings (`+proj=geocent +R=...`) because PROJ refuses to convert across celestial bodies. Without this fix, applying a `pc_align` translation to a Mars/Moon DEM raised `RuntimeError: Source and target ellipsoid do not belong to the same celestial body`.
+- **`planetary_to_dem_dh()` also samples the aligned DEM** when `self.aligned_dem_fn` is set, populating `aligned_dem_height` and `altimetry_minus_aligned_dem` so pre/post plots share a single sample. Refactored shared interpolation into `_sample_dem_at_planetary_points()`.
+
+### Documentation
+- **MOC NA notebook consolidated** into `notebooks/Mars_MGS/mars_mgs_orbital_camera.ipynb` covering both stereo variants of the M0100115 / E0201461 pair (the `mars_mgs_orbital_camera_narrow_angle.ipynb` notebook for a different scene pair was removed). Mirrors the ASTER mapproj/non-mapproj layout. Stereo commands match this repo's WorldView convention (`parallel_stereo --stereo-algorithm asp_mgm --subpixel-mode 9 --processes 2 --threads 4`, `--alignment-method affineepipolar` for non-mapprojected, `--alignment-method none` for mapprojected via `cam2map4stereo.py`). The notebook intro includes a callout explaining the spherical-vs-oblate elevation-range surprise. Reports: `MOC-asp-plot-report.pdf` and `MOC_mapproj-asp-plot-report.pdf`.
+- **LRO NAC notebook reprocessed on the full 5000×5000 cubes** in [`LRONAC_example.tar`](https://github.com/NeoGeographyToolkit/StereoPipelineSolvedExamples/releases/download/LRONAC/LRONAC_example.tar) instead of the 900×973 sub-window the ASP "lightning fast" tutorial uses. Resulting DEM is 4720×4510 at 1.04 m GSD (~4.7 km × 4.7 km, vs the old ~1 km × 1 km), 95.88% valid pixels. LOLA query expanded to match: 1539 of 2044 LOLA points overlap the DEM (vs 12 of 19 on the old crop), enough for a meaningful `pc_align` and to bring out spacecraft jitter in the disparity panels.
+
 ## [1.13.0] - 2026-04-20
 
 ### Added

{asp_plot-1.13.0 → asp_plot-1.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asp_plot
-Version: 1.13.0
+Version: 1.14.1
 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.13.0 → asp_plot-1.14.1}/asp_plot/alignment.py

@@ -5,7 +5,23 @@ import re
 import numpy as np
 from osgeo import gdal, osr
 
-from asp_plot.utils import Raster, glob_file, run_subprocess_command
+from asp_plot.utils import (
+    Raster,
+    detect_planetary_body,
+    glob_file,
+    run_subprocess_command,
+)
+
+# Body-centered geocentric ("ECEF-equivalent") CRS for each supported
+# planet. Used by apply_dem_translation to convert pc_align's Cartesian
+# translation vector into the DEM's projected coordinate system. The
+# Earth case is keyed via EPSG; planets need a PROJ string because PROJ
+# refuses to operate across celestial bodies.
+_GEOCENTRIC_PROJ = {
+    "earth": None,  # use EPSG:4978
+    "moon": "+proj=geocent +R=1737400 +units=m +no_defs",
+    "mars": "+proj=geocent +R=3396190 +units=m +no_defs",
+}
 
 logging.basicConfig(level=logging.WARNING)
 logger = logging.getLogger(__name__)
@@ -134,6 +150,86 @@ class Alignment:
 
         run_subprocess_command(command)
 
+    def pc_align_dem_to_planetary_csv(
+        self,
+        planetary_csv,
+        body,
+        max_displacement=500,
+        max_source_points=10000000,
+        alignment_method="point-to-point",
+        output_prefix="pc_align/pc_align",
+    ):
+        """
+        Align DEM to MOLA/LOLA point cloud using pc_align.
+
+        Parameters
+        ----------
+        planetary_csv : str
+            Path to a CSV with ``lon``, ``lat``, ``radius_m`` columns
+            (planetary radius in meters from the body center). Produced by
+            :meth:`asp_plot.altimetry.Altimetry.to_csv_for_pc_align_planetary`.
+        body : str
+            ``"moon"`` or ``"mars"`` — selects the ASP ``--datum`` flag.
+        max_displacement : float, optional
+            Maximum expected displacement in meters. ASAP-Stereo's CTX
+            cookbook recommends ~500 m as a generic default for planetary
+            stereo where absolute pointing is uncertain.
+        max_source_points : int, optional
+            Maximum number of source DEM points pc_align will sample.
+        alignment_method : str, optional
+            ASP alignment method. Default ``point-to-point``.
+        output_prefix : str, optional
+            Prefix for pc_align output files, relative to ``self.directory``.
+
+        Notes
+        -----
+        Uses ``--csv-format '1:lon 2:lat 3:radius_m'`` so pc_align reads
+        the absolute planetary radius and avoids any datum/areoid
+        ambiguity. ``--datum`` is set to ``D_MARS`` (3,396,190 m) or
+        ``D_MOON`` (1,737,400 m) to match ASP DEM heights, which are
+        stored as ``radius - sphere``.
+        """
+        if not os.path.exists(planetary_csv):
+            raise ValueError(
+                f"\nPlanetary altimetry CSV not found: {planetary_csv}\n"
+                "Use Altimetry.to_csv_for_pc_align_planetary() to create it.\n"
+            )
+
+        datum = {"moon": "D_MOON", "mars": "D_MARS"}.get(body)
+        if datum is None:
+            raise ValueError(
+                f"Unsupported body for pc_align_dem_to_planetary_csv: {body}"
+            )
+
+        pc_align_folder = os.path.join(self.directory, output_prefix)
+
+        print(
+            f"Running pc_align on {self.dem_fn} and {planetary_csv}\n"
+            f"  --datum {datum}, --max-displacement {max_displacement}\n"
+            f"Writing to {pc_align_folder}*"
+        )
+
+        command = [
+            "pc_align",
+            "--max-displacement",
+            str(max_displacement),
+            "--max-num-source-points",
+            str(max_source_points),
+            "--alignment-method",
+            alignment_method,
+            "--csv-format",
+            "1:lon 2:lat 3:radius_m",
+            "--datum",
+            datum,
+            "--compute-translation-only",
+            "--output-prefix",
+            pc_align_folder,
+            self.dem_fn,
+            planetary_csv,
+        ]
+
+        run_subprocess_command(command)
+
     def pc_align_report(self, output_prefix="pc_align/pc_align"):
         """
         Extract alignment statistics from pc_align log files.
@@ -281,8 +377,18 @@ class Alignment:
         llz_c = llz_c[i]
         llz_shift = llz_shift[i]
 
+        # pc_align's Cartesian translation lives in the body-centered
+        # frame defined by --datum, so the source CRS must match the
+        # body of the DEM. PROJ refuses to convert between celestial
+        # bodies, so use a body-specific geocentric PROJ string for
+        # Mars/Moon and EPSG:4978 for Earth.
+        body = detect_planetary_body(self.dem_fn)
         ecef_srs = osr.SpatialReference()
-        ecef_srs.ImportFromEPSG(4978)
+        proj_string = _GEOCENTRIC_PROJ.get(body)
+        if proj_string is None:
+            ecef_srs.ImportFromEPSG(4978)
+        else:
+            ecef_srs.ImportFromProj4(proj_string)
 
         s_srs = ecef_srs
         src_c = ecef_c

{asp_plot-1.13.0 → asp_plot-1.14.1}/asp_plot/altimetry.py

@@ -25,6 +25,11 @@ logger = logging.getLogger(__name__)
 
 ICESAT2_MISSION_START = datetime(2018, 10, 14, tzinfo=timezone.utc)
 
+# IAU 2000 mean equatorial radii used by ASP DEMs and pc_align.
+# ASP DEM heights are stored as (planetary_radius - sphere_radius).
+MARS_IAU_SPHERE_RADIUS = 3_396_190.0  # meters
+MOON_IAU_SPHERE_RADIUS = 1_737_400.0  # meters
+
 WORLDCOVER_NAMES = {
     10: "Tree cover",
     20: "Shrubland",
@@ -1379,7 +1384,16 @@ class Altimetry:
     ]
     _LAT_CANDIDATES = ["pt_latitude", "lat_north", "latitude", "areocentric_latitude"]
     _TOPO_CANDIDATES = ["topography", "topo"]
-    _RADIUS_CANDIDATES = ["planet_rad", "radius", "planetary_radius"]
+    # PLANET_RAD column names from ODE GDS PEDR (Mars) and LOLA RDR
+    # "Point Per Row" CSV (Moon, has Pt_Radius). Order matters — names
+    # earlier in the list are preferred.
+    _RADIUS_CANDIDATES = [
+        "planet_rad",
+        "planet_rad (shot_planetary_radius)",
+        "pt_radius",
+        "planetary_radius",
+        "radius",
+    ]
 
     # Geographic CRS WKT strings for building GeoDataFrames
     _MOON_GEO_CRS = 'GEOGCRS["Moon",DATUM["D_MOON",ELLIPSOID["MOON",1737400,0]],PRIMEM["Reference_Meridian",0],CS[ellipsoidal,2],AXIS["latitude",north,ORDER[1],ANGLEUNIT["degree",0.0174532925199433]],AXIS["longitude",east,ORDER[2],ANGLEUNIT["degree",0.0174532925199433]]]'
@@ -1406,10 +1420,13 @@ class Altimetry:
                 return cols_lower[c]
         return None
 
-    def _load_planetary_csv_common(self, csv_path, instrument):
+    def _load_planetary_csv_common(self, csv_path, instrument, prefer="radius"):
         """Shared CSV loading logic for LOLA and MOLA.
 
         Reads the CSV, validates columns, converts longitude to -180/180.
+        Picks PLANET_RAD over TOPOGRAPHY by default (``prefer="radius"``)
+        because TOPOGRAPHY is referenced to the oblate areoid and produces
+        a latitude-dependent offset against ASP's spherical-IAU DEMs.
 
         Parameters
         ----------
@@ -1417,12 +1434,14 @@ class Altimetry:
             Path to the CSV file.
         instrument : str
             ``"LOLA"`` or ``"MOLA"`` (for error messages).
+        prefer : {"radius", "topo"}
+            Which column family to try first.
 
         Returns
         -------
-        tuple of (pandas.DataFrame, str or None, bool)
+        tuple of (pandas.DataFrame, bool)
             (df with ``lon``, ``lat``, ``height_raw`` columns,
-             height column name found, whether it was a radius column)
+             ``is_radius`` flag — True if the chosen column is a planetary radius)
         """
         df = pd.read_csv(csv_path)
 
@@ -1436,21 +1455,24 @@ class Altimetry:
 
         lon_col = self._find_csv_column(cols_lower, self._LON_CANDIDATES)
         lat_col = self._find_csv_column(cols_lower, self._LAT_CANDIDATES)
-        topo_col = self._find_csv_column(cols_lower, self._TOPO_CANDIDATES)
 
-        is_radius = False
-        height_col = topo_col
-        if height_col is None:
-            height_col = self._find_csv_column(cols_lower, self._RADIUS_CANDIDATES)
-            is_radius = height_col is not None
+        if prefer == "radius":
+            primary = self._find_csv_column(cols_lower, self._RADIUS_CANDIDATES)
+            fallback = self._find_csv_column(cols_lower, self._TOPO_CANDIDATES)
+            is_radius = primary is not None
+        else:
+            primary = self._find_csv_column(cols_lower, self._TOPO_CANDIDATES)
+            fallback = self._find_csv_column(cols_lower, self._RADIUS_CANDIDATES)
+            is_radius = primary is None and fallback is not None
+
+        height_col = primary if primary is not None else fallback
 
         if lon_col is None or lat_col is None or height_col is None:
             raise ValueError(
                 f"{instrument} CSV does not have expected columns.\n"
                 f"  Found: {list(df.columns)}\n"
-                f"  Expected longitude, latitude, and topography columns.\n\n"
-                f"Make sure you are using the '*_topo_csv.csv' file from the "
-                f"ODE GDS download, not the '*_pts_csv.csv' or label file."
+                f"  Expected longitude, latitude, and either a planetary "
+                f"radius (PLANET_RAD / Pt_Radius) or topography column."
             )
 
         df = df.rename(
@@ -1463,15 +1485,44 @@ class Altimetry:
         return df, is_radius
 
     def _load_lola_csv(self, csv_path):
-        """Parse a LOLA simple-topography CSV into a GeoDataFrame.
+        """Parse a LOLA topo CSV into a GeoDataFrame.
+
+        Stores height above the IAU 1737.4 km lunar sphere on
+        ``self.planetary_points["height"]`` and the planetary radius on
+        ``self.planetary_points["radius_m"]`` (used by pc_align).
+
+        The Moon is nearly spherical (1.4 km equatorial-vs-polar variation),
+        so LOLA TOPOGRAPHY ≈ Pt_Radius − 1737.4 km. Either column gives the
+        same dh against an ASP lunar DEM to <1 m.
 
         Parameters
         ----------
         csv_path : str
-            Path to the CSV file.
+            Path to a LOLA RDR CSV from the ODE GDS API.
         """
-        df, _ = self._load_planetary_csv_common(csv_path, "LOLA")
-        df["height"] = df["height_raw"]
+        df, is_radius = self._load_planetary_csv_common(
+            csv_path, "LOLA", prefer="radius"
+        )
+
+        if is_radius:
+            # LOLA RDR Pt_Radius is in KILOMETERS (per the ODE GDS Point
+            # per Row CSV header), unlike MOLA PEDR PLANET_RAD which is
+            # in meters. Detect units by magnitude (~1737 vs ~1737000)
+            # and normalize to meters.
+            if df["height_raw"].median() < 10000:
+                df["height_raw"] = df["height_raw"] * 1000.0
+                unit_note = " (km → m)"
+            else:
+                unit_note = ""
+            df["height"] = df["height_raw"] - MOON_IAU_SPHERE_RADIUS
+            df["radius_m"] = df["height_raw"]
+            source = f"Pt_Radius{unit_note}"
+        else:
+            # Topography path: the Moon is essentially spherical so LOLA
+            # topography ≈ height above the IAU 1737.4 km sphere.
+            df["height"] = df["height_raw"]
+            df["radius_m"] = df["height_raw"] + MOON_IAU_SPHERE_RADIUS
+            source = "Topography"
 
         gdf = gpd.GeoDataFrame(
             df,
@@ -1479,62 +1530,89 @@ class Altimetry:
             crs=self._MOON_GEO_CRS,
         )
         self.planetary_points = gdf
-        print(f"Loaded {len(gdf)} LOLA points")
+        print(f"Loaded {len(gdf)} LOLA points (using {source} column)")
 
     def _load_mola_csv(self, csv_path):
         """Parse a MOLA PEDR CSV into a GeoDataFrame.
 
-        TOPOGRAPHY values are heights above the MOLA areoid (Mars
-        geoid).  ASP DEMs store heights above the IAU sphere
-        (3,396,190 m).  These are different vertical datums, so a
-        systematic offset equal to the local areoid height will be
-        present in the dh values.  If only PLANET_RAD (radius) is
-        available, a -190 m correction converts from the MOLA sphere
-        (3,396,000 m) to the IAU sphere.
+        Uses the PLANET_RAD column and converts to height above the IAU
+        Mars sphere (3,396,190 m): ``height = PLANET_RAD - 3,396,190``.
+        This is the same reference as ASP DEMs, so dh = MOLA − DEM is
+        directly meaningful at all latitudes.
+
+        TOPOGRAPHY (in ``*_topo_csv.csv``) is referenced to the MOLA
+        oblate areoid and produces a latitude-dependent offset of up to
+        ~10 km against an ASP DEM, so it is rejected here. Pass the
+        ``*_pts_csv.csv`` from the ODE GDS download instead.
 
         Parameters
         ----------
         csv_path : str
-            Path to the CSV file.
+            Path to a MOLA PEDR CSV from the ODE GDS API. Must include
+            a ``PLANET_RAD`` column (use the ``*_pts_csv.csv`` file).
         """
-        df, is_radius = self._load_planetary_csv_common(csv_path, "MOLA")
+        df, is_radius = self._load_planetary_csv_common(
+            csv_path, "MOLA", prefer="radius"
+        )
 
-        MOLA_SPHERE_OFFSET = 190.0  # meters
-        if is_radius:
-            df["height"] = df["height_raw"] - MOLA_SPHERE_OFFSET
-            print(
-                f"Applied -{MOLA_SPHERE_OFFSET} m correction "
-                "(MOLA sphere → IAU sphere)"
-            )
-        else:
-            # MOLA TOPOGRAPHY is height above the MOLA areoid (Mars geoid).
-            # ASP DEMs store height above the IAU sphere (3,396,190 m).
-            # These are different vertical datums, so a systematic offset
-            # (equal to the local areoid height) will be present in the
-            # dh values.  This is a known limitation — correcting it
-            # requires the MOLA areoid grid or ASP's `dem_geoid --geoid MOLA`.
-            df["height"] = df["height_raw"]
-            print(
-                "Note: MOLA topography is referenced to the MOLA areoid. "
-                "ASP DEMs use the IAU sphere. A systematic vertical offset "
-                "may be present in dh values."
+        if not is_radius:
+            raise ValueError(
+                f"MOLA CSV is missing the PLANET_RAD column: {csv_path}\n"
+                "The ODE GDS '*_topo_csv.csv' only has TOPOGRAPHY, which is "
+                "height above the oblate MOLA areoid. ASP DEMs use the "
+                "spherical IAU 2000 datum (3,396,190 m), so dh from "
+                "TOPOGRAPHY carries a latitude-dependent offset of up to "
+                "~10 km that pc_align cannot remove.\n\n"
+                "Pass the '*_pts_csv.csv' file from the same ODE GDS "
+                "download instead — it contains PLANET_RAD."
             )
 
+        df["height"] = df["height_raw"] - MARS_IAU_SPHERE_RADIUS
+        df["radius_m"] = df["height_raw"]
+
         gdf = gpd.GeoDataFrame(
             df,
             geometry=gpd.points_from_xy(df["lon"], df["lat"]),
             crs=self._MARS_GEO_CRS,
         )
         self.planetary_points = gdf
-        print(f"Loaded {len(gdf)} MOLA points")
+        print(
+            f"Loaded {len(gdf)} MOLA points "
+            f"(PLANET_RAD - {MARS_IAU_SPHERE_RADIUS:.0f} m → height above IAU sphere)"
+        )
+
+    def _sample_dem_at_planetary_points(self, dem_fn, height_col, dh_col):
+        """Interpolate DEM heights at the loaded altimetry points.
+
+        Adds ``height_col`` and ``dh_col`` (= altimetry height − DEM height)
+        to ``self.planetary_points`` in-place. Used by
+        :meth:`planetary_to_dem_dh` for both the raw and aligned DEMs.
+        """
+        if self.planetary_points is None or self.planetary_points.empty:
+            return
+
+        dem = rioxarray.open_rasterio(dem_fn, masked=True).squeeze()
+        dem_crs = dem.rio.crs
+
+        pts = self.planetary_points.to_crs(dem_crs)
+        x = xr.DataArray(pts.geometry.x.values, dims="z")
+        y = xr.DataArray(pts.geometry.y.values, dims="z")
+        sample = dem.interp(x=x, y=y).values
+
+        self.planetary_points[height_col] = sample
+        self.planetary_points[dh_col] = self.planetary_points["height"] - sample
 
     def planetary_to_dem_dh(self, n_sigma=3):
         """Compute height differences between planetary altimetry and DEM.
 
         Reprojects ``self.planetary_points`` to the DEM CRS, interpolates
         DEM heights at altimetry locations, and computes the difference
-        ``altimetry_minus_dem = height - dem_height``. Outliers beyond
-        ``n_sigma`` × std from the mean are removed by default.
+        ``altimetry_minus_dem = height - dem_height``. When
+        ``self.aligned_dem_fn`` is set, also populates
+        ``aligned_dem_height`` and ``altimetry_minus_aligned_dem`` so
+        pre/post-alignment plots can share a single sample. Outliers
+        beyond ``n_sigma`` × std from the mean (computed on the
+        unaligned dh) are removed by default.
 
         Parameters
         ----------
@@ -1548,23 +1626,15 @@ class Altimetry:
             logger.warning("No planetary altimetry points loaded.")
             return
 
-        dem = rioxarray.open_rasterio(self.dem_fn, masked=True).squeeze()
-        dem_crs = dem.rio.crs
-
-        # Reproject points to the DEM CRS (use CRS object, not EPSG)
-        pts = self.planetary_points.to_crs(dem_crs)
-
-        x = xr.DataArray(pts.geometry.x.values, dims="z")
-        y = xr.DataArray(pts.geometry.y.values, dims="z")
-        sample = dem.interp(x=x, y=y)
-
-        pts["dem_height"] = sample.values
-        pts["altimetry_minus_dem"] = pts["height"] - pts["dem_height"]
-
-        # Update geometry back to geographic CRS for storage
-        self.planetary_points = pts.to_crs(self.planetary_points.crs)
-        self.planetary_points["dem_height"] = pts["dem_height"].values
-        self.planetary_points["altimetry_minus_dem"] = pts["altimetry_minus_dem"].values
+        self._sample_dem_at_planetary_points(
+            self.dem_fn, "dem_height", "altimetry_minus_dem"
+        )
+        if self.aligned_dem_fn:
+            self._sample_dem_at_planetary_points(
+                self.aligned_dem_fn,
+                "aligned_dem_height",
+                "altimetry_minus_aligned_dem",
+            )
 
         valid = self.planetary_points["altimetry_minus_dem"].dropna()
         print(f"Computed dh for {len(valid)} of {len(self.planetary_points)} points")
@@ -1587,28 +1657,272 @@ class Altimetry:
                         f"(removed {n_before - n_after})"
                     )
 
+    def to_csv_for_pc_align_planetary(self, filename_prefix="planetary_for_pc_align"):
+        """Export ``self.planetary_points`` to a CSV for pc_align.
+
+        Writes columns ``lon, lat, radius_m`` (planetary radius from the
+        body center, in meters). Used as the ``planetary_csv`` argument
+        to :meth:`asp_plot.alignment.Alignment.pc_align_dem_to_planetary_csv`.
+
+        Parameters
+        ----------
+        filename_prefix : str, optional
+            Prefix for the output CSV filename. Saved in
+            ``self.directory``.
+
+        Returns
+        -------
+        str
+            Absolute path to the created CSV file.
+        """
+        if self.planetary_points is None or self.planetary_points.empty:
+            raise ValueError("No planetary altimetry points loaded.")
+        if "radius_m" not in self.planetary_points.columns:
+            raise ValueError(
+                "planetary_points has no radius_m column. Call "
+                "load_planetary_csv() first to populate it."
+            )
+
+        # Drop dh-NaN rows so pc_align doesn't reject the file. We also
+        # restrict to points that fall on the DEM (have a finite
+        # dem_height) when available — pc_align can use them as the
+        # reference cloud only if they overlap the source.
+        df = self.planetary_points.copy()
+        df["lon"] = df.geometry.x
+        df["lat"] = df.geometry.y
+        df = df[["lon", "lat", "radius_m"]].dropna()
+        if df.empty:
+            raise ValueError("No valid planetary altimetry points after dropping NaNs.")
+
+        csv_fn = os.path.join(self.directory, f"{filename_prefix}.csv")
+        df.to_csv(csv_fn, header=True, index=False)
+        return csv_fn
+
+    def align_and_evaluate_planetary(
+        self,
+        max_displacement=500,
+        improvement_threshold_pct=5.0,
+        min_translation_threshold=0.1,
+        minimum_points=20,
+    ):
+        """Run pc_align against MOLA/LOLA and evaluate whether to keep it.
+
+        Mirrors :meth:`align_and_evaluate` (the ICESat-2 path) but for
+        planetary altimetry. Requires :meth:`load_planetary_csv` to have
+        been called so ``self.planetary_points`` is populated.
+
+        Decision logic:
+
+        1. If fewer than ``minimum_points`` valid planetary points are
+           available, return ``status="insufficient_points"``.
+        2. Otherwise compute
+           ``improvement_pct = (p50_beg - p50_end) / p50_beg * 100``. If
+           ``p50_end >= p50_beg`` or
+           ``improvement_pct <= improvement_threshold_pct`` or the
+           translation magnitude is below ``min_translation_threshold ×
+           DEM GSD``, delete the aligned DEM and return
+           ``status="no_improvement"``.
+        3. Otherwise re-run :meth:`planetary_to_dem_dh` to populate
+           ``altimetry_minus_aligned_dem`` and return ``status="success"``.
+
+        Parameters
+        ----------
+        max_displacement : float, optional
+            ``--max-displacement`` for pc_align, in meters. Default 500
+            (ASAP-Stereo's CTX cookbook recommendation).
+        improvement_threshold_pct : float, optional
+            Minimum p50 reduction (%) required to keep the aligned DEM.
+        min_translation_threshold : float, optional
+            Minimum translation magnitude as a fraction of the DEM GSD.
+        minimum_points : int, optional
+            Minimum number of valid altimetry points to attempt
+            alignment. Planetary tracks are sparser than ICESat-2, so
+            this defaults to a much smaller number than the Earth path.
+
+        Returns
+        -------
+        AlignmentResult
+        """
+        from asp_plot.utils import detect_planetary_body
+
+        body = detect_planetary_body(self.dem_fn)
+        instrument = {"moon": "LOLA", "mars": "MOLA"}.get(body, "Altimetry")
+
+        parameters_used = {
+            "max_displacement": max_displacement,
+            "minimum_points": minimum_points,
+            "min_translation_threshold": min_translation_threshold,
+            "improvement_threshold_pct": improvement_threshold_pct,
+        }
+
+        if self.planetary_points is None or self.planetary_points.empty:
+            return AlignmentResult(
+                status="insufficient_points",
+                alignment_report_df=pd.DataFrame(),
+                aligned_dem_fn=None,
+                improvement_pct=None,
+                message=(
+                    f"Alignment skipped: no {instrument} points loaded. "
+                    "Call load_planetary_csv() first."
+                ),
+                parameters_used=parameters_used,
+            )
+
+        # planetary_to_dem_dh both samples and 3σ-filters; require enough
+        # points whose dh is finite (i.e. fall inside the DEM extent).
+        if "altimetry_minus_dem" not in self.planetary_points.columns:
+            self.planetary_to_dem_dh()
+        n_valid = int(self.planetary_points["altimetry_minus_dem"].notna().sum())
+        if n_valid < minimum_points:
+            self._remove_aligned_dem_if_present()
+            return AlignmentResult(
+                status="insufficient_points",
+                alignment_report_df=pd.DataFrame(),
+                aligned_dem_fn=None,
+                improvement_pct=None,
+                message=(
+                    f"Alignment skipped: only {n_valid} {instrument} points "
+                    f"overlap the DEM (need >= {minimum_points})."
+                ),
+                parameters_used=parameters_used,
+            )
+
+        csv_fn = self.to_csv_for_pc_align_planetary(
+            filename_prefix=f"{instrument.lower()}_for_pc_align"
+        )
+
+        alignment = Alignment(self.directory, self.dem_fn)
+        output_prefix = f"pc_align/pc_align_{instrument.lower()}"
+        alignment.pc_align_dem_to_planetary_csv(
+            planetary_csv=csv_fn,
+            body=body,
+            max_displacement=max_displacement,
+            output_prefix=output_prefix,
+        )
+
+        report = alignment.pc_align_report(output_prefix=output_prefix)
+        if not report:
+            self._remove_aligned_dem_if_present()
+            return AlignmentResult(
+                status="insufficient_points",
+                alignment_report_df=pd.DataFrame(),
+                aligned_dem_fn=None,
+                improvement_pct=None,
+                message=(
+                    "pc_align ran but produced no parseable log. Check "
+                    f"{output_prefix}-log-pc_align*.txt."
+                ),
+                parameters_used=parameters_used,
+            )
+
+        df = pd.DataFrame([{"key": instrument.lower(), **report}])
+
+        gsd = Raster(self.dem_fn).get_gsd()
+        translation_too_small = (
+            df["translation_magnitude"].iloc[0] < min_translation_threshold * gsd
+        )
+
+        p50_beg = float(report.get("p50_beg", float("nan")))
+        p50_end = float(report.get("p50_end", float("nan")))
+        if not np.isfinite(p50_beg) or not np.isfinite(p50_end) or p50_beg == 0:
+            improvement_pct = None
+        else:
+            improvement_pct = (p50_beg - p50_end) / p50_beg * 100.0
+
+        if (
+            improvement_pct is None
+            or p50_end >= p50_beg
+            or improvement_pct <= improvement_threshold_pct
+            or translation_too_small
+        ):
+            self._remove_aligned_dem_if_present()
+            improvement_repr = (
+                f"{improvement_pct:.1f}%" if improvement_pct is not None else "n/a"
+            )
+            if translation_too_small:
+                reason = (
+                    f"Translation magnitude is below {min_translation_threshold*100:.0f}% "
+                    f"of the DEM GSD ({gsd:.2f} m), so no aligned DEM was "
+                    f"written despite a {improvement_repr} p50 reduction."
+                )
+            else:
+                reason = (
+                    f"p50 {p50_beg:.2f} m -> {p50_end:.2f} m, "
+                    f"{improvement_repr} <= {improvement_threshold_pct:.1f}% "
+                    "threshold."
+                )
+            return AlignmentResult(
+                status="no_improvement",
+                alignment_report_df=df,
+                aligned_dem_fn=None,
+                improvement_pct=improvement_pct,
+                message=f"No significant improvement: {reason}",
+                parameters_used=parameters_used,
+            )
+
+        # Apply the translation and persist the aligned DEM
+        aligned = alignment.apply_dem_translation(output_prefix=output_prefix)
+        if aligned is None:
+            self._remove_aligned_dem_if_present()
+            return AlignmentResult(
+                status="no_improvement",
+                alignment_report_df=df,
+                aligned_dem_fn=None,
+                improvement_pct=improvement_pct,
+                message=(
+                    "pc_align reported an improvement but the translation "
+                    "could not be applied. Aligned DEM not written."
+                ),
+                parameters_used=parameters_used,
+            )
+
+        self.aligned_dem_fn = aligned
+        # Re-run planetary_to_dem_dh with n_sigma=None so we don't filter
+        # the already-clean sample again.
+        self.planetary_to_dem_dh(n_sigma=None)
+
+        return AlignmentResult(
+            status="success",
+            alignment_report_df=df,
+            aligned_dem_fn=self.aligned_dem_fn,
+            improvement_pct=improvement_pct,
+            message=(
+                f"p50 improved from {p50_beg:.2f} m -> {p50_end:.2f} m "
+                f"({improvement_pct:.1f}% reduction). Aligned DEM written to "
+                f"{self.aligned_dem_fn}."
+            ),
+            parameters_used=parameters_used,
+        )
+
     def mapview_plot_planetary_to_dem(
         self,
         clim=None,
         save_dir=None,
         fig_fn=None,
         title=None,
+        plot_aligned=False,
     ):
         """Map view of planetary altimetry vs DEM height differences.
 
         Plots the DEM hillshade as background with altimetry dh points
-        overlaid using a divergent colourmap.
+        overlaid using a divergent colourmap. When ``plot_aligned=True``
+        and ``self.aligned_dem_fn`` is set, renders pre/post panels side
+        by side.
 
         Parameters
         ----------
         clim : tuple or None, optional
-            Colour limits ``(min, max)`` for dh. Default auto.
+            Colour limits ``(min, max)`` for dh. Default auto (symmetric
+            ±|max| around zero).
         save_dir : str or None, optional
             Directory to save figure.
         fig_fn : str or None, optional
             Filename for saved figure.
         title : str or None, optional
             Custom plot title. Auto-detected if None.
+        plot_aligned : bool, optional
+            Add a second panel showing dh against the aligned DEM.
+            Requires that pc_align has been run successfully.
         """
         from asp_plot.utils import Raster, detect_planetary_body
 
@@ -1619,68 +1933,86 @@ class Altimetry:
         if "altimetry_minus_dem" not in self.planetary_points.columns:
             self.planetary_to_dem_dh()
 
-        gdf = self.planetary_points.dropna(subset=["altimetry_minus_dem"])
-        if gdf.empty:
-            logger.warning("No valid dh values for map view.")
-            return
-
-        dh = gdf["altimetry_minus_dem"]
-        n = len(dh)
-        med = np.nanmedian(dh.values)
-        nmad = _nmad(dh.values)
-
         body = detect_planetary_body(self.dem_fn)
         instrument = {"moon": "LOLA", "mars": "MOLA"}.get(body, "Altimetry")
         if title is None:
             title = f"{instrument} vs DEM"
 
-        # Generate hillshade
-        dem_raster = Raster(self.dem_fn, downsample=4)
+        show_aligned = (
+            plot_aligned
+            and self.aligned_dem_fn
+            and "altimetry_minus_aligned_dem" in self.planetary_points.columns
+        )
+
+        # Generate hillshade — use the aligned DEM as the backdrop when
+        # available so the post-alignment panel matches the dh sample.
+        backdrop_dem = self.aligned_dem_fn if show_aligned else self.dem_fn
+        dem_raster = Raster(backdrop_dem, downsample=4)
         hs = dem_raster.hillshade()
         extent = rioplot.plotting_extent(dem_raster.ds, transform=dem_raster.transform)
-
-        # Reproject points to DEM CRS for plotting
         dem_crs = dem_raster.ds.crs
-        gdf_proj = gdf.to_crs(dem_crs)
 
-        fig, ax = plt.subplots(1, 1, figsize=(8, 6), dpi=220)
-        ax.imshow(hs, cmap="gray", extent=extent, alpha=0.7, interpolation="none")
+        # Build the symmetric ±|max| color limits across all visible
+        # panels so they are directly comparable.
+        gdf_unaligned = self.planetary_points.dropna(subset=["altimetry_minus_dem"])
+        if gdf_unaligned.empty:
+            logger.warning("No valid dh values for map view.")
+            return
+        dh_arrays = [gdf_unaligned["altimetry_minus_dem"].values]
+        if show_aligned:
+            dh_arrays.append(
+                self.planetary_points["altimetry_minus_aligned_dem"].dropna().values
+            )
 
-        # Symmetric ±3σ centered on 0 (data is already 3σ-filtered in
-        # planetary_to_dem_dh, so min/max ≈ ±3σ from the mean)
         if clim is None:
-            abs_max = max(abs(dh.min()), abs(dh.max()))
+            abs_max = max(np.nanmax(np.abs(a)) for a in dh_arrays if a.size)
             clim = (-abs_max, abs_max)
-            cbar_label = f"{instrument} - DEM (m)\n[±3σ]"
-        else:
-            cbar_label = f"{instrument} - DEM (m)"
-
-        gdf_proj.plot(
-            ax=ax,
-            column="altimetry_minus_dem",
-            cmap="RdBu",
-            vmin=clim[0],
-            vmax=clim[1],
-            markersize=2,
-            legend=True,
-            legend_kwds={"label": cbar_label},
-        )
 
-        stats_text = f"n={n}\nMedian={med:+.2f} m\nNMAD={nmad:.2f} m"
-        ax.text(
-            0.02,
-            0.98,
-            stats_text,
-            transform=ax.transAxes,
-            verticalalignment="top",
-            fontsize=8,
-            fontfamily="monospace",
-            bbox=dict(boxstyle="round,pad=0.4", facecolor="white", alpha=0.9),
+        ncols = 2 if show_aligned else 1
+        fig, axes = plt.subplots(
+            1, ncols, figsize=(8 * ncols, 6), dpi=220, squeeze=False
         )
+        axes = axes[0]
+
+        panels = [("altimetry_minus_dem", "ASP DEM")]
+        if show_aligned:
+            panels.append(("altimetry_minus_aligned_dem", "Aligned DEM"))
+
+        for ax, (column, label) in zip(axes, panels):
+            gdf = self.planetary_points.dropna(subset=[column])
+            dh = gdf[column]
+            n = len(dh)
+            med = np.nanmedian(dh.values)
+            nmad = _nmad(dh.values)
+
+            ax.imshow(hs, cmap="gray", extent=extent, alpha=0.7, interpolation="none")
+            cbar_label = f"{instrument} - {label} (m)\n[±|max|]"
+            gdf.to_crs(dem_crs).plot(
+                ax=ax,
+                column=column,
+                cmap="RdBu",
+                vmin=clim[0],
+                vmax=clim[1],
+                markersize=2,
+                legend=True,
+                legend_kwds={"label": cbar_label},
+            )
+            stats_text = f"n={n}\nMedian={med:+.2f} m\nNMAD={nmad:.2f} m"
+            ax.text(
+                0.02,
+                0.98,
+                stats_text,
+                transform=ax.transAxes,
+                verticalalignment="top",
+                fontsize=8,
+                fontfamily="monospace",
+                bbox=dict(boxstyle="round,pad=0.4", facecolor="white", alpha=0.9),
+            )
+            ax.set_title(label, size=9)
+            ax.set_xticks([])
+            ax.set_yticks([])
 
-        ax.set_xticks([])
-        ax.set_yticks([])
-        fig.suptitle(f"{title}\n(n={n})", size=10)
+        fig.suptitle(title, size=10)
         fig.tight_layout()
         if save_dir and fig_fn:
             save_figure(fig, save_dir, fig_fn)
@@ -1690,6 +2022,7 @@ class Altimetry:
         save_dir=None,
         fig_fn=None,
         title=None,
+        plot_aligned=False,
     ):
         """Histogram of planetary altimetry vs DEM height differences.
 
@@ -1701,6 +2034,9 @@ class Altimetry:
             Filename for saved figure.
         title : str or None, optional
             Custom plot title. Auto-detected if None.
+        plot_aligned : bool, optional
+            Overlay the post-alignment dh distribution on the same axes.
+            Requires that pc_align has been run successfully.
         """
         from asp_plot.utils import detect_planetary_body
 
@@ -1716,25 +2052,64 @@ class Altimetry:
             logger.warning("No valid dh values for histogram.")
             return
 
-        n = len(dh)
-        med = np.nanmedian(dh.values)
-        nmad = _nmad(dh.values)
-
         body = detect_planetary_body(self.dem_fn)
         instrument = {"moon": "LOLA", "mars": "MOLA"}.get(body, "Altimetry")
         if title is None:
             title = f"{instrument} vs ASP DEM"
 
-        fig, ax = plt.subplots(1, 1, figsize=(8, 5), dpi=220)
+        show_aligned = (
+            plot_aligned
+            and self.aligned_dem_fn
+            and "altimetry_minus_aligned_dem" in self.planetary_points.columns
+        )
+        if show_aligned:
+            dh_aligned = self.planetary_points["altimetry_minus_aligned_dem"].dropna()
+
+        # Shared bin edges and xlim across both distributions
+        if show_aligned:
+            abs_max = max(
+                abs(dh.min()),
+                abs(dh.max()),
+                abs(dh_aligned.min()),
+                abs(dh_aligned.max()),
+            )
+        else:
+            abs_max = max(abs(dh.min()), abs(dh.max()))
+        bins = np.linspace(-abs_max, abs_max, 129)
 
-        ax.hist(dh.values, bins=128, alpha=0.7, color="steelblue")
+        fig, ax = plt.subplots(1, 1, figsize=(8, 5), dpi=220)
+        ax.hist(
+            dh.values,
+            bins=bins,
+            alpha=0.6,
+            color="steelblue",
+            label=f"DEM (n={len(dh)})",
+        )
+        if show_aligned:
+            ax.hist(
+                dh_aligned.values,
+                bins=bins,
+                alpha=0.6,
+                color="orange",
+                label=f"Aligned DEM (n={len(dh_aligned)})",
+            )
 
-        # Symmetric ±3σ centered on 0 (data is already 3σ-filtered in
-        # planetary_to_dem_dh; stats above are on the filtered data)
-        abs_max = max(abs(dh.min()), abs(dh.max()))
         ax.set_xlim(-abs_max, abs_max)
 
-        stats_text = f"n={n}\nMedian={med:+.2f} m\nNMAD={nmad:.2f} m"
+        if show_aligned:
+            med0 = np.nanmedian(dh.values)
+            nmad0 = _nmad(dh.values)
+            med1 = np.nanmedian(dh_aligned.values)
+            nmad1 = _nmad(dh_aligned.values)
+            stats_text = (
+                f"DEM:         Med={med0:+.2f}  NMAD={nmad0:.2f} m\n"
+                f"Aligned DEM: Med={med1:+.2f}  NMAD={nmad1:.2f} m"
+            )
+        else:
+            n = len(dh)
+            med = np.nanmedian(dh.values)
+            nmad = _nmad(dh.values)
+            stats_text = f"n={n}\nMedian={med:+.2f} m\nNMAD={nmad:.2f} m"
         ax.text(
             0.02,
             0.98,
@@ -1746,9 +2121,10 @@ class Altimetry:
             bbox=dict(boxstyle="round,pad=0.4", facecolor="white", alpha=0.9),
         )
 
-        ax.set_xlabel(f"{instrument} - DEM (m) [±3σ]")
+        ax.set_xlabel(f"{instrument} - DEM (m) [±|max|]")
         ax.set_ylabel("Count")
-        fig.suptitle(f"{title}\n(n={n})", size=10)
+        ax.legend(loc="upper right", fontsize=8)
+        fig.suptitle(title, size=10)
         fig.tight_layout()
         if save_dir and fig_fn:
             save_figure(fig, save_dir, fig_fn)

{asp_plot-1.13.0 → asp_plot-1.14.1}/asp_plot/cli/asp_plot.py

@@ -93,7 +93,7 @@ from asp_plot.utils import Raster, detect_planetary_body, get_acquisition_dates
     "--pc_align",
     prompt=False,
     default=True,
-    help="If True and --plot_altimetry is True, run pc_align against ICESat-2 (Earth only) and append the alignment-report pages. Disabled automatically when --plot_altimetry / --plot_icesat is False. Default: True.",
+    help="If True and --plot_altimetry is True, run pc_align against the reference altimetry (ICESat-2 for Earth, MOLA for Mars, LOLA for Moon) and append the alignment-report pages. Disabled automatically when --plot_altimetry / --plot_icesat is False. Default: True.",
 )
 @click.option(
     "--plot_geometry",
@@ -742,7 +742,7 @@ def main(
                     f"  1. Run: request_planetary_altimetry --dem {asp_dem} --email <your_email>\n"
                     f"  2. Wait for the email with a download link\n"
                     f"  3. Download and unzip the result\n"
-                    f"  4. Re-run asp_plot with: --altimetry_csv <path_to_topo_csv.csv>\n"
+                    f"  4. Re-run asp_plot with: --altimetry_csv <path_to_pts_csv.csv>\n"
                     f"\nSkipping {instrument} altimetry plots.\n"
                     f"{'='*60}\n"
                 )
@@ -777,6 +777,120 @@ def main(
                     )
                 )
 
+                # ---- pc_align + planetary alignment report (Moon/Mars) ----
+                if pc_align:
+                    align_result = alt.align_and_evaluate_planetary()
+                    stats_row = {}
+                    if (
+                        align_result.alignment_report_df is not None
+                        and not align_result.alignment_report_df.empty
+                    ):
+                        row = align_result.alignment_report_df.iloc[0].to_dict()
+                        row.pop("key", None)
+                        stats_row = row
+
+                    align_title = f"DEM Alignment with {instrument}"
+                    alignment_description = (
+                        f"ASP's pc_align estimates a rigid 3D translation that "
+                        f"minimizes the height residuals between the ASP DEM "
+                        f"and the {instrument} planetary radii. The CSV is "
+                        f"passed as the reference cloud with --csv-format "
+                        f"'1:lon 2:lat 3:radius_m', and --datum is set to "
+                        f"D_MARS or D_MOON to match the ASP DEM. The "
+                        f"resulting translation is applied to the DEM "
+                        f"directly (geotransform + pixel-value shift, no "
+                        f"resampling) to produce the aligned DEM.\n\n"
+                        f"Alignment Parameters (above):\n"
+                        f"  - max_displacement: pc_align upper bound on the "
+                        f"translation magnitude (m).\n"
+                        f"  - minimum_points: minimum {instrument} points "
+                        f"that overlap the DEM; below this the alignment is "
+                        f"skipped.\n"
+                        f"  - min_translation_threshold: minimum translation "
+                        f"magnitude (as a fraction of the DEM GSD) required "
+                        f"to write out an aligned DEM.\n"
+                        f"  - improvement_threshold_pct: minimum percentage "
+                        f"reduction in p50 required to keep the aligned DEM "
+                        f"on disk; below this, the aligned DEM is removed.\n\n"
+                        f"Alignment Statistics (above, in meters):\n"
+                        f"  - p16_beg / p50_beg / p84_beg: 16th / 50th / 84th "
+                        f"percentile of the DEM-vs-{instrument} absolute "
+                        f"height residuals before alignment.\n"
+                        f"  - p16_end / p50_end / p84_end: same percentiles "
+                        f"after alignment.\n"
+                        f"  - N_shift / E_shift / D_shift: north / east / down "
+                        f"components of the applied translation vector.\n"
+                        f"  - |T|: magnitude of the translation vector."
+                    )
+
+                    if align_result.status == "insufficient_points":
+                        sections.append(
+                            AlignmentReportPage(
+                                title=align_title,
+                                parameters=align_result.parameters_used,
+                                description=alignment_description,
+                                status_message=align_result.message,
+                            )
+                        )
+                    elif align_result.status == "no_improvement":
+                        sections.append(
+                            AlignmentReportPage(
+                                title=align_title,
+                                parameters=align_result.parameters_used,
+                                stats_row=stats_row,
+                                description=alignment_description,
+                                status_message=align_result.message,
+                            )
+                        )
+                    elif align_result.status == "success":
+                        sections.append(
+                            AlignmentReportPage(
+                                title=align_title,
+                                parameters=align_result.parameters_used,
+                                stats_row=stats_row,
+                                description=alignment_description,
+                                status_message=align_result.message,
+                            )
+                        )
+
+                        fig_fn = f"{next(figure_counter):02}.png"
+                        alt.mapview_plot_planetary_to_dem(
+                            plot_aligned=True,
+                            save_dir=plots_directory,
+                            fig_fn=fig_fn,
+                        )
+                        sections.append(
+                            ReportSection(
+                                title=f"{instrument} Altimetry Map (Aligned DEM)",
+                                image_path=os.path.join(plots_directory, fig_fn),
+                                caption=(
+                                    f"Pre- (left) and post-alignment (right) "
+                                    f"map views of {instrument} elevation "
+                                    f"differences. The aligned-DEM hillshade "
+                                    f"is used as the backdrop for both panels."
+                                ),
+                            )
+                        )
+
+                        fig_fn = f"{next(figure_counter):02}.png"
+                        alt.histogram_planetary_to_dem(
+                            plot_aligned=True,
+                            save_dir=plots_directory,
+                            fig_fn=fig_fn,
+                        )
+                        sections.append(
+                            ReportSection(
+                                title=f"{instrument} Altimetry Histogram (Aligned DEM)",
+                                image_path=os.path.join(plots_directory, fig_fn),
+                                caption=(
+                                    f"Pre- (steelblue) and post-alignment "
+                                    f"(orange) distributions of {instrument} "
+                                    f"minus DEM height differences with shared "
+                                    f"bin edges."
+                                ),
+                            )
+                        )
+
     # Compile report
     processing_parameters = ProcessingParameters(
         processing_directory=directory,

{asp_plot-1.13.0 → asp_plot-1.14.1}/asp_plot/utils.py

@@ -774,8 +774,18 @@ class Raster:
         -------
         int
             EPSG code
+
+        Notes
+        -----
+        If the CRS has no exact EPSG match (e.g. a compound or 3D-promoted
+        CRS such as "EPSG:32610+EPSG:4979"), falls back to the EPSG code
+        of the horizontal (2D) component.
         """
         epsg = self.ds.crs.to_epsg()
+        if epsg is None:
+            from pyproj import CRS
+
+            epsg = CRS(self.ds.crs).to_2d().to_epsg()
         return epsg
 
     def get_utm_epsg_code(self):

{asp_plot-1.13.0 → asp_plot-1.14.1}/pyproject.toml

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