asp_plot.gallery
================

.. py:module:: asp_plot.gallery


Attributes
----------

.. autoapisummary::

   asp_plot.gallery.GALLERY_TARGET_PX
   asp_plot.gallery.logger


Classes
-------

.. autoapisummary::

   asp_plot.gallery.GalleryPlotter


Module Contents
---------------

.. py:class:: GalleryPlotter(raster_list, downsample='auto', **kwargs)

   Bases: :py:obj:`asp_plot.utils.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.

   .. attribute:: raster_list

      Resolved list of raster file paths to plot.

      :type: list of str

   .. attribute:: downsample

      Downsampling factor for reads, or "auto" to pick per-raster factors
      so the longest edge is ~``GALLERY_TARGET_PX`` pixels.

      :type: int or str

   .. attribute:: title

      Figure suptitle, inherited from the Plotter class.

      :type: str or None

   .. rubric:: Examples

   >>> gallery = GalleryPlotter.from_directory("/path/to/dems", pattern="*-DEM.tif")
   >>> gallery.plot_gallery(save_dir="/path/to/output", fig_fn="dem_gallery.png")


   .. py:method:: from_directory(directory, pattern='*-DEM.tif', **kwargs)
      :classmethod:


      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)

      :param directory: Directory to search for rasters.
      :type directory: str
      :param pattern: Glob pattern for the rasters, default is "*-DEM.tif". Supports
                      recursive ``**`` to match nested subdirectories.
      :type pattern: str, optional
      :param \*\*kwargs: Additional keyword arguments passed to ``__init__`` (e.g.
                         ``downsample``, ``title``).
      :type \*\*kwargs: dict, optional

      :returns: Plotter initialized with the sorted list of matching files.
      :rtype: GalleryPlotter

      :raises ValueError: If no files in ``directory`` match ``pattern``.



   .. py:method:: plot_gallery(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.

      :param hillshade: 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.
      :type hillshade: bool, optional
      :param cmap: Colormap for the DEMs, default is "viridis".
      :type cmap: str, optional
      :param clim: Color limits (min, max). If None (default), a global percentile
                   stretch shared across all rasters is computed via ``ColorBar``.
      :type clim: tuple or None, optional
      :param cbar_label: Label for the shared colorbar, default is "Elevation (m HAE)".
      :type cbar_label: str, optional
      :param panel_size: Longest-edge size of each panel in inches, default 3.0.
      :type panel_size: float, optional
      :param dpi: 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``.
      :type dpi: int or None, optional
      :param max_dpi: Upper bound on the auto dpi to keep file size in check, default 600.
      :type max_dpi: int, optional
      :param max_filesize_mb: 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.
      :type max_filesize_mb: float, optional
      :param save_dir: Directory to save the figure, default is None (don't save).
      :type save_dir: str or None, optional
      :param fig_fn: Filename for the saved figure, default is None.
      :type fig_fn: str or None, optional

      :returns: The gallery figure.
      :rtype: matplotlib.figure.Figure



   .. py:attribute:: downsample
      :value: 'auto'



   .. py:attribute:: raster_list


.. py:data:: GALLERY_TARGET_PX
   :value: 1200


.. py:data:: logger