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

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

@@ -5,6 +5,20 @@ 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.15.1] - 2026-06-10
+
+### Fixed
+- **`Altimetry.to_csv_for_pc_align()` wrote its CSV to the current working directory instead of the run directory.** Running the `asp_plot` CLI (or `Altimetry.align_and_evaluate()`) from a directory other than the dataset directory left a stray `atl06sr_for_pc_align_<key>.csv` in the cwd. The output path is now rooted at `self.directory` via `os.path.join()`, matching every other output in the class (`_save_to_parquet`, the `pc_align` outputs, and the planetary twin `to_csv_for_pc_align_planetary()`). No consumer changes were needed — the single internal caller (`align_and_evaluate()`) uses the return value directly, and `Alignment.pc_align_dem_to_atl06sr()` handles the directory-prefixed path unchanged.
+
+## [1.15.0] - 2026-06-09
+
+### Added
+- **Gallery plotting for many DEM outputs** ([#11](https://github.com/uw-cryo/asp_plot/issues/11)). New `GalleryPlotter` class (`asp_plot/gallery.py`) and `gallery` CLI tool that lay out a *stack* of DEMs as a grid of thumbnails sharing a single global percentile color stretch and one shared colorbar — useful for QA'ing multi-date / multi-pair ASP output at a glance. Brings the legacy `original_code/gallery.py` into the modular package, dropping its `pygeotools` / `imview` dependencies in favor of the existing `Raster`, `Plotter`, and `ColorBar` utilities.
+  - DEMs are rendered with the package's standard convention (gray hillshade underlay + semi-transparent `viridis` DEM); the hillshade underlay is on by default and can be disabled with `--no-hillshade`.
+  - The layout sizes each panel to the rasters' aspect ratio and places panels with absolute positioning, so galleries of 1 to N rasters (including non-square ones) pack tightly without stray whitespace. Per-panel titles use the full filename, auto-shrunk (by measuring rendered text width) to fit the panel.
+  - Output resolution is matched to the rendered detail for crisp zooming, with an automatic dpi cap that keeps the PNG under `--max_filesize_mb` (default 10) regardless of the number of rasters.
+  - `GalleryPlotter.from_directory(directory, pattern="*-DEM.tif")` resolves a directory + glob into the raster list; the CLI also accepts an explicit list of files.
+
 ## [1.14.1] - 2026-06-05
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asp_plot
-Version: 1.14.1
+Version: 1.15.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.14.1 → asp_plot-1.15.1}/asp_plot/altimetry.py

@@ -1012,7 +1012,7 @@ class Altimetry:
         CSV format with columns for longitude, latitude, and height.
         """
         atl06sr = self.atl06sr_processing_levels_filtered[key].to_crs("EPSG:4326")
-        csv_fn = f"{filename_prefix}_{key}.csv"
+        csv_fn = os.path.join(self.directory, f"{filename_prefix}_{key}.csv")
         df = atl06sr[["geometry", "h_mean"]].copy()
         df["lon"] = df["geometry"].x
         df["lat"] = df["geometry"].y

asp_plot-1.15.1/asp_plot/cli/gallery.py

@@ -0,0 +1,126 @@
+import os
+
+import click
+
+from asp_plot.gallery import GalleryPlotter
+
+
+@click.command()
+@click.option(
+    "--directory",
+    prompt=False,
+    default="./",
+    help="Directory to search for rasters. Default: current directory.",
+)
+@click.option(
+    "--pattern",
+    prompt=False,
+    default="*-DEM.tif",
+    help="Glob pattern for rasters within the directory; recursive '**' matches subdirectories (e.g. '**/*-DEM.tif'). Default: '*-DEM.tif'.",
+)
+@click.argument("files", nargs=-1, type=click.Path(exists=True))
+@click.option(
+    "--hillshade/--no-hillshade",
+    default=True,
+    help="Draw a gray hillshade underlay beneath each DEM. Default: True.",
+)
+@click.option(
+    "--cmap",
+    prompt=False,
+    default="viridis",
+    help="Colormap for the DEMs. Default: viridis.",
+)
+@click.option(
+    "--downsample",
+    prompt=False,
+    default="auto",
+    help="Downsample factor for reads, or 'auto' to size thumbnails automatically. Default: auto.",
+)
+@click.option(
+    "--max_filesize_mb",
+    prompt=False,
+    default=10.0,
+    type=float,
+    help="Soft cap on the output PNG size in MB; auto dpi is reduced to respect it. Default: 10.",
+)
+@click.option(
+    "--title",
+    prompt=False,
+    default=None,
+    help="Figure suptitle. Default: none.",
+)
+@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 _gallery.png suffix.",
+)
+def main(
+    directory,
+    pattern,
+    files,
+    hillshade,
+    cmap,
+    downsample,
+    max_filesize_mb,
+    title,
+    output_directory,
+    output_filename,
+):
+    """
+    Generate a gallery figure of many DEMs sharing a single color scale.
+
+    Provide either a --directory (searched with --pattern) or an explicit list
+    of FILES. Explicit files take precedence over the directory + pattern.
+    """
+    directory = os.path.expanduser(directory)
+    if output_directory:
+        output_directory = os.path.expanduser(output_directory)
+
+    # "auto" downsample passes through as a string; an explicit integer is cast.
+    if downsample != "auto":
+        downsample = int(downsample)
+
+    if files:
+        print(f"\nBuilding gallery from {len(files)} explicit file(s)\n")
+        plotter = GalleryPlotter(sorted(files), downsample=downsample, title=title)
+        # Default output location is the directory of the first file.
+        default_dir = os.path.dirname(os.path.abspath(files[0]))
+        dir_name = os.path.split(default_dir.rstrip("/\\"))[-1]
+    else:
+        print(f"\nBuilding gallery from '{pattern}' in {directory}\n")
+        plotter = GalleryPlotter.from_directory(
+            directory, pattern=pattern, downsample=downsample, title=title
+        )
+        default_dir = directory
+        dir_name = os.path.split(directory.rstrip("/\\"))[-1]
+
+    if output_directory is None:
+        output_directory = default_dir
+
+    if output_filename is None:
+        output_filename = f"{dir_name}_gallery.png"
+
+    os.makedirs(output_directory, exist_ok=True)
+
+    plotter.plot_gallery(
+        hillshade=hillshade,
+        cmap=cmap,
+        max_filesize_mb=max_filesize_mb,
+        save_dir=output_directory,
+        fig_fn=output_filename,
+    )
+
+    print(
+        f"\nGallery plot saved to {os.path.join(output_directory, output_filename)}\n"
+    )
+
+
+if __name__ == "__main__":
+    main()

asp_plot-1.15.1/asp_plot/gallery.py

@@ -0,0 +1,426 @@
+import glob
+import logging
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+from osgeo import gdal
+
+from asp_plot.utils import Plotter, Raster, save_figure
+
+logging.basicConfig(level=logging.WARNING)
+logger = logging.getLogger(__name__)
+
+# Target longest-edge size (pixels) for "auto" downsampling of gallery thumbnails.
+# Full-resolution ASP DEMs are often 15k+ pixels and hundreds of MB. This sets
+# how much detail each thumbnail preserves; the save dpi is matched to it so one
+# source pixel maps to ~one rendered pixel (crisp when zoomed) without bloating
+# the file. 1200 px keeps a 1-to-N-panel gallery comfortably under ~10 MB.
+GALLERY_TARGET_PX = 1200
+
+
+class GalleryPlotter(Plotter):
+    """
+    Plot a grid of DEM thumbnails sharing a single color scale.
+
+    This class extends the base Plotter class to visualize a *stack* of
+    rasters (e.g. multi-date or multi-pair ASP DEMs over the same area) as a
+    gallery of thumbnails. All panels share a single global percentile color
+    stretch and one shared colorbar, which makes it easy to QA elevation
+    differences across many outputs at a glance.
+
+    DEMs are rendered using the same convention as the rest of the package
+    (gray hillshade underlay with a semi-transparent ``viridis`` DEM on top).
+
+    The layout sizes every panel to the rasters' actual aspect ratio and places
+    panels with absolute positioning, so a gallery of 1 to N rasters (including
+    non-square ones) packs tightly without stray whitespace. Per-panel titles
+    use the full filename, auto-shrunk to fit the panel width.
+
+    Attributes
+    ----------
+    raster_list : list of str
+        Resolved list of raster file paths to plot.
+    downsample : int or str
+        Downsampling factor for reads, or "auto" to pick per-raster factors
+        so the longest edge is ~``GALLERY_TARGET_PX`` pixels.
+    title : str or None
+        Figure suptitle, inherited from the Plotter class.
+
+    Examples
+    --------
+    >>> gallery = GalleryPlotter.from_directory("/path/to/dems", pattern="*-DEM.tif")
+    >>> gallery.plot_gallery(save_dir="/path/to/output", fig_fn="dem_gallery.png")
+    """
+
+    def __init__(self, raster_list, downsample="auto", **kwargs):
+        """
+        Initialize the GalleryPlotter object.
+
+        Parameters
+        ----------
+        raster_list : list of str
+            List of raster file paths to plot. Use the ``from_directory``
+            classmethod to resolve a directory + glob pattern into this list.
+        downsample : int or str, optional
+            Downsampling factor passed to ``Raster``. "auto" (default) picks a
+            per-raster factor so the longest edge is ~``GALLERY_TARGET_PX``.
+        **kwargs : dict, optional
+            Additional keyword arguments passed to the Plotter base class,
+            particularly 'title' for the figure suptitle.
+
+        Raises
+        ------
+        ValueError
+            If ``raster_list`` is empty.
+        """
+        super().__init__(**kwargs)
+        self.raster_list = [os.path.expanduser(fn) for fn in raster_list]
+        if not self.raster_list:
+            raise ValueError(
+                "\n\nNo rasters to plot. Provide a non-empty list of files, "
+                "or check the directory and pattern.\n\n"
+            )
+        self.downsample = downsample
+
+    @classmethod
+    def from_directory(cls, directory, pattern="*-DEM.tif", **kwargs):
+        """
+        Build a GalleryPlotter by globbing a directory for rasters.
+
+        Globbing is recursive, so ``**`` in the pattern descends into
+        subdirectories. This is handy for typical ASP layouts where each pair
+        lives in its own subdirectory:
+
+        - ``"*-DEM.tif"``      — top-level only
+        - ``"*/*-DEM.tif"``    — exactly one subdirectory deep
+        - ``"**/*-DEM.tif"``   — any depth (recursive)
+
+        Parameters
+        ----------
+        directory : str
+            Directory to search for rasters.
+        pattern : str, optional
+            Glob pattern for the rasters, default is "*-DEM.tif". Supports
+            recursive ``**`` to match nested subdirectories.
+        **kwargs : dict, optional
+            Additional keyword arguments passed to ``__init__`` (e.g.
+            ``downsample``, ``title``).
+
+        Returns
+        -------
+        GalleryPlotter
+            Plotter initialized with the sorted list of matching files.
+
+        Raises
+        ------
+        ValueError
+            If no files in ``directory`` match ``pattern``.
+        """
+        directory = os.path.expanduser(directory)
+        matches = sorted(glob.glob(os.path.join(directory, pattern), recursive=True))
+        if not matches:
+            raise ValueError(
+                f"\n\nNo files matching '{pattern}' found in {directory}.\n\n"
+            )
+        return cls(matches, **kwargs)
+
+    @staticmethod
+    def _grid_shape(n, aspect=1.0):
+        """
+        Compute the (nrows, ncols) grid for ``n`` panels of a given aspect.
+
+        Searches all column counts and picks the one whose overall grid is
+        closest to square in display space (accounting for each panel's
+        width/height ``aspect``), lightly penalizing empty trailing cells.
+        This keeps galleries of 1 to N panels — square or not — visually
+        balanced.
+
+        Parameters
+        ----------
+        n : int
+            Number of panels.
+        aspect : float, optional
+            Panel width / height ratio, default 1.0 (square).
+
+        Returns
+        -------
+        tuple of int
+            (nrows, ncols)
+        """
+        best = None
+        for ncols in range(1, n + 1):
+            nrows = int(np.ceil(n / ncols))
+            display_aspect = (ncols * aspect) / nrows
+            empty = nrows * ncols - n
+            # log() so e.g. 2:1 and 1:2 are penalized equally around square.
+            cost = abs(np.log(display_aspect)) + 0.1 * empty
+            if best is None or cost < best[0]:
+                best = (cost, (nrows, ncols))
+        return best[1]
+
+    @staticmethod
+    def _fit_title_fontsize(text, panel_w_in, max_fs=8.0, min_fs=4.0):
+        """
+        Pick a font size so ``text`` fits within ``panel_w_in`` inches.
+
+        Uses an average character-width estimate (~0.58 * fontsize in points)
+        rather than a renderer, so it works headlessly and deterministically.
+
+        Parameters
+        ----------
+        text : str
+            The title text.
+        panel_w_in : float
+            Panel width in inches.
+        max_fs, min_fs : float, optional
+            Font-size clamps in points.
+
+        Returns
+        -------
+        float
+            Font size in points.
+        """
+        panel_w_pts = panel_w_in * 72.0
+        fs = panel_w_pts / (0.58 * max(len(text), 1))
+        return float(np.clip(fs, min_fs, max_fs))
+
+    def _fit_titles(self, fig, title_artists, panel_w_in, min_fs=3.5, pad=0.92):
+        """
+        Shrink each title's font so its *rendered* width fits the panel.
+
+        Measures the real text extent with an Agg renderer (accurate for any
+        font, unlike a character-count estimate), then scales the font size by
+        the width ratio. Falls back to the heuristic ``_fit_title_fontsize`` if
+        measurement fails for any reason (e.g. an unusual backend).
+
+        Parameters
+        ----------
+        fig : matplotlib.figure.Figure
+            The figure (used for its dpi).
+        title_artists : list of matplotlib.text.Text
+            The per-panel title artists to resize in place.
+        panel_w_in : float
+            Panel width in inches.
+        min_fs : float, optional
+            Lower clamp on the font size, default 3.5.
+        pad : float, optional
+            Fraction of the panel width to fill (leaves a small margin).
+        """
+        panel_w_px = panel_w_in * fig.dpi
+        try:
+            from matplotlib.backends.backend_agg import RendererAgg
+
+            renderer = RendererAgg(
+                int(fig.get_figwidth() * fig.dpi),
+                int(fig.get_figheight() * fig.dpi),
+                fig.dpi,
+            )
+            for t in title_artists:
+                w = t.get_window_extent(renderer=renderer).width
+                if w <= 0:
+                    continue
+                scaled = t.get_fontsize() * (panel_w_px / w) * pad
+                t.set_fontsize(float(np.clip(scaled, min_fs, t.get_fontsize())))
+        except Exception:
+            for t in title_artists:
+                t.set_fontsize(self._fit_title_fontsize(t.get_text(), panel_w_in))
+
+    def _resolve_downsample(self, ds):
+        """
+        Resolve the downsample factor for a single dataset.
+
+        Returns ``self.downsample`` directly if it is an integer, otherwise
+        ("auto") picks a factor so the longest edge is ~``GALLERY_TARGET_PX``.
+        """
+        if isinstance(self.downsample, str):
+            longest = max(ds.height, ds.width)
+            return max(1, int(np.ceil(longest / GALLERY_TARGET_PX)))
+        return self.downsample
+
+    def _hillshade_at(self, fn, shape):
+        """
+        Compute a GDAL hillshade for ``fn`` matching a downsampled DEM shape.
+
+        Mirrors ``Raster.hillshade()`` (GDAL ``hillshade``, computeEdges) but
+        runs on a downsampled in-memory copy so the underlay array matches the
+        downsampled DEM array in shape.
+
+        Parameters
+        ----------
+        fn : str
+            Path to the DEM.
+        shape : tuple of int
+            Target (height, width) of the downsampled DEM.
+
+        Returns
+        -------
+        numpy.ma.MaskedArray
+            Hillshade array (nodata masked at 0).
+        """
+        out_h, out_w = shape
+        gdal_ds = gdal.Open(fn)
+        mem = gdal.Translate("", gdal_ds, format="MEM", width=out_w, height=out_h)
+        hs_ds = gdal.DEMProcessing(
+            "", mem, "hillshade", format="MEM", computeEdges=True
+        )
+        return np.ma.masked_equal(hs_ds.ReadAsArray(), 0)
+
+    def plot_gallery(
+        self,
+        hillshade=True,
+        cmap="viridis",
+        clim=None,
+        cbar_label="Elevation (m HAE)",
+        panel_size=3.0,
+        dpi=None,
+        max_dpi=600,
+        max_filesize_mb=10.0,
+        save_dir=None,
+        fig_fn=None,
+    ):
+        """
+        Plot the DEM gallery.
+
+        Reads every raster (downsampled), computes a global shared color
+        stretch, and lays the thumbnails out in an aspect-matched grid with one
+        shared colorbar. Each panel is titled with its filename, auto-shrunk to
+        fit the panel width.
+
+        Parameters
+        ----------
+        hillshade : bool, optional
+            If True (default), draw a gray hillshade underlay beneath each DEM
+            and render the DEM semi-transparently on top, matching the
+            convention used elsewhere in the package.
+        cmap : str, optional
+            Colormap for the DEMs, default is "viridis".
+        clim : tuple or None, optional
+            Color limits (min, max). If None (default), a global percentile
+            stretch shared across all rasters is computed via ``ColorBar``.
+        cbar_label : str, optional
+            Label for the shared colorbar, default is "Elevation (m HAE)".
+        panel_size : float, optional
+            Longest-edge size of each panel in inches, default 3.0.
+        dpi : int or None, optional
+            Save resolution. If None (default), matched to the rendered detail
+            (so one source pixel ~ one image pixel), then lowered if needed to
+            respect ``max_filesize_mb`` and clamped to ``max_dpi``.
+        max_dpi : int, optional
+            Upper bound on the auto dpi to keep file size in check, default 600.
+        max_filesize_mb : float, optional
+            Soft cap on the output PNG size in MB, default 10. The auto dpi is
+            reduced so the total rendered pixel count stays within an estimated
+            budget; this keeps galleries of many rasters from exceeding the cap.
+            Ignored when ``dpi`` is given explicitly.
+        save_dir : str or None, optional
+            Directory to save the figure, default is None (don't save).
+        fig_fn : str or None, optional
+            Filename for the saved figure, default is None.
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+            The gallery figure.
+        """
+        # Read every raster once (downsampled), caching arrays so we don't
+        # re-read the (potentially huge) source files for plotting.
+        arrays = []
+        for fn in self.raster_list:
+            ds_probe = Raster(fn)
+            downsample = self._resolve_downsample(ds_probe.ds)
+            arrays.append(Raster(fn, downsample=downsample).read_array())
+
+        if clim is None:
+            clim = self.cb.find_common_clim(arrays)
+
+        n = len(arrays)
+
+        # Panel box sized to the rasters' (median) aspect ratio so imshow's
+        # equal-aspect images fill each box with minimal internal whitespace.
+        aspects = [a.shape[1] / a.shape[0] for a in arrays]
+        aspect = float(np.median(aspects))
+        if aspect >= 1.0:
+            panel_w, panel_h = panel_size, panel_size / aspect
+        else:
+            panel_w, panel_h = panel_size * aspect, panel_size
+
+        nrows, ncols = self._grid_shape(n, panel_w / panel_h)
+
+        # Absolute (inches) layout so trailing empty cells leave no gap.
+        # Reserve vertical room for the largest possible title (titles are
+        # shrunk, never grown, beyond this in _fit_titles).
+        max_title_fs = 8.0
+        title_h = max_title_fs / 72.0 + 0.06
+        left, right, bottom = 0.12, 0.12, 0.12
+        top = 0.12 + (0.3 if self.title else 0.0)
+        wgap, hgap = 0.14, title_h + 0.06
+        cbar_gap, cbar_w = 0.18, 0.22
+
+        grid_w = ncols * panel_w + (ncols - 1) * wgap
+        grid_h = nrows * panel_h + (nrows - 1) * hgap
+        fig_w = left + grid_w + cbar_gap + cbar_w + right
+        fig_h = top + grid_h + bottom
+
+        # Match save dpi to the actual rendered detail (median longest edge),
+        # then lower it if needed so the total rendered pixel count stays within
+        # a file-size budget (keeps many-raster galleries under max_filesize_mb).
+        if dpi is None:
+            med_long_px = float(np.median([max(a.shape) for a in arrays]))
+            detail_dpi = round(med_long_px / panel_size)
+            # ~0.8 bytes/pixel is a conservative estimate for these hillshaded
+            # DEM PNGs; the 0.85 factor adds headroom against the soft cap.
+            budget_px = 0.85 * max_filesize_mb * 1e6 / 0.8
+            budget_dpi = (budget_px / (fig_w * fig_h)) ** 0.5
+            dpi = int(np.clip(min(detail_dpi, budget_dpi), 100, max_dpi))
+
+        fig = plt.figure(figsize=(fig_w, fig_h))
+        if self.title is not None:
+            fig.suptitle(self.title, size=10)
+
+        im = None
+        title_artists = []
+        for i, (fn, array) in enumerate(zip(self.raster_list, arrays)):
+            row, col = divmod(i, ncols)
+            x_in = left + col * (panel_w + wgap)
+            y_in = fig_h - top - row * (panel_h + hgap) - panel_h
+            ax = fig.add_axes(
+                [x_in / fig_w, y_in / fig_h, panel_w / fig_w, panel_h / fig_h]
+            )
+            if hillshade:
+                hs = self._hillshade_at(fn, array.shape)
+                self.plot_array(ax=ax, array=hs, cmap="gray", add_cbar=False)
+                im = self.plot_array(
+                    ax=ax,
+                    array=array,
+                    clim=clim,
+                    cmap=cmap,
+                    add_cbar=False,
+                    alpha=0.5,
+                )
+            else:
+                im = self.plot_array(
+                    ax=ax, array=array, clim=clim, cmap=cmap, add_cbar=False
+                )
+            title_artists.append(ax.set_title(os.path.basename(fn), size=max_title_fs))
+
+        # Shrink each title so the full filename fits within its panel width.
+        self._fit_titles(fig, title_artists, panel_w)
+
+        # Single shared colorbar spanning the panel grid on the right.
+        if im is not None:
+            cbar_x = left + grid_w + cbar_gap
+            cax = fig.add_axes(
+                [cbar_x / fig_w, bottom / fig_h, cbar_w / fig_w, grid_h / fig_h]
+            )
+            cbar = fig.colorbar(
+                im,
+                cax=cax,
+                extend=self.cb.get_cbar_extend(arrays[0], clim),
+            )
+            cbar.set_label(cbar_label)
+
+        if save_dir and fig_fn:
+            save_figure(fig, save_dir, fig_fn, dpi=dpi)
+
+        return fig

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "asp_plot"
-version = "1.14.1"
+version = "1.15.1"
 license = {text = "BSD-3-Clause"}
 authors = [
   { name="Ben Purinton", email="purinton@uw.edu" },
@@ -44,6 +44,7 @@ asp_plot = "asp_plot.cli.asp_plot:main"
 csm_camera_plot = "asp_plot.cli.csm_camera_plot:main"
 stereo_geom = "asp_plot.cli.stereo_geom:main"
 request_planetary_altimetry = "asp_plot.cli.request_planetary_altimetry:main"
+gallery = "asp_plot.cli.gallery:main"
 
 [project.optional-dependencies]
 dev = [