Dataset Class

At a glance

Hold "Ctrl" to enable pan & zoom

flowchart LR
    CR["<b>create / read</b><br/>read_file · from_array · from_dataframe<br/>from_features · from_band_files<br/>from_zarr · from_bytes"] --> DS(("Dataset"))

    DS --> PR["<b>properties</b><br/>rows · columns · band_count · band_names<br/>epsg · crs · cell_size · geotransform<br/>bbox · bounds · no_data_value · dtype"]
    DS --> AC["<b>access data</b><br/>read_array — window · bbox · chunks<br/>sample · extract · get_tile · read_part"]
    DS --> SP["<b>spatial</b><br/>crop · to_crs · warped_view · resample<br/>align · fill_gaps · wrap_longitude"]
    DS --> AN["<b>analysis</b><br/>stats · zonal_stats · apply · overlay<br/>map_blocks · slope · aspect · hillshade<br/>proximity · cluster"]
    DS --> ND["<b>no-data</b><br/>change_no_data_value · fill · get_mask"]
    DS --> MD["<b>missing data</b><br/>where · fillna · isnull · notnull<br/>equals · identical"]
    DS --> CW["<b>cell-wise</b><br/>clip · round · astype · isin"]
    DS --> VE["<b>vectorize</b><br/>to_geodataframe · contour · sieve"]
    DS --> VI["<b>visualize</b><br/>plot · plot_histogram · to_image<br/>color_table · create_overviews · preview"]
    DS --> WR["<b>write</b><br/>to_file — .tif · .nc · .asc<br/>to_cog · to_zarr · to_terrain_rgb"]

Architecture — the engine layer

Dataset is a thin facade: each family of operations lives in its own engine (ds.io, ds.spatial, …) and ds.<method>(...) forwards to ds.<engine>.<method>(...). The reference pages below are one per engine (COG's page lives in its own COG section).

Hold "Ctrl" to enable pan & zoom

flowchart TB
    DS(("Dataset<br/>facade"))
    DS -->|ds.io| IO["<b>IO</b> · io.md<br/>read_array · write_array · to_file<br/>to_bytes · get_tile · to_xyz<br/>to_terrain_rgb · create_overviews"]
    DS -->|ds.spatial| SP["<b>Spatial</b> · spatial.md<br/>crop · to_crs · warped_view<br/>resample · align · wrap_longitude"]
    DS -->|ds.analysis| AN["<b>Analysis</b> · analysis.md<br/>stats · extract · sample · overlay<br/>proximity · masks · footprint · plot"]
    DS -->|ds.bands| BA["<b>Bands</b> · band_metadata.md<br/>attribute tables · colours<br/>add_band · change_no_data_value"]
    DS -->|ds.cell| CE["<b>Cell</b> · cell.md<br/>get_cell_coords · to_geodataframe<br/>cell_area · map ↔ array"]
    DS -->|ds.georef| GE["<b>Georef</b> · georef.md<br/>GCPs · RPCs · orthorectify<br/>set_gcps · georeference"]
    DS -->|ds.vectorize| VE["<b>Vectorize</b> · vectorize.md<br/>contour · to_geodataframe<br/>cluster · translate"]
    DS -->|ds.cog| CG["<b>COG</b> · cog/ section<br/>to_cog · validate_cog · info<br/>read_part · preview · read_tile"]

• Detailed class diagram for the Dataset class and related components:

Hold "Ctrl" to enable pan & zoom

classDiagram
    %% configuration class
    class Config {
    }

    %% abstract base class for rasters
    class RasterBase {
        +__init__(src, access)
        +__str__()
        +__repr__()
        +access()
        +raster()
        +raster(value)
        +values()
        +rows()
        +columns()
        +shape()
        +geotransform()
        +top_left_corner()
        +epsg()
        +epsg(value)
        +crs()
        +crs(value)
        +cell_size()
        +no_data_value()
        +no_data_value(value)
        +meta_data()
        +meta_data(value)
        +block_size()
        +block_size(value)
        +file_name()
        +driver_type()
        +read_file(path, read_only)
        +read_array(band, window)
        +_read_block(band, window)
        +plot(band, exclude_value, overview, overview_index, rgb_options, *, fig, ax, **kwargs)
    }

    %% concrete raster class
    class Dataset {
        +__init__(src, access)
        +__str__()
        +__repr__()
        +access()
        +raster()
        +raster(value)
        +values()
        +rows()
        +columns()
        +shape()
        +geotransform()
        +epsg()
        +epsg(value)
        +crs()
        +crs(value)
        +cell_size()
        +band_count()
        +band_names()
        +band_names(name_list)
        +band_units()
        +band_units(value)
        +no_data_value()
        +no_data_value(value)
        +meta_data()
        +meta_data(value)
        +block_size()
        +block_size(value)
        +file_name()
        +driver_type()
        +scale()
        +scale(value)
        +offset()
        +offset(value)
        +read_file(path, read_only)
        +from_array(arr, geo_ref, no_data_value, path)
        +read_array(band, window)
        +_read_block(band, window)
        +_resolve_plot_band(band, rgb)
        +plot(band, exclude_value, overview, overview_index, rgb_options, *, fig, ax, **kwargs)
        +to_file(path, driver, band)
        +to_crs(to_epsg, method, maintain_alignment)
        +resample(cell_size, method)
        +align(alignment_src)
        +crop(mask, touch)
        +merge(src, dst, no_data_value, init, n)
        +apply(ufunc)
        +overlay(classes_map, exclude_value)
    }



    %% Driver catalog
    class _utils_Catalog {
    }

    %% NetCDF
    class NetCDF {
    }

    %% error classes
    class _errors_ReadOnlyError
    class _errors_DatasetNotFoundError
    class _errors_NoDataValueError
    class _errors_AlignmentError
    class _errors_DriverNotExistError
    class _errors_FileFormatNotSupportedError
    class _errors_OptionalPackageDoesNotExist
    class _errors_FailedToSaveError
    class _errors_OutOfBoundsError
    class _errors_OverviewTargetError

    %% inheritance relations
    RasterBase <|-- Dataset
    Dataset <|-- NetCDF

    %% composition/usage relations
    RasterBase ..> _utils_Catalog : "uses Catalog constant"
    RasterBase ..> feature_FeatureCollection : "vector ops"
    Dataset ..> feature_FeatureCollection : "vector ops"
    Dataset ..> _errors_ReadOnlyError : "raises"
    Dataset ..> _errors_AlignmentError : "raises"
    Dataset ..> _errors_NoDataValueError : "raises"
    Dataset ..> _errors_FailedToSaveError : "raises"
    Dataset ..> _errors_OverviewTargetError : "raises"
    Dataset ..> _errors_OutOfBoundsError : "raises"
    NetCDF ..> _errors_OptionalPackageDoesNotExist : "raises"
    Config ..> Dataset : "initialises raster settings"

Hold "Ctrl" to enable pan & zoom

classDiagram

    %% Central dataset class with its main attributes
    class Dataset {
        +raster
        +cell_size
        +values
        +shape
        +rows
        +columns
        +pivot_point
        +geotransform
        +bounds
        +bbox
        +epsg
        +crs
        +lon
        +lat
        +x
        +y
        +band_count
        +band_names
        +variables
        +no_data_value
        +meta_data
        +dtype
        +gdal_dtype
        +numpy_dtype
        +file_name
        +time_stamp
        +driver_type
    }

    %% Group: visualisation functionality
    class Visualization {
        +plot()
        +overview_count()
        +read_overview_array()
        +create_overviews()
        +recreate_overviews()
        +get_overview()
        +get_overview_dataset()
    }
    Dataset --> Visualization : «visualisation»

    %% Group: data access methods
    class AccessData {
        +read_array()
        +get_variables()
        +count_domain_cells()
        +cell_area()
        +domain_area()
        +get_band_names()
        +extract()
        +stats()
    }
    Dataset --> AccessData : «data access»

    %% Group: mathematical operations on raster values
    class MathOperations {
        +apply()
        +fill()
        +normalize()
        +cluster()
        +to_polygons()
        +get_tile()
        +groupNeighbours()
    }
    Dataset --> MathOperations : «math ops»

    %% Group: spatial operations and reprojection
    class SpatialOperations {
        +to_crs()
        +resample()
        +align()
        +crop()
        +locate_points()
        +overlay()
        +extract()
        +footprint()
    }
    Dataset --> SpatialOperations : «spatial ops»

    %% Group: conversion to other data types
    class Conversion {
        +to_geodataframe()
    }
    Dataset --> Conversion : «conversion»

    %% Group: coordinate system handling
    class OSR {
        +create_sr_from_epsg()
    }
    Dataset --> OSR : «osr»

    %% Group: bounding‐box and bounds calculations
    class BBoxBounds {
        +calculate_bbox()
        +calculate_bounds()
    }
    Dataset --> BBoxBounds : «bbox/bounds»

    %% Group: CRS/EPSG getters
    class CrsEpsg {
        +get_crs()
        +get_epsg()
    }
    Dataset --> CrsEpsg : «crs/epsg»

    %% Group: latitude/longitude getters
    class LatLon {
        +get_lat_lon()
    }
    Dataset --> LatLon : «lat/lon»

    %% Group: band names management
    class BandNames {
        +get_band_names_internal()
        +set_band_names()
    }
    Dataset --> BandNames : «band names»

    %% Group: timestamp handling
    class TimeStamp {
        +get_time_variable()
        +read_variable()
    }
    Dataset --> TimeStamp : «time»

    %% Group: handling of no‐data values
    class NoDataValue {
        +set_no_data_value()
        +set_no_data_value_backend()
        +change_no_data_value_attr()
    }
    Dataset --> NoDataValue : «no data value»

    %% Group: helpers for creating GDAL datasets
    class GdalDataset {
        +create_empty_driver()
        +create_driver_from_scratch()
        +create_mem_gtiff_dataset()
    }
    Dataset --> GdalDataset : «gdal creation»

    %% Group: factory methods for creating Dataset objects
    class CreateObject {
        +from_gdal_dataset()
        +read_file()
        +from_array()
        +dataset_like()
        +from_bytes()
        +from_band_files()
        +from_archive()
    }
    Dataset --> CreateObject : «object factory»

Factory methods at a glance

Method	Use when
read_file(path, vsi=…, file_i=…)	Open a path, URL, or archive member (zip/tar/gzip). URLs auto-rewrite to /vsi*.
from_bytes(data, suffix=".tif")	The caller already holds the bytes (HTTP body, DB blob, S3 get_object payload). Backed by /vsimem/.
from_band_files(paths)	Stack N single-band rasters (one file per band) into one multi-band Dataset — the natural target for the <asset>.<band>.tif layout of GEE / Landsat / Sentinel downloads.
from_archive(url_or_path, member_glob=…)	Merge every matching member of a local or remote archive into one multi-band Dataset (composes from_band_files over gdal.ReadDir). For one-Dataset-per-member use DatasetCollection.from_archive.
from_array(arr, …)	Build a Dataset from a numpy array + geobox.
from_dataframe(df, crs=…)	Rebuild a raster from a (band, y, x) frame (inverse of to_dataframe).
dataset_like(template, arr)	Stamp a new Dataset that inherits its grid / CRS from template.

See the Recipes page for runnable examples of each.

The pandas round trip

to_dataframe() hands the raster to pandas as one row per cell on a (band, y, x) MultiIndex with a single values column, and from_dataframe() rebuilds a raster from such a frame: Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg) reproduces ds's values, band count/order, grid and CRS. Gaps come back as NaN (pass no_data_value=ds.no_data_value[0] to restore a specific sentinel and dtype). This is the coordinate-keyed, geometry-free view for pandas analytics; for a geometry-per-cell GeoDataFrame (points or polygons, optionally with the band values) use to_geodataframe, and to read values at scattered points use sample / extract. The band level is always present (a one-band raster carries band 0); df["values"].unstack("band") gives the wide, one-column-per-band view.

pyramids.dataset.Dataset

Bases: RasterBase

Single-band or multi-band raster dataset (GeoTIFF, etc.).

Wraps a GDAL dataset with spatial operations (crop, reproject, align, mosaic), band-level I/O, and no-data handling. For NetCDF files use the :class:~pyramids.netcdf.NetCDF subclass; for temporal stacks of rasters use :class:~pyramids.dataset.DatasetCollection.

The eight public-API families are exposed as collaborator instances (ds.io, ds.spatial, ds.bands, ds.analysis, ds.cell, ds.vectorize, ds.cog, ds.georef) and via thin facade methods on the Dataset itself, so ds.crop(mask) and ds.spatial.crop(mask) are equivalent. Each collaborator holds a weakref proxy back to the Dataset; the proxy keeps GDAL handle release deterministic on Windows.

Source code in src/pyramids/dataset/dataset.py

class Dataset(RasterBase):
    """Single-band or multi-band raster dataset (GeoTIFF, etc.).

    Wraps a GDAL dataset with spatial operations (crop, reproject, align,
    mosaic), band-level I/O, and no-data handling. For NetCDF files use
    the :class:`~pyramids.netcdf.NetCDF` subclass; for temporal stacks of
    rasters use :class:`~pyramids.dataset.DatasetCollection`.

    The eight public-API families are exposed as collaborator instances
    (`ds.io`, `ds.spatial`, `ds.bands`, `ds.analysis`,
    `ds.cell`, `ds.vectorize`, `ds.cog`, `ds.georef`) and via thin facade
    methods on the Dataset itself, so `ds.crop(mask)` and
    `ds.spatial.crop(mask)` are equivalent. Each collaborator holds a
    weakref proxy back to the Dataset; the proxy keeps GDAL handle
    release deterministic on Windows.
    """

    # Instance attributes assigned outside ``__init__`` — lazily by the io
    # engine (``_backend``), by warp/georef operations (``_warp_source``),
    # by the bytes/VSI round-trip (``_vsimem_path``), or on the base
    # ``Dataset`` that ``NetCDF`` produces for a flattened band axis (the
    # ``_band_dim_*`` / ``_variable_attrs`` group, also initialised in
    # ``NetCDF.__init__``). Declared here so the checker knows the surface;
    # the runtime values are set where each is produced.
    _backend: str
    # Strong reference to the *source GDAL raster* a warped VRT reads through, kept
    # so it outlives the VRT. It must not be the pyramids `Dataset`: engines reach
    # their parent through a `weakref.proxy`, so pinning that would keep nothing
    # alive. `NetCDF.warped_view` carries this across when it re-wraps a view.
    _warp_source: gdal.Dataset | None
    _vsimem_path: str
    _band_dim_name: str | None
    _band_dim_values: list[Any] | None
    _band_dim_names: tuple[str, ...]
    _band_dim_values_map: dict[str, list[Any] | None]
    _band_dim_sizes: tuple[int, ...]
    _variable_attrs: dict[str, Any]

    def __init__(
        self,
        src: gdal.Dataset,
        access: str = "read_only",
        *,
        gdal_env: dict[str, str] | None = None,
        open_options: tuple[str, ...] | list[str] | None = None,
    ):
        """Wrap an open ``gdal.Dataset`` as a :class:`Dataset`.

        A thin override of :meth:`RasterBase.__init__` that attaches a logger and
        forwards every argument unchanged; see the base for the full contract.
        Prefer :meth:`read_file` over constructing directly.

        Args:
            src: An open :class:`osgeo.gdal.Dataset` to wrap.
            access: The mode ``src`` was opened with — ``"read_only"`` (default)
                or ``"write"``.
            gdal_env: GDAL config captured for reopen paths; ``None`` captures
                nothing.
            open_options: GDAL open options captured for reopen paths; ``None``
                captures nothing (#1025).
        """
        self.logger = logging.getLogger(__name__)
        super().__init__(
            src, access=access, gdal_env=gdal_env, open_options=open_options
        )

        self._no_data_value = [
            src.GetRasterBand(i).GetNoDataValue() for i in range(1, self.band_count + 1)
        ]
        self._band_names = self._get_band_names()
        self._band_units = [
            src.GetRasterBand(i).GetUnitType() for i in range(1, self.band_count + 1)
        ]

        # Each collaborator owns the bodies of one public-API family
        # (io, spatial, bands, analysis, cell, vectorize, cog) and
        # holds a `weakref.proxy(self)` back-reference. Dataset
        # exposes facade methods that delegate to the collaborator,
        # so both `ds.crop(mask)` and `ds.spatial.crop(mask)` are
        # equivalent.
        self.io = IO(self)
        self.spatial = Spatial(self)
        self.bands = Bands(self)
        self.analysis = Analysis(self)
        self.cell = Cell(self)
        self.vectorize = Vectorize(self)
        self.cog = COG(self)
        self.georef = Georef(self)

    def _update_inplace(self, src: gdal.Dataset, access: str | None = None) -> None:
        """Swap internal state from a new GDAL dataset.

        Creates a fresh instance of `type(self)` and copies its
        internal state into `self`. Using `type(self)` rather
        than the literal `Dataset` is what keeps a NetCDF instance
        a NetCDF after any in-place op (set_crs, change_no_data_value,
        apply(inplace=True), to_file). Subclasses that carry extra
        state across the swap (e.g. NetCDF's variable-subset
        attributes) override this method.

        after `__dict__.update`, the collaborators on
        `self` came from `new.__dict__` and point at the temporary
        `new` instance, not at `self`. Re-bind every collaborator's
        `_ds` to `self` so subsequent `self.spatial.crop(...)`
        calls reach back into `self`, not the discarded `new`.

        Why ``collab._ds = self_proxy`` works despite the slot:
            ``_Engine`` declares ``__slots__ = ("_ds",)`` (see
            :mod:`pyramids.dataset.engines._base`). Slots prevent
            adding *new* attributes to an instance, not reassigning
            existing ones, so direct rebinding of the single
            declared slot stays legal. The proxy is freshly built
            from ``self`` (not pulled from ``new``) so the engines
            point at the live Dataset after the swap.
        """
        new = type(self)(src, access=access or self._access)
        self.__dict__.update(new.__dict__)
        # `update` merges, so a lazily-set cache the fresh instance never
        # populated would survive the swap and describe the OLD raster. Drop the
        # inferred-CF-CRS memo explicitly.
        self.__dict__.pop("_cf_crs_cache", None)
        # Re-bind via `weakref.proxy` so the back-reference stays
        # weak after the dict swap (matches `_Engine.__init__`).
        # Direct slot reassignment is allowed because `_Engine`
        # declares `_ds` as its only slot — see method docstring.
        self_proxy = weakref.proxy(self)
        for attr in _COLLABORATOR_ATTRS:
            collab = self.__dict__.get(attr)
            if collab is not None:
                collab._ds = self_proxy
        # Drop cached registered accessors so they rebuild against the new raster
        # (the `__dict__.update` above would otherwise keep a stale one).
        _invalidate_cached_accessors(self)

    def focal_mean(
        self, radius: int = 1, *, chunks=None, band: int = 0
    ) -> np.ndarray | da.Array:
        """Thin forwarder to :func:`pyramids.dataset.ops._focal.focal_mean`."""
        return focal_mean(self, radius=radius, chunks=chunks, band=band)

    def focal_std(
        self, radius: int = 1, *, chunks=None, band: int = 0
    ) -> np.ndarray | da.Array:
        """Thin forwarder to :func:`pyramids.dataset.ops._focal.focal_std`."""
        return focal_std(self, radius=radius, chunks=chunks, band=band)

    def focal_apply(
        self, func, radius: int = 1, *, chunks=None, band: int = 0
    ) -> np.ndarray | da.Array:
        """Thin forwarder to :func:`pyramids.dataset.ops._focal.focal_apply`."""
        return focal_apply(self, func, radius=radius, chunks=chunks, band=band)

    def slope(
        self, *, chunks=None, band: int = 0, units: str = "degrees"
    ) -> np.ndarray | da.Array:
        """Thin forwarder to :func:`pyramids.dataset.ops._focal.slope`."""
        return slope(self, chunks=chunks, band=band, units=units)

    def aspect(self, *, chunks=None, band: int = 0) -> np.ndarray | da.Array:
        """Thin forwarder to :func:`pyramids.dataset.ops._focal.aspect`."""
        return aspect(self, chunks=chunks, band=band)

    def hillshade(
        self,
        *,
        azimuth: float = 315.0,
        altitude: float = 45.0,
        chunks=None,
        band: int = 0,
    ) -> np.ndarray | da.Array:
        """Thin forwarder to :func:`pyramids.dataset.ops._focal.hillshade`."""
        return hillshade(
            self,
            azimuth=azimuth,
            altitude=altitude,
            chunks=chunks,
            band=band,
        )

    def get_cell_coords(self, *args, **kwargs):
        """Facade — delegates to :meth:`Cell.get_cell_coords <pyramids.dataset.engines.Cell.get_cell_coords>`."""
        return self.cell.get_cell_coords(*args, **kwargs)

    def cell_area(self, *args, **kwargs):
        """Facade — delegates to :meth:`Cell.cell_area <pyramids.dataset.engines.Cell.cell_area>`."""
        return self.cell.cell_area(*args, **kwargs)

    def map_to_array_coordinates(self, *args, **kwargs):
        """Facade — delegates to :meth:`Cell.map_to_array_coordinates <pyramids.dataset.engines.Cell.map_to_array_coordinates>`."""
        return self.cell.map_to_array_coordinates(*args, **kwargs)

    def array_to_map_coordinates(self, *args, **kwargs):
        """Facade — delegates to :meth:`Cell.array_to_map_coordinates <pyramids.dataset.engines.Cell.array_to_map_coordinates>`."""
        return self.cell.array_to_map_coordinates(*args, **kwargs)

    def to_cog(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.to_cog <pyramids.dataset.engines.COG.to_cog>`."""
        return self.cog.to_cog(*args, **kwargs)

    @property
    def is_cog(self) -> bool:
        """Facade — delegates to :attr:`COG.is_cog <pyramids.dataset.engines.COG.is_cog>`."""
        return self.cog.is_cog

    def validate_cog(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.validate_cog <pyramids.dataset.engines.COG.validate_cog>`."""
        return self.cog.validate_cog(*args, **kwargs)

    def cog_info(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.info <pyramids.dataset.engines.COG.info>`."""
        return self.cog.info(*args, **kwargs)

    def to_cog_bytes(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.to_cog_bytes <pyramids.dataset.engines.COG.to_cog_bytes>`."""
        return self.cog.to_cog_bytes(*args, **kwargs)

    def read_part(
        self, *args, **kwargs
    ) -> (
        np.typing.NDArray
        | tuple[np.typing.NDArray, tuple[float, float, float, float, float, float]]
    ):
        """Facade — delegates to :meth:`COG.read_part <pyramids.dataset.engines.COG.read_part>`.

        Typed with the engine's union return -- a bare array, or an
        `(array, geotransform)` tuple when `return_transform=True` -- so the
        public entry point stays type-safe instead of erasing to `Any` through
        the `*args, **kwargs` passthrough. The per-flag narrowing lives on
        `COG.read_part`; duplicating its `@overload` stubs here bought the facade
        nothing over this union and only tripped the duplication gate.
        """
        # `*args`/`**kwargs` are `Any`, so the overloaded engine call resolves to
        # `Any`; cast back to the declared union to keep the facade type-safe.
        return cast(
            "np.typing.NDArray"
            " | tuple[np.typing.NDArray, tuple[float, float, float, float, float, float]]",
            self.cog.read_part(*args, **kwargs),
        )

    def preview(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.preview <pyramids.dataset.engines.COG.preview>`."""
        return self.cog.preview(*args, **kwargs)

    def point(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.point <pyramids.dataset.engines.COG.point>`."""
        return self.cog.point(*args, **kwargs)

    def read_tile(self, *args, **kwargs):
        """Facade — delegates to :meth:`COG.read_tile <pyramids.dataset.engines.COG.read_tile>`."""
        return self.cog.read_tile(*args, **kwargs)

    def to_geodataframe(self, *args, **kwargs):
        """Facade — delegates to :meth:`Vectorize.to_geodataframe <pyramids.dataset.engines.Vectorize.to_geodataframe>`."""
        return self.vectorize.to_geodataframe(*args, **kwargs)

    def contour(self, *args, **kwargs):
        """Facade — delegates to :meth:`Vectorize.contour <pyramids.dataset.engines.Vectorize.contour>`."""
        return self.vectorize.contour(*args, **kwargs)

    def translate(self, *args, **kwargs):
        """Facade — delegates to :meth:`Vectorize.translate <pyramids.dataset.engines.Vectorize.translate>`."""
        return self.vectorize.translate(*args, **kwargs)

    def cluster(self, *args, **kwargs):
        """Facade — delegates to :meth:`Vectorize.cluster <pyramids.dataset.engines.Vectorize.cluster>`."""
        return self.vectorize.cluster(*args, **kwargs)

    def to_polygons(self, *args, **kwargs):
        """Facade — delegates to :meth:`Vectorize.to_polygons <pyramids.dataset.engines.Vectorize.to_polygons>`."""
        return self.vectorize.to_polygons(*args, **kwargs)

    def cluster2(self, *args, **kwargs):
        """Deprecated alias for :meth:`to_polygons` — delegates to
        :meth:`Vectorize.cluster2 <pyramids.dataset.engines.Vectorize.cluster2>`."""
        return self.vectorize.cluster2(*args, **kwargs)

    def stats(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.stats <pyramids.dataset.engines.Analysis.stats>`."""
        return self.analysis.stats(*args, **kwargs)

    def domain_area(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.domain_area <pyramids.dataset.engines.Analysis.domain_area>`."""
        return self.analysis.domain_area(*args, **kwargs)

    def count_domain_cells(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.count_domain_cells <pyramids.dataset.engines.Analysis.count_domain_cells>`."""
        return self.analysis.count_domain_cells(*args, **kwargs)

    def apply(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.apply <pyramids.dataset.engines.Analysis.apply>`.

        The collaborator returns `None` for `inplace=True` so the facade
        can substitute the actual `self` (preserving identity); the proxy
        used by the collaborator's back-reference would otherwise fail
        `result is ds` checks.
        """
        result = self.analysis.apply(*args, **kwargs)
        return self if result is None else result

    def combine(
        self,
        other: Dataset,
        func: Callable[[np.ndarray, np.ndarray], np.ndarray],
        *,
        band: int | None = None,
        no_data_value: Any = _DERIVE_NO_DATA,
    ) -> Dataset:
        """Facade — delegates to :meth:`Analysis.combine <pyramids.dataset.engines.Analysis.combine>`.

        Spelled out rather than `*args, **kwargs` like its neighbours: `combine`
        has keyword-only options and a `no_data_value` default that is neither
        `None` nor a value, so a bare forwarding signature tells an IDE or mypy
        user nothing — and a typo like `no_data=` would reach the engine as an
        unexpected keyword instead of being caught here.

        Args:
            other: The second operand, on this dataset's grid.
            func: Binary callable applied to the operands' matching cells.
            band: Zero-based band to combine, or `None` for every band.
            no_data_value: Sentinel for the result, as documented on the engine
                method. Left unset it is derived from the computed values.

        Returns:
            Dataset: The combined raster, on this dataset's grid.
        """
        return self.analysis.combine(
            other, func, band=band, no_data_value=no_data_value
        )

    def fill(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.fill <pyramids.dataset.engines.Analysis.fill>`.

        The collaborator returns `None` for `inplace=True`; see
        :meth:`apply` for the rationale.
        """
        result = self.analysis.fill(*args, **kwargs)
        return self if result is None else result

    def where(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.where <pyramids.dataset.engines.Analysis.where>`.

        Keeps the cells a condition selects and masks the rest — the inverse of
        :meth:`fill`, which writes to the cells that are data rather than deciding which
        ones stay data.
        """
        return self.analysis.where(*args, **kwargs)

    def fillna(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.fillna <pyramids.dataset.engines.Analysis.fillna>`.

        Writes to the **gaps**, where :meth:`fill` writes to the cells that already hold
        data. One letter apart, opposite effects.
        """
        return self.analysis.fillna(*args, **kwargs)

    def isnull(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.isnull <pyramids.dataset.engines.Analysis.isnull>`."""
        return self.analysis.isnull(*args, **kwargs)

    def equals(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.equals <pyramids.dataset.engines.Analysis.equals>`.

        Value equality, which :meth:`same_grid` does not provide: that says two rasters
        *could* be combined, this says they agree.
        """
        return self.analysis.equals(*args, **kwargs)

    def identical(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.identical <pyramids.dataset.engines.Analysis.identical>`.

        :meth:`equals` with the attributes read too.
        """
        return self.analysis.identical(*args, **kwargs)

    def clip(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.clip <pyramids.dataset.engines.Analysis.clip>`."""
        return self.analysis.clip(*args, **kwargs)

    def round(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.round <pyramids.dataset.engines.Analysis.round>`."""
        return self.analysis.round(*args, **kwargs)

    def astype(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.astype <pyramids.dataset.engines.Analysis.astype>`."""
        return self.analysis.astype(*args, **kwargs)

    def isin(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.isin <pyramids.dataset.engines.Analysis.isin>`."""
        return self.analysis.isin(*args, **kwargs)

    def notnull(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.notnull <pyramids.dataset.engines.Analysis.notnull>`."""
        return self.analysis.notnull(*args, **kwargs)

    def extract(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.extract <pyramids.dataset.engines.Analysis.extract>`."""
        return self.analysis.extract(*args, **kwargs)

    def sample(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.sample <pyramids.dataset.engines.Analysis.sample>`."""
        return self.analysis.sample(*args, **kwargs)

    def transect(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.transect <pyramids.dataset.engines.Analysis.transect>`."""
        return self.analysis.transect(*args, **kwargs)

    def sieve(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.sieve <pyramids.dataset.engines.Analysis.sieve>`."""
        return self.analysis.sieve(*args, **kwargs)

    def proximity(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.proximity <pyramids.dataset.engines.Analysis.proximity>`."""
        return self.analysis.proximity(*args, **kwargs)

    def pan_sharpen(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.pan_sharpen <pyramids.dataset.engines.Analysis.pan_sharpen>`."""
        return self.analysis.pan_sharpen(*args, **kwargs)

    def match_histogram(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.match_histogram <pyramids.dataset.engines.Analysis.match_histogram>`."""
        return self.analysis.match_histogram(*args, **kwargs)

    def percentile_stretch(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.percentile_stretch <pyramids.dataset.engines.Analysis.percentile_stretch>`."""
        return self.analysis.percentile_stretch(*args, **kwargs)

    def overlay(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.overlay <pyramids.dataset.engines.Analysis.overlay>`."""
        return self.analysis.overlay(*args, **kwargs)

    def get_mask(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.get_mask <pyramids.dataset.engines.Analysis.get_mask>`."""
        return self.analysis.get_mask(*args, **kwargs)

    def mask_flags(self, *args, **kwargs):
        """Facade — :meth:`Analysis.mask_flags <pyramids.dataset.engines.Analysis.mask_flags>`."""
        return self.analysis.mask_flags(*args, **kwargs)

    def read_masks(self, *args, **kwargs):
        """Facade — :meth:`Analysis.read_masks <pyramids.dataset.engines.Analysis.read_masks>`."""
        return self.analysis.read_masks(*args, **kwargs)

    def create_mask_band(self, *args, **kwargs):
        """Facade — :meth:`Analysis.create_mask_band <pyramids.dataset.engines.Analysis.create_mask_band>`."""
        return self.analysis.create_mask_band(*args, **kwargs)

    def footprint(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.footprint <pyramids.dataset.engines.Analysis.footprint>`."""
        return self.analysis.footprint(*args, **kwargs)

    def get_histogram(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.get_histogram <pyramids.dataset.engines.Analysis.get_histogram>`."""
        return self.analysis.get_histogram(*args, **kwargs)

    def plot_histogram(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.plot_histogram <pyramids.dataset.engines.Analysis.plot_histogram>`."""
        return self.analysis.plot_histogram(*args, **kwargs)

    def to_image(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.to_image <pyramids.dataset.engines.Analysis.to_image>`."""
        return self.analysis.to_image(*args, **kwargs)

    def plot_vector_field(self, *args, **kwargs):
        """Facade — delegates to :meth:`Analysis.plot_vector_field <pyramids.dataset.engines.Analysis.plot_vector_field>`."""
        return self.analysis.plot_vector_field(*args, **kwargs)

    def _resolve_plot_band(
        self, band: int | None, rgb: list[int] | None
    ) -> tuple[int, list[int] | None]:
        """Resolve which band index (and effective ``rgb`` list) to render for :meth:`plot`.

        Applies the GeoTIFF / Sentinel-imagery band-resolution policy that used to live
        inside :meth:`Analysis.plot`. The rules, in order, are:

        1. If ``band`` is explicitly provided, it is returned as-is (and ``rgb`` passes
           through untouched).
        2. If the dataset has fewer than 3 bands, return ``(0, rgb)``.
        3. If the dataset has 3+ bands but **no** band is tagged as an RGB channel
           (``red``/``green``/``blue``), return ``(0, rgb)``. This is the D-1 fix:
           ``band_count >= 3`` alone is not a sufficient signal that the data is an RGB
           image — multi-band scalar cubes (e.g. time series stacked into one GeoTIFF)
           also have ``band_count >= 3`` and must not be misinterpreted as RGB. Only the
           three RGB-channel interpretations count; ``palette_index``, ``gray_index`` and
           the other single-channel tags are rendered as single bands, not RGB (see #910).
        4. Otherwise, treat the dataset as RGB imagery. If ``rgb`` was supplied, its
           first entry is the red band. If it was not supplied, resolve red/green/blue
           via :meth:`get_band_by_color`; fall back to ``[2, 1, 0]`` (the default
           Sentinel-2 band order) only when one or more colour channels can't be
           identified.

        Args:
            band: User-supplied band index, or ``None`` to trigger the heuristic.
            rgb: User-supplied ``[r, g, b]`` band index list, or ``None``.

        Returns:
            tuple[int, list[int] | None]: The resolved single-band index and the
                effective ``rgb`` list to forward to :meth:`Analysis.plot`. The ``rgb``
                element is ``None`` when no RGB rendering should happen.

        Examples:
            - Explicit ``band`` is always returned untouched (rule 1):

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> arr = np.random.rand(4, 8, 8).astype(np.float32)
              >>> ds = Dataset.from_array(
              ...     arr,
              ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
              ... )
              >>> ds._resolve_plot_band(band=2, rgb=None)
              (2, None)

              ```

            - Single-band raster falls back to band ``0`` (rule 2):

              ```python
              >>> single = np.random.rand(6, 6).astype(np.float32)
              >>> ds_1band = Dataset.from_array(
              ...     single,
              ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
              ... )
              >>> ds_1band._resolve_plot_band(band=None, rgb=None)
              (0, None)

              ```

            - Multi-band dataset with no ``ColorInterpretation`` defaults to band ``0``
              (rule 3, the D-1 fix). ``Dataset.from_array`` produces a multi-band
              MEM raster whose bands all report ``undefined`` colour interpretation —
              asserted explicitly here so this doctest fails loudly if that ever changes:

              ```python
              >>> list(ds.band_color.values())
              ['undefined', 'undefined', 'undefined', 'undefined']
              >>> ds._resolve_plot_band(band=None, rgb=None)
              (0, None)

              ```

            - Explicit ``rgb`` passes through alongside an explicit ``band``:

              ```python
              >>> ds._resolve_plot_band(band=1, rgb=[2, 1, 0])
              (1, [2, 1, 0])

              ```

            - A ``palette_index`` band is not an RGB channel, so it does not trigger
              the RGB branch — the raster resolves to the paletted band so its GDAL
              colour table renders (#913; band ``0`` here). A fresh dataset is built
              here so the example is independent of the tags set above:

              ```python
              >>> paletted = np.random.rand(3, 8, 8).astype(np.float32)
              >>> ds_pal = Dataset.from_array(
              ...     paletted,
              ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
              ... )
              >>> ds_pal.band_color = {0: 'palette_index'}
              >>> ds_pal._resolve_plot_band(band=None, rgb=None)
              (0, None)

              ```
        """
        if band is not None:
            # Coerce to a plain ``int`` here too (the RGB branch already
            # does) so the return type matches the ``tuple[int, ...]``
            # docstring even when the caller passed e.g. a ``numpy.int64``.
            resolved_band = int(band)
            resolved_rgb = rgb
        elif self.band_count < 3:
            resolved_band = 0
            resolved_rgb = rgb
        else:
            resolved_band, resolved_rgb = self._resolve_multiband_plot(rgb)
        return resolved_band, resolved_rgb

    def _resolve_multiband_plot(
        self, rgb: list[int] | None
    ) -> tuple[int, list[int] | None]:
        """Resolve ``(band, rgb)`` for a raster with ``band_count >= 3``.

        Only a true RGB channel (``red``/``green``/``blue``) marks the raster as
        RGB imagery; ``undefined``, ``palette_index``, ``gray_index`` and the
        other single-channel/paletted interpretations do not -- otherwise a
        multi-band raster carrying any of them is mis-resolved as a false-colour
        RGB composite (see #910). A non-RGB raster renders a single band:
        ``rgb[0]`` when an explicit ``rgb`` is supplied, else the first
        ``palette_index`` band so its GDAL colour table renders (#913), else
        band 0. The downstream ``exclude_value`` nodata mask keys off the same
        band the render uses.
        """
        band_colors = list(self.band_color.values())
        has_rgb_interp = any(c in RGB_CHANNEL_INTERPS for c in band_colors)
        if not has_rgb_interp:
            resolved_rgb = rgb
            if rgb is not None:
                resolved_band = int(rgb[0])
            else:
                # Prefer a paletted band so its colour table renders (#913),
                # otherwise fall back to band 0.
                palette_bands = [
                    i for i, c in enumerate(band_colors) if c == "palette_index"
                ]
                resolved_band = palette_bands[0] if palette_bands else 0
        else:
            resolved_rgb = rgb if rgb is not None else self._infer_rgb_band_order()
            resolved_band = int(resolved_rgb[0])
        return resolved_band, resolved_rgb

    def _infer_rgb_band_order(self) -> list[int]:
        """Infer the ``[r, g, b]`` band-index order from the bands' colour tags.

        Resolves red/green/blue via :meth:`get_band_by_color`; falls back to the
        Sentinel-2 default ``[2, 1, 0]`` (emitting a :class:`DeprecationWarning`)
        when any channel cannot be identified from the tags.
        """
        candidate: list[int | None] = [
            self.get_band_by_color("red"),
            self.get_band_by_color("green"),
            self.get_band_by_color("blue"),
        ]
        if None in candidate:
            warnings.warn(
                "The implicit Sentinel-2 RGB band order [2, 1, 0] used "
                "when colour-interpretation is absent is deprecated and "
                "will be removed: it is a remote-sensing sensor "
                "assumption, not a generic raster default. Pass an "
                "explicit rgb=[...] (e.g. via rgb_options) instead.",
                DeprecationWarning,
                stacklevel=5,
            )
            resolved_rgb = [2, 1, 0]
        else:
            # None NOT in candidate here, so every element is a
            # plain int -- mypy does not narrow list contents from
            # an `in` check.
            resolved_rgb = [int(v) for v in cast("list[int]", candidate)]
        return resolved_rgb

    # The override is deliberate: it narrows the base's open **kwargs to cleopatra's
    # typed PlotKwargs. The fig/ax pair itself matches the RasterBase contract.
    def plot(  # type: ignore[override]
        self,
        band: int | None = None,
        exclude_value: Any | None = None,
        overview: bool | None = False,
        overview_index: int | None = 0,
        basemap: bool | str | dict[str, Any] | Basemap | None = None,
        colorbar: bool | ColorBar | None = None,
        points: np.ndarray | PointOverlay | None = None,
        kind: str = "auto",
        title: str | None = None,
        color: ColorScaling | None = None,
        contour: Contour | None = None,
        cells: CellValues | None = None,
        data_style: DataStyle | None = None,
        rgb_options: dict | None = None,
        *,
        fig: Figure | None = None,
        ax: Axes | None = None,
        **kwargs: Unpack[PlotKwargs],
    ):
        """Plot the values/overviews of a band.

        Facade for :meth:`Analysis.plot <pyramids.dataset.engines.Analysis.plot>`. Resolves
        the band index via :meth:`_resolve_plot_band` (GeoTIFF/Sentinel semantics) and then
        forwards the call to the generic rendering engine.

        When ``band`` is ``None`` and the dataset looks like an RGB image — i.e. it has
        at least 3 bands **and** at least one band is tagged as an RGB channel
        (``red``/``green``/``blue``) — the red band is auto-selected (either from
        ``rgb[0]`` or by resolving the colour tags). A ``palette_index``, ``gray_index``
        or other non-RGB interpretation does **not** count as RGB imagery. Otherwise the
        facade defaults to band ``0``. See :meth:`Analysis.plot` for the full kwargs
        surface.

        The four satellite-imagery options (``rgb``, ``surface_reflectance``, ``cutoff``,
        ``percentile``) are passed through the single ``rgb_options=`` dict.

        Args:
            band (int, optional):
                Band index to render. When ``None``, the index is resolved by
                :meth:`_resolve_plot_band`.
            exclude_value (Any, optional):
                Pixel value to mask out before plotting. Default is ``None``.
            overview (bool, optional):
                If ``True``, plot the overview pyramid level instead of the full-resolution
                array. Default is ``False``.
            overview_index (int, optional):
                Index of the overview level to plot when ``overview=True``. Default is ``0``.
            basemap (bool, str, or Basemap, optional):
                Reference layer, dispatched by type. ``True`` or a tile-provider string
                (e.g. ``"CartoDB.Positron"``) overlays a pyramids web-tile basemap. A
                ``pyramids.plot.Basemap(relief=..., features=...)``
                draws a shaded-relief / coastline layer instead. Passing a ``dict`` here is
                a deprecated alias for ``Basemap`` (emits a ``DeprecationWarning``). Default
                is ``None``. Requires the ``[viz]`` extra.
            colorbar (bool or ColorBar, optional):
                Colour-bar spec. A ``pyramids.plot.ColorBar(label=…, length=…,
                orientation=…, …)`` draws a configured bar. The loose ``cbar_*`` /
                ``ticks_spacing`` kwargs it replaces were removed — passing one now raises a
                :class:`ValueError` pointing here. ``False`` hides the bar, ``None`` uses
                cleopatra's default. Default is ``None``.
            points (np.ndarray or PointOverlay, optional):
                Point overlay. A 3-column array ``(value, row, col)`` draws unstyled
                points; pass a ``pyramids.plot.PointOverlay(points, color=…, size=…, …)``
                to style them. Default is ``None``.
            kind (str, optional):
                Renderer to use. ``"auto"`` (default) picks per data; otherwise one of
                ``"imshow"`` / ``"pcolormesh"`` / ``"contour"`` / ``"contourf"``.
            title (str, optional):
                Axes title. Default is ``None`` (cleopatra's default title).
            color (ColorScaling, optional):
                Colour-scale spec ``pyramids.plot.ColorScaling`` (linear / power / sym-log /
                boundary / midpoint norm), e.g. ``ColorScaling.power(gamma=0.7)`` or
                ``ColorScaling.boundary(bounds=[0, 0.5, 1])``. Default ``None``.
            contour (Contour, optional):
                Contour-line spec ``pyramids.plot.Contour(levels=…, labels=…, label_kw=…)``.
                Default ``None``.
            cells (CellValues, optional):
                Per-cell value annotation ``pyramids.plot.CellValues(show=…, size=…,
                background_threshold=…)``. Default ``None``.
            data_style (DataStyle, optional):
                Data-style / relief spec ``pyramids.plot.DataStyle(style=…, hillshade=…)``.
                Default ``None``.
            rgb_options (dict, optional):
                Grouped Sentinel-imagery options for a true-colour composite. Accepted
                keys: ``"rgb"`` (3- or 4-element band-index list ``[r, g, b(, a)]``, only
                honoured when the dataset has >= 3 bands and a colour interpretation),
                ``"surface_reflectance"`` (reflectance scale factor, e.g. ``10000`` for
                Sentinel-2), ``"cutoff"`` (per-band clip values), ``"percentile"``
                (percentile stretch). Default is ``None``.
            fig (matplotlib.figure.Figure, optional):
                Draw into this figure instead of creating one. Pass it alongside ``ax``;
                supplying ``fig`` on its own currently raises inside cleopatra
                (serapeum-org/cleopatra#326). Default is ``None``.
            ax (matplotlib.axes.Axes, optional):
                Draw into these axes instead of creating them. This is what lets several
                rasters share one figure — a ``plt.subplots`` grid of side-by-side panels —
                while every panel keeps the georeferenced extent and nodata masking that
                ``plot`` applies. An axes already carries its figure, so ``ax`` on its own
                is sufficient. A shared colour range across panels is then applied through
                the returned glyph, whose colour bar tracks its mappable
                (``glyph.cbar.mappable is glyph.im``), e.g. ``glyph.im.set_clim(0, vmax)``.
                Default is ``None``.

                ```python
                >>> import matplotlib.pyplot as plt  # doctest: +SKIP
                >>> fig, axes = plt.subplots(1, 3)  # doctest: +SKIP
                >>> panels = [ds.plot(fig=fig, ax=a) for a in axes]  # doctest: +SKIP

                ```
            **kwargs:
                Additional keyword arguments forwarded verbatim to
                :meth:`Analysis.plot`. See that method for the full kwargs surface
                (figure size, color scale, color bar, basemap, etc.). Notably
                ``add_colorbar`` (``bool``, default ``True``) is a cleopatra
                pass-through: set ``add_colorbar=False`` to suppress the
                auto-generated colorbar (the returned glyph's ``cbar`` is then
                ``None``).

        Returns:
            ArrayGlyph: A cleopatra ``ArrayGlyph`` wrapping the rendered figure.
                Use it to drop down to raw matplotlib:

                - ``glyph.fig`` / ``glyph.ax`` — the :class:`matplotlib.figure.Figure`
                  and :class:`matplotlib.axes.Axes`.
                - ``glyph.im`` — the colour-mapped mappable (populated for every
                  ``kind=``: imshow/pcolormesh/contour/contourf). Use it to tweak
                  colour limits after the fact, e.g. ``glyph.im.set_clim(0, 100)``.
                - ``glyph.cbar`` — the auto-created :class:`matplotlib.colorbar.Colorbar`,
                  or ``None`` when ``add_colorbar=False`` (or for RGB renders).

                ```python
                >>> glyph = dataset.plot(band=0, kind="pcolormesh")  # doctest: +SKIP
                >>> glyph.im.set_clim(0, 100)  # doctest: +SKIP
                >>> _ = glyph.cbar.set_label("elevation [m]")  # doctest: +SKIP

                ```

        Examples:
            - Render the first band of a single-band MEM raster. Tagged ``+SKIP`` because
              the call requires the optional ``[viz]`` extra (cleopatra + matplotlib):

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> arr = np.random.rand(8, 8).astype(np.float32)
              >>> ds = Dataset.from_array(
              ...     arr,
              ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
              ... )
              >>> cleo = ds.plot()  # doctest: +SKIP
              >>> cleo.fig          # doctest: +SKIP
              <Figure size 800x800 with 2 Axes>

              ```

            - Override the resolved band index. The facade forwards ``band=1`` straight
              to the engine without consulting the heuristic:

              ```python
              >>> cleo = ds.plot(band=1)  # doctest: +SKIP

              ```

            - Render a multi-band raster as a true-colour composite via the
              recommended ``rgb_options=`` group:

              ```python
              >>> arr3 = np.random.rand(3, 8, 8).astype(np.float32)
              >>> rgb_ds = Dataset.from_array(
              ...     arr3,
              ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
              ... )
              >>> cleo = rgb_ds.plot(  # doctest: +SKIP
              ...     rgb_options={"rgb": [0, 1, 2], "surface_reflectance": 255},
              ... )

              ```
        """
        rgb, surface_reflectance, cutoff, percentile = self._unpack_rgb_options(
            rgb_options
        )
        resolved_band, resolved_rgb = self._resolve_plot_band(band, rgb)
        # Spread the explicitly-set cleopatra render groups as their own ``**`` (not merged
        # into the typed ``**kwargs``, whose PlotKwargs TypedDict has no group keys); the
        # unset ones are dropped so they do not override cleopatra's backend default for
        # that group.
        group_kwargs = nonnull_group_kwargs(
            color=color, contour=contour, cells=cells, data_style=data_style
        )
        return self.analysis.plot(
            band=resolved_band,
            exclude_value=exclude_value,
            rgb=resolved_rgb,
            surface_reflectance=surface_reflectance,
            cutoff=cutoff,
            overview=overview,
            overview_index=overview_index,
            percentile=percentile,
            basemap=basemap,
            colorbar=colorbar,
            points=points,
            kind=kind,
            title=title,
            fig=fig,
            ax=ax,
            **group_kwargs,
            **kwargs,
        )

    @staticmethod
    def _unpack_rgb_options(
        rgb_options: dict | None,
    ) -> tuple[list[int] | None, int | None, list | None, int | None]:
        """Unpack the ``rgb_options`` group into the four Sentinel-imagery values.

        Args:
            rgb_options: Grouped Sentinel-imagery options, or ``None``. Accepted keys:
                ``"rgb"``, ``"surface_reflectance"``, ``"cutoff"``, ``"percentile"``.

        Returns:
            tuple: ``(rgb, surface_reflectance, cutoff, percentile)`` — each the value from
                ``rgb_options`` or ``None`` when absent.

        Raises:
            ValueError: If ``rgb_options`` contains a key outside the accepted set.

        Examples:
            - Unpack the grouped form (``None`` yields an all-``None`` tuple):

                ```python
                >>> from pyramids.dataset import Dataset
                >>> Dataset._unpack_rgb_options(
                ...     {"rgb": [2, 1, 0], "surface_reflectance": 10000}
                ... )
                ([2, 1, 0], 10000, None, None)
                >>> Dataset._unpack_rgb_options(None)
                (None, None, None, None)

                ```

            - An unknown key raises :class:`ValueError`:

                ```python
                >>> Dataset._unpack_rgb_options(  # doctest: +IGNORE_EXCEPTION_DETAIL
                ...     {"unknown": 1}
                ... )
                Traceback (most recent call last):
                    ...
                ValueError: Unknown keys in `rgb_options`: ['unknown']...

                ```
        """
        accepted = ("rgb", "surface_reflectance", "cutoff", "percentile")
        opts = rgb_options or {}
        unknown = set(opts) - set(accepted)
        if unknown:
            raise ValueError(
                f"Unknown keys in `rgb_options`: {sorted(unknown)}. "
                f"Accepted: {sorted(accepted)}."
            )
        return (
            opts.get("rgb"),
            opts.get("surface_reflectance"),
            opts.get("cutoff"),
            opts.get("percentile"),
        )

    def _spend_packing(self) -> None:
        """Forget the packing once a compute has replaced the values with physical ones.

        Called after an in-place compute (`apply(inplace=True)`, `fill(inplace=True)`),
        once `_update_inplace` has swapped the computed raster in. That raster holds
        physical values and declares no packing on its bands, so for a plain `Dataset`
        there is nothing left to forget and this does nothing. `NetCDF` overrides it,
        because a variable also carries the recipe in Python -- which `_update_inplace`
        preserves -- and `_effective_packing` would otherwise apply it to the
        already-physical values on the next read.
        """

    def _effective_packing(self, band: int = 0) -> tuple[Any, Any]:
        """The `(scale, offset)` a read of `band` applies, as this class resolves it.

        The resolver every path that applies packing shares -- `read_array` and the reads
        built on it (`point`, `read_part`, `preview`, `get_tile`, the overview reads),
        `stats`, `get_histogram`, `plot_histogram`, the domain reads behind `apply` and
        `combine`, `stream_transform`, `map_blocks`, `zonal_stats`, the sentinel
        conversion in `Analysis._physical_no_data`, and the writers that carry or spend
        the recipe (`to_zarr`, `DatasetCollection.to_netcdf`, `NetCDF.set_variable`) --
        so they cannot resolve it differently and report the same band in different
        units. For a plain raster the band's own `GetScale` / `GetOffset` are the whole
        story; `NetCDF` overrides this because a variable can also carry the pair in
        Python, and the two can disagree. The public `scale` / `offset` properties are
        not this: they report the band's slots, normalised.

        Args:
            band: Zero-based band index. Defaults to `0`.

        Returns:
            tuple: `(scale, offset)` as GDAL answers them. Either may be `None` for
                "unset" -- unlike the normalising `scale` / `offset` properties, which
                report `1.0` / `0` -- and both are `None` when no raster is open.

        Examples:
            - An unpacked band answers `None` for both slots, where `scale` says `1.0`:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.array([[100, 200]], dtype="int16"),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ... )
                >>> ds._effective_packing(0), ds.scale
                ((None, None), [1.0])

                ```
            - A packed band answers the pair the default read applies:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.array([[100, 200]], dtype="int16"),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ... )
                >>> ds.scale = [0.01]
                >>> ds.offset = [1.5]
                >>> ds._effective_packing(0)
                (0.01, 1.5)
                >>> ds.read_array().tolist()
                [[2.5, 3.5]]

                ```
        """
        raster = self._raster
        if raster is None:
            return None, None
        gdal_band = raster.GetRasterBand(band + 1)
        return gdal_band.GetScale(), gdal_band.GetOffset()

    def crop(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.crop <pyramids.dataset.engines.Spatial.crop>`."""
        return self.spatial.crop(*args, **kwargs)

    def to_crs(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.to_crs <pyramids.dataset.engines.Spatial.to_crs>`."""
        return self.spatial.to_crs(*args, **kwargs)

    def set_gcps(self, *args, **kwargs):
        """Facade — delegates to :meth:`Georef.set_gcps <pyramids.dataset.engines.Georef.set_gcps>`."""
        return self.georef.set_gcps(*args, **kwargs)

    def georeference(self, *args, **kwargs):
        """Facade — :meth:`Georef.georeference <pyramids.dataset.engines.Georef.georeference>`."""
        return self.georef.georeference(*args, **kwargs)

    @property
    def gcps(self):
        """Facade — :attr:`Georef.gcps <pyramids.dataset.engines.Georef.gcps>`."""
        return self.georef.gcps

    @property
    def gcp_count(self):
        """Facade — :attr:`Georef.gcp_count <pyramids.dataset.engines.Georef.gcp_count>`."""
        return self.georef.gcp_count

    @property
    def gcp_projection(self):
        """Facade — :attr:`Georef.gcp_projection <pyramids.dataset.engines.Georef.gcp_projection>`."""
        return self.georef.gcp_projection

    @property
    def has_gcps(self):
        """Facade — :attr:`Georef.has_gcps <pyramids.dataset.engines.Georef.has_gcps>`."""
        return self.georef.has_gcps

    @property
    def rpcs(self):
        """Facade — :attr:`Georef.rpcs <pyramids.dataset.engines.Georef.rpcs>`."""
        return self.georef.rpcs

    @property
    def has_rpcs(self):
        """Facade — :attr:`Georef.has_rpcs <pyramids.dataset.engines.Georef.has_rpcs>`."""
        return self.georef.has_rpcs

    def set_rpcs(self, *args, **kwargs):
        """Facade — :meth:`Georef.set_rpcs <pyramids.dataset.engines.Georef.set_rpcs>`."""
        return self.georef.set_rpcs(*args, **kwargs)

    def orthorectify(self, *args, **kwargs):
        """Facade — :meth:`Georef.orthorectify <pyramids.dataset.engines.Georef.orthorectify>`."""
        return self.georef.orthorectify(*args, **kwargs)

    @property
    def geolocation(self):
        """Facade — :attr:`Georef.geolocation <pyramids.dataset.engines.Georef.geolocation>`."""
        return self.georef.geolocation

    @property
    def has_geolocation(self):
        """Facade — :attr:`Georef.has_geolocation <pyramids.dataset.engines.Georef.has_geolocation>`."""
        return self.georef.has_geolocation

    def geolocate(self, *args, **kwargs):
        """Facade — :meth:`Georef.geolocate <pyramids.dataset.engines.Georef.geolocate>`."""
        return self.georef.geolocate(*args, **kwargs)

    def _geolocation_source(self) -> Dataset:
        """The Dataset whose GDAL handle carries the ``GEOLOCATION`` domain.

        A base raster carries its geolocation arrays on its own handle, so the
        default is ``self``. ``NetCDF`` overrides this to reopen the classic GDAL
        handle, on which the domain is exposed (the multidimensional view drops it).
        """
        return self

    def warped_view(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.warped_view <pyramids.dataset.engines.Spatial.warped_view>`."""
        return self.spatial.warped_view(*args, **kwargs)

    def set_crs(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.set_crs <pyramids.dataset.engines.Spatial.set_crs>`."""
        return self.spatial.set_crs(*args, **kwargs)

    def wrap_longitude(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.wrap_longitude <pyramids.dataset.engines.Spatial.wrap_longitude>`."""
        return self.spatial.wrap_longitude(*args, **kwargs)

    def resample(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.resample <pyramids.dataset.engines.Spatial.resample>`."""
        return self.spatial.resample(*args, **kwargs)

    def align(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.align <pyramids.dataset.engines.Spatial.align>`."""
        return self.spatial.align(*args, **kwargs)

    def same_grid(self, other: Dataset, *, compare_crs: bool = True) -> bool:
        """Facade — delegates to :meth:`Spatial.same_grid <pyramids.dataset.engines.Spatial.same_grid>`.

        Spelled out for the same reason as :meth:`combine`, whose contract it
        states: the keyword-only `compare_crs` is invisible in a bare forwarding
        signature.

        Args:
            other: Dataset to compare against this one.
            compare_crs: Whether the CRSes must agree too. Default `True`.

        Returns:
            bool: `True` iff both rasters occupy the same pixel grid.
        """
        return self.spatial.same_grid(other, compare_crs=compare_crs)

    def fill_gaps(self, *args, **kwargs):
        """Facade — delegates to :meth:`Spatial.fill_gaps <pyramids.dataset.engines.Spatial.fill_gaps>`."""
        return self.spatial.fill_gaps(*args, **kwargs)

    def read_array(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.read_array <pyramids.dataset.engines.IO.read_array>`."""
        return self.io.read_array(*args, **kwargs)

    @property
    def _copy_source(self) -> gdal.Dataset:
        """The backing raster, made window-readable first, for a `CreateCopy`.

        `CreateCopy` reads the source block by block, so it hits the same
        partial-window restriction every other eager read does: a NetCDF
        variable subset backed by a reversed multidimensional view raises
        `arrayStartIdx[...] + (count-1)*arrayStep >= <dim>` part-way through
        the copy. Reading through this property instead of `self._raster`
        materialises the view first, exactly as the windowed read paths do.

        Note that materialisation mutates this dataset in place -- that is what
        :meth:`_materialize_md_view` has always done -- so the caller's own
        raster is the materialised one afterwards.

        Returns:
            gdal.Dataset: The backing raster, safe to hand to `CreateCopy`.
        """
        self._materialize_md_view()
        return self._raster

    def _materialize_md_view(self) -> None:
        """Make the backing raster window-readable. No-op for an ordinary raster.

        Hook overridden by :class:`pyramids.netcdf.NetCDF`, whose variable subsets are backed by a
        GDAL multidimensional ``AsClassicDataset`` view that GDAL >= 3.13 cannot read with a partial
        window (it raises ``arrayStartIdx[...] >= <dim>``). The override replaces that view with a
        materialised in-memory raster. A plain :class:`Dataset` is already window-readable, so this
        does nothing.
        """
        return None

    def read_windows(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.read_windows <pyramids.dataset.engines.IO.read_windows>`."""
        return self.io.read_windows(*args, **kwargs)

    def write_array(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.write_array <pyramids.dataset.engines.IO.write_array>`."""
        return self.io.write_array(*args, **kwargs)

    def to_file(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.to_file <pyramids.dataset.engines.IO.to_file>`."""
        return self.io.to_file(*args, **kwargs)

    def to_bytes(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.to_bytes <pyramids.dataset.engines.IO.to_bytes>`."""
        return self.io.to_bytes(*args, **kwargs)

    def to_raster(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.to_raster <pyramids.dataset.engines.IO.to_raster>`."""
        return self.io.to_raster(*args, **kwargs)

    def get_block_arrangement(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.get_block_arrangement <pyramids.dataset.engines.IO.get_block_arrangement>`."""
        return self.io.get_block_arrangement(*args, **kwargs)

    def get_tile(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.get_tile <pyramids.dataset.engines.IO.get_tile>`."""
        return self.io.get_tile(*args, **kwargs)

    def map_blocks(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.map_blocks <pyramids.dataset.engines.IO.map_blocks>`."""
        return self.io.map_blocks(*args, **kwargs)

    def to_xyz(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.to_xyz <pyramids.dataset.engines.IO.to_xyz>`."""
        return self.io.to_xyz(*args, **kwargs)

    def to_terrain_rgb(self, *args, **kwargs):
        """Facade — delegates to
        :meth:`IO.to_terrain_rgb <pyramids.dataset.engines.IO.to_terrain_rgb>`."""
        return self.io.to_terrain_rgb(*args, **kwargs)

    @property
    def overview_count(self):
        """Facade — delegates to :attr:`IO.overview_count <pyramids.dataset.engines.IO.overview_count>`."""
        return self.io.overview_count

    def create_overviews(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.create_overviews <pyramids.dataset.engines.IO.create_overviews>`."""
        return self.io.create_overviews(*args, **kwargs)

    def recreate_overviews(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.recreate_overviews <pyramids.dataset.engines.IO.recreate_overviews>`."""
        return self.io.recreate_overviews(*args, **kwargs)

    def get_overview(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.get_overview <pyramids.dataset.engines.IO.get_overview>`."""
        return self.io.get_overview(*args, **kwargs)

    def get_overview_dataset(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.get_overview_dataset <pyramids.dataset.engines.IO.get_overview_dataset>`."""
        return self.io.get_overview_dataset(*args, **kwargs)

    def read_overview_array(self, *args, **kwargs):
        """Facade — delegates to :meth:`IO.read_overview_array <pyramids.dataset.engines.IO.read_overview_array>`."""
        return self.io.read_overview_array(*args, **kwargs)

    def _read_block(self, *args, **kwargs):
        """Facade — concrete override of the abstract :meth:`RasterBase._read_block`."""
        return self.io._read_block(*args, **kwargs)

    def get_attribute_table(self, *args, **kwargs):
        """Facade — delegates to :meth:`Bands.get_attribute_table <pyramids.dataset.engines.Bands.get_attribute_table>`."""
        return self.bands.get_attribute_table(*args, **kwargs)

    def set_attribute_table(self, *args, **kwargs):
        """Facade — delegates to :meth:`Bands.set_attribute_table <pyramids.dataset.engines.Bands.set_attribute_table>`."""
        return self.bands.set_attribute_table(*args, **kwargs)

    def add_band(self, *args, **kwargs):
        """Facade — delegates to :meth:`Bands.add_band <pyramids.dataset.engines.Bands.add_band>`."""
        return self.bands.add_band(*args, **kwargs)

    def get_band_by_color(self, *args, **kwargs):
        """Facade — delegates to :meth:`Bands.get_band_by_color <pyramids.dataset.engines.Bands.get_band_by_color>`."""
        return self.bands.get_band_by_color(*args, **kwargs)

    def select_bands(self, *args, **kwargs):
        """Facade — delegates to :meth:`Bands.select <pyramids.dataset.engines.Bands.select>`."""
        return self.bands.select(*args, **kwargs)

    def change_no_data_value(self, *args, **kwargs):
        """Facade — concrete override of the abstract :meth:`RasterBase.change_no_data_value`.

        The collaborator returns `None` for the `inplace=True` path; the
        facade substitutes `self` for identity preservation, matching
        :meth:`apply` and :meth:`fill`.
        """
        result = self.bands.change_no_data_value(*args, **kwargs)
        return self if result is None else result

    @property
    def band_color(self):
        """Facade — delegates to :attr:`Bands.band_color <pyramids.dataset.engines.Bands.band_color>`."""
        return self.bands.band_color

    @band_color.setter
    def band_color(self, values):
        """Facade setter.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk (a bare
                `SetColorInterpretation` would otherwise silently spill a PAM sidecar).
        """
        self._require_writable("set band colors")
        self.bands.band_color = values

    def set_color_ramp(
        self,
        band: int = 1,
        *,
        start_value: int,
        end_value: int,
        start_color: str | None = None,
        end_color: str | None = None,
        colormap: str | None = None,
    ) -> None:
        """Facade — delegates to :meth:`Bands.set_color_ramp <pyramids.dataset.engines.Bands.set_color_ramp>`.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk (writing the palette
                would otherwise silently spill a PAM sidecar).
        """
        self._require_writable("set a color ramp")
        return self.bands.set_color_ramp(
            band,
            start_value=start_value,
            end_value=end_value,
            start_color=start_color,
            end_color=end_color,
            colormap=colormap,
        )

    @property
    def color_table(self):
        """Facade — delegates to :attr:`Bands.color_table <pyramids.dataset.engines.Bands.color_table>`."""
        return self.bands.color_table

    @color_table.setter
    def color_table(self, df):
        """Facade setter.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk (a bare
                `SetColorTable` would otherwise silently spill a PAM sidecar).
        """
        self._require_writable("set the color table")
        self.bands.color_table = df

    def _check_no_data_value(self, *args, **kwargs):
        """Facade — concrete override of the abstract :meth:`RasterBase._check_no_data_value`."""
        return self.bands._check_no_data_value(*args, **kwargs)

    def _set_no_data_value(self, *args, **kwargs):
        """Facade — concrete override of the abstract :meth:`RasterBase._set_no_data_value`."""
        return self.bands._set_no_data_value(*args, **kwargs)

    def _calculate_bbox(self) -> list:
        """Concrete override of :meth:`RasterBase._calculate_bbox`.

        Direct on Dataset (not via the Bands collaborator) because the
        `bbox` / `bounds` properties are reachable before the
        collaborator is wired during `Dataset.__init__`.
        """
        # `transform.extent` projects and reduces all four corners, so it returns a
        # normalised [min_x, min_y, max_x, max_y] for a south-up (gt[5] > 0), east-left
        # (gt[1] < 0) or rotated grid alike -- the same derivation merge/cog_info use,
        # rather than a fourth hand-rolled copy that assumed a north-up, west-left grid
        # and inverted the box otherwise. Non-square cells are honoured (separate gt[1],
        # gt[5]). A no-op for the usual north-up, west-left grid.
        min_x, min_y, max_x, max_y = self.transform.extent(self.columns, self.rows)
        return [min_x, min_y, max_x, max_y]

    def _calculate_bounds(self):
        """Concrete override of :meth:`RasterBase._calculate_bounds`."""
        x_min, y_min, x_max, y_max = self._calculate_bbox()
        coords = [(x_min, y_max), (x_min, y_min), (x_max, y_min), (x_max, y_max)]
        poly = create_polygon(coords)
        gdf = gpd.GeoDataFrame(geometry=[poly])
        gdf.set_crs(crs_spec(self.epsg, self.crs), inplace=True)
        return gdf

    def _get_band_names(self) -> list[str]:
        """Concrete override of :meth:`RasterBase._get_band_names`.

        Defined directly on Dataset (not via the bands collaborator)
        because `Dataset.__init__` calls `self._get_band_names()`
        before the `Bands` collaborator is wired up. Mirrors
        :meth:`Bands._get_band_names`.
        """
        names: list[str] = []
        for i in range(1, self.band_count + 1):
            band = self.raster.GetRasterBand(i)
            if band.GetDescription():
                names.append(band.GetDescription())
            else:
                band_name = f"Band_{band.GetBand()}"
                metadata = band.GetDataset().GetMetadata_Dict()
                if band_name in metadata and metadata[band_name]:
                    names.append(metadata[band_name])
                else:
                    names.append(band_name)
        return names

    def _get_crs(self) -> str:
        """Concrete override of :meth:`RasterBase._get_crs`.

        Defined directly on Dataset rather than as a facade because
        `RasterBase.__init__` calls `_get_epsg()` (which calls
        `_get_crs()`) before `Dataset.__init__` has a chance to wire
        up the Spatial collaborator. The Spatial collaborator's
        `Spatial._get_crs` returns the projection as GDAL reports it; this
        override adds the CF inference on top, so the two bodies differ.
        """
        crs = str(self.raster.GetProjection())
        cached: str | None = getattr(self, "_cf_crs_cache", None)
        if not crs and cached is not None:
            # Memoised: the scan below walks the whole metadata dict, and `.crs`
            # is read on every spatial operation. Keyed to the current raster —
            # `_update_inplace` drops it.
            crs = cached
        elif not crs:
            crs = self._infer_cf_crs()
            self._cf_crs_cache = crs
        return crs

    def _infer_cf_crs(self) -> str:
        """WGS 84 WKT when CF metadata says this is a lat/lon grid, else ``""``.

        A CF NetCDF opened through the *classic* driver reports no projection but
        exposes its coordinate metadata as ``<var>#units`` / ``<var>#axis``.
        Degrees east/north on a coordinate there mean a geographic grid by CF
        convention, so read it as WGS 84 rather than as ungeoreferenced (ARC-26).
        Any other unprojected raster still reports no CRS.

        The multidim equivalent is :meth:`pyramids.netcdf.NetCDF._cf_geographic_crs`,
        which reads the same evidence off the GDAL group API instead of off
        flattened metadata keys.

        Returns:
            str: WGS 84 WKT when the evidence says geographic, otherwise ``""``.
        """
        metadata = self.raster.GetMetadata() or {}
        evidence_names, axis_names, vertical_names = self._classify_cf_variables(
            metadata
        )
        units = self._units_of(metadata, evidence_names, set())
        axis_units = self._paired_axis_units(metadata, axis_names, vertical_names)
        crs = cf_geographic_wkt(units, axis_units)
        # Last check, on the geometry rather than the metadata: a grid whose own
        # coordinates fall outside the lon/lat range is not lat/lon, no matter
        # which variable supplied the degrees.
        if crs and not within_lonlat_range(self._own_extent()):
            crs = ""
        return crs

    @staticmethod
    def _classify_cf_variables(
        metadata: dict,
    ) -> tuple[set[str], set[str], set[str]]:
        """Split CF variable names into evidence, veto and vertical sets.

        Three distinct roles, easy to conflate:

        * **Evidence** — variables whose degrees units may imply a geographic
          grid. Only plausible coordinates qualify: one that declares
          `axis: X|Y`, one named in a `coordinates` attribute (how CF identifies
          a curvilinear grid's 2-D lat/lon, which declare no `axis`), or one
          carrying a conventional coordinate name. A wind direction in
          `degrees_east` is a data variable and is not evidence.
        * **Veto** — variables whose projected units mean the grid is not
          lat/lon. The declared axes are *unioned* with the name list rather than
          replacing it: a file may declare `axis` on some variables (the
          near-universal `time#axis = "T"`) while leaving its projected x/y
          undeclared, and keying on the declarations alone then misses the veto
          entirely. Only `axis: X|Y` counts as a declared horizontal axis — a
          declared `T` is not one.
        * **Vertical** — declared `axis: Z`, plus the conventional names. A depth
          or height in metres says nothing about the horizontal frame, so it must
          never veto.

        Args:
            metadata: GDAL metadata dict, with flattened `<var>#attr` keys.

        Returns:
            tuple[set[str], set[str], set[str]]: `(evidence, veto, vertical)`
            variable names, lower-cased.
        """
        coordinate_refs: set[str] = set()
        declared_horizontal: set[str] = set()
        declared_vertical: set[str] = set()
        for key, value in metadata.items():
            if not isinstance(value, str):
                continue
            lowered = key.lower()
            if lowered.endswith("#coordinates"):
                coordinate_refs.update(name.lower() for name in value.split())
            elif lowered.endswith("#axis"):
                name = key.rsplit("#", 1)[0].rsplit("/", 1)[-1].lower()
                role = value.strip().upper()
                if role == "Z":
                    declared_vertical.add(name)
                elif role in ("X", "Y"):
                    declared_horizontal.add(name)
        evidence = declared_horizontal | coordinate_refs | _AXIS_VARIABLE_NAMES
        veto = declared_horizontal | _AXIS_VARIABLE_NAMES
        return evidence, veto, set(VERTICAL_AXIS_NAMES) | declared_vertical

    @staticmethod
    def _paired_axis_units(
        metadata: dict, include: set[str], exclude: set[str]
    ) -> set[str]:
        """Projected units, but only when both an X and a Y axis carry them.

        A real projected grid always has *both* horizontal axes in projected
        units. One variable named `x` in metres beside `lon` / `lat` in degrees
        is a data variable — a ROMS bathymetry, a sea-surface height — and must
        not strip a geographic grid's CRS; `east` **and** `north`, or `rlon`
        **and** `rlat`, is a grid and must. Requiring the pair is what lets the
        name-based veto stay strict without destroying the CRS of a file that
        merely contains a similarly-named data variable.

        Args:
            metadata: GDAL metadata dict, with flattened `<var>#attr` keys.
            include: Candidate axis names.
            exclude: Names to skip (the vertical set).

        Returns:
            set[str]: The projected units when an X/Y pair carries them,
            otherwise an empty set.
        """
        per_axis: dict[str, str] = {}
        for key, value in metadata.items():
            if not isinstance(value, str) or not key.lower().endswith("#units"):
                continue
            name = key.rsplit("#", 1)[0].rsplit("/", 1)[-1].lower()
            if name in include and name not in exclude:
                per_axis[name] = value.strip().lower()
        projected = {
            name: unit
            for name, unit in per_axis.items()
            if unit in PROJECTED_AXIS_UNITS
        }
        has_x = any(name in _X_AXIS_NAMES for name in projected)
        has_y = any(name in _Y_AXIS_NAMES for name in projected)
        return set(projected.values()) if has_x and has_y else set()

    @staticmethod
    def _units_of(metadata: dict, include: set[str], exclude: set[str]) -> set[str]:
        """Lower-cased ``#units`` values of the named variables.

        Args:
            metadata: GDAL metadata dict, with flattened ``<var>#attr`` keys.
            include: Variable names to collect units from.
            exclude: Variable names to skip even when they are in `include`.

        Returns:
            set[str]: The matching unit strings.
        """
        collected = set()
        for key, value in metadata.items():
            if not isinstance(value, str) or not key.lower().endswith("#units"):
                continue
            name = key.rsplit("#", 1)[0].rsplit("/", 1)[-1].lower()
            if name in include and name not in exclude:
                collected.add(value.strip().lower())
        return collected

    def _own_extent(self) -> tuple[float, float, float, float] | None:
        """Corner-to-corner extent in the raster's own coordinates, or ``None``.

        Read straight off the GDAL handle rather than through :attr:`bounds`,
        because this runs from :meth:`_get_crs` during ``RasterBase.__init__``,
        before the Spatial collaborator exists.

        Returns:
            ``(min_x, min_y, max_x, max_y)``, or ``None`` when the raster carries
            no real geotransform (GDAL's identity default) and its extent
            therefore says nothing.
        """
        result: tuple[float, float, float, float] | None = None
        try:
            geotransform = self.raster.GetGeoTransform()
            columns, rows = self.raster.RasterXSize, self.raster.RasterYSize
        except (RuntimeError, AttributeError):
            geotransform = None
        # GDAL hands back the identity transform for a raster that has none; its
        # "extent" is then pixel indices, which must not veto anything.
        if geotransform and tuple(geotransform) != (0.0, 1.0, 0.0, 0.0, 0.0, 1.0):
            # All four corners: with a rotated geotransform (non-zero gt[2] /
            # gt[4]) the two diagonal corners do not bound the other two, and
            # under a symmetric rotation they coincide -- collapsing the extent
            # to a point, which silently disables the range check.
            corners = [(0, 0), (columns, 0), (0, rows), (columns, rows)]
            xs = [
                geotransform[0] + col * geotransform[1] + row * geotransform[2]
                for col, row in corners
            ]
            ys = [
                geotransform[3] + col * geotransform[4] + row * geotransform[5]
                for col, row in corners
            ]
            result = (min(xs), min(ys), max(xs), max(ys))
        return result

    def _get_epsg(self) -> int | None:
        """Concrete override of :meth:`RasterBase._get_epsg`.

        Defined directly on Dataset for the same reason as
        :meth:`_get_crs`.

        Returns `None` for a raster with no CRS, honouring the documented
        `int | None` contract of :attr:`epsg` — a missing georeference must not
        be reported as WGS 84.
        """
        return epsg_of_crs(self._get_crs())

    def zonal_stats(
        self,
        fc,
        *,
        stats=("mean",),
        method: str = "rasterize",
        band: int = 0,
    ):
        """Compute zonal statistics of this dataset over a polygon FeatureCollection.

        Thin forwarder to
        :func:`pyramids.dataset.ops._zonal.zonal_stats`; see that
        function for the full argument contract. The statistics are in
        physical units (a CF-packed band is unpacked), and the band's
        no-data cells, found in its stored values, are left out.

        Args:
            fc: A :class:`pyramids.feature.FeatureCollection` of
                polygons sharing this dataset's CRS.
            stats: Sequence of stat names (`"mean"`, `"sum"`,
                `"min"`, `"max"`, `"std"`, `"var"`,
                `"count"`).
            method: `"rasterize"` is the only supported value today;
                an area-weighted `"fractional"` method is planned.
            band: Zero-based band index.

        Returns:
            pandas.DataFrame: Indexed by `fc.index`; one column per stat.
        """
        return _zonal_stats(self, fc, stats=stats, method=method, band=band)

    def to_zarr(
        self,
        store,
        *,
        compute: bool = True,
        mode: str = "w",
        chunks=None,
        storage_options: dict | None = None,
        compressor="auto",
        overview_factors: list | None = None,
        overview_resampling: str = "average",
    ):
        """Serialise this Dataset to a Zarr store (parallel writes per chunk).

        Thin forwarder to
        :func:`pyramids.dataset.ops._zarr.write_dataset_to_zarr`; see
        that function for the full argument contract. Zarr is the
        only raster output format where pyramids can write in true
        parallel — each dask chunk becomes an independent Zarr chunk
        file. Requires the `[lazy]` optional extra, and a dataset backed
        by a file the chunk reader can reopen.

        The values written are the physical ones `read_array` returns, and
        pyramids' Zarr metadata has no `scale_factor` / `add_offset`, so a
        CF-packed source is written materialised: the store's `data` array
        holds `float64` values, its `dtype` attribute says so, and its no-data
        is the sentinel in physical units (`-9999` at `scale=0.5` is recorded
        as `-4999.5`). Read back, it declares no packing.

        Args:
            store: Target store (path / fsspec URL / zarr.Store).
            compute: `True` writes immediately; `False` returns a
                :class:`dask.delayed.Delayed`.
            mode: Zarr open mode, usually `"w"` or `"a"`.
            chunks: Chunk spec forwarded to :meth:`read_array`.
                `None` defaults to `"auto"` via the zarr helper.
            storage_options: fsspec options for cloud stores.
            compressor: Zarr codec(s) for the `data` array. `"auto"` (default)
                keeps zarr's default codec; pass a zarr-v3 codec or list of them
                (e.g. `zarr.codecs.BloscCodec(cname="zstd")`) to override, or
                `None` for an uncompressed array.
            overview_factors: Optional downsample factors (e.g. `[2, 4, 8]`) to
                also write decimated multiscale pyramid levels as `data_<factor>`
                arrays plus a `multiscales` attribute. Requires `compute=True`.
                Read a level back with `Dataset.from_zarr(store, level=factor)`.
            overview_resampling: GDAL resampling for the pyramid levels
                (`"average"` default, `"nearest"`, `"bilinear"`, ...).

        Returns:
            `None` when `compute=True`; a :class:`dask.delayed.Delayed` that
            performs the write when `compute=False`.

        Raises:
            OverviewTargetError: `overview_factors` was given and this dataset cannot
                hold overviews — a plain VRT whose description is not a path: an empty
                one, a blank one, or inline VRT XML. The levels are built through
                `create_overviews`, which refuses that shape, so the target is checked
                pre-flight and no store is written at all. The check runs *before* the
                `compute` one, so a call that is wrong in both ways reports this rather
                than the `ValueError` below — passing `compute=True` would still leave
                the dataset refused. Save it with `to_file(path)` and write the Zarr
                from the saved raster.
            ValueError: `overview_factors` was given with `compute=False`; the pyramid
                levels are written eagerly.

        Examples:
            - A packed raster is stored as its physical values, with the sentinel in the
              same units, and reads back declaring no packing:
                ```python
                >>> import os, tempfile
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> folder = tempfile.mkdtemp()
                >>> source = Dataset.from_array(
                ...     np.array([[100, -9999], [300, 400]], dtype="int16"),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ...     no_data_value=-9999,
                ...     path=os.path.join(folder, "packed.tif"),
                ... )
                >>> source.scale = [0.5]
                >>> source.close()
                >>> packed = Dataset.read_file(os.path.join(folder, "packed.tif"))
                >>> packed.to_zarr(os.path.join(folder, "packed.zarr"))
                >>> store = Dataset.from_zarr(os.path.join(folder, "packed.zarr"))
                >>> store.read_array().tolist(), store.dtype, store.scale
                ([[50.0, -4999.5], [150.0, 200.0]], ['float64'], [1.0])
                >>> float(store.no_data_value[0])
                -4999.5

                ```
        """
        resolved_chunks = chunks if chunks is not None else "auto"
        return write_dataset_to_zarr(
            self,
            store,
            compute=compute,
            mode=mode,
            chunks=resolved_chunks,
            storage_options=storage_options,
            compressor=compressor,
            overview_factors=overview_factors,
            overview_resampling=overview_resampling,
        )

    @classmethod
    def from_zarr(
        cls,
        store,
        *,
        chunks=None,
        storage_options: dict | None = None,
        level: int = 1,
        data_name: str | None = None,
    ) -> Dataset:
        """Load a pyramids-written Zarr store into a new :class:`Dataset`.

        Thin forwarder to
        :func:`pyramids.dataset.ops._zarr.read_dataset_from_zarr`.

        Args:
            store: Input store (path / fsspec URL / zarr.Store).
            chunks: If non-None, the loaded Dataset is flagged as
                dask-backed so downstream `read_array` calls return
                lazy arrays.
            storage_options: fsspec options for cloud stores.
            level: Pyramid downsample factor to read (`1` = full resolution).
                Pass a factor written via `to_zarr(overview_factors=...)` to read
                that decimated overview level.
            data_name: Explicit name of the data array. ``None`` (default)
                auto-detects; pass an explicit name to read a specific variable
                from a foreign GeoZarr store whose auto-detect picks the wrong
                array.
        """
        return read_dataset_from_zarr(
            store,
            chunks=chunks,
            storage_options=storage_options,
            level=level,
            data_name=data_name,
        )

    def __str__(self) -> str:
        """Human-readable multi-line summary, or a `<Dataset: closed>` sentinel.

        `repr()` / `str()` run in debuggers, logging, and pytest introspection, so a
        closed dataset returns a sentinel rather than raising (a raising `__repr__`
        would mask the surrounding error). Reads that must fail loudly use
        `_require_open` instead.
        """
        message = "<Dataset: closed>"
        if self._raster is not None:
            message = f"""
            Top Left Corner: {self.top_left_corner}
            Cell size: {self.cell_size}
            Dimension: {self.rows} * {self.columns}
            EPSG: {self.epsg}
            Number of Bands: {self.band_count}
            Band names: {self.band_names}
            Band colors: {self.band_color}
            Band units: {self.band_units}
            Scale: {self.scale}
            Offset: {self.offset}
            Mask: {self.no_data_value[0]}
            Data type: {self.dtype[0]}
            File: {self.file_name}
        """
        return message

    def __repr__(self) -> str:
        """GDAL info string, or a `<Dataset: closed>` sentinel on a closed dataset.

        The info string's ``Files:`` section lists every source a VRT
        references, and for a mosaic built by
        :func:`pyramids.stac.build_vrt_from_stac` with a bearer signer those
        paths carry the live token — so the text goes through
        :func:`~pyramids.base.remote.redact_credentials` first. ``repr`` is
        called far more often than deliberately: pytest prints it for every
        operand of a failing assertion, ``logging.error("%r", ds)`` is idiomatic,
        and a notebook auto-displays it.
        """
        info = "<Dataset: closed>"
        if self._raster is not None:
            info = redact_credentials(str(gdal.Info(self.raster)))
        return info

    # numpy would otherwise treat a Dataset as an opaque object and broadcast
    # over it, so `np.array([0.0]) + ds` came back as an object array of raster
    # copies instead of refusing. `None` tells numpy this type has no ufunc
    # protocol, so every such expression is a TypeError. The two sides word it
    # differently: `ds + np.array([1.0])` says "operand 'Dataset' does not
    # support ufuncs", while `np.array([1.0]) + ds` comes out of numpy's own
    # dispatch as "Concatenation operation is not implemented for NumPy
    # arrays" -- unhelpful, but an error rather than a silent wrong answer.
    __array_ufunc__ = None

    def _combine_layout_source(self, other: Any, band: int | None) -> Any:
        """Check two operands' band layouts before `Analysis._combine` computes, and name the source.

        A hook: `Analysis._combine` calls it on the left operand after the grid and band-count
        checks, and hands what it returns to `_label_combined`. A plain raster has no band
        dimensions, so it checks nothing and names no source; `NetCDF` overrides it.

        Args:
            other: The right operand, or `None` when `Analysis._fold` combines this raster with
                itself.
            band: The single band being combined, or `None` for all of them.

        Returns:
            Any: `None` for a plain raster.
        """

    def _label_combined(self, result: Any, source: Any) -> None:
        """Label a combined result with its operands' band layout, after `Analysis._combine`.

        A hook, paired with `_combine_layout_source`. A plain raster has no layout to carry;
        `NetCDF` overrides it.

        Args:
            result: The combined raster.
            source: What `_combine_layout_source` returned.
        """

    def _arithmetic(self, other: Any, op: Callable) -> Any:
        """Route a binary operator to :meth:`combine`, or decline the operand.

        Shared by the arithmetic operators and the comparisons — a comparison
        is just a `combine` whose `func` returns booleans, which GDAL has no
        band type for, so the result is stored as Byte: `1` where the test
        holds, `0` where it does not, `255` wherever either operand was
        no-data.

        A second raster or a real scalar is handled here; anything else yields
        `NotImplemented`, so Python raises its own `TypeError` naming both
        operand types.

        A scalar takes the **same** route as a raster operand — `combine`'s
        machinery, with the constant folded into the callable and this raster read
        once rather than twice (:meth:`Analysis._fold`) — so `ds * 2` agrees with
        `ds * other` on band count, dtype and sentinel. It does *not* always
        agree with `ds.apply(lambda v: v * 2)`: :meth:`apply` transforms one
        band and keeps the source's sentinel, while :meth:`combine` spans every
        band and derives one (`NaN` for a floating result). The two are
        different tools and the operator can only match one of them; it matches
        the operator family, because `ds * 2` and `ds * other` are the same
        syntax and should not mean different things. Reach for :meth:`apply`
        when you want its single-band, sentinel-preserving contract.

        The scalar's own type is kept where NumPy can hold it, so `ds * 2` on an
        `int16` band stays `int16` rather than widening to `float64`; only an
        exotic `numbers.Real` such as a `fractions.Fraction` is narrowed, to
        `float` — see :func:`_numeric_scalar`. `ds + 0`, `ds * 1`, `ds - 0` and
        `ds ** 1` short-circuit to :meth:`copy`: the commutative two from either side
        of the operator, `ds - 0` and `ds ** 1` from the right only, since `0 - ds`
        negates and `1 ** ds` is all ones. A no-op therefore cannot widen the dtype or
        drop the band's declared sentinel.
        `ds / 1` is deliberately not one of them — true division widens an integer
        band to `float64` everywhere else, and absorbing it would make this the one
        division that does not. The short-circuit also runs before anything reads a
        band, so a NetCDF root container answers `c + 0` with a copy where `c * 2`
        raises its container guard — see :func:`_is_identity`.

        `bool` is declined deliberately: `True` is a `Real` equal to `1`, and
        `ds * True` silently succeeding reads as a caller's bug. So is a complex
        scalar — no band holds an imaginary part.

        A comparison — `<`, `<=`, `>`, `>=` — is the same journey with a
        callable that returns booleans. GDAL has no boolean band type, so the
        result is stored as Byte: `1` where the test holds, `0` where it does
        not, and `255` wherever either operand was no-data. The mask always
        declares `255`, whether or not anything was masked; it cannot collide
        with `0`/`1`, and it leaves a marker for a later crop or warp fringe.
        A cell holding `NaN` is compared rather than excluded unless `NaN` is
        that band's declared sentinel — `NaN >= x` is `False`, so it reads as
        `0` rather than as a gap; declare `no_data_value=np.nan` on the operand
        when NaN should mean "missing".

        `__eq__` and `__ne__` are deliberately *not* routed through here.
        Python gives every object a working identity-based equality, the
        codebase and its tests rely on it, and replacing it with something that
        returns a raster would break `in`, `dict`, `assert a == b` and hashing
        all at once. Ask for `a.combine(b, np.equal)` when you want that mask.

        Args:
            other: The right-hand operand — another raster, or a real,
                non-boolean scalar. Anything else is declined.
            op: The two-argument operator to apply cell by cell.

        Returns:
            Dataset | NotImplemented: The combined raster — a :meth:`copy` when
            `op` and `other` form an identity — or `NotImplemented` when `other`
            is neither a raster nor a real, non-boolean scalar, which makes
            Python raise its own `TypeError` naming both operand types.

        Raises:
            AlignmentError: `other` is a raster that does not share this one's
                grid and CRS. :meth:`combine` refuses rather than resampling;
                :meth:`align` is the explicit step.
            ValueError: `other` is a raster whose band count neither agrees with
                this one's nor broadcasts against it (a single band does), or the
                values `op` produced have a dtype GDAL has no band type for —
                both raised by :meth:`combine`.

        See Also:
            Analysis.combine: The engine method every non-identity operand goes
                through, and the source of the dtype and sentinel rules.
            Analysis.apply: The single-band, sentinel-preserving alternative for
                a one-raster transform.
        """
        result: Any = NotImplemented
        if isinstance(other, RasterBase):
            # `RasterBase`, matching `Analysis.combine`'s own guard: were the two
            # to differ, `ds - x` would decline an operand `ds.combine(x, ...)`
            # accepts. `cast` because `RasterBase` is the ABC the engine checks
            # while `combine` is typed for the concrete raster.
            result = self.combine(cast("Dataset", other), op)
        elif isinstance(other, Real) and not isinstance(other, bool):
            scalar = _numeric_scalar(other)
            if _is_identity(op, scalar):
                # `ds + 0` and `ds * 1` are no-ops, so they answer with the raster
                # unchanged -- the same short-circuit `__radd__` and `__rmul__` apply
                # from the left. It runs before anything touches a band, so a NetCDF
                # root container answers with a copy where `c * 2` raises its
                # container guard: `sum([container])` has always worked that way, and
                # absorbing from one side only is what this exists to prevent.
                # Without it the two spellings of one commutative
                # expression disagree: `combine` would widen `ds + 0.0` from `int16` to
                # `float64` where `0.0 + ds` is a byte-identical copy, and `ds + 0`
                # would *drop* the band's declared sentinel, because an integer result
                # that masked nothing declares none. A no-op must not strip the no-data
                # tag off a raster on its way to disk.
                result = self.copy()
            else:
                # The scalar is folded into the callable and `self` is passed as the
                # second operand, so the grid and band count match by construction and
                # every rule `combine` already enforces -- band span, dtype width,
                # sentinel derivation -- applies unchanged. The second array is ignored
                # on purpose; it is there to satisfy `combine`'s two-operand shape.
                result = self.analysis._fold(lambda values: op(values, scalar))
        return result

    def _reflected_arithmetic(self, other: Any, op: Callable) -> Any:
        """Route a *reflected* binary operator — the scalar is the left operand.

        `2 - ds` is not `ds - 2`, so subtraction and division need the operands in
        the order the caller wrote them. Addition and multiplication commute and
        reuse :meth:`_arithmetic` directly, which is how `0 + ds` and `1 * ds` reach
        the same identity short-circuit their left-hand spellings take.

        Nothing short-circuits *here*: the operators that land on this method have no
        left identity to absorb — `0 - ds` negates and `1 / ds` is a reciprocal — so
        every call computes. It does so through :meth:`Analysis._fold`, one read of
        this raster with the scalar folded into the callable, which is what keeps
        `2 - ds` agreeing with `ds - 2` on band span, dtype and derived sentinel.

        Args:
            other: The left-hand operand, which reached here because its own
                operator declined this dataset.
            op: The two-argument operator to apply cell by cell.

        Returns:
            Dataset | NotImplemented: The computed raster, or `NotImplemented`
            when `other` is not a real, non-boolean scalar, which makes Python raise
            its own `TypeError` naming both operand types.

        Raises:
            ValueError: The values `op` produced have a dtype GDAL has no band type
                for, or an integer result masked something and no candidate sentinel
                is free to mark it — both raised by the machinery behind
                :meth:`combine`.

        See Also:
            Dataset._arithmetic: The left-hand form, and the identity short-circuit
                the commutative operators share with it.
            Analysis._fold: The single-read path the computed result comes back
                through.
        """
        result: Any = NotImplemented
        if isinstance(other, Real) and not isinstance(other, bool):
            scalar = _numeric_scalar(other)
            result = self.analysis._fold(lambda values: op(scalar, values))
        return result

    def __add__(self, other: Any) -> Any:
        """Add another raster, or a real scalar, cell by cell.

        Routed through :meth:`_arithmetic`, so both operand kinds land in
        :meth:`combine` and agree on band span, dtype and derived sentinel.
        `ds + 0` is the one exception: it short-circuits to :meth:`copy`, which
        is why a no-op keeps the band's declared no-data value where a computed
        integer result that masked nothing declares none.

        Args:
            other: Another raster on this one's grid, or a real, non-boolean
                scalar.

        Returns:
            Dataset | NotImplemented: The summed raster, or `NotImplemented` for
            any other operand, which makes Python raise its own `TypeError`.

        Raises:
            AlignmentError: `other` is a raster on a different grid or CRS.

        Examples:
            - Add two aligned rasters, then a constant to one of them:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> rain = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
              >>> melt = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((rain + melt).read_array()).mean())
              52.0

              ```
            - A constant keeps an integer band integer, and the computed result
              declares no sentinel because it masked nothing:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
              >>> (counts + 5).dtype
              ['int16']
              >>> int(np.asarray((counts + 5).read_array())[0, 0])
              15
              >>> (counts + 5).no_data_value
              (None,)

              ```
            - Adding zero is a no-op, so it hands back a copy that still carries
              the source's no-data value:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
              >>> (counts + 0).no_data_value == counts.no_data_value
              True

              ```
            - A non-numeric operand is declined, so Python reports the pair:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> Dataset.from_array(np.full((3, 3), 1.0, "float32"), geo_ref=geo_ref) + "2"
              Traceback (most recent call last):
                  ...
              TypeError: unsupported operand type(s) for +: 'Dataset' and 'str'

              ```

        See Also:
            Dataset._arithmetic: The shared router, with the full operand rules.
            Analysis.combine: The engine method that does the work.
        """
        return self._arithmetic(other, operator.add)

    def __sub__(self, other: Any) -> Any:
        """Subtract another raster, or a real scalar, cell by cell.

        Routed through :meth:`_arithmetic` into :meth:`combine`. Subtraction has
        no identity to short-circuit on this side, so every operand computes;
        `100 - ds` is the reflected spelling and lives in :meth:`__rsub__`.

        Args:
            other: Another raster on this one's grid, or a real, non-boolean
                scalar.

        Returns:
            Dataset | NotImplemented: The difference raster, or `NotImplemented`
            for any other operand.

        Raises:
            AlignmentError: `other` is a raster on a different grid or CRS.

        Examples:
            - Difference two aligned surfaces — a canopy height model:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> surface = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
              >>> bare = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((surface - bare).read_array()).mean())
              8.0

              ```
            - Subtract a constant offset from every cell:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> gauge = Dataset.from_array(np.full((3, 3), 20.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((gauge - 5).read_array()).mean())
              15.0

              ```

        See Also:
            Dataset.__rsub__: The reflected form, `scalar - ds`.
            Analysis.combine: The engine method that does the work.
        """
        return self._arithmetic(other, operator.sub)

    def __mul__(self, other: Any) -> Any:
        """Multiply by another raster, or by a real scalar, cell by cell.

        Routed through :meth:`_arithmetic` into :meth:`combine`. A scalar keeps
        its own NumPy type, so scaling an integer band by an integer stays in
        that band's dtype; `ds * 1` short-circuits to :meth:`copy`.

        Args:
            other: Another raster on this one's grid, or a real, non-boolean
                scalar.

        Returns:
            Dataset | NotImplemented: The product raster, or `NotImplemented`
            for any other operand.

        Raises:
            AlignmentError: `other` is a raster on a different grid or CRS.

        Examples:
            - Scale an integer band by a constant without widening its dtype:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
              >>> (counts * 2).dtype
              ['int16']
              >>> int(np.asarray((counts * 2).read_array())[0, 0])
              20

              ```
            - A scalar spans every band, unlike :meth:`apply`, which transforms one:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> stack = np.stack(
              ...     [np.full((3, 3), 1.0, "float32"), np.full((3, 3), 2.0, "float32")]
              ... )
              >>> scaled = Dataset.from_array(stack, geo_ref=geo_ref) * 3
              >>> scaled.shape
              (2, 3, 3)
              >>> [float(band.mean()) for band in np.asarray(scaled.read_array())]
              [3.0, 6.0]

              ```
            - Weight one raster by another, cell by cell:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> depth = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
              >>> weight = Dataset.from_array(np.full((3, 3), 0.5, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((depth * weight).read_array()).mean())
              1.5

              ```
            - A `bool` is declined on purpose, so `ds * True` does not quietly
              succeed:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> Dataset.from_array(np.full((3, 3), 1.0, "float32"), geo_ref=geo_ref) * True
              Traceback (most recent call last):
                  ...
              TypeError: unsupported operand type(s) for *: 'Dataset' and 'bool'

              ```

        See Also:
            Dataset._arithmetic: The shared router, with the full operand rules.
            Analysis.apply: The single-band, sentinel-preserving alternative.
        """
        return self._arithmetic(other, operator.mul)

    def __truediv__(self, other: Any) -> Any:
        """Divide by another raster, or by a real scalar, cell by cell.

        Routed through :meth:`_arithmetic` into :meth:`combine`. A true divide
        always produces a floating result, so the sentinel :meth:`combine`
        derives is `NaN`; a division by zero stores an infinity as a **value**
        rather than masking it, and numpy's own `RuntimeWarning` reaches the
        caller — only `0/0`, which is `NaN`, reads back as a gap.

        Args:
            other: Another raster on this one's grid, or a real, non-boolean
                scalar.

        Returns:
            Dataset | NotImplemented: The quotient raster, or `NotImplemented`
            for any other operand.

        Raises:
            AlignmentError: `other` is a raster on a different grid or CRS.

        Warns:
            RuntimeWarning: numpy's own `divide by zero` / `invalid value`
                warning, raised where a divisor cell holds zero. The infinity
                (or `NaN`) it produces is stored, so mask the zeros first if that
                is not what you want downstream.

        Examples:
            - Turn a count raster into a rate by dividing by a constant:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> counts = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((counts / 0.5).read_array()).mean())
              6.0

              ```
            - A band ratio between two aligned rasters, and the `NaN` sentinel a
              floating result declares:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> nir = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
              >>> red = Dataset.from_array(np.full((3, 3), 0.5, "float32"), geo_ref=geo_ref)
              >>> ratio = nir / red
              >>> float(np.asarray(ratio.read_array()).mean())
              6.0
              >>> float(ratio.no_data_value[0])
              nan

              ```

        See Also:
            Dataset.__rtruediv__: The reflected form, `scalar / ds`.
            Analysis.combine: The engine method that derives the sentinel.
        """
        return self._arithmetic(other, operator.truediv)

    def __pow__(self, other: Any) -> Any:
        """Raise each cell to a power — another raster's, or a real scalar's.

        Routed through :meth:`_arithmetic` into :meth:`combine`, so it inherits the same
        operand rules, no-data domain, band-dimension labelling and dtype behaviour as
        `*` and `/`: `ds ** 2` on an `int16` band stays `int16`, and a scalar spans every
        band. A fractional power follows NumPy's own casting — `int16 ** 0.5` widens to
        `float64` — and where NumPy yields a non-finite cell (a negative base raised to a
        fractional power, or a zero raised to a negative power) that value is stored as-is
        and NumPy's `RuntimeWarning` reaches the caller. The one power NumPy refuses
        outright is a negative integer power of an integer band, which raises `ValueError`;
        cast the band to a floating dtype first. `** 1` is the exception to the widening
        rule: it is a no-op, absorbed to a `copy()` that keeps the source dtype and
        sentinel (like `* 1`), so `int16 ** 1.0` stays `int16` where `int16 ** 2.0`
        widens to `float64`.

        Args:
            other: Another raster on this one's grid, or a real, non-boolean scalar.

        Returns:
            Dataset | NotImplemented: The powered raster, or `NotImplemented` for any
            other operand.

        Raises:
            AlignmentError: `other` is a raster on a different grid or CRS.
            ValueError: numpy refuses a negative integer power of an integer band
                (`Integers to negative integer powers are not allowed`); cast the band to a
                floating dtype first.

        Warns:
            RuntimeWarning: numpy's own `invalid value` / `divide by zero` warning, raised
                where a power yields a non-finite cell — a negative base to a fractional
                power, or a zero to a negative power. The non-finite value is stored, not
                masked.

        Examples:
            - Square a band, the common use — its dtype is kept:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), 3, "int16"), geo_ref=geo_ref)
              >>> squared = ds ** 2
              >>> int(np.asarray(squared.read_array())[0, 0]), squared.dtype
              (9, ['int16'])

              ```
            - A negative integer power of an integer band is refused by numpy; give it a
              floating band (or use a floating power) to get the reciprocal instead:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> Dataset.from_array(np.full((3, 3), 4, "int16"), geo_ref=geo_ref) ** -1
              Traceback (most recent call last):
                  ...
              ValueError: Integers to negative integer powers are not allowed.
              >>> recip = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref) ** -1
              >>> float(np.asarray(recip.read_array())[0, 0])
              0.25

              ```

        See Also:
            Dataset.__rpow__: The reflected form, `scalar ** ds`.
            Dataset._arithmetic: The shared router, with the full operand rules.
        """
        return self._arithmetic(other, operator.pow)

    def __radd__(self, other: Any) -> Any:
        """Add from the right, so a list of rasters can be `sum()`-ed.

        `sum()` seeds its accumulator with the integer `0` and only then
        starts adding, so `0 + ds` has to succeed for a list of rasters to be
        summable at all. Zero is the additive identity, so the answer is this
        dataset's values — returned as a copy, not as `self`. Otherwise
        `sum([one])` would hand back the very raster it was given while
        `sum([a, b])` hands back a fresh one, and an in-place write to "the
        total" would reach into the input in the one-element case only. numpy
        makes the same choice: `sum([arr]) is arr` is `False`.

        Zero is absorbed from **either** side — `ds + 0` is the same copy — so
        the two spellings of one commutative expression cannot disagree. Every
        other real scalar computes through :meth:`combine`, so `1 + ds` is
        `ds + 1`. `False + ds` still raises (a bool is not a numeric seed) and
        so does `0j + ds` (no band holds an imaginary part).

        Two wrinkles worth knowing. `sum()` of a **single** raster never reaches
        :meth:`combine`, so it returns that raster's values and sentinel
        verbatim, while `sum()` of two or more goes through `combine` and takes
        `combine`'s derived sentinel (`NaN` for a floating result) — a fold over
        a glob can therefore report a different no-data value depending on how
        many files matched. And the one-element answer is a :meth:`copy`, so it
        carries whatever `copy` carries: the grid, CRS, band names and sentinel,
        but not derived products such as overviews. Pass `no_data_value=` to
        :meth:`combine <pyramids.dataset.engines.Analysis.combine>` and rebuild
        overviews explicitly when either matters.

        Args:
            other: The left-hand operand, which reached here because its own
                `__add__` declined this dataset.

        Returns:
            Dataset | NotImplemented: A copy of this dataset when `other` is
            zero, the computed raster for any other real scalar, else
            `NotImplemented` so Python raises its own `TypeError`.

        Examples:
            - Fold a list of aligned rasters into their total:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> rasters = [
              ...     Dataset.from_array(np.full((4, 4), value, "float32"), geo_ref=geo_ref)
              ...     for value in (1.0, 2.0, 3.0)
              ... ]
              >>> float(np.asarray(sum(rasters).read_array()).mean())
              6.0

              ```

            - A scalar on the left computes the same raster as one on the right,
              because addition commutes:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((10 + ds).read_array()).mean())
              14.0

              ```

        See Also:
            Dataset.__add__: The same router from the other side.
            Analysis.combine: The engine method every non-zero seed goes through.
        """
        # Addition commutes, so this is `ds + other` outright. `_arithmetic` owns both
        # halves of what used to be duplicated here: the `Real`-and-not-`bool` guard
        # that turns away `False` and `0j`, and the zero short-circuit to `copy()` --
        # which it applies from either side, so the two spellings cannot disagree.
        return self._arithmetic(other, operator.add)

    def __rmul__(self, other: Any) -> Any:
        """Multiply from the right, so `math.prod()` folds a list of rasters.

        The multiplicative twin of :meth:`__radd__`: `math.prod` seeds its
        accumulator with the integer `1`, so `1 * ds` has to succeed for a list
        of rasters to be multipliable at all. One is the multiplicative
        identity, so the answer is this dataset's values, as a copy — for the
        aliasing reason :meth:`__radd__` gives.

        Args:
            other: The left-hand operand, which reached here because its own
                `__mul__` declined this dataset.

        Returns:
            Dataset | NotImplemented: A copy of this dataset when `other` is a
            real numeric one, the computed raster for any other real scalar,
            else `NotImplemented`.

        Examples:
            - Fold a list of aligned rasters into their product:

              ```python
              >>> import math
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> rasters = [
              ...     Dataset.from_array(np.full((3, 3), value, "float32"), geo_ref=geo_ref)
              ...     for value in (2.0, 3.0)
              ... ]
              >>> float(np.asarray(math.prod(rasters).read_array()).mean())
              6.0

              ```
            - Multiplying by one is a no-op, so it hands back a copy that still
              carries the source's no-data value:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
              >>> (1 * counts).no_data_value == counts.no_data_value
              True

              ```

        See Also:
            Dataset.__radd__: The additive twin, and the aliasing reason both
                return a copy rather than `self`.
        """
        # `ds * other`, for the reason `__radd__` gives: multiplication commutes and
        # `_arithmetic` already short-circuits the multiplicative identity to `copy()`.
        return self._arithmetic(other, operator.mul)

    def __rsub__(self, other: Any) -> Any:
        """Subtract this raster from a scalar — `100 - ds`, not `ds - 100`.

        Subtraction does not commute, so this cannot defer to :meth:`__sub__`; the
        operands keep the order the caller wrote them in.

        Args:
            other: The left-hand operand, which reached here because its own
                `__sub__` declined this dataset.

        Returns:
            Dataset | NotImplemented: The computed raster, or `NotImplemented` when
            `other` is not a real, non-boolean scalar.

        Examples:
            - Invert a normalised band, the common use for a reflected subtraction:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), 0.25, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((1 - ds).read_array()).mean())
              0.75

              ```
        """
        return self._reflected_arithmetic(other, operator.sub)

    def __rtruediv__(self, other: Any) -> Any:
        """Divide a scalar by this raster — `1000 / ds`, not `ds / 1000`.

        Division does not commute, so this cannot defer to :meth:`__truediv__`.

        A cell holding zero divides to an infinity, and that infinity is **stored as a
        value**, not masked: :meth:`combine` derives `NaN` as the result's sentinel but
        has no non-finite handling, so only a `0/0` — which is `NaN` — reads as a gap.
        numpy's own `RuntimeWarning: divide by zero` reaches the caller. Mask the zeros
        first, or post-process with :meth:`apply`, if an infinity is not what you want
        downstream.

        Args:
            other: The left-hand operand, which reached here because its own
                `__truediv__` declined this dataset.

        Returns:
            Dataset | NotImplemented: The computed raster, or `NotImplemented` when
            `other` is not a real, non-boolean scalar.

        Warns:
            RuntimeWarning: numpy's own `divide by zero` / `invalid value`
                warning, raised where a cell of this raster holds zero.

        Examples:
            - Turn a rate into its reciprocal:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((1 / ds).read_array()).mean())
              0.25

              ```
        """
        return self._reflected_arithmetic(other, operator.truediv)

    def __rpow__(self, other: Any) -> Any:
        """Raise a scalar to this raster's cells — `2 ** ds`, not `ds ** 2`.

        Exponentiation does not commute, so this cannot defer to :meth:`__pow__`; the
        operands keep the order the caller wrote them in, computed through
        :meth:`Analysis._fold` (one read of this raster). `2 ** ds` takes whatever dtype
        NumPy makes of the base and the cells, exactly as `ds ** other` does.

        Args:
            other: The left-hand operand, which reached here because its own `__pow__`
                declined this dataset.

        Returns:
            Dataset | NotImplemented: The computed raster, or `NotImplemented` when
            `other` is not a real, non-boolean scalar.

        Raises:
            ValueError: The base is an integer and this raster is an integer band
                holding a negative cell — `2 ** int16(-3)` — which numpy forbids, as
                `ds ** other` does.

        Warns:
            RuntimeWarning: numpy's own warning where the result is non-finite — a
                negative base to a fractional cell gives `nan` (`(-2.0) ** ds`), stored
                as-is, exactly as on `__pow__`.

        Examples:
            - Two raised to an exponent field:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((2 ** ds).read_array())[0, 0])
              8.0

              ```
        """
        return self._reflected_arithmetic(other, operator.pow)

    def __neg__(self) -> Any:
        """Negate every cell, `-ds`, keeping gaps and band dimensions.

        A one-operand transform run through :meth:`Analysis._fold`, so it inherits the
        same no-data domain, band-dimension labelling and dtype behaviour as the binary
        operators: a masked cell stays masked, every band is negated, and a signed band
        keeps its dtype.

        On an **unsigned** band `-ds` wraps modulo the dtype range — `-uint8(3)` is
        `253`, not `-3` — matching numpy and `0 - ds` (its arithmetic equal, folded the
        same way), and unlike `ds * -1`, whose scalar path rejects `-1` as out of range
        for the band. Negate a signed or float band if a true sign flip is wanted.

        Returns:
            Dataset: The negated raster, on this one's grid.

        Examples:
            - Flip the sign of a band:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), 2.5, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray((-ds).read_array())[0, 0])
              -2.5

              ```

        See Also:
            Dataset.__abs__: The magnitude, the other unary transform.
            Analysis._fold: The single-read path the result comes back through.
        """
        return self.analysis._fold(operator.neg)

    def __abs__(self) -> Any:
        """Take the magnitude of every cell, `abs(ds)`, keeping gaps and band dimensions.

        A one-operand transform run through :meth:`Analysis._fold`, so it inherits the
        same no-data domain, band-dimension labelling and dtype behaviour as the binary
        operators: a masked cell stays masked and every band is folded.

        Two numpy-native edges to know: on an unsigned band `abs(ds)` is a no-op (every
        value is already non-negative), and the magnitude of a signed dtype's minimum
        overflows and stays negative — `abs(int16(-32768))` is `-32768`, since `32768`
        does not fit `int16`. Cast to a wider or float band first if that matters.

        Returns:
            Dataset: The magnitude raster, on this one's grid.

        Examples:
            - The magnitude of a signed band:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> ds = Dataset.from_array(np.full((3, 3), -4.0, "float32"), geo_ref=geo_ref)
              >>> float(np.asarray(abs(ds).read_array())[0, 0])
              4.0

              ```

        See Also:
            Dataset.__neg__: The sign flip, the other unary transform.
            Analysis._fold: The single-read path the result comes back through.
        """
        return self.analysis._fold(operator.abs)

    def __lt__(self, other: Any) -> Any:
        """Cell-by-cell `<` against another raster or a real scalar — see :meth:`_arithmetic`."""
        return self._arithmetic(other, operator.lt)

    def __le__(self, other: Any) -> Any:
        """Cell-by-cell `<=` against another raster or a real scalar — see :meth:`_arithmetic`."""
        return self._arithmetic(other, operator.le)

    def __gt__(self, other: Any) -> Any:
        """Cell-by-cell `>` against another raster or a real scalar — see :meth:`_arithmetic`."""
        return self._arithmetic(other, operator.gt)

    def __ge__(self, other: Any) -> Any:
        """Cell-by-cell `>=` against another raster or a real scalar, as a Byte mask.

        See :meth:`_arithmetic` for the mask's dtype, sentinel and NaN rules.

        Examples:
            - Where does the surface stand at least as high as the bare earth:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> surface = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
              >>> bare = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
              >>> mask = surface >= bare
              >>> np.asarray(mask.read_array()).dtype.name, int(mask.no_data_value[0])
              ('uint8', 255)
              >>> bool((np.asarray(mask.read_array()) == 1).all())
              True

              ```
        """
        return self._arithmetic(other, operator.ge)

    def __bool__(self) -> bool:
        """Refuse to collapse a raster into a single true/false.

        `if surface >= bare:` reads like a question, but a comparison between
        two rasters is a *raster* — one answer per cell — so there is no honest
        single truth value to give back. `sorted`, `min`, `max` and `bisect`
        compare and then reduce the same way, and before the comparison
        operators existed they raised `TypeError` on a list of rasters. Letting
        them quietly return the wrong element instead would be strictly worse
        than raising.

        The refusal is class-wide rather than scoped to comparison results,
        which is the choice numpy, pandas and xarray all make. A scoped version
        was tried: mark the raster a comparison produced and refuse only that.
        It fails in both directions — the mark is lost by `copy`, `crop`,
        `to_crs`, `align`, `resample`, a `to_file`/`read_file` round trip and
        pickling, so the hazard returns after one operation; and it survives
        `apply(inplace=True)` and `write_array`, so a raster holding ordinary
        measurements starts refusing. A property that cannot be carried
        correctly is not worth carrying.

        Use `ds is not None` for a presence check, and reduce a comparison
        explicitly — `bool(np.asarray((a >= b).read_array()).all())` — for a
        yes/no.

        Returns:
            bool: Never returns; the annotation is what `__bool__` must declare.

        Raises:
            ValueError: Always.

        Examples:
            - A comparison has to be reduced before it can be a condition:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
              >>> a = Dataset.from_array(np.ones((3, 3), "float32"), geo_ref=geo_ref)
              >>> b = Dataset.from_array(np.zeros((3, 3), "float32"), geo_ref=geo_ref)
              >>> bool(a >= b)
              Traceback (most recent call last):
                  ...
              ValueError: the truth value of a Dataset is ambiguous ...
              >>> bool(np.asarray((a >= b).read_array()).all())
              True

              ```
        """
        raise ValueError(
            "the truth value of a Dataset is ambiguous — a raster holds one "
            "value per cell, and a comparison between two rasters is itself a "
            "raster. Reduce it, e.g. "
            "`bool(np.asarray((a >= b).read_array()).all())`; use "
            "`ds is not None` for a presence check. This is also why `sorted`, "
            "`min` and `max` refuse a list of rasters"
        )

    @property
    def access(self) -> str:
        """
        Access mode.

        Returns:
            str:
                The access mode of the dataset (read_only/write).
        """
        return str(super().access)

    @property
    def raster(self) -> gdal.Dataset:
        """Base GDAL Dataset (read-only)."""
        return super().raster

    @property
    def rows(self) -> int:
        """Number of rows in the raster array."""
        return int(self._rows)

    @property
    def columns(self) -> int:
        """Number of columns in the raster array."""
        return int(self._columns)

    @property
    def shape(self) -> tuple[int, int, int]:
        """Shape (bands, rows, columns)."""
        return self.band_count, self.rows, self.columns

    @property
    def epsg(self) -> int | None:
        """EPSG number, or ``None``.

        ``None`` means either the raster has **no CRS at all** — pyramids does
        not assume WGS 84 for an unprojected grid (ARC-26) — or its CRS carries
        no EPSG authority code (a geostationary fixed-grid projection, say).
        Read :attr:`crs` to tell the two apart: it is empty in the first case and
        a WKT string in the second.
        """
        return self._epsg

    @epsg.setter
    def epsg(self, value: int):
        """EPSG number.

        Raises:
            ReadOnlyError: The dataset is opened read-only.
        """
        self._require_writable("set the EPSG code")
        sr = sr_from_epsg(value)
        self.raster.SetProjection(sr.ExportToWkt())
        self._update_inplace(self._raster)

    @property
    def crs(self) -> str:
        """Coordinate reference system.

        Returns:
            str:
                the coordinate reference system of the dataset.

        See Also:
            Dataset.set_crs : Set the Coordinate Reference System (CRS).
            Dataset.to_crs : Reproject the dataset to any projection.
            Dataset.epsg : epsg number of the dataset coordinate reference system.
        """
        return self._get_crs()

    @crs.setter
    def crs(self, value: str):
        """Coordinate reference system.

        Args:
            value (str):
                WellKnownText (WKT) string.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk (setting the CRS
                would otherwise silently spill a PAM sidecar).

        See Also:
            - Dataset.set_crs: Set the Coordinate Reference System (CRS).
            - Dataset.to_crs: Reproject the dataset to any projection.
            - Dataset.epsg: EPSG number of the dataset coordinate reference system.
        """
        self.set_crs(value)

    @property
    def cell_size(self) -> float:
        """Cell size."""
        return float(self._cell_size)

    @property
    def band_count(self) -> int:
        """Number of bands in the raster."""
        return int(self._band_count)

    @property
    def band_names(self) -> list[str]:
        """Band names."""
        return self._get_band_names()

    @band_names.setter
    def band_names(self, name_list: list):
        """Band names setter.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk (a bare
                `SetDescription` would otherwise silently spill a PAM sidecar).
        """
        self._require_writable("set band names")
        self.bands._set_band_names(name_list)

    @property
    def band_units(self) -> list[str]:
        """Facade — delegates to :attr:`Bands.band_units <pyramids.dataset.engines.Bands.band_units>`."""
        return self.bands.band_units

    @band_units.setter
    def band_units(self, value: list[str]):
        """Facade setter.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk.
        """
        self.bands.band_units = value

    def convert_units(self, target: str, band: int | None = None) -> Dataset:
        """Convert band values to ``target`` units, returning a new Dataset.

        Unlike the :attr:`band_units` setter — which only relabels bands — this
        actually transforms the values using a small affine conversion table
        (see :func:`pyramids.dataset.ops.units.convert_array`) and records the new
        unit on the result. The output is a new in-memory `float64` Dataset; the
        source is left untouched.

        The values converted are the physical ones `read_array` returns, so a
        CF-packed band (`scale_factor` / `add_offset`) is unpacked first and the
        result, holding computed values, declares no packing. No-data cells are
        found in the stored values, where the sentinel lives, and keep the declared
        `no_data_value` unchanged rather than being converted as if they were data.

        Args:
            target: Target unit label (e.g. ``"celsius"``, ``"hPa"``, ``"knots"``).
            band: Zero-based band index to convert. ``None`` (default) converts every
                band; bands already in ``target`` units are passed through unchanged.

        Returns:
            A new :class:`Dataset` with converted values and updated
            :attr:`band_units`.

        Raises:
            ValueError: ``band`` is out of range, a converted band has no source unit
                set, or the ``(source, target)`` pair is unsupported.

        Examples:
            - Convert a Kelvin raster to Celsius and read the new values:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.array([[273.15, 283.15], [293.15, 303.15]]),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ... )
                >>> ds.band_units = ["K"]
                >>> converted = ds.convert_units("celsius")
                >>> converted.read_array().tolist()
                [[0.0, 10.0], [20.0, 30.0]]
                >>> converted.band_units
                ['celsius']

                ```
            - An unsupported target raises a clear error:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset
                >>> ds = Dataset.from_array(
                ...     np.array([[273.15]]),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ... )
                >>> ds.band_units = ["K"]
                >>> try:
                ...     ds.convert_units("furlongs")
                ... except ValueError as exc:
                ...     print("No unit conversion" in str(exc))
                True

                ```
            - A packed band is converted from its physical values, and its gap keeps
              the sentinel:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> packed = Dataset.from_array(
                ...     np.array([[10, -9999]], dtype="int16"),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ...     no_data_value=-9999,
                ... )
                >>> packed.offset = [273.15]
                >>> packed.band_units = ["K"]
                >>> converted = packed.convert_units("celsius")
                >>> [round(value, 6) for value in converted.read_array().ravel().tolist()]
                [10.0, -9999.0]
                >>> converted.scale, converted.offset
                ([1.0], [0])

                ```
        """
        if band is not None and not 0 <= band < self.band_count:
            raise ValueError(
                f"band {band} is out of range for a {self.band_count}-band dataset."
            )

        band_indices = range(self.band_count) if band is None else [band]
        source_units = list(self.band_units)
        new_units = list(self.band_units)

        # `squeeze=True` keeps the classic flattened `(bands, rows, cols)` this per-band unit
        # conversion expects, not the dimension-preserving default (#1241).
        full = self.read_array(squeeze=True)
        # The gaps are found in the stored counts, where the sentinel lives; the values
        # converted are the physical ones. Comparing the physical read against the
        # stored `-9999` matched nothing, so a packed band's gap was converted as if it
        # were a temperature (-98.49 K came out -371.64 degC) under a declared -9999.
        stored = np.asarray(self.read_array(unpack=False, squeeze=True))
        single_band = self.band_count == 1
        stack = full[np.newaxis, ...] if single_band else full
        stored_stack = stored[np.newaxis, ...] if single_band else stored
        # astype(copy=True by default) already returns a fresh writable array;
        # the trailing .copy() was a redundant second full-cube copy.
        out = stack.astype("float64")
        no_data = self.no_data_value

        for index in band_indices:
            layer = out[index]
            nodata_value = no_data[index]
            mask = (
                stored_stack[index] == nodata_value
                if nodata_value is not None
                else None
            )
            converted = convert_array(layer, source_units[index], target)
            if mask is not None:
                converted[mask] = nodata_value
            out[index] = converted
            new_units[index] = target

        result_array = out[0] if single_band else out
        # `Dataset.from_array`, not `self.from_array`: this method is inherited
        # by NetCDF / Container / Variable, whose override returns a *bandless*
        # Container -- so the `band_units` assignment below died with
        # `IndexError: index 0 is out of bounds for axis 0 with size 0`, three
        # frames from the cause. A unit conversion yields a plain raster in
        # every case, so the base constructor is the right one to name.
        result = Dataset.from_array(
            result_array,
            no_data_value=list(no_data),
            geo_ref=GeoReference(
                geo=self.geotransform, epsg=crs_spec(self.epsg, self.crs)
            ),
        )
        result.band_units = new_units
        return result

    @property
    def no_data_value(self) -> tuple:
        """Per-band nodata markers as an immutable tuple.

        Returns a `tuple` (not a `list`) to make the read-only
        contract explicit — assign through the setter to change
        values; mutating the returned object never propagates to
        the underlying state.

        **The entries are numbers, not necessarily Python `int`s.** No dtype
        fabricates a sentinel on a caller's behalf: a `NaN` asked of an integer
        band is reported back as `NaN` and an **unset** no-data as `None`,
        whatever the dtype, rather than being answered with a number the band's
        real data may already hold. Writing such a sentinel to the band is the
        step that refuses — `change_no_data_value(None)` on any integer raster
        raises `NoDataValueError`, since there is nothing storable to write.

        A sentinel that is set still round-trips through GDAL's
        `SetNoDataValue`, which takes a C double, so a `uint16` band asked for
        `65535` reports `(np.float64(65535.0),)`. Compare with `==` rather than
        `is`, and call `float(...)` / `int(...)` before anything that needs a
        builtin (JSON, `%` formatting of an `int`). `uint64` is the one row
        that stays a numpy *integer*, since its maximum has no exact float64:
        it reports `np.uint64(2**64 - 1)`. See `docs/migration.md`,
        dataset / unreleased.

        Returns:
            tuple: One entry per band, in band order -- a number, or `None` for
            a band that declares no sentinel.

        Examples:
            - A band created with a sentinel reports it, through GDAL's C
              double:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
                >>> raster = Dataset.from_array(
                ...     np.ones((4, 4), "float32"), geo_ref=geo_ref, no_data_value=-9999.0
                ... )
                >>> raster.no_data_value
                (np.float64(-9999.0),)

                ```
            - An integer band asked for `NaN` reports `NaN`, not a fabricated
              maximum, so nothing in it is marked absent:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
                >>> raster = Dataset.create(
                ...     rows=4, columns=4, bands=1, dtype="uint16",
                ...     no_data_value=np.nan, geo_ref=geo_ref,
                ... )
                >>> bool(np.isnan(raster.no_data_value[0]))
                True

                ```
            - One entry per band, so a two-band raster reports a pair:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
                >>> raster = Dataset.from_array(
                ...     np.ones((2, 4, 4), "float32"), geo_ref=geo_ref, no_data_value=0.0
                ... )
                >>> len(raster.no_data_value)
                2

                ```

        See Also:
            change_no_data_value: Rewrites the cells as well as the
                declaration, and refuses a sentinel the band cannot store.
        """
        return tuple(self._no_data_value)

    @no_data_value.setter
    def no_data_value(self, value: list | tuple | np.ndarray | Number):
        """Set the no_data_value marker on every band.

        Args:
            value: Either a scalar (broadcast to all bands) or a
                sequence (`list`, `tuple`, or 1-D :class:`numpy.ndarray`)
                with `len == band_count` providing one value per band.
                A 0-D ndarray is treated as a scalar.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk (a bare
                `SetNoDataValue` would otherwise silently mutate only the
                in-memory attribute, persisting nothing).
            ValueError: When `value` is a sequence whose length
                differs from `band_count`, or a multi-dimensional
                ndarray (only 0-D scalars and 1-D sequences are
                accepted).

        Notes:
            - The setter does not change the values of the cells to the new no_data_value, it only changes the
            `no_data_value` attribute.
            - Use this method to change the `no_data_value` attribute to match the value that is stored in the cells.
            - To change the values of the cells, to the new no_data_value, use the `change_no_data_value` method.

        See Also:
            - Dataset.change_no_data_value: Change the No Data Value.
        """
        self._require_writable("set the no-data value")
        if isinstance(value, np.ndarray):
            if value.ndim == 0:
                value = value.item()
            elif value.ndim == 1:
                value = value.tolist()
            else:
                raise ValueError(
                    f"no_data_value ndarray must be 0-D (scalar) or 1-D "
                    f"(per-band sequence); got ndim={value.ndim}"
                )
        if isinstance(value, (list, tuple)):
            if len(value) != self.band_count:
                raise ValueError(
                    f"no_data_value sequence length {len(value)} does "
                    f"not match band_count {self.band_count}"
                )
            for i, val in enumerate(value):
                self.bands._change_no_data_value_attr(i, val)
        else:
            for i in range(self.band_count):
                self.bands._change_no_data_value_attr(i, value)

    @property
    def meta_data(self):
        """Meta-data."""
        return super().meta_data

    @meta_data.setter
    def meta_data(self, value: dict[str, str]):
        """Meta-data.

        Raises:
            ReadOnlyError: The dataset is opened read-only.
        """
        self._require_writable("set metadata")
        for key, val in value.items():
            self._raster.SetMetadataItem(key, val)
        # The CF geographic inference reads this metadata (axis units), so the
        # memoised answer is stale once it changes -- and `_epsg` was memoised
        # from it during __init__, so re-derive that too. Dropping only the WKT
        # cache left `.crs` reporting WGS 84 while `.epsg` reported None, a
        # combination documented to mean "a CRS with no EPSG authority".
        self.__dict__.pop("_cf_crs_cache", None)
        self._epsg = self._get_epsg()

    def set_meta_data(
        self, value: dict[str, str] | list[str], domain: str = ""
    ) -> None:
        """Replace a *named* GDAL metadata domain.

        Writes ``value`` into ``domain`` with ``SetMetadata`` — a **replace**, not a
        merge (the replace semantics match the band-level
        :meth:`Bands.set_metadata <pyramids.dataset.engines.Bands.set_metadata>`;
        unlike it, this method **refuses the default domain** — see below). Assigning
        ``{}`` (or ``[]``) empties the domain's keys, though the domain name itself may
        still be listed by :attr:`meta_data_domains`.

        Most domains take a ``KEY=VALUE`` mapping; an ``xml:*`` domain instead takes a
        single-element ``list[str]`` of one XML document, mirroring what
        :meth:`get_meta_data` returns for it (passing a ``dict`` to an ``xml:*`` domain
        is a mistake — GDAL flattens it to ``["KEY=VALUE"]``).

        The **default** domain (``""``) is deliberately rejected: it holds
        GDAL/CF-managed keys — ``AREA_OR_POINT`` and the CF axis metadata that drives
        CRS inference — and a whole-domain replace would silently drop them (and the
        CRS/EPSG caches would then re-derive from the corrupted state). Use the
        :attr:`meta_data` setter for the default domain; it merges per key and
        refreshes those caches.

        Args:
            value: The metadata to write into ``domain`` — a ``dict[str, str]``
                mapping for a ``KEY=VALUE`` domain, or a single-element ``list[str]``
                for an ``xml:*`` domain.
            domain: The named GDAL metadata domain to write (for example
                ``"IMAGE_STRUCTURE"``, ``"RPC"``, or a custom domain). The empty
                default domain is not accepted.

        Raises:
            ValueError: ``domain`` is the empty default domain — use the
                :attr:`meta_data` setter instead.
            ReadOnlyError: The dataset is a read-only on-disk file.
        """
        if not domain:
            raise ValueError(
                "set_meta_data writes named domains only; use the `meta_data` setter "
                "for the default domain (it merges per key and refreshes CRS caches)."
            )
        self._require_writable("set metadata")
        self._raster.SetMetadata(value, domain)

    def open_subdataset(self, key: int | str) -> Dataset:
        """Open one of this container's subdatasets, carrying its open context.

        Resolves ``key`` against :attr:`subdatasets` and reopens the chosen nested
        raster with this dataset's access mode, GDAL environment, and open options.

        The result is a **base** :class:`Dataset`: a subdataset connection string is
        a classic-mode raster reference, so it is opened as an ordinary raster
        (unlike :meth:`SubDataset.open`, this carries the parent's access mode, GDAL
        env, and open options). The parent's open options are reapplied verbatim to
        the child open. If the parent is open in update mode the child is opened in
        update mode too; not every driver supports updating a subdataset connection
        string, so a write-mode open can fail for some containers. For a ``NetCDF``
        container, use
        :meth:`~pyramids.netcdf.netcdf.NetCDF.get_variable` / ``NetCDF.variables``
        instead when you want the multidimensional, ``NetCDF``-preserving view of a
        variable — those handle the multidim open a raw subdataset string cannot.

        Args:
            key: An index into :attr:`subdatasets` (0-based; negative indices count
                from the end, per Python list semantics), or a subdataset's full
                ``name`` (its GDAL connection string).

        Returns:
            Dataset: The opened subdataset as a base ``Dataset``.

        Raises:
            TypeError: ``key`` is neither an ``int`` index nor a ``str`` name.
            IndexError: ``key`` is an out-of-range index.
            ValueError: ``key`` is a name that is not among this container's
                subdatasets.
        """
        subs = self.subdatasets
        if isinstance(key, bool):
            raise TypeError(
                f"key must be an int index or a str name, not bool: {key!r}"
            )
        if isinstance(key, int):
            name = subs[key].name  # negative indices follow Python list semantics
        elif isinstance(key, str):
            if key not in {sub.name for sub in subs}:
                # Connection strings can embed credentials (signed URLs, SAS tokens);
                # redact before echoing them in the error.
                available = [redact_credentials(sub.name) for sub in subs]
                raise ValueError(
                    f"{redact_credentials(key)!r} is not a subdataset of this "
                    f"dataset; available: {available}"
                )
            name = key
        else:
            raise TypeError(
                f"key must be an int index or a str name, got {type(key).__name__}"
            )
        # Open the classic-mode subdataset string as a base Dataset. read_file both
        # installs the captured GDAL env around the open (so remote credentials apply)
        # and re-attaches it to the result, so no separate context/attach is needed.
        # warn_on_container=False: the caller deliberately drilled into a subdataset, so
        # a container warning here (if the target is itself a nested container) is noise.
        return Dataset.read_file(
            name,
            read_only=self.access == "read_only",
            gdal_env=self._gdal_env or None,
            open_options=list(self._open_options) or None,
            warn_on_container=False,
        )

    @property
    def band_meta_data(self) -> list[dict[str, str]]:
        """Per-band metadata, one mapping per band, in band order.

        The per-band sibling of :attr:`meta_data`. Facade — delegates to
        :attr:`Bands.metadata <pyramids.dataset.engines.Bands.metadata>`; see it for
        the empty-band and default-domain conventions.

        Returns:
            list[dict[str, str]]: One mapping per band (0-based, band order); an empty
            ``dict`` for a band with no metadata.
        """
        return self.bands.metadata

    @band_meta_data.setter
    def band_meta_data(self, value: list[dict[str, str]]) -> None:
        """Replace each band's metadata (one mapping per band).

        Facade setter — delegates to
        :attr:`Bands.metadata <pyramids.dataset.engines.Bands.metadata>`, which
        replaces (does not merge) each band's default-domain metadata.

        Raises:
            ReadOnlyError: The dataset is a read-only on-disk file.
            ValueError: ``value`` does not carry exactly one mapping per band.
        """
        self.bands.metadata = value

    @property
    def file_name(self) -> str:
        """File name."""
        return super().file_name

    @property
    def driver_type(self):
        """Driver Type."""
        return super().driver_type

    @property
    def scale(self) -> list[float]:
        """Facade — delegates to :attr:`Bands.scale <pyramids.dataset.engines.Bands.scale>`.

        The CF packing factor: how the real-world values are **stored**, not what the
        values you hold already mean. `real = stored * scale + offset`.

        Since #1124 a read applies it, so :meth:`read_array` hands back real-world values
        and this stays the recipe describing the file. The two must not be applied twice:
        an array that has already been unpacked belongs in a dataset that declares no
        packing (`scale == 1`), which is what :meth:`apply` and
        :meth:`from_array` produce. An operation that copies the *stored* bytes --
        :meth:`copy`, a `CreateCopy` write -- carries the recipe along with them instead,
        and stays consistent that way.

        This reports each GDAL band's own slot. `NetCDF` overrides it to report the
        variable's own `_scale` when it carries one, since a read applies that ahead of
        the band's (see `_effective_packing`) -- so on every class the property names the
        factor the values are actually unpacked with.

        Returns:
            list[float]: One factor per band; `1.0` where a band is not packed.
        """
        return self.bands.scale

    @scale.setter
    def scale(self, value: list[float]):
        """Facade setter.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk.
        """
        self.bands.scale = value

    @property
    def offset(self):
        """Facade — delegates to :attr:`Bands.offset <pyramids.dataset.engines.Bands.offset>`.

        The additive half of the CF packing, `real = stored * scale + offset`. See
        :attr:`scale` for how the stored form and the values' meaning are kept apart;
        like it, `NetCDF` reports the variable's own `_offset` when it carries one.

        Returns:
            list[float]: One offset per band; `0` where a band is not packed.
        """
        return self.bands.offset

    @offset.setter
    def offset(self, value: list[float]):
        """Facade setter.

        Raises:
            ReadOnlyError: The dataset is opened read-only on-disk.
        """
        self.bands.offset = value

    @property
    def top_left_corner(self):
        """Top left corner coordinates.

        See Also:
            - Dataset.geotransform: Dataset geotransform.
        """
        return super().top_left_corner

    @property
    def bounds(self) -> GeoDataFrame:
        """Bounds - the bbox as a geodataframe with a polygon geometry.

        See Also:
            - Dataset.bbox: Dataset bounding box.
        """
        return self._calculate_bounds()

    @property
    def bbox(self) -> list:
        """The raster's map-space bounding box, ``[xmin, ymin, xmax, ymax]``.

        Always normalised min-before-max on each axis, whatever the
        geotransform's orientation: a south-up (positive ``geotransform[5]``),
        east-left (negative ``geotransform[1]``) or rotated grid returns a proper
        box, not an inverted one. Derived from
        :meth:`~pyramids.dataset.transform.GeoTransform.extent`.

        Examples:
            - A north-up raster spans its cells:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=3857),
                ... )
                >>> ds.bbox
                [0.0, 0.0, 3.0, 2.0]

                ```
            - A south-up raster (positive y step) reports the same box, not an
              inverted one:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 0.0, 0.0, 1.0), epsg=3857),
                ... )
                >>> ds.bbox
                [0.0, 0.0, 3.0, 2.0]

                ```

        See Also:
            - Dataset.bounds: Dataset bounding polygon.
        """
        return self._calculate_bbox()

    def to_stac_item(
        self,
        item_id: str,
        *,
        asset_href: str,
        datetime=None,
        start_datetime=None,
        end_datetime=None,
        asset_key: str = "data",
        asset_media_type: str | None = None,
        asset_roles: Sequence[str] = ("data",),
        bands: BandMetadata | None = None,
        footprint: Footprint | None = None,
        extensions: StacExtensions | None = None,
    ) -> dict:
        """Describe this raster as a STAC Item dict (proj + raster extensions).

        Thin forwarder to :func:`pyramids.dataset._stac.to_stac_item` — the
        inverse of :meth:`DatasetCollection.from_stac`. Returns a plain
        STAC-JSON dict (pystac not required); the footprint is this dataset's
        bounding rectangle reprojected to EPSG:4326, or the polygonised extent
        of its valid pixels with `footprint=Footprint(mode="data")`.

        Args:
            item_id: The STAC Item id.
            asset_href: Href to record for the single data asset.
            datetime: Item datetime (`datetime.datetime` or RFC 3339 string).
                `None` with no range defaults to the current UTC time; `None`
                with `start_datetime`/`end_datetime` writes a null `datetime`
                plus the range (the STAC-valid null-datetime form).
            start_datetime: Optional range start, written to
                `properties.start_datetime`.
            end_datetime: Optional range end, written to
                `properties.end_datetime`.
            asset_key: Key for the data asset (default `"data"`).
            asset_media_type: Optional media type for the asset.
            asset_roles: STAC `roles` for the asset (default `("data",)`).
            bands: How much per-band metadata the asset publishes — the
                `statistics` / `histogram` / `eo:bands` blocks that make GDAL
                look at the bands. See
                :class:`~pyramids.dataset.stac_options.BandMetadata`; `None`
                (default) measures nothing.
            footprint: How the Item's geometry and bbox are derived from this
                dataset's extent, and to how many decimals the result is
                rounded. See
                :class:`~pyramids.dataset.stac_options.Footprint`; `None`
                (default) is the bounding rectangle at 6 decimals.
            extensions: Which STAC extension blocks are stamped onto the Item.
                See :class:`~pyramids.dataset.stac_options.StacExtensions`;
                `None` (default) populates both `proj` and `raster`.

        Returns:
            dict: The STAC Item (a GeoJSON Feature).

        Examples:
            - Describe an in-memory raster: the Item is a GeoJSON Feature whose bbox is
              the dataset's extent in EPSG:4326, and both extensions are stamped on:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
                ... )
                >>> item = ds.to_stac_item(
                ...     "scene-1", asset_href="scene.tif", datetime="2023-06-01T00:00:00Z"
                ... )
                >>> item["type"], item["id"]
                ('Feature', 'scene-1')
                >>> item["bbox"]
                [0.0, 0.0, 2.0, 2.0]
                >>> item["properties"]["proj:epsg"], item["properties"]["proj:shape"]
                (4326, [2, 2])
                >>> item["assets"]["data"]["href"]
                'scene.tif'

                ```
            - Name the asset and its media type, and give it extra roles:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
                ... )
                >>> item = ds.to_stac_item(
                ...     "scene-1",
                ...     asset_href="red.tif",
                ...     datetime="2023-06-01T00:00:00Z",
                ...     asset_key="red",
                ...     asset_media_type="image/tiff; application=geotiff",
                ...     asset_roles=("data", "reflectance"),
                ... )
                >>> sorted(item["assets"])
                ['red']
                >>> item["assets"]["red"]["type"]
                'image/tiff; application=geotiff'
                >>> item["assets"]["red"]["roles"]
                ['data', 'reflectance']

                ```
            - A datetime range with no instant writes the STAC-valid null `datetime`
              plus the range:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
                ... )
                >>> item = ds.to_stac_item(
                ...     "scene-1",
                ...     asset_href="scene.tif",
                ...     start_datetime="2023-06-01T00:00:00Z",
                ...     end_datetime="2023-06-02T00:00:00Z",
                ... )
                >>> item["properties"]["datetime"] is None
                True
                >>> item["properties"]["start_datetime"], item["properties"]["end_datetime"]
                ('2023-06-01T00:00:00Z', '2023-06-02T00:00:00Z')

                ```

        See Also:
            - pyramids.dataset.stac_options.BandMetadata: the opt-in band blocks.
            - pyramids.dataset.stac_options.Footprint: how the geometry is derived.
            - pyramids.dataset.stac_options.StacExtensions: which extensions are stamped on.
            - DatasetCollection.from_stac: the inverse — Items back into a cube.
        """
        # Imported here to avoid the dataset <-> stac import cycle at load time.
        from pyramids.dataset._stac import to_stac_item

        return to_stac_item(
            self,
            item_id,
            asset_href=asset_href,
            datetime=datetime,
            start_datetime=start_datetime,
            end_datetime=end_datetime,
            asset_key=asset_key,
            asset_media_type=asset_media_type,
            asset_roles=asset_roles,
            bands=bands,
            footprint=footprint,
            extensions=extensions,
        )

    @property
    def total_bounds(self) -> np.typing.NDArray:
        """Bounding box `[minx, miny, maxx, maxy]` as a NumPy array.

        introduced this property so that `Dataset` and
        :class:`pyramids.feature.FeatureCollection` expose the same
        shape (`GeoDataFrame.total_bounds` is the geopandas name
        for exactly this array), letting both classes satisfy the
        :class:`pyramids.base.protocols.SpatialObject` protocol.
        """
        return np.asarray(self._calculate_bbox())

    @property
    def lon(self) -> np.typing.NDArray:
        """Longitude / x cell-centre coordinates.

        Uses the geotransform's pixel width (``geotransform[1]``) so the axis is
        correct even when cells are not square (pixel width != pixel height). Reads the
        cached ``_geotransform`` (like :attr:`top_left_corner`) rather than the
        ``geotransform`` property, so subclasses that derive ``geotransform`` from
        ``lon``/``lat`` (e.g. :class:`~pyramids.netcdf.NetCDF`) do not recurse.

        Examples:
            - Read the column-centre longitudes of a small raster:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
                ... )
                >>> ds.lon.tolist()
                [0.25, 0.75, 1.25]

                ```

        See Also:
            - Dataset.x: Dataset x coordinates.
            - Dataset.lat: Dataset latitude.
        """
        # Built from the cached `_geotransform` (not the `geotransform` property) so
        # a subclass that derives `geotransform` from `lon`/`lat` does not recurse.
        # `x_axis` reads the signed pixel width (`geotransform[1]`), ignoring rotation.
        return GeoTransform(*self._geotransform).x_axis(self.columns)

    @property
    def lat(self) -> np.typing.NDArray:
        """Latitude / y cell-centre coordinates.

        Uses the geotransform's **signed** pixel height (``geotransform[5]``) rather
        than :attr:`cell_size` (which only tracks pixel width), so the axis is correct
        for non-square cells and honours the step's sign — a north-up raster (negative
        ``geotransform[5]``) descends from north to south and a south-up one (positive
        ``geotransform[5]``) ascends, mirroring how :attr:`lon` honours
        ``geotransform[1]``. Reads the cached ``_geotransform`` (like
        :attr:`top_left_corner`) rather than the ``geotransform`` property, so
        subclasses that derive ``geotransform`` from ``lon``/``lat`` (e.g.
        :class:`~pyramids.netcdf.NetCDF`) do not recurse.

        Examples:
            - A north-up raster's row-centre latitudes decrease from north to south:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
                ... )
                >>> ds.lat.tolist()
                [-0.25, -0.75]

                ```
            - A south-up raster (positive ``geotransform[5]``) ascends instead:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 0.0, 0.0, 1.0), epsg=3857),
                ... )
                >>> ds.lat.tolist()
                [0.5, 1.5]

                ```
            - With non-square cells the latitude axis uses the pixel height, not the
              pixel width:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(geo=(10.0, 2.0, 0.0, 50.0, 0.0, -1.0), epsg=4326),
                ... )
                >>> ds.lat.tolist()
                [49.5, 48.5]

                ```

        See Also:
            - Dataset.x: Dataset x coordinates.
            - Dataset.y: Dataset y coordinates.
            - Dataset.lon: Dataset longitude.
        """
        # Built from the cached `_geotransform` (not the `geotransform` property) so
        # a subclass that derives `geotransform` from `lon`/`lat` does not recurse.
        # `y_axis` reads the signed pixel height (`geotransform[5]`), so a north-up
        # grid descends and a south-up one ascends.
        return GeoTransform(*self._geotransform).y_axis(self.rows)

    @property
    def x(self) -> np.typing.NDArray:
        """X cell-centre coordinates (alias of :attr:`lon`).

        Examples:
            - x mirrors lon for the same raster:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
                ... )
                >>> ds.x.tolist()
                [0.25, 0.75, 1.25]

                ```

        See Also:
            - Dataset.lon: the longitude axis this property aliases.
            - Dataset.y: Dataset y coordinates.
        """
        return self.lon

    @property
    def y(self) -> np.typing.NDArray:
        """Y cell-centre coordinates (alias of :attr:`lat`).

        Examples:
            - y mirrors lat for the same raster:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 3)),
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
                ... )
                >>> ds.y.tolist()
                [-0.25, -0.75]

                ```

        See Also:
            - Dataset.lat: the latitude axis this property aliases.
            - Dataset.x: Dataset x coordinates.
        """
        return self.lat

    @property
    def gdal_dtype(self):
        """Data Type."""
        return [
            self.raster.GetRasterBand(i).DataType for i in range(1, self.band_count + 1)
        ]

    @property
    def numpy_dtype(self) -> list[type]:
        """List of the numpy data Type of each band, the data type is a numpy function."""
        return [gdal_to_numpy_type(code) for code in self.gdal_dtype]

    @property
    def dtype(self) -> list[str]:
        """The data type of each band, as a string.

        numpy's spelling wherever numpy has one -- so a Byte band reports
        `uint8`, which is what STAC's `raster:bands[].data_type` wants and what
        this branch changed it to. GDAL's complex-integer and complex-half
        types have no numpy name (numpy's narrowest complex is a pair of
        float32), so those keep the catalog's own spelling rather than all
        collapsing onto `complex64` and losing which type the band is.

        Returns:
            list[str]: One name per band, in band order.

        See Also:
            gdal_dtype: The raw GDAL type constants these are derived from.
            pyramids.base._utils.gdal_dtype_name: The per-code mapping.
        """
        return [gdal_dtype_name(code) for code in self.gdal_dtype]

    @classmethod
    def read_file(
        cls,
        path: str | Path,
        read_only=True,
        file_i: int = 0,
        *,
        driver: str | None = None,
        vsi: str | None = None,
        gdal_env: dict[str, str] | None = None,
        open_options: dict[str, str] | list[str] | tuple[str, ...] | None = None,
        warn_on_container: bool = True,
    ) -> Dataset:
        """Open a raster from a path, URL, or archive member.

        Plain local paths, ``/vsi*`` paths, and URL schemes
        (``http(s)://``, ``s3://``, ``gs://``, ``az://``, ``abfs://`` / ``abfss://``,
        ``file://``) are all accepted — URLs are transparently rewritten to
        GDAL's virtual filesystem (GDAL fetches via HTTP range requests for
        ``http(s)``). Compressed archives are detected from the extension; pass
        ``vsi=`` to be explicit about it (e.g. an archive with an unusual
        extension, or to open a specific member by index).

        Args:
            path (str | Path):
                Path or URL of the file to open.
            read_only (bool):
                File mode; set to ``False`` to open in update mode.
            file_i (int):
                Which member to open when ``path`` is (or is forced to be) a
                multi-file archive. Default ``0``. Counts *file* members only,
                in archive order, so a directory entry does not consume an
                index and a member inside a subdirectory has one. It counts
                them the same way whether the archive was recognised by its
                extension or forced with ``vsi=``: those two used to select
                from differently built lists, so one index named two different
                members of one archive. A negative index is refused rather
                than given Python's from-the-end meaning: it names a member of
                an archive the caller has not listed, so it is far more likely
                a bug than an intent. Zip and tar used to answer ``-1`` with
                the last member while gzip refused it.
            driver (str | None):
                Force a specific third-party raster driver registered in the
                ``pyramids.raster_drivers`` entry-point group (see
                :mod:`pyramids.dataset._drivers`), bypassing GDAL — e.g. to read
                an Earth Engine asset or a Sentinel product a plugin provides.
                ``None`` (default) opens through GDAL, with two exceptions that
                still reach a plugin on the bare path: a driver that *pre-empts*
                GDAL for this source (declares the source's suffix/scheme in its
                ``preempts`` and confirms it via ``can_open``) is tried **before**
                GDAL, and a driver whose ``can_open`` claims the source is tried
                **after** GDAL fails to recognise it. The pre-empt check consults
                the driver registry, so a bare install does one cached entry-point
                scan (finding nothing, then reused for every later read) rather
                than none — it never pays per-read discovery, and with no drivers
                registered nothing pre-empts. Raises
                :class:`~pyramids.base._errors.DriverNotExistError` when the named
                driver is not installed.
            vsi (str | None):
                Treat ``path`` as an archive of this kind and open member
                ``file_i`` from inside it: ``"zip"``, ``"tar"`` (also
                ``"tar.gz"`` / ``"tgz"``), ``"gzip"`` (also ``"gz"``), or
                ``"auto"`` (infer from the extension). Default ``None`` —
                ``path`` is opened directly / extension-sniffed as before.
                Works for archives reachable locally or over the network
                (``/vsizip//vsicurl/…`` is built automatically) **provided the
                file name carries a recognised archive extension** — GDAL's
                archive handlers key off the extension, so an extension-less
                download URL must first be fetched and saved with a ``.zip``
                name (or written to ``/vsimem/<name>.zip`` via
                :func:`osgeo.gdal.FileFromMemBuffer`).
            gdal_env (dict[str, str] | None):
                Optional GDAL config (cloud credentials, HTTP knobs) installed
                for this open **and captured on the returned dataset**, so it is
                re-installed around its reads. Needed by the read paths that
                open the file again instead of reusing this handle:
                ``threadsafe=True`` per-thread handles, lazy ``chunks=`` reads
                inside dask tasks, and unpickling on a worker.
                :func:`pyramids.stac.load_asset` passes a signer's
                ``gdal_env()`` here. It does **not** reach a VRT's source opens
                — GDAL ignores the thread-local config there, so
                :func:`pyramids.stac.build_vrt_from_stac` puts those credentials
                in the source path instead. Default ``None`` — no extra config,
                nothing captured.
            open_options:
                GDAL open options as a mapping
                (``{"GEOREF_SOURCES": "INTERNAL"}``) or GDAL's native
                ``["KEY=VALUE"]`` list. Forwarded to the driver and captured on
                the returned :class:`Dataset`, so the paths that reopen the file
                (``threadsafe=True`` handles, lazy ``chunks=`` reads, unpickle on
                a worker) reopen with the same options. Default ``None``.
            warn_on_container:
                When the path opens to a *container* — a raster with no bands of
                its own whose payload is a set of nested subdatasets (NetCDF/HDF/
                Zarr, GRIB, WMS/WMTS, a Sentinel product) — emit a
                :class:`~pyramids.errors.ContainerRasterWarning` naming the
                subdatasets, instead of silently returning a 0-band dataset. Use
                :attr:`subdatasets` to list them and :meth:`open_subdataset` to open
                one. Set ``False`` to open a container quietly (callers that open
                containers on purpose). Default ``True``.

        Returns:
            Dataset:
                Opened dataset instance.

        See Also:
            - :meth:`read_array`: read the values stored in a dataset band.
            - :meth:`from_bytes`: open a raster held in memory.
            - :attr:`gdal_env`: the config captured by ``gdal_env=``.
            - :meth:`pyramids.dataset.DatasetCollection.from_archive`: open
              *every* member of an archive as a temporal stack.
        """
        # An explicit driver= routes straight to that registered third-party raster
        # driver, bypassing GDAL (resolve_driver raises DriverNotExistError if unknown).
        # open_options is passed through to the driver uninterpreted (all of dict / list /
        # tuple / None survive), and the driver's read must return a Dataset.
        if driver is not None:
            selected = resolve_driver(driver)
            _warn_ignored_gdal_args(selected.name, read_only, file_i, vsi, gdal_env)
            return _read_via_driver(selected, str(path), open_options)
        # A registered driver that declares `preempts` for this source's suffix/scheme (and whose
        # can_open confirms it) gets first refusal, *before* GDAL — so a plugin that reads a format
        # better than GDAL's generic container (a Sentinel-2 .SAFE, say) wins the bare path. This
        # is opt-in: a driver with no `preempts` is not consulted, so GDAL-first stays the default
        # and a bare install (which registers no drivers) scans nothing. An explicit `vsi=` is a
        # deliberate "open member N of this archive" intent that outranks pre-emption, so the scan
        # is skipped then (as `driver=` short-circuits above); the first registered pre-empting
        # driver wins a tie, and a debug log records which driver took the read.
        preempting = None if vsi is not None else select_preempting_driver(str(path))
        if preempting is not None:
            logging.getLogger(__name__).debug(
                "read_file: driver %r pre-empted GDAL for %s",
                preempting.name,
                str(path),
            )
            _warn_ignored_gdal_args(preempting.name, read_only, file_i, vsi, gdal_env)
            return _read_via_driver(preempting, str(path), open_options)
        # Normalize once here so the value captured on the instance below is the
        # KEY=VALUE list form (a raw dict would lose its values when the base
        # __init__ tuple-ifies it). _io.read_file re-normalizes idempotently for
        # its own direct callers — the double pass is intentional and harmless.
        options = _io.normalize_open_options(open_options)
        try:
            with cloud_config_from_env(gdal_env, path=str(path)):
                src = _io.read_file(
                    path,
                    read_only=read_only,
                    file_i=file_i,
                    vsi=vsi,
                    open_options=options,
                )
        except (FileFormatNotSupportedError, FileNotFoundError, RuntimeError):
            # GDAL could not open the source. For a source with a suffix/scheme the pre-empt scan
            # above already warmed the discovery cache; for a tokenless source this failed read is
            # what warms it. Either way, give a *claiming* registered driver a chance
            # (an ``ee://`` asset id, a ``.SAFE`` directory, an FCI ``.nat`` granule); the scan
            # routes only to a driver whose can_open claims the source. ``ee://`` / ``s3://``
            # surface as a bare RuntimeError from GDAL, which is why RuntimeError is caught — a
            # claimed source is handed to its driver even then, so a driver's can_open should
            # stay specific. A source no driver claims re-raises GDAL's own error unchanged (a
            # missing file stays FileNotFoundError, a corrupt raster keeps its read error), so
            # read_file's error contract does not depend on whether a plugin is installed.
            fallback = select_driver(str(path), None)
            if fallback is None:
                raise
            _warn_ignored_gdal_args(fallback.name, read_only, file_i, vsi, gdal_env)
            return _read_via_driver(fallback, str(path), open_options)
        dataset = cls(
            src,
            access="read_only" if read_only else "write",
            gdal_env=gdal_env,
            open_options=options,
        )
        if warn_on_container and not dataset.band_count:
            subdatasets = dataset.subdatasets
            if subdatasets:
                count = len(subdatasets)
                # Cap the preview so a many-variable container (tens of NetCDF/HDF
                # variables) does not produce an unbounded warning string.
                shown = [redact_credentials(sub.name) for sub in subdatasets[:10]]
                if count > len(shown):
                    shown.append(f"… and {count - 10} more")
                warnings.warn(
                    f"{redact_credentials(str(path))!r} is a container raster with no "
                    f"bands of its own; it has {count} subdataset(s). Use "
                    f".subdatasets to list them and .open_subdataset(<index or name>) "
                    f"to open one. Available: {shown}",
                    ContainerRasterWarning,
                    stacklevel=2,
                )
        return dataset

    @classmethod
    def from_bytes(
        cls,
        data: bytes | bytearray | memoryview,
        *,
        suffix: str = ".tif",
        name: str | None = None,
        read_only: bool = True,
    ) -> Dataset:
        """Open a raster held in memory as a byte string.

        Writes ``data`` to a temporary GDAL ``/vsimem/`` path and opens
        it — no on-disk temp file needed. Useful for HTTP response
        bodies (``requests.get(url).content``), object-store
        ``get_object`` payloads, database blobs, and test fixtures.

        This is **not** a URL helper. Reading from a URL is already
        supported by :meth:`read_file`, which rewrites ``http(s)://``,
        ``s3://``, ``gs://``, ``az://``, ``abfs://`` / ``abfss://`` and ``file://``
        to GDAL ``/vsi*`` paths. Use ``from_bytes`` only when you
        already hold the bytes.

        The ``/vsimem/`` entry is removed automatically when the
        returned :class:`Dataset` is garbage-collected
        (:func:`weakref.finalize`); :meth:`close` does not need to be
        called for cleanup. Note that an in-memory dataset is **not
        picklable** — :meth:`__reduce__` raises ``TypeError`` for
        ``/vsimem/`` paths; call :meth:`to_file` first to anchor it to
        disk before sending it to another process.

        Args:
            data: Raw bytes of a raster (GeoTIFF, ASCII grid, ...). For
                NetCDF bytes use :meth:`pyramids.netcdf.NetCDF.from_bytes`.
            suffix: Extension hint for GDAL's driver detection. Needed
                only for headerless formats (e.g. ESRI ASCII grid:
                ``suffix=".asc"``); GDAL sniffs anything with a magic
                header regardless. Defaults to ``".tif"``.
            name: Optional label recorded as the dataset's
                :attr:`file_name` (cosmetic only — it is still an
                in-memory dataset). Defaults to ``None``.
            read_only: Open the dataset read-only. Defaults to ``True``.

        Returns:
            Dataset: The opened in-memory dataset.

        Raises:
            TypeError: ``data`` is not a bytes-like object.
            ValueError: GDAL could not open the bytes (corrupt /
                truncated payload, or a headerless format without a
                ``suffix`` hint).

        Examples:
            - Open the bytes of a downloaded GeoTIFF and inspect it (the
              bytes here come from a file, but they could just as well be
              ``requests.get(url).content``):
                ```python
                >>> from pathlib import Path
                >>> from pyramids.dataset import Dataset
                >>> data = Path("tests/data/acc4000.tif").read_bytes()
                >>> ds = Dataset.from_bytes(data, name="downloaded-scene")
                >>> ds.band_count
                1
                >>> ds.shape
                (1, 13, 14)
                >>> ds.epsg
                32618
                >>> ds.file_name
                'downloaded-scene'
                >>> ds.close()

                ```
            - The bytes path yields the same data as opening the file directly:
                ```python
                >>> from pathlib import Path
                >>> from pyramids.dataset import Dataset
                >>> data = Path("tests/data/acc4000.tif").read_bytes()
                >>> from_bytes = Dataset.from_bytes(data)
                >>> from_file = Dataset.read_file("tests/data/acc4000.tif")
                >>> from_bytes.shape == from_file.shape
                True
                >>> from_bytes.epsg == from_file.epsg
                True

                ```
            - An in-memory dataset cannot be pickled — anchor it to disk first:
                ```python
                >>> import pickle
                >>> from pathlib import Path
                >>> from pyramids.dataset import Dataset
                >>> data = Path("tests/data/acc4000.tif").read_bytes()
                >>> try:
                ...     pickle.dumps(Dataset.from_bytes(data))
                ... except TypeError as exc:
                ...     print("to_file" in str(exc))
                True

                ```

        See Also:
            - :meth:`read_file`: open a raster from a path or URL.
            - :meth:`to_file`: write an in-memory dataset to disk.
            - :meth:`pyramids.netcdf.NetCDF.from_bytes`: the NetCDF variant.
        """
        src, vsi_path = _io.bytes_to_gdal(data, suffix=suffix, read_only=read_only)
        try:
            obj = cls(src, access="read_only" if read_only else "write")
        except Exception as e:
            src = None
            _io.silent_unlink(vsi_path)
            raise ValueError(
                "could not open the supplied bytes as a raster dataset "
                f"(the data may be corrupt or truncated): {e}"
            ) from e
        obj._vsimem_path = vsi_path
        weakref.finalize(obj, _io.silent_unlink, vsi_path)
        if name is not None:
            obj._file_name = str(name)
        return obj

    @classmethod
    def from_wcs(
        cls,
        endpoint: str,
        *,
        coverage: str,
        bbox: tuple[float, float, float, float],
        crs: str = _DEFAULT_CRS,
        output_crs: str | None = None,
        resolution: float | tuple[float, float] | None = None,
        version: str | None = None,
        coverage_crs: str | None = None,
        wcs_format: str | None = None,
        output: str | Path | None = None,
        resample: str = "nearest",
        auth: tuple[str, str] | None = None,
        timeout: float = 60.0,
        extra_params: dict[str, str] | None = None,
        direct: bool = False,
        subset_axes: tuple[str, str] | None = None,
    ) -> Dataset:
        """Read a coverage subset from an OGC Web Coverage Service (WCS).

        Fetches a windowed subset of a coverage from a WCS server and returns it
        as a :class:`Dataset`. The transport is GDAL's native WCS driver, so the
        WCS ``1.0.0`` vs ``2.0.x`` dialect fork — ``bbox`` + ``resx/resy`` versus
        named-axis ``subsets`` + ``scaling`` — is handled inside GDAL; the caller
        always supplies a single lon/lat ``bbox`` (plus optional ``resolution``
        and ``output_crs``).

        Two things GDAL does **not** do for every server, which this method adds:

        * **CRS shim.** Some servers advertise a coverage CRS under an authority
          code absent from the local PROJ database (notably ISRIC SoilGrids'
          ``EPSG:152160``, a custom Interrupted Goode Homolosine). GDAL then opens
          the coverage without a spatial reference and cannot place the request
          window. Pass ``coverage_crs`` with the coverage's real CRS and it is
          attached client-side.
        * **bbox reprojection.** ``bbox`` is given in ``crs`` (lon/lat by
          default) and transformed into the coverage's native CRS with ``pyproj``
          before the request, so subsetting lands on the correct pixels even when
          the server only honours its native CRS.

        For a **``GetCoverage``-only endpoint** — a "WCS shim" that returns
        ``502``/``400`` for ``GetCapabilities``/``DescribeCoverage`` but serves
        ``GetCoverage`` (e.g. Copernicus EDO/GDO) — pass ``direct=True``. That skips
        both discovery steps and issues a KVP ``GetCoverage`` built straight from
        ``coverage`` / ``crs`` / ``bbox`` / ``wcs_format`` / ``extra_params``, so the
        caller owns correctness (no capabilities check). For WCS ``2.0.x`` the
        ``SUBSET`` axis labels default to ``("Long", "Lat")`` for a geographic
        ``crs`` — override with ``subset_axes`` if the server names its axes
        differently.

        A non-conformant shim may also reject the spec KVP spellings themselves: the
        Copernicus EDO/GDO MapServer ``500``s on the uppercase ``COVERAGEID`` key and
        on ``SUBSETTINGCRS=`` (it wants a lowercase ``coverageID`` and the WCS-1.x
        ``CRS=``). In direct mode ``extra_params`` can override a built-in KVP by key,
        so pass ``extra_params={"coverageID": <id>, "CRS": <crs>}`` to hand such a
        server its exact spelling — the override replaces the built-in rather than
        duplicating it.

        Args:
            endpoint: The WCS service URL, including any server-specific query
                prefix (e.g. ``"https://maps.isric.org/mapserv?map=/map/nitrogen.map"``).
                Catalog / coverage-name routing belongs in the calling layer, not
                here.
            coverage: The coverage identifier as advertised by
                ``GetCapabilities`` (e.g. ``"nitrogen_0-5cm_mean"``). A value the
                server does not advertise raises :class:`ValueError`.
            bbox: ``(minx, miny, maxx, maxy)`` in ``crs`` order (lon/lat for the
                default ``"EPSG:4326"``). ``minx > maxx`` reads as a window crossing
                the antimeridian, the same wrap :meth:`crop` accepts: it is fetched
                as two ``GetCoverage`` requests either side of the 180 degree seam
                and concatenated into one raster whose longitude runs on past it
                (``170 .. 180`` then ``180 .. 190``). Both halves are read off a
                single open connection, so they come from the same source lattice
                and stitch without resampling, and a half that misses the coverage
                is skipped rather than requested. ``output_crs``, ``resolution`` and
                ``output`` are applied once, to the merged raster. In ``direct``
                mode there is no shared connection: the halves are two separate
                ``GetCoverage`` requests, snapped to ``resolution`` so they land on
                one lattice. Pass a ``resolution`` for a wrapping ``direct`` read —
                without one nothing constrains the server to grid the two halves
                alike, and a mismatch is refused rather than stitched.
            crs: CRS of ``bbox``. Defaults to ``"EPSG:4326"``.
            output_crs: Optional CRS to reproject the result into (any form
                :meth:`to_crs` accepts). ``None`` (default) keeps the coverage's
                native CRS.
            resolution: Output pixel size in the units of ``output_crs`` (or the
                native CRS when ``output_crs`` is ``None``). A scalar gives square
                pixels; an ``(x_res, y_res)`` pair gives non-square pixels.
                ``None`` (default) keeps the coverage's native resolution.
            version: Force a WCS protocol version (``"1.0.0"``, ``"2.0.1"``, …).
                ``None`` (default) lets GDAL negotiate from the server's
                capabilities. Note that some MapServer builds silently downgrade a
                requested ``2.0.x`` to ``1.0.0``.
            coverage_crs: The coverage's CRS, used only when the server's
                advertised CRS does not resolve in PROJ (see the CRS-shim note).
                Any proj4 / WKT / authority string ``pyproj`` understands.
            wcs_format: Optional GDAL ``PreferredFormat`` for the ``GetCoverage``
                response (e.g. ``"GEOTIFF_INT16"``). ``None`` lets GDAL pick from
                the coverage's advertised formats.
            output: Optional path to also write the result to as a GeoTIFF. The
                method still returns the :class:`Dataset`.
            resample: Resampling method for the ``output_crs`` / ``resolution``
                warp. Defaults to ``"nearest"``.
            auth: Optional ``(username, password)`` for Basic-authed services.
            timeout: HTTP timeout in seconds for the metadata / coverage
                requests. Defaults to ``60.0``.
            extra_params: Optional extra ``GetCoverage`` query parameters folded
                into the request (a workaround hook for server quirks). In direct
                mode a key that matches a built-in KVP (case-insensitively, with the
                cross-version pairs ``CRS``/``SUBSETTINGCRS`` and
                ``COVERAGE``/``COVERAGEID`` each treated as one) *overrides* it with
                the given spelling and value — e.g. ``{"coverageID": "spaST"}`` sends
                a lowercase key, ``{"CRS": "EPSG:4326"}`` sends the WCS-1.x CRS token
                instead of ``SUBSETTINGCRS``. Non-matching keys are appended in caller
                order (e.g. a ``TIME`` axis). The fixed protocol keys ``SERVICE`` /
                ``VERSION`` / ``REQUEST`` / ``SUBSET`` cannot be overridden and raise
                :class:`ValueError`; because ``SUBSET`` is locked, an additional
                WCS-2.0 ``SUBSET`` axis (e.g. a temporal subset) cannot be added in
                direct mode — use discovery mode for that. Two keys targeting the
                same built-in parameter (e.g. both ``CRS`` and ``SUBSETTINGCRS``) also
                raise.
            direct: When ``True``, skip ``GetCapabilities``/``DescribeCoverage`` and
                issue a KVP ``GetCoverage`` directly — for shim servers that only
                implement ``GetCoverage``. Defaults to ``False`` (full handshake).
            subset_axes: Direct mode, WCS ``2.0.x`` only — the ``(x, y)`` ``SUBSET``
                axis labels. ``None`` (default) derives them from ``crs``
                (``("Long", "Lat")`` for geographic, ``("X", "Y")`` otherwise). These
                defaults are a best-effort guess — direct mode skips the
                ``DescribeCoverage`` that would reveal the coverage's real (case-
                sensitive) axis labels — so MapServer-family shims often need
                ``subset_axes=("x", "y")`` or the server's exact axis names.

        Returns:
            Dataset: The fetched coverage subset.

        Raises:
            ValueError: ``bbox`` is malformed — an inverted *latitude* range still
                counts, since there is no seam in latitude — ``coverage`` is not
                advertised (discovery mode), ``coverage_crs`` cannot be interpreted,
                the requested window exceeds the pixel ceiling
                (:data:`~pyramids.base._coverage.MAX_PX`; a native-resolution read
                over a wide ``bbox`` — pass a coarser ``resolution`` or a smaller
                ``bbox`` to bound it), or (direct mode) the WCS version is
                unsupported, ``1.0.0`` lacks a ``resolution``, or an ``extra_params``
                key targets a locked protocol parameter.
            pyramids.errors.WCSError: The server could not be reached or returned
                an error / a non-raster (``<ows:ExceptionReport>``) body.

        Examples:
            Read a Netherlands subset of SoilGrids nitrogen (its native CRS needs
            the ``coverage_crs`` shim):

            ```python
            >>> ds = Dataset.from_wcs(  # doctest: +SKIP
            ...     "https://maps.isric.org/mapserv?map=/map/nitrogen.map",
            ...     coverage="nitrogen_0-5cm_mean",
            ...     bbox=(5.0, 51.0, 6.0, 52.0),
            ...     coverage_crs="+proj=igh +lat_0=0 +lon_0=0 +datum=WGS84 +units=m +no_defs",
            ... )

            ```

            Direct mode for a ``GetCoverage``-only endpoint (Copernicus EDO/GDO),
            whose ``GetCapabilities``/``DescribeCoverage`` return ``502``/``400``.
            EDO also rejects the spec KVP spellings, so override the coverage key and
            CRS token via ``extra_params`` to send the lowercase ``coverageID`` and
            the WCS-1.x ``CRS=`` it accepts:

            ```python
            >>> ds = Dataset.from_wcs(  # doctest: +SKIP
            ...     "https://drought.emergency.copernicus.eu/api/wcs?map=DO_WCS",
            ...     coverage="spaST",
            ...     bbox=(10.0, 45.0, 15.0, 48.0),
            ...     crs="EPSG:4326",
            ...     version="2.0.0",
            ...     wcs_format="GEOTIFF",
            ...     direct=True,
            ...     extra_params={
            ...         "coverageID": "spaST",
            ...         "CRS": "EPSG:4326",
            ...         "TIME": "2023-06-01",
            ...         "SELECTED_TIMESCALE": "01",
            ...     },
            ... )

            ```

        See Also:
            - :meth:`read_file`: open a raster from a path or URL.
            - :meth:`from_bytes`: open a raster already held in memory.
        """
        return _from_wcs(
            cls,
            endpoint,
            coverage=coverage,
            bbox=bbox,
            crs=crs,
            output_crs=output_crs,
            resolution=resolution,
            version=version,
            coverage_crs=coverage_crs,
            wcs_format=wcs_format,
            output=output,
            resample=resample,
            auth=auth,
            timeout=timeout,
            extra_params=extra_params,
            direct=direct,
            subset_axes=subset_axes,
        )

    @classmethod
    def from_wms(
        cls,
        endpoint: str,
        *,
        layers: str | list[str] | tuple[str, ...],
        bbox: tuple[float, float, float, float],
        crs: str = _DEFAULT_CRS,
        size: tuple[int, int] | None = None,
        resolution: float | tuple[float, float] | None = None,
        image_format: str = "image/png",
        version: str = "1.3.0",
        bands: int = 3,
        output_crs: str | None = None,
        output: str | Path | None = None,
        resample: str = "nearest",
        auth: tuple[str, str] | None = None,
        timeout: float = 60.0,
    ) -> Dataset:
        """Render a WMS ``GetMap`` window into a :class:`Dataset`.

        Fetches a server-rendered map image for ``bbox`` from an OGC Web Map
        Service via GDAL's native WMS driver, and returns it as a georeferenced
        raster. Because WMS renders in the requested ``crs``, the ``bbox`` is the
        request window directly — no client-side reprojection is needed.

        The result is **rendered imagery** (RGB / RGBA pixels), not data values: a
        WMS styles the data server-side. Use :meth:`from_wcs` /
        :meth:`from_ogc_coverages` when you need the underlying coverage values.

        Args:
            endpoint: The WMS base URL, ending with ``?`` or ``&`` so GDAL can
                append the ``GetMap`` query (e.g.
                ``"https://ows.terrestris.de/osm/service?"``). Layer catalogs and
                auth routing belong in the calling layer, not here.
            layers: One layer name, or several to composite, as advertised by the
                service ``GetCapabilities`` (joined with commas for the request).
            bbox: ``(minx, miny, maxx, maxy)`` in ``crs`` order (lon/lat for the
                default ``"EPSG:4326"``). ``minx > maxx`` reads as a window crossing
                the antimeridian, the same wrap :meth:`crop` accepts:
                ``(170, -10, -170, 10)`` is the 20 degrees around Fiji, not the 340
                the corners subtract to. It is served as two ``GetMap`` requests
                either side of the 180 degree seam and stitched into one raster whose
                longitude runs on past it (``170 .. 180`` then ``180 .. 190``);
                ``size`` is the width of the whole result, divided between the halves
                at one shared resolution so the pixel size does not change across the
                seam. Only a geographic ``crs`` has such a seam, so a wrapping bbox
                with a projected one is refused rather than read as inverted.
            crs: CRS of ``bbox`` and of the rendered request. Defaults to
                ``"EPSG:4326"`` (GDAL handles the WMS 1.3.0 lat/lon axis order).
            size: Output image size ``(width, height)`` in pixels. Mutually
                exclusive with ``resolution``; exactly one is required.
            resolution: Output pixel size in ``crs`` units — a scalar (square) or
                ``(x_res, y_res)`` pair — divided into the bbox extent to size the
                image. Mutually exclusive with ``size``. The derived size is capped
                at :data:`~pyramids.base._coverage.MAX_PX` per axis; ``size``
                itself is not, since a number the caller states cannot be amplified
                by a mistake in ``bbox`` the way a derived one can.
            image_format: WMS ``FORMAT`` MIME type. Defaults to ``"image/png"``.
            version: WMS protocol version. Defaults to ``"1.3.0"``.
            bands: Number of bands to request (``3`` RGB, ``4`` RGBA). Defaults to
                ``3``.
            output_crs: Optional CRS to reproject the result into (any form
                :meth:`to_crs` accepts). ``None`` keeps ``crs``.
            output: Optional path to also write the result to as a GeoTIFF.
            resample: Resampling method for the ``output_crs`` warp. Defaults to
                ``"nearest"``.
            auth: Optional ``(username, password)`` for Basic-authed services.
            timeout: HTTP timeout in seconds. Defaults to ``60.0``.

        Returns:
            Dataset: The rendered map window.

        Raises:
            ValueError: ``bbox`` is malformed, ``layers`` is empty, ``size`` /
                ``resolution`` was not given exactly once, or ``resolution`` over
                this ``bbox`` exceeds
                :data:`~pyramids.base._coverage.MAX_PX` on either axis. A wrapping
                ``bbox`` is malformed when ``crs`` is projected, or when a corner
                falls outside ``-180 .. 180`` and "west of the seam" stops meaning
                anything.
            pyramids.errors.WMSError: The server could not be reached or returned a
                non-raster body.

        Examples:
            Render a small OSM window as a 512-px-wide PNG raster:

            ```python
            >>> ds = Dataset.from_wms(  # doctest: +SKIP
            ...     "https://ows.terrestris.de/osm/service?",
            ...     layers="OSM-WMS",
            ...     bbox=(5.0, 51.0, 6.0, 52.0),
            ...     size=(512, 512),
            ... )

            ```

        See Also:
            - :meth:`from_wmts`: the tiled (WMTS) sibling.
            - :meth:`from_wcs`: read coverage *data values* instead of imagery.
        """
        return _from_wms(
            cls,
            endpoint,
            layers=layers,
            bbox=bbox,
            crs=crs,
            size=size,
            resolution=resolution,
            image_format=image_format,
            version=version,
            bands=bands,
            output_crs=output_crs,
            output=output,
            resample=resample,
            auth=auth,
            timeout=timeout,
        )

    @classmethod
    def from_wmts(
        cls,
        endpoint: str,
        *,
        layer: str,
        bbox: tuple[float, float, float, float],
        crs: str = _DEFAULT_CRS,
        tile_matrix_set: str | None = None,
        resolution: float | tuple[float, float] | None = None,
        layer_crs: str | None = None,
        output_crs: str | None = None,
        output: str | Path | None = None,
        resample: str = "nearest",
        auth: tuple[str, str] | None = None,
        timeout: float = 60.0,
    ) -> Dataset:
        """Crop a WMTS tile-pyramid layer to ``bbox`` into a :class:`Dataset`.

        Opens a Web Map Tile Service layer as a full georeferenced tile pyramid
        via GDAL's native WMTS driver, then crops ``bbox`` out of it (reprojecting
        the bbox into the layer's native CRS with ``pyproj``, mirroring
        :meth:`from_wcs`). The result is **rendered imagery** (RGB / RGBA), not data
        values.

        Args:
            endpoint: The WMTS ``GetCapabilities`` URL (e.g.
                ``"https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml"``).
            layer: The layer identifier as advertised by the capabilities document.
                A value the service does not advertise raises :class:`ValueError`
                (with the available layers listed).
            bbox: ``(minx, miny, maxx, maxy)`` in ``crs`` order. ``minx > maxx``
                reads as a window crossing the antimeridian and is read as two crops
                either side of the 180 degree seam, stitched into one raster whose
                longitude continues past it. The seam offset is *measured* in the
                layer's native CRS rather than assumed, so a layer tiled in Web
                Mercator crosses as cleanly as a lon/lat one; a wrapping bbox in a
                projected ``crs`` is still refused, since only lon/lat has the seam.
            crs: CRS of ``bbox``. Defaults to ``"EPSG:4326"``.
            tile_matrix_set: Optional tile-matrix-set id to pin. ``None`` lets GDAL
                pick the layer's default.
            resolution: Output pixel size in the layer's native CRS units — GDAL
                reads from the matching overview level. ``None`` (default) uses the
                finest level, which can be **very large** for a wide bbox; pass
                ``resolution`` to coarsen a large area.
            layer_crs: The layer's CRS, used only when the WMTS layer opens without
                a resolvable spatial reference (any proj4 / WKT / authority string).
            output_crs: Optional CRS to reproject the result into. ``None`` keeps
                the layer's native CRS.
            output: Optional path to also write the result to as a GeoTIFF.
            resample: Resampling method for the crop / warp. Defaults to
                ``"nearest"``.
            auth: Optional ``(username, password)`` for Basic-authed services.
            timeout: HTTP timeout in seconds. Defaults to ``60.0``.

        Returns:
            Dataset: The cropped WMTS window.

        Raises:
            ValueError: ``bbox`` is malformed -- including a wrapping ``bbox`` with
                a projected ``crs`` or a corner outside ``-180 .. 180`` -- ``layer``
                is not advertised, ``layer_crs`` cannot be interpreted, or the
                requested window exceeds the pixel ceiling
                (:data:`~pyramids.base._coverage.MAX_PX`; a finest-level read over a
                wide ``bbox`` — pass a coarser ``resolution`` or a smaller ``bbox``
                to bound it).
            pyramids.errors.WMSError: The server could not be reached or the tile
                read failed.

        Examples:
            Crop a NASA GIBS true-colour window (coarsened to ~0.01° pixels):

            ```python
            >>> ds = Dataset.from_wmts(  # doctest: +SKIP
            ...     "https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml",
            ...     layer="MODIS_Terra_CorrectedReflectance_TrueColor",
            ...     bbox=(5.0, 51.0, 6.0, 52.0),
            ...     resolution=0.01,
            ... )

            ```

        See Also:
            - :meth:`from_wms`: the untiled (WMS ``GetMap``) sibling.
            - :meth:`from_wcs`: read coverage *data values* instead of imagery.
        """
        return _from_wmts(
            cls,
            endpoint,
            layer=layer,
            bbox=bbox,
            crs=crs,
            tile_matrix_set=tile_matrix_set,
            resolution=resolution,
            layer_crs=layer_crs,
            output_crs=output_crs,
            output=output,
            resample=resample,
            auth=auth,
            timeout=timeout,
        )

    @classmethod
    def from_ogc_coverages(
        cls,
        endpoint: str,
        *,
        coverage: str,
        bbox: tuple[float, float, float, float],
        output_crs: str | None = None,
        resolution: float | tuple[float, float] | None = None,
        coverage_crs: str | None = None,
        output: str | Path | None = None,
        resample: str = "nearest",
        auth: tuple[str, str] | None = None,
        timeout: float = 60.0,
    ) -> Dataset:
        """Read a coverage subset from an **OGC API – Coverages** service.

        Fetches a windowed subset of a coverage from an OGC API – Coverages
        service and returns it as a :class:`Dataset`. OGC API – Coverages is the
        modern REST/JSON successor to WCS: a landing page links to
        ``/collections`` and each coverage exposes ``/collections/{id}/coverage``
        with format negotiation. The transport is GDAL's native ``OGCAPI`` driver,
        so discovery, GeoTIFF negotiation and the windowed read happen inside GDAL;
        the caller supplies a single lon/lat ``bbox`` (plus optional ``resolution``
        and ``output_crs``). The driver exposes the coverage as an unbounded virtual
        raster, so the ``bbox`` is applied at read time as a native-CRS ``projWin``
        window (not passed through as a service-side ``bbox`` subset). This is the
        OGC-API-era sibling of :meth:`from_wcs`.

        A ``bbox`` is **required**. The driver exposes the coverage as an unbounded
        virtual raster, so a windowless read is impossible; pyramids projects the
        lon/lat ``bbox`` into the coverage's native CRS and reads it with an
        explicit output-size cap so the fetch always stays bounded.

        The ``coverage`` is validated against a (cached) ``/collections`` document
        so an unadvertised coverage fails fast with a clear :class:`ValueError`
        rather than an opaque driver error.

        Args:
            endpoint: The OGC API landing-page / base URL (e.g.
                ``"https://maps.gnosis.earth/ogcapi"``). Catalog / coverage-name
                routing belongs in the calling layer, not here.
            coverage: The coverage identifier as advertised by ``/collections``
                (e.g. ``"SRTM_ViewFinderPanorama"``). A value the service does not
                advertise raises :class:`ValueError`.
            bbox: **Required** ``(minx, miny, maxx, maxy)`` spatial subset in
                **lon/lat (CRS84)**. It is projected into the coverage's native CRS
                and read as a bounded, size-capped window; an unbounded full read is
                not supported (the virtual raster spans the whole coverage).
                ``minx > maxx`` reads as a subset crossing the antimeridian, as in
                :meth:`from_wcs`, and is read as two windows either side of the 180
                degree seam. With no ``resolution`` the two are sized *together* —
                the combined span is capped once and the resulting pixel size
                applied to both — because sizing each half against the cap on its
                own gives them different pixel sizes and row counts, which cannot be
                concatenated at all.
            output_crs: Optional CRS to reproject the result into (any form
                :meth:`to_crs` accepts). ``None`` (default) keeps the coverage's
                native CRS.
            resolution: Approximate pixel size of the read window, in the units of
                the coverage's **native CRS** (CRS84 degrees by default). A scalar
                gives square pixels; an ``(x_res, y_res)`` pair gives non-square
                pixels; every axis must be strictly positive (:class:`ValueError`
                otherwise). The window size is ``round(span / resolution)`` per
                axis, so the realised cell size equals ``resolution`` exactly only
                when ``span / resolution`` is integral and is otherwise the nearest
                whole-pixel fit. ``None`` (default) caps the longer side of the
                window at 1024 px (preserving the bbox aspect ratio). A window
                larger than 25000 px on either side is rejected with
                :class:`ValueError`. When ``output_crs`` is set, ``resolution``
                sizes the native-CRS read; the reprojected output's pixel size is
                then chosen by the warp.
            coverage_crs: The coverage's CRS, used only when the service's
                advertised CRS does not resolve in PROJ so GDAL opens the coverage
                with no spatial reference. Any proj4 / WKT / authority string
                ``pyproj`` understands. ``None`` (default) relies on the CRS the
                service advertises. Mirrors :meth:`from_wcs`.
            output: Optional path to also write the result to as a GeoTIFF. The
                method still returns the :class:`Dataset`.
            resample: Resampling method for the ``output_crs`` reprojection.
                Defaults to ``"nearest"``.
            auth: Optional ``(username, password)`` for Basic-authed services.
            timeout: HTTP timeout in seconds for the metadata / coverage requests
                (whole seconds; a value below 1 is clamped to 1). Defaults to
                ``60.0``.

        Returns:
            Dataset: The fetched coverage subset.

        Raises:
            ValueError: ``bbox`` is malformed — an inverted *latitude* range
                still counts, since there is no seam in latitude — ``coverage`` is
                not advertised, or ``coverage_crs`` cannot be interpreted.
            pyramids.errors.OGCAPIError: The service could not be reached or
                returned an error / a non-raster body.

        Examples:
            Read a small bbox subset of a public coverage (network call — skipped
            in doctests):

            ```python
            >>> ds = Dataset.from_ogc_coverages(  # doctest: +SKIP
            ...     "https://maps.gnosis.earth/ogcapi",
            ...     coverage="SRTM_ViewFinderPanorama",
            ...     bbox=(5.0, 51.0, 6.0, 52.0),
            ... )

            ```

        See Also:
            - :meth:`from_wcs`: the classic WCS sibling.
            - :meth:`pyramids.feature.FeatureCollection.from_ogc_features`: the OGC
              API – Features (vector) sibling.
            - :meth:`read_file`: open a raster from a path or URL.
        """
        return _from_ogc_coverages(
            cls,
            endpoint,
            coverage=coverage,
            bbox=bbox,
            output_crs=output_crs,
            resolution=resolution,
            coverage_crs=coverage_crs,
            output=output,
            resample=resample,
            auth=auth,
            timeout=timeout,
        )

    def copy(self, path: str | Path | None = None) -> Dataset:
        """Deep copy.

        Args:
            path (str, optional):
                Destination for the copy. `None` (default) copies into memory
                with the `MEM` driver. Otherwise the extension alone selects
                the output format (`.tif` -> GTiff, `.nc` -> netCDF,
                `.png` -> PNG, …), so `copy` doubles as a format conversion
                and is not GeoTIFF-only. The copy is made with `CreateCopy`,
                so a write-by-copy-only format such as PNG or JPEG is accepted
                here even though the `Create`-based constructors
                (`from_array`, `create_empty`) refuse it.

        Returns:
            Dataset: An independent copy. Access mode of the returned
            Dataset:

            * `path is None` (in-memory copy) → `"write"`. The copy is a
              fresh MEM raster that nothing else references, so refusing
              writes on it protects nothing: the source file is untouched
              either way. Propagating the source's mode instead meant a
              `copy()` taken specifically to get a mutable working copy of
              a read-only file could not be written to, and the resulting
              `ReadOnlyError` advised reopening the *source* with
              `read_only=False`, which is not what the caller wanted.
            * `path is not None` and the format supports `Create`
              (GTiff, netCDF, HFA, …) → `"write"`, because the caller
              has just made a new file they presumably want to
              populate.
            * `path is not None` and the format is write-by-copy only
              (`.png`, `.jpg` / `.jpeg`, `.jp2` / `.j2k`, `.asc`) →
              `"read_only"`. `CreateCopy` hands back a read-only
              dataset for those, so claiming otherwise would let a
              write fail inside GDAL instead of raising
              :class:`~pyramids.errors.ReadOnlyError` here.

        Raises:
            DriverNotExistError: `path` has no extension, or one the driver
                catalog does not know.
            FileFormatNotSupportedError: `path` names a format that writes a
                reference rather than a self-contained raster (`.vrt`), which
                would produce a file GDAL cannot reopen.

        Examples:
            - Copy into memory and edit the copy without touching the source:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> src = Dataset.from_array(
                ...     np.zeros((3, 4), dtype="int16"),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ... )
                >>> clone = src.copy()
                >>> clone.write_array(np.full((3, 4), 7, dtype="int16"))
                >>> int(clone.read_array().max()), int(src.read_array().max())
                (7, 0)

                ```
            - The destination extension picks the format, so a copy can convert:
                ```python
                >>> import os, tempfile
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> src = Dataset.from_array(
                ...     np.arange(12, dtype="uint8").reshape(3, 4),
                ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
                ...     no_data_value=None,
                ... )
                >>> out = os.path.join(tempfile.mkdtemp(), "converted.png")
                >>> png = src.copy(out)
                >>> png.raster.GetDriver().ShortName
                'PNG'
                >>> png.close()

                ```
        """
        if path is None:
            path = ""
            driver = MEMORY_DRIVER
            # A MEM copy is a fresh buffer nothing else holds, so it is always
            # writable. Carrying the source's read-only flag over made the copy
            # useless for the case it exists to serve: getting a mutable working
            # copy of a read-only file.
            new_access = "write"
        else:
            # From the extension, not hardcoded: `copy(path="x.nc")` produced a
            # GTiff carrying a netCDF name. `for_copy` because this writes
            # with CreateCopy, which copy-only formats support.
            driver = resolve_output_driver(path, for_copy=True)
            # A copy-only driver returns a read-only handle, so claiming
            # "write" here meant `write_array` leaked a raw GDAL error past
            # the package's own ReadOnlyError guard.
            new_access = "write" if copy_yields_writable(driver) else "read_only"

        src = gdal.GetDriverByName(driver).CreateCopy(str(path), self._raster)
        return Dataset(src, access=new_access)

    def close(self) -> None:
        """Close the dataset.

        Safe to call multiple times — subsequent calls after the first are no-ops.

        Also releases the per-thread file manager created by
        ``read_array(threadsafe=True)``: the calling thread's handle is
        closed eagerly and the manager reference is dropped, so handles
        held by other (finished) threads are released with it. Without
        this, lingering read-only handles would keep the file locked on
        Windows after ``close()``.
        """
        if self._raster is not None:
            self._raster.FlushCache()
            self._raster = None
        manager = getattr(self, "_thread_manager", None)
        if manager is not None:
            manager.close()
            self._thread_manager = None

    @staticmethod
    def _create_dataset(
        cols: int,
        rows: int,
        bands: int,
        dtype: int,
        path: str | Path | None = None,
        options: list[str] | None = None,
    ) -> gdal.Dataset:
        """Create a GDAL driver.

            creates a driver and save it to disk and in memory if the path is not given.

        Args:
            cols (int):
                Number of columns.
            rows (int):
                Number of rows.
            bands (int):
                Number of bands.
            dtype:
                GDAL data type.
            path (str):
                Destination, which alone selects the driver: `None` builds in
                memory (MEM), otherwise the extension decides via
                :func:`~pyramids.dataset._driver.resolve_output_driver`.
            options (list[str] | None):
                GDAL creation options for the disk driver (e.g.
                ``["TILED=YES", "SPARSE_OK=TRUE", "BIGTIFF=YES"]``). When
                `None` (default), GTiff falls back to ``["COMPRESS=LZW"]`` —
                the historical behaviour — and every other disk driver gets an
                empty list. Must not be given without a `path`: the MEM driver
                takes no creation options, so they would be silently dropped.

        Returns:
            gdal.Dataset: The freshly allocated GDAL dataset — in memory when
            `path` is `None`, otherwise created on disk by the driver the
            extension selected.

        Raises:
            ValueError: `options` is given without a `path`.
            DriverNotExistError: `path` has no extension, or one the driver
                catalog does not know.
            FileFormatNotSupportedError: `path`'s extension maps to a
                write-by-copy-only format, which has no working `Create`.
        """
        if path is None and options is not None:
            raise ValueError(
                "creation options need a path to write to; pass path='out.tif' for a "
                "disk-backed raster, or drop the options for an in-memory one (the "
                "MEM driver takes none, so they would be silently dropped)."
            )
        driver = resolve_output_driver(path)
        if path is None:
            dataset = gdal.GetDriverByName(driver).Create("", cols, rows, bands, dtype)
        else:
            if options is not None:
                # Callers that need tiled / sparse / BigTIFF output (e.g.
                # create_empty) pass their own options.
                creation_options = options
            elif driver == "GTiff":
                # LZW is lossless and compresses well, at the cost of more
                # computation. GTiff-specific, so other drivers get nothing
                # rather than an option they would reject.
                creation_options = ["COMPRESS=LZW"]
            else:
                creation_options = []
            dataset = gdal.GetDriverByName(driver).Create(
                str(path), cols, rows, bands, dtype, creation_options
            )
        return dataset

    @classmethod
    def _build_dataset(
        cls,
        cols: int,
        rows: int,
        bands: int,
        dtype: int,
        geo: tuple,
        crs: str,
        no_data_value: Any | None = DEFAULT_NO_DATA_VALUE,
        path: str | Path | None = None,
        access: str = "write",
        array: np.ndarray | None = None,
        options: list[str] | None = None,
    ) -> Dataset:
        """Build a Dataset: allocate, set geo/CRS, optionally fill no-data, optionally write.

        Single canonical factory for raster construction. Consolidates the
        ``_create_dataset + SetGeoTransform + SetProjection + wrap +
        _set_no_data_value (+ WriteArray)` pattern that `create``,
        `from_array`, `dataset_like`, and the per-op factories
        across `Spatial` / `Analysis` all need.

        Args:
            cols: Number of columns.
            rows: Number of rows.
            bands: Number of bands.
            dtype: GDAL data type code.
            geo: Geotransform tuple
                `(top_left_x, pixel_w, row_skew, top_left_y, col_skew,
                pixel_h)`.
            crs: Projection as WKT string.
            no_data_value: No-data value. Scalar (broadcast to all bands)
                or list (one per band). Pass `None` to skip the
                `_set_no_data_value` call so bands have no no-data
                sentinel — the same behaviour the public `create`
                factory exposes.
            path: Destination, which alone selects the driver. `None`
                (default) keeps the dataset in memory (MEM); otherwise the
                extension decides.
            access: Access mode for the Dataset wrapper. Default `"write"`.
                Note: MEM driver datasets can be written to regardless
                of access mode since the access flag is enforced at the
                pyramids level, not by GDAL.
            array: Optional numpy array to write into the bands after
                construction. When the array is 2-D it goes to band 1;
                when 3-D, `array[i, :, :]` goes to band `i+1`. The
                caller is responsible for matching `array.shape` to
                `bands x rows x cols` (or `rows x cols` for a
                single-band array). Default `None` (allocate but
                don't write).
            options: GDAL creation options forwarded to
                :meth:`_create_dataset` for disk drivers (e.g. the
                tiled / sparse / BigTIFF set used by :meth:`create_empty`).
                `None` (default) keeps the historical ``["COMPRESS=LZW"]``
                for GTiff and is ignored by the MEM driver.

        Returns:
            Dataset: A fully configured Dataset object.
        """
        dst = cls._create_dataset(cols, rows, bands, dtype, path=path, options=options)
        dst.SetGeoTransform(geo)
        dst.SetProjection(crs)
        dst_obj = cls(dst, access=access)
        if no_data_value is not None:
            dst_obj._set_no_data_value(no_data_value=no_data_value)
        if array is not None:
            if array.ndim == 2:
                dst_obj.raster.GetRasterBand(1).WriteArray(array)
            else:
                for i in range(bands):
                    dst_obj.raster.GetRasterBand(i + 1).WriteArray(array[i, :, :])
            dst_obj._raster.FlushCache()
        return dst_obj

    @classmethod
    def create(
        cls,
        rows: int,
        columns: int,
        dtype: str,
        bands: int,
        *,
        geo_ref: GeoReference,
        no_data_value: Any | None = None,
        path: str | Path | None = None,
    ) -> Dataset:
        """Create a new dataset, optionally filled with the no_data_value.

        With a `no_data_value` the sentinel is stamped on every band and the
        array is filled with it. The parameter defaults to `None`, which stamps
        no sentinel and performs no fill -- the bands read back as whatever the
        driver allocates (0 for GTiff). Pass one explicitly to get a filled
        raster, as :meth:`create_empty` documents for the same opt-out.

        Args:
            rows (int):
                Number of rows.
            columns (int):
                Number of columns.
            dtype (str):
                Data type.
            bands (int):
                Number of bands to create in the output raster. Required.
            geo_ref (GeoReference):
                How the array maps to space — an affine ``geo`` transform, or a
                ``top_left_corner`` + ``cell_size``, plus the ``epsg``. Required;
                a raster has to be placed somewhere. Note the CRS is not:
                ``epsg`` defaults to 4326, so a reference that omits it stamps
                WGS 84 rather than refusing. This method previously took a
                **required** ``epsg`` and raised ``TypeError`` when it was
                missing — pass ``epsg`` explicitly, or ``epsg=None`` for a
                deliberately CRS-less raster.
            no_data_value (float|None):
                No data value.
            path (str, optional):
                Destination, which alone decides the driver. `None` (default)
                builds the raster in memory; otherwise the extension selects the
                format (``.tif`` -> GTiff, ``.nc`` -> netCDF, …).

        Returns:
            Dataset: A new dataset

        Raises:
            ValueError: `geo_ref` carries neither a ``geo`` nor a complete
                ``top_left_corner`` + ``cell_size`` pair.
            DriverNotExistError: `path` has no extension, or one the driver
                catalog does not know.
            FileFormatNotSupportedError: `path`'s extension maps to a
                write-by-copy-only format such as PNG, which cannot be built
                with ``Create``.

        Examples:
            - Create a filled in-memory raster and read a cell back:
                ```python
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.create(
                ...     3, 4, "float32", 1,
                ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 3.0, 0.0, -1.0)),
                ...     no_data_value=-9999.0,
                ... )
                >>> (ds.rows, ds.columns, ds.band_count)
                (3, 4, 1)
                >>> float(ds.read_array()[0, 0])
                -9999.0

                ```
            - Place it with a corner and a cell size instead of a transform:
                ```python
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.create(
                ...     2, 2, "int16", 1,
                ...     geo_ref=GeoReference(
                ...         top_left_corner=(10.0, 50.0), cell_size=0.5, epsg=4326
                ...     ),
                ... )
                >>> tuple(ds.geotransform)
                (10.0, 0.5, 0.0, 50.0, 0.0, -0.5)
                >>> ds.epsg
                4326

                ```

        See Also:
            - :meth:`create_empty`: Allocate the header only, without filling
              every cell — the out-of-core sibling of this method.
            - :meth:`from_array`: Build a raster around an array you already
              have.
        """
        gdal_dtype = numpy_to_gdal_dtype(dtype)
        crs_wkt = _crs_wkt_from_epsg(geo_ref.epsg)
        geotransform = geo_ref.resolve_geotransform()
        return cls._build_dataset(
            columns,
            rows,
            bands,
            gdal_dtype,
            geotransform,
            crs_wkt,
            no_data_value,
            path=path,
        )

    @classmethod
    def create_empty(
        cls,
        rows: int,
        cols: int,
        *,
        bands: int = 1,
        dtype: str = "float32",
        geo_ref: GeoReference | None = None,
        no_data_value: Any = DEFAULT_NO_DATA_VALUE,
        path: str | Path | None = None,
        options: list[str] | None = None,
    ) -> Dataset:
        """Allocate an empty, header-only raster without materialising a full array.

        Out-of-core algorithms allocate the output once and scatter result
        windows into it with
        ``write_array(array, window=Window(col_off, row_off, cols, rows))``
        (see :class:`~pyramids.dataset.window.Window`).
        With a ``.tif`` path the file is **tiled, sparse,
        and BigTIFF** (see :data:`OUT_OF_CORE_CREATION_OPTIONS`), so a
        50 000 x 50 000 float32 raster is created in O(1) RAM, never-written
        blocks cost no disk, and writes past the 4 GB classic-TIFF ceiling
        succeed. A never-written cell reads back as ``no_data_value`` (not 0) —
        on GTiff because SPARSE_OK + the band no-data sentinel returns no-data
        for unwritten blocks, and on MEM because the band is filled with the
        no-data value at allocation — so downstream code must treat unwritten
        tiles as no-data.

        Args:
            rows: Number of rows of the output raster.
            cols: Number of columns of the output raster.
            bands: Number of bands. Default 1.
            dtype: NumPy dtype name for the bands (e.g. ``"float32"``,
                ``"int16"``). Default ``"float32"``.
            geo_ref: How the raster maps to space — an affine ``geo``
                transform, or a ``top_left_corner`` + ``cell_size``, plus the
                ``epsg``. Unlike the other constructors this one is optional:
                a header-only allocation often does not care where it sits, so
                `None` (default) — or a reference carrying *no* transform at
                all, such as ``GeoReference(epsg=3857)`` — keeps the identity
                transform ``(0.0, 1.0, 0.0, 0.0, 0.0, -1.0)``, a unit-pixel
                grid with the origin at ``(0, 0)``. A **partially** specified
                reference is not covered by that convenience: a
                ``top_left_corner`` without a ``cell_size`` (or the reverse)
                raises, exactly as it does in :meth:`from_array` and
                :meth:`create`, rather than silently discarding the half that
                was supplied.
            no_data_value: No-data sentinel stamped on every band at
                creation. Default :data:`DEFAULT_NO_DATA_VALUE`. Keep it set
                so sparse unwritten blocks read back as no-data rather than 0.
                Passing ``None`` skips the band fill and stamps no sentinel,
                which opts out of that guarantee — a sparse GTiff's unwritten
                blocks then read back as **0**, not no-data. A path that
                resolves to GTiff emits a :class:`NoDataSentinelWarning`;
                the in-RAM ``"MEM"`` driver is dense, and the other disk
                drivers are not sparse, so neither warns.
            path: Destination, which alone decides the driver. `None`
                (default) builds an in-memory ``"MEM"`` raster; otherwise the
                extension selects the format (``.tif`` -> GTiff). The sparse /
                tiled / BigTIFF defaults below apply only when the path
                resolves to GTiff.
            options: GDAL creation options. `None` (default) uses
                :data:`OUT_OF_CORE_CREATION_OPTIONS` for GTiff. Override to
                align ``BLOCKXSIZE`` / ``BLOCKYSIZE`` to your tile size or to
                change compression. Forwarded to whichever disk driver the
                extension selects — only the *default* set is GTiff-specific;
                passing `options` without a `path` raises rather than silently
                dropping them.

        Returns:
            Dataset: An empty raster whose bands read back as `no_data_value`
            before any write. On GTiff this is sparse — SPARSE_OK keeps
            never-written blocks unallocated and GDAL returns the no-data
            sentinel for them; on MEM every band is filled with `no_data_value`
            at allocation, so unwritten MEM cells read back as no-data too.

        Raises:
            ValueError: ``options`` is given without a ``path`` — creation
                options apply only to a disk driver, so accepting them for an
                in-memory raster would silently drop them; or `geo_ref` is
                partially specified (one half of the
                ``top_left_corner`` / ``cell_size`` pair).
            DriverNotExistError: ``path`` has an extension the driver catalog
                does not know.
            FileFormatNotSupportedError: ``path``'s extension maps to a
                write-by-copy-only format, which cannot be allocated with
                ``Create``.

        Examples:
            - Allocate an in-memory empty raster and read its no-data metadata:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset
                >>> ds = Dataset.create_empty(
                ...     4, 5, dtype="float32", no_data_value=-9999.0
                ... )
                >>> (ds.rows, ds.columns, ds.band_count)
                (4, 5, 1)
                >>> float(ds.no_data_value[0])
                -9999.0

                ```
            - Allocate, then scatter a window into it and read it back:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset
                >>> from pyramids.dataset import Window
                >>> ds = Dataset.create_empty(4, 4, dtype="float32")
                >>> block = np.arange(4, dtype="float32").reshape(2, 2)
                >>> ds.write_array(block, window=Window(1, 1, 2, 2))
                >>> ds.read_array(window=[1, 1, 2, 2]).tolist()
                [[0.0, 1.0], [2.0, 3.0]]

                ```

        See Also:
            - :meth:`empty_like`: Allocate an empty raster shaped like an
              existing template instead of from explicit dimensions.
            - :meth:`create`: Allocate a raster and eagerly fill every cell
              with the no-data value (no sparse / BigTIFF defaults).
            - :meth:`write_array`: Scatter a window into the allocated raster
              (``window=(row_off, col_off, n_rows, n_cols)``).
        """
        # The old "GTiff without a path" guard is gone: that combination is now
        # unrepresentable, because the driver comes from the path.
        # Creation options apply only to a disk driver (path given); the MEM
        # driver takes none. Reject explicit options that would be dropped
        # rather than silently ignoring them.
        if options is not None and path is None:
            raise ValueError(
                "create_empty received `options` but no `path`: GDAL creation "
                "options apply only to a disk driver. Pass a `path`, or drop "
                "`options` for the in-memory MEM raster."
            )
        # Only a sparse GTiff can read back 0 instead of no-data for a block
        # that was never written, so the warning is specific to that target.
        # The MEM driver (path is None) is a dense in-RAM buffer, and the other
        # disk drivers are not sparse either — warning about unwritten sparse
        # blocks on a netCDF would state a reason that does not apply to it.
        if no_data_value is None and _resolves_to_gtiff(path):
            warnings.warn(
                "create_empty(no_data_value=None) on a GTiff target stamps no "
                "no-data sentinel, so unwritten sparse blocks read back as 0, not "
                "no-data. Pass a no_data_value to keep the 'unwritten == no-data' "
                "guarantee.",
                NoDataSentinelWarning,
                stacklevel=2,
            )
        gdal_dtype = numpy_to_gdal_dtype(dtype)
        # `create_empty` allocates a header; where it sits in space is often
        # irrelevant to the caller. A geo_ref that carries no transform at all
        # (e.g. `GeoReference(epsg=3857)`) therefore keeps the identity one
        # rather than raising, which is what the flat `epsg=`-only form did.
        geo_ref = geo_ref if geo_ref is not None else GeoReference()
        # Substitute the identity transform only when the reference carries no
        # georeferencing at all. A *half*-filled pair (a corner with no cell
        # size, or the reverse) is a mistake, not a request for the origin:
        # falling back here would silently discard the half the caller did
        # supply, and place the raster at (0, 0) with 1-unit pixels. Leaving it
        # to `resolve_geotransform()` makes it raise, which is what the same
        # value object already does in `from_array` and `create`.
        if (
            geo_ref.geo is None
            and geo_ref.top_left_corner is None
            and geo_ref.cell_size is None
        ):
            geo_ref = replace(geo_ref, geo=_IDENTITY_GEO)
        crs_wkt = _crs_wkt_from_epsg(geo_ref.epsg)
        geo = geo_ref.resolve_geotransform()
        # The tiled / sparse / BigTIFF defaults are GTiff-specific, so apply them
        # only when the path actually resolves to GTiff.
        if options is None and _resolves_to_gtiff(path):
            options = list(OUT_OF_CORE_CREATION_OPTIONS)
        return cls._build_dataset(
            cols,
            rows,
            bands,
            gdal_dtype,
            geo,
            crs_wkt,
            no_data_value,
            path=path,
            options=options,
            array=None,
        )

    @classmethod
    def empty_like(
        cls,
        template: Dataset,
        *,
        dtype: str | None = None,
        bands: int | None = None,
        no_data_value: Any = INHERIT_NO_DATA,
        path: str | Path | None = None,
        options: list[str] | None = None,
    ) -> Dataset:
        """Allocate an empty raster aligned to a template's geo / epsg / shape / nodata.

        The header-only sibling of :meth:`dataset_like` — same spatial
        footprint as `template` (geotransform, CRS, rows, columns, no-data),
        but **no array is written**, so it can allocate an out-of-core output
        the size of an input DEM without materialising it. The driver comes
        from `path`: MEM when it is `None`, otherwise whatever the extension
        selects. A `.tif` destination additionally gets the tiled / sparse /
        BigTIFF defaults in :data:`OUT_OF_CORE_CREATION_OPTIONS`.

        Args:
            template: Source raster whose geotransform, CRS, shape, and
                no-data value the output copies.
            dtype: NumPy dtype name for the output bands. `None` (default)
                reuses the template's dtype.
            bands: Number of output bands. `None` (default) reuses the
                template's band count.
            no_data_value: No-data sentinel for the output. Default inherits
                from the template: when the band count is unchanged and every
                template band has a sentinel, the **per-band** no-data values
                are preserved; otherwise (a `bands` override, or a template
                band with no sentinel) the template's first-band value is used.
                Pass an explicit scalar or per-band list to override. If this
                resolves to ``None`` (passed explicitly, or inherited from a
                template with no no-data set), no sentinel is stamped and a
                sparse GTiff's unwritten blocks read back as **0**, not no-data;
                a path that resolves to GTiff emits a
                :class:`NoDataSentinelWarning` (the in-RAM MEM result and the
                other, non-sparse disk drivers do not warn).
            path: Destination, which alone decides the driver. `None`
                (default) keeps the raster in memory (MEM); otherwise the
                extension selects the format (`.tif` -> GTiff, `.nc` ->
                netCDF, ...).
            options: GDAL creation options forwarded to the disk driver.
                `None` (default) uses :data:`OUT_OF_CORE_CREATION_OPTIONS`,
                but only when the path resolves to GTiff — those options are
                GTiff-specific, so any other disk driver gets none. Passing
                `options` without a `path` raises rather than silently
                dropping them.

        Returns:
            Dataset: An empty raster matching the template's footprint.

        Raises:
            ValueError: `options` is given without a `path` (creation
                options apply only to a disk driver).
            DriverNotExistError: `path` has no extension, or one the driver
                catalog does not know.
            FileFormatNotSupportedError: `path`'s extension maps to a
                write-by-copy-only format, which cannot be allocated with
                `Create`.

        Examples:
            - Allocate an empty raster shaped like an existing one, with a
              different dtype:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> template = Dataset.from_array(
                ...     np.ones((3, 4, 5), dtype="float32"),
                ...     no_data_value=-9999.0,
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 10.0), cell_size=0.5, epsg=4326),
                ... )
                >>> out = Dataset.empty_like(template, dtype="int16")
                >>> (out.rows, out.columns, out.band_count, out.epsg)
                (4, 5, 3, 4326)
                >>> out.geotransform == template.geotransform
                True

                ```
            - Reduce the band count and inherit the template's no-data value,
              then confirm the empty output reads back as no-data:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> template = Dataset.from_array(
                ...     np.ones((3, 4, 4), dtype="float32"),
                ...     no_data_value=-9999.0,
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 10.0), cell_size=1.0, epsg=4326),
                ... )
                >>> out = Dataset.empty_like(template, bands=1)
                >>> out.band_count
                1
                >>> float(out.no_data_value[0])
                -9999.0

                ```

        See Also:
            - :meth:`create_empty`: Allocate an empty raster from explicit
              dimensions / CRS instead of copying a template.
            - :meth:`dataset_like`: The array-writing sibling — copies the
              template footprint *and* writes a supplied array.
            - :meth:`write_array`: Scatter a window into the allocated raster.
        """
        if options is not None and path is None:
            raise ValueError(
                "empty_like received `options` but no `path`: GDAL creation options "
                "apply only to a disk driver. Pass a `path`, or drop "
                "`options` for the in-memory MEM raster."
            )
        gdal_dtype = (
            template.gdal_dtype[0] if dtype is None else numpy_to_gdal_dtype(dtype)
        )
        n_bands = template.band_count if bands is None else bands
        if no_data_value is not INHERIT_NO_DATA:
            nodata = no_data_value
        else:
            template_nd = template.no_data_value
            # Preserve the template's per-band sentinels when the band count is
            # unchanged and every band actually has one; otherwise (band-count
            # override, or a band with no sentinel) fall back to band 0's value.
            if bands is None and all(v is not None for v in template_nd):
                nodata = list(template_nd)
            else:
                nodata = template_nd[0]
        # Warn only for a GTiff target, the only one whose unwritten sparse
        # blocks read back as 0 when no sentinel is stamped. An in-RAM MEM
        # result (no path) is dense, and the other disk drivers are not sparse,
        # so the stated reason would not apply to them.
        if nodata is None and _resolves_to_gtiff(path):
            warnings.warn(
                "empty_like produced a GTiff raster with no no-data sentinel "
                "(no_data_value resolved to None, explicitly or inherited from a "
                "template with no no-data), so unwritten sparse blocks read back as "
                "0, not no-data. Pass no_data_value to keep the 'unwritten == "
                "no-data' guarantee.",
                NoDataSentinelWarning,
                stacklevel=2,
            )
        # The tiled / sparse / BigTIFF defaults are GTiff-specific, so apply them
        # only when the path actually resolves to GTiff — matching `create_empty`.
        # Hardcoding "GTiff for any path" was harmless while the driver was
        # passed down explicitly; now that it comes from the extension, a `.nc`
        # destination really is netCDF and must not be handed GTiff options.
        if options is None and _resolves_to_gtiff(path):
            options = list(OUT_OF_CORE_CREATION_OPTIONS)
        return cls._build_dataset(
            template.columns,
            template.rows,
            n_bands,
            gdal_dtype,
            template.geotransform,
            template.crs,
            nodata,
            path=path,
            options=options,
            array=None,
        )

    @classmethod
    def from_features(
        cls,
        features: FeatureCollection,
        *,
        cell_size: Any | None = None,
        template: Dataset | None = None,
        snap_to_template: bool = False,
        column_name: str | list[str] | None = None,
    ) -> Dataset:
        """Rasterize a :class:`FeatureCollection` into a new :class:`Dataset`.

        Burns the values from `column_name` (or every attribute
        column if `None`) into a single-band or multi-band raster.
        When a `template` Dataset is given, the output adopts its
        geotransform, cell size, row/column count, and no-data value —
        the vector is burned onto the template's fixed grid, so features
        outside it are clipped. With `snap_to_template=True` the template
        supplies only the cell size and grid alignment while the extent is
        cropped to the features (snapped onto the template's grid lines),
        giving a small raster co-registered with the template. Otherwise
        `cell_size` controls the resolution and the extent is derived from
        :attr:`FeatureCollection.total_bounds`.

        Args:
            features (FeatureCollection):
                The vector to rasterize.
            cell_size (int | float | None):
                Cell size for the new raster. Required unless
                `template` is given.
            template (Dataset | None):
                Optional template raster. When supplied, the output
                inherits its geotransform and no-data value. Features
                that fall entirely outside the template extent, or an
                empty FeatureCollection, produce an all-nodata raster
                and emit a `UserWarning` (#46); use `cell_size` instead
                to size the output to the features.
            snap_to_template (bool):
                When `True` (requires `template`), keep the template's
                cell size and grid alignment but size the output to the
                features' bounds snapped outward onto the template's grid
                lines — a small raster that still co-registers with the
                template pixel-for-pixel (#46). Requires a square,
                axis-aligned template and features with valid (non-NaN)
                geometry bounds. The output is sized to the features, so a
                fine-celled template with far-apart features can allocate a
                large raster.
            column_name (str | list[str] | None):
                Attribute column(s) to burn as band values. `None`
                burns every non-geometry column as a separate band.
                Mixed-dtype column lists are promoted to the smallest
                numpy dtype that holds every selected column without
                lossy cast (numpy result-type rules).

        Returns:
            Dataset: The burned raster.

        Raises:
            ValueError: `cell_size` missing or non-positive,
                `column_name` empty or referencing missing columns,
                `snap_to_template` set without a `template`, or (in snap
                mode) a rotated / non-square template or features with no
                valid (non-NaN) geometry bounds.
            TypeError: `template` is not a Dataset, or
                `column_name` is not `str` / `list` / `None`.
            CRSError: `features.epsg` is `None`, or
                `template.epsg!= features.epsg`.

        Examples:
            - `cell_size` sizes the output to the feature bounds:

              ```python
              >>> import geopandas as gpd
              >>> from shapely.geometry import box
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> from pyramids.feature import FeatureCollection
              >>> gdf = gpd.GeoDataFrame(
              ...     {"class_id": [7]},
              ...     geometry=[box(0.0, 0.0, 3.0, 3.0)],
              ...     crs="EPSG:4326",
              ... )
              >>> raster = Dataset.from_features(
              ...     FeatureCollection(gdf), cell_size=1.0, column_name="class_id"
              ... )
              >>> (raster.rows, raster.columns)
              (3, 3)
              >>> int(raster.read_array().max())
              7

              ```

            - A `template` burns onto its fixed grid, so the output adopts the template's
              shape (features outside it would warn and yield all-nodata — see #46):

              ```python
              >>> import numpy as np
              >>> template = Dataset.from_array(
              ...     np.zeros((5, 5), dtype="int32"),
              ...     geo_ref=GeoReference(top_left_corner=(0.0, 5.0), cell_size=1.0, epsg=4326),
              ... )
              >>> inside = FeatureCollection(
              ...     gpd.GeoDataFrame(
              ...         {"class_id": [7]},
              ...         geometry=[box(1.0, 1.0, 4.0, 4.0)],
              ...         crs="EPSG:4326",
              ...     )
              ... )
              >>> burned = Dataset.from_features(
              ...     inside, template=template, column_name="class_id"
              ... )
              >>> (burned.rows, burned.columns)
              (5, 5)

              ```

            - `snap_to_template=True` keeps the template's grid but crops to the features,
              so the output is small yet co-registered (its origin is on the template's
              grid lines):

              ```python
              >>> snapped = Dataset.from_features(
              ...     inside,
              ...     template=template,
              ...     snap_to_template=True,
              ...     column_name="class_id",
              ... )
              >>> (snapped.rows, snapped.columns)
              (3, 3)
              >>> snapped.top_left_corner
              (1.0, 4.0)

              ```
        """
        return rasterize_features(
            features,
            cls,
            cell_size=cell_size,
            template=template,
            snap_to_template=snap_to_template,
            column_name=column_name,
        )

    @classmethod
    def from_points(
        cls,
        points: FeatureCollection,
        value_column: str,
        *,
        algorithm: str = "invdist:power=2.0:smoothing=0.0",
        cell_size: float | None = None,
        width: int | None = None,
        height: int | None = None,
        bbox: tuple[float, float, float, float] | None = None,
        epsg: Any | None = None,
    ) -> Dataset:
        """Interpolate scattered point samples onto a regular grid (``gdal.Grid``).

        The GDAL-native equivalent of ``gdal_grid`` — turns an irregular point
        layer (gauge readings, soundings, station observations) into a
        continuous single-band raster. The output extent defaults to the points'
        bounding box and the resolution is set by ``cell_size`` (or an explicit
        ``width``/``height``).

        Args:
            points (FeatureCollection):
                A point :class:`FeatureCollection` carrying ``value_column``.
            value_column (str):
                Numeric attribute column to interpolate (the Z field).
            algorithm (str):
                A ``gdal.Grid`` algorithm string. Defaults to inverse-distance
                weighting (``"invdist:power=2.0:smoothing=0.0"``). Other options
                include ``"invdistnn"``, ``"nearest"``, ``"linear"``, and
                ``"average"``.
            cell_size (float | None):
                Output pixel size in the points' CRS units. Required unless both
                ``width`` and ``height`` are given.
            width (int | None):
                Output width in pixels. Overrides ``cell_size`` on the x axis.
            height (int | None):
                Output height in pixels. Overrides ``cell_size`` on the y axis.
            bbox (tuple[float, float, float, float] | None):
                ``(minx, miny, maxx, maxy)`` output extent. Defaults to the
                points' total bounds.
            epsg (int | None):
                Output EPSG code. Defaults to the points' CRS.

        Returns:
            Dataset: A single-band raster of the interpolated surface.

        Raises:
            ValueError: ``value_column`` missing, output bounds degenerate, or
                neither ``cell_size`` nor ``width``+``height`` provided.
            FailedToSaveError: ``gdal.Grid`` produced no dataset.

        Examples:
            - Inverse-distance interpolate four corner readings onto a 1-degree
              grid and read back the surface shape:
                ```python
                >>> from shapely.geometry import Point
                >>> from geopandas import GeoDataFrame
                >>> from pyramids.feature import FeatureCollection
                >>> from pyramids.dataset import Dataset
                >>> gdf = GeoDataFrame(
                ...     {"rain": [10.0, 20.0, 30.0, 40.0]},
                ...     geometry=[Point(0, 0), Point(10, 0), Point(0, 10), Point(10, 10)],
                ...     crs="EPSG:4326",
                ... )
                >>> ds = Dataset.from_points(FeatureCollection(gdf), "rain", cell_size=1.0)
                >>> (ds.rows, ds.columns, ds.band_count)
                (10, 10, 1)

                ```
            - Use nearest-neighbour with an explicit output size:
                ```python
                >>> from shapely.geometry import Point
                >>> from geopandas import GeoDataFrame
                >>> from pyramids.feature import FeatureCollection
                >>> from pyramids.dataset import Dataset
                >>> gdf = GeoDataFrame(
                ...     {"z": [1.0, 2.0, 3.0, 4.0]},
                ...     geometry=[Point(0, 0), Point(5, 0), Point(0, 5), Point(5, 5)],
                ...     crs="EPSG:4326",
                ... )
                >>> ds = Dataset.from_points(
                ...     FeatureCollection(gdf), "z", algorithm="nearest", width=5, height=5
                ... )
                >>> ds.columns
                5

                ```
        """
        return grid_points(
            points,
            value_column,
            cls,
            algorithm=algorithm,
            cell_size=cell_size,
            width=width,
            height=height,
            bbox=bbox,
            epsg=epsg,
        )

    @classmethod
    def from_point_arrays(
        cls,
        x: Any,
        y: Any,
        z: Any,
        *,
        algorithm: str = "invdist:power=2.0:smoothing=0.0",
        cell_size: float | None = None,
        width: int | None = None,
        height: int | None = None,
        bbox: tuple[float, float, float, float] | None = None,
        crs: Any = None,
        epsg: int | None = None,
    ) -> Dataset:
        """Interpolate raw coordinate arrays onto a grid — no geometry built.

        The array-native sibling of :meth:`from_points`. Where ``from_points``
        takes a point :class:`~pyramids.feature.FeatureCollection` (a shapely
        geometry per point), this takes raw ``x`` / ``y`` / ``z`` arrays straight
        into ``gdal.Grid`` through an in-memory CSV, so a large sample table
        (bathymetric soundings, a dense gauge network, a CSV of readings) never
        materialises a geometry object. Both share one gridding core, so the two
        differ only in how the points arrive.

        ``gdal.Grid`` does not reproject: ``crs`` / ``epsg`` only label the output.
        The grid is computed in the coordinates' own space, so ``cell_size`` and
        ``bbox`` are in those units.

        This is the low-level array entry, and like :meth:`from_points` it does not
        enforce the minimum-point-count or column-dtype policy that the higher-level
        :meth:`~pyramids.feature.FeatureCollection.interpolate_to_raster` applies --
        gridding a single point is allowed. It does reject the inputs ``gdal.Grid``
        cannot use: non-finite coordinates or ``bbox`` raise, non-finite values are
        dropped as missing readings, and an all-non-finite value array raises.

        Args:
            x (Any):
                Point x-coordinates (anything :func:`numpy.asarray` reads as a 1-D
                float array).
            y (Any):
                Point y-coordinates, the same length as ``x``.
            z (Any):
                The value to interpolate at each point, the same length as ``x``.
            algorithm (str):
                A ``gdal.Grid`` algorithm string. Defaults to inverse-distance
                weighting (``"invdist:power=2.0:smoothing=0.0"``); other options
                include ``"invdistnn"``, ``"nearest"``, ``"linear"`` and
                ``"average"``.
            cell_size (float | None):
                Output pixel size in the coordinates' units. Required unless both
                ``width`` and ``height`` are given.
            width (int | None):
                Output width in pixels. With ``height``, overrides ``cell_size``.
            height (int | None):
                Output height in pixels. With ``width``, overrides ``cell_size``.
            bbox (tuple[float, float, float, float] | None):
                ``(minx, miny, maxx, maxy)`` output extent. Defaults to the arrays'
                own min/max.
            crs (Any):
                CRS the coordinates are in, to stamp on the output (any form
                :func:`~pyramids.base.crs.sr_from_user_input` accepts), or ``None``.
                Mutually informative with ``epsg``; ``epsg`` wins if both are given.
            epsg (int | None):
                Output EPSG code. Takes precedence over ``crs``.

        Returns:
            Dataset: A single-band raster of the interpolated surface.

        Raises:
            ValueError: ``x`` / ``y`` / ``z`` are not 1-D of equal length, are
                empty, a coordinate (``x`` or ``y``) or ``bbox`` is non-finite,
                every ``z`` value is non-finite (nothing to interpolate), the bounds
                are degenerate, ``cell_size`` is not positive, or neither
                ``cell_size`` nor ``width`` + ``height`` was given.
            FailedToSaveError: ``gdal.Grid`` produced no dataset.

        Examples:
            - Grid four corner readings onto a 1-degree grid straight from arrays:
                ```python
                >>> from pyramids.dataset import Dataset
                >>> x = [0.0, 10.0, 0.0, 10.0]
                >>> y = [0.0, 0.0, 10.0, 10.0]
                >>> z = [10.0, 20.0, 30.0, 40.0]
                >>> ds = Dataset.from_point_arrays(x, y, z, cell_size=1.0, epsg=4326)
                >>> (ds.rows, ds.columns, ds.band_count)
                (10, 10, 1)
                >>> ds.epsg
                4326

                ```
            - Nearest-neighbour with an explicit output size and a wider extent:
                ```python
                >>> from pyramids.dataset import Dataset
                >>> ds = Dataset.from_point_arrays(
                ...     [0.0, 5.0, 0.0, 5.0], [0.0, 0.0, 5.0, 5.0],
                ...     [1.0, 2.0, 3.0, 4.0],
                ...     algorithm="nearest", width=8, height=8, bbox=(-2, -2, 7, 7),
                ... )
                >>> (ds.rows, ds.columns)
                (8, 8)
                >>> round(ds.geotransform[0])
                -2

                ```

        See Also:
            - :meth:`from_points`: the same gridding from a point
              :class:`~pyramids.feature.FeatureCollection`.
            - :meth:`pyramids.feature.FeatureCollection.from_xyz`: build a point
              layer from arrays when you want the vector model, not a raster.
        """
        output_srs: str | None = None
        if epsg is not None:
            output_srs = f"EPSG:{int(epsg)}"
        elif crs is not None:
            output_srs = sr_from_user_input(crs).ExportToWkt()
        return grid_arrays(
            x,
            y,
            z,
            cls,
            algorithm=algorithm,
            cell_size=cell_size,
            width=width,
            height=height,
            bbox=bbox,
            output_srs=output_srs,
        )

    def to_dataframe(
        self, *, bands: int | Sequence[int] | None = None, dropna: bool = False
    ) -> pd.DataFrame:
        """Hand the raster to pandas, one row per cell on a ``(band, y, x)`` MultiIndex.

        The inverse of :meth:`from_dataframe`. Each row is a cell; the single ``values``
        column holds that cell's value; the ``MultiIndex`` names ``band`` (0-based,
        outermost), then the row (``y``) and column (``x``) cell-centre coordinates — the
        order the array is laid out, so ``df["values"].to_numpy().reshape(bands, rows, cols)``
        is the array back, with nodata as ``NaN``. The frame is coordinate-keyed and carries
        **no geometry or CRS**; for a geometry-per-cell ``GeoDataFrame`` (points or polygons,
        optionally with the band values) use :meth:`to_geodataframe`, and to read values at
        scattered points use :meth:`sample` / :meth:`extract`.

        The ``band`` level is always present, even for a one-band raster (value ``[0]``);
        ``df["values"].unstack("band")`` gives the wide, one-column-per-band view.

        Args:
            bands: Which band(s) become rows, zero-based. ``None`` (default) takes every band;
                a single ``int`` takes that one; a sequence takes them in the given order. The
                ``band`` index level holds these positional indices.
            dropna: Drop rows whose ``values`` is ``NaN`` (the no-data / gap cells). ``False``
                (default) keeps the full grid, which is what makes the round trip with
                :meth:`from_dataframe` reproduce the raster; ``True`` returns only the cells
                that carry data.

        Returns:
            pandas.DataFrame: ``prod(len(bands), rows, cols)`` rows, one ``values`` column,
            every value ``float64`` whatever the raster's own dtype, gaps as ``NaN``,
            north-up (``y`` descending, ``x`` ascending). Integer values above ``2**53`` are
            not exactly representable once coerced to ``float64``.

        Raises:
            ValueError: A requested band index is out of range for the raster, or ``bands=``
                is an empty selection (pass ``bands=None`` for every band).
            TypeError: ``bands=`` is a boolean (``bool`` subclasses ``int``, so it is refused
                rather than silently selecting band 0 / 1).

        Examples:
            - A one-band 2x2 raster as pandas sees it (the ``band`` level is kept):

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> ds = Dataset.from_array(
              ...     np.array([[1.0, 2.0], [3.0, 4.0]]),
              ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=4326),
              ... )
              >>> ds.to_dataframe()["values"].tolist()
              [1.0, 2.0, 3.0, 4.0]
              >>> list(ds.to_dataframe().index.names)
              ['band', 'y', 'x']

              ```
        """
        count = self.band_count
        if bands is None:
            selected = list(range(count))
        elif isinstance(bands, bool):
            # bool subclasses int, so guard it before the int branch or True/False
            # would silently select band 1/0 — almost certainly a caller mistake.
            raise TypeError(
                f"Dataset.to_dataframe() got a boolean bands={bands!r}; pass a band index, a "
                "sequence of indices, or None for every band."
            )
        elif isinstance(bands, (int, np.integer)):
            selected = [int(bands)]
        else:
            selected = [int(b) for b in bands]
        if not selected:
            raise ValueError(
                "Dataset.to_dataframe() was given an empty bands= selection; pass "
                f"bands=None for every band, or indices in 0..{count - 1}."
            )
        out_of_range = [b for b in selected if not 0 <= b < count]
        if out_of_range:
            raise ValueError(
                f"Dataset.to_dataframe() got band index/indices {out_of_range} out of range "
                f"for a {count}-band raster (valid 0..{count - 1})."
            )
        # `squeeze=True` keeps the classic flattened `(bands, rows, cols)` this band-indexed
        # dataframe build expects, not the dimension-preserving default (#1241).
        array = np.asarray(self.read_array(squeeze=True), dtype="float64")
        if array.ndim == 2:
            array = array[np.newaxis, ...]
        array = array[selected]
        sentinels = self.no_data_value
        for i, band in enumerate(selected):
            sentinel = sentinels[band]
            # A NaN sentinel already reads back as NaN; only a real value needs masking.
            # Guard the isnan by type — it raises on integer sentinels (e.g. uint64).
            is_nan_sentinel = isinstance(sentinel, (float, np.floating)) and np.isnan(
                sentinel
            )
            if sentinel is not None and not is_nan_sentinel:
                array[i] = np.where(array[i] == sentinel, np.nan, array[i])
        index = pd.MultiIndex.from_product(
            [
                selected,
                list(np.asarray(self.y, dtype="float64")),
                list(np.asarray(self.x, dtype="float64")),
            ],
            names=["band", "y", "x"],
        )
        frame = pd.DataFrame({"values": array.reshape(-1)}, index=index)
        if dropna:
            frame = frame.dropna(subset=["values"])
        return frame

    @classmethod
    def from_dataframe(
        cls,
        df: pd.DataFrame,
        *,
        crs: str | int | None = None,
        x: str | None = None,
        y: str | None = None,
        no_data_value: Any = np.nan,
        path: str | Path | None = None,
    ) -> Dataset:
        """Rebuild a raster from a ``(band, y, x)`` MultiIndex DataFrame — inverse of ``to_dataframe``.

        The frame is indexed by its axes: the innermost two index levels are the ``(y, x)``
        grid and an optional outer level is the positional ``band`` axis, so
        ``Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg)`` reproduces ``ds``'s values,
        band count/order, grid and CRS (the geotransform is recovered by differencing cell
        centres); gaps come back as ``NaN`` unless ``no_data_value=`` restores a specific
        sentinel. A frame with no band level (a plain ``(y, x)`` MultiIndex) builds a single-band
        raster. A DataFrame carries no georeferencing, so the geotransform is inferred from
        the ``x`` / ``y`` cell centres (a regular grid is required; a single-row or
        single-column axis is refused) and the CRS is taken from ``crs``. The result is always
        north-up.

        A raster's bands are positional, so — unlike
        :meth:`pyramids.netcdf.NetCDF.from_dataframe` — this takes a **single** value column
        (the band axis lives in the index); a multi-column frame is refused with a pointer to
        ``NetCDF.from_dataframe``.

        Args:
            df: A DataFrame on a ``pandas.MultiIndex`` of at least two named levels — the
                innermost two the row (``y``) and column (``x``) axes (unless ``x`` / ``y``
                name them), an optional outer level the ``band`` axis — and exactly one value
                column. A tidy frame on a plain index is refused.
            crs: The CRS for the result, an EPSG code or a CRS string. ``None`` (default)
                leaves it unset — a DataFrame carries none, so a full round trip needs
                ``crs=ds.epsg`` to recover it.
            x: The index level holding the column (x) coordinates; defaults to the innermost.
            y: The index level holding the row (y) coordinates; defaults to the
                second-innermost.
            no_data_value: Sentinel stamped on gaps (``NaN`` cells and cells absent from the
                frame). Defaults to ``np.nan``, so gaps stay ``NaN`` and the rebuilt raster
                declares ``NaN`` as its nodata; pass e.g. ``no_data_value=ds.no_data_value[0]``
                to restore a specific sentinel and its dtype.
            path: Destination — ``None`` (default) builds in memory; otherwise the extension
                selects the driver, exactly as :meth:`from_array`.

        Returns:
            Dataset: The rebuilt raster on the inferred grid.

        Raises:
            ValueError: The frame is not a MultiIndex of at least two named levels; a named
                ``x`` / ``y`` level is missing or the two coincide; there is not exactly one
                value column; more than one band index level is present; the index has
                duplicate rows; or the ``x`` / ``y`` axis is irregular or single-celled.

        Examples:
            - Round-trip a two-band raster through pandas and back:

              ```python
              >>> import numpy as np
              >>> from pyramids.dataset import Dataset, GeoReference
              >>> ds = Dataset.from_array(
              ...     np.arange(8.0).reshape(2, 2, 2),
              ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=4326),
              ... )
              >>> back = Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg)
              >>> back.read_array().tolist()
              [[[0.0, 1.0], [2.0, 3.0]], [[4.0, 5.0], [6.0, 7.0]]]
              >>> back.band_count
              2

              ```
        """
        columns = value_columns(df, None)
        if len(columns) != 1:
            raise ValueError(
                "Dataset.from_dataframe() expects a single value column — a raster's bands "
                f"live in the index, not in columns — but the frame has {columns}. For a "
                "multi-variable table use NetCDF.from_dataframe()."
            )
        band_names, row_name, col_name = frame_axes(df, x, y)
        if len(band_names) > 1:
            raise ValueError(
                "Dataset.from_dataframe() expects at most one band index level (band, y, x), "
                f"but got band levels {band_names}. For several band dimensions use "
                "NetCDF.from_dataframe()."
            )
        check_no_duplicate_index(df)
        _band_coords, _y_coords, _x_coords, geo, ordered, shape = reshape_to_grid(
            df, band_names, row_name, col_name
        )
        arr = column_array(ordered, columns[0], shape)
        arr = np.where(np.isnan(arr), no_data_value, arr)
        return cls.from_array(
            arr,
            geo_ref=GeoReference(geo=geo, epsg=crs),
            no_data_value=no_data_value,
            path=path,
        )

    @classmethod
    def from_array(
        cls,
        arr: np.ndarray,
        *,
        geo_ref: GeoReference,
        no_data_value: Any | list = DEFAULT_NO_DATA_VALUE,
        path: str | Path | None = None,
    ) -> Dataset:
        """Create a new dataset from an array.

        Args:
            arr (np.ndarray):
                Numpy array.
            geo_ref (GeoReference):
                How the array maps to space — an affine ``geo`` transform, or a
                ``top_left_corner`` + ``cell_size``, plus the ``epsg``. Required;
                a raster has to be placed somewhere. An ``epsg`` of `None` (or
                `0`) creates an ungeoreferenced raster that reports no CRS,
                rather than one silently stamped WGS 84.
            no_data_value (Any, optional):
                No data value to mask the cells out of the domain. The default is -9999.
            path (str, optional):
                Destination. `None` (default) builds the raster in memory;
                otherwise the extension selects the driver (``.tif`` -> GTiff,
                ``.nc`` -> netCDF, …). A ``.nc`` destination here writes a
                *classic* single-variable netCDF through the plain GDAL raster
                API; for a multi-variable, CF-attributed store use
                :meth:`pyramids.netcdf.NetCDF.from_array`, which goes through
                the multidimensional path.

        Returns:
            Dataset:
                Dataset object will be returned.

        Raises:
            ValueError: `geo_ref` carries neither a ``geo`` nor a complete
                ``top_left_corner`` + ``cell_size`` pair.
            DriverNotExistError: `path` has no extension, or one the driver
                catalog does not know.
            FileFormatNotSupportedError: `path`'s extension maps to a
                write-by-copy-only format such as PNG, which cannot be built
                with ``Create``.

        Examples:
            - Wrap a 2-D array, then read it back:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> arr = np.arange(6, dtype="float32").reshape(2, 3)
                >>> ds = Dataset.from_array(
                ...     arr, geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0))
                ... )
                >>> ds.read_array().tolist()
                [[0.0, 1.0, 2.0], [3.0, 4.0, 5.0]]
                >>> (ds.rows, ds.columns, ds.band_count)
                (2, 3, 1)

                ```
            - A leading axis becomes bands:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> stack = np.ones((3, 2, 2), dtype="int16")
                >>> ds = Dataset.from_array(
                ...     stack,
                ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0),
                ... )
                >>> ds.band_count
                3

                ```
            - `epsg=None` builds an ungeoreferenced raster rather than
              silently claiming WGS 84:
                ```python
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> ds = Dataset.from_array(
                ...     np.zeros((2, 2), dtype="float32"),
                ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=None),
                ... )
                >>> ds.crs
                ''

                ```

        See Also:
            - :meth:`dataset_like`: Reuse another dataset's georeferencing
              instead of stating it.
            - :meth:`create`: Allocate a raster filled with the no-data value
              when there is no array yet.
        """
        geo = geo_ref.resolve_geotransform()
        epsg = geo_ref.epsg

        if arr.ndim == 2:
            bands = 1
            rows = int(arr.shape[0])
            cols = int(arr.shape[1])
        else:
            bands = arr.shape[0]
            rows = int(arr.shape[1])
            cols = int(arr.shape[2])

        # The shared helper owns the CRS rules — the `sr_from_epsg` path for an
        # EPSG int/numeric string, the `sr_from_user_input` fallback that carries
        # a no-EPSG CRS such as geostationary through as WKT (#706), and the
        # empty-string result that leaves a deliberately ungeoreferenced raster
        # unprojected rather than stamping a default (ARC-26).
        crs_wkt = _crs_wkt_from_epsg(epsg)

        return cls._build_dataset(
            cols,
            rows,
            bands,
            numpy_to_gdal_dtype(arr),
            geo,
            crs_wkt,
            no_data_value,
            path=path,
            array=arr,
        )

    @classmethod
    def dataset_like(
        cls,
        src: Dataset,
        array: np.ndarray,
        path: str | Path | None = None,
    ) -> Dataset:
        """Create a new dataset like another dataset.

        dataset_like method creates a Dataset from an array like another source dataset. The new dataset
        will have the same `projection`, `coordinates` or the `top left corner` of the original dataset,
        `cell size`, `no_data_velue`, and number of `rows` and `columns`.
        the array and the source dataset should have the same number of columns and rows

        Args:
            src (Dataset):
                source raster to get the spatial information
            array (ndarray):
                data to store in the new dataset.
            path (str, optional):
                path to save the new dataset, if not given, the method will return in-memory dataset.

        Returns:
            Dataset:
                if the `path` is given, the method will save the new raster to the given path, else the
                method will return an in-memory dataset.
        """
        if not isinstance(array, np.ndarray):
            raise TypeError("array should be of type numpy array")

        bands = 1 if array.ndim == 2 else array.shape[0]
        return cls._build_dataset(
            src.columns,
            src.rows,
            bands,
            numpy_to_gdal_dtype(array),
            src.geotransform,
            src.crs,
            src.no_data_value[0],
            path=path,
            array=array,
        )

    @classmethod
    def from_band_files(
        cls,
        files: Sequence[str | Path],
        *,
        band_names: list[str] | None = None,
        align: bool = False,
        resampling: str | dict[str, str] | None = None,
        no_data_value: Any = INHERIT_NO_DATA,
        path: str | Path | None = None,
    ) -> Dataset:
        """Stack N single-band rasters into one multi-band :class:`Dataset`.

        Each input file becomes one band, in order, with its name preserved.
        This is the natural target for an Earth Engine default download
        (`<assetSlug>.<bandName>.tif` — one file per band), a Landsat
        Collection-2 scene (per-band `.TIF`), or a Sentinel-2 SAFE
        (per-band JP2s).

        By default all inputs must already share the same grid and CRS;
        pass `align=True` to resample mismatched rasters onto the first
        file's grid (nearest-neighbour, via :meth:`align`) — or
        `resampling=` to pick the algorithm, globally or per band. When the
        inputs have different numpy dtypes the output dtype is the smallest
        type that holds every input without a lossy cast.

        Stacking copies the stores rather than computing anything: each band
        holds its source's stored values, and each source's CF packing
        (`scale_factor` / `add_offset`) is carried onto its band, so a packed
        input still reads back in physical units from the stack.

        Args:
            files: Paths (or URLs / `/vsi*` strings) of the single-band
                rasters to stack. Order is preserved as band order.
            band_names: Explicit band names, one per file. When `None`
                (default) names are derived from the file names
                (`<slug>.<band>.tif` → `<band>`; dotless stems are kept
                whole; duplicates get a `_<n>` suffix).
            align: When `False` (default), a grid/CRS mismatch among the
                inputs raises :class:`AlignmentError`. When `True`, every
                input is resampled onto `files[0]`'s grid first.
            resampling: Which algorithm that alignment uses (`align=True`
                only). `None` (default) keeps the historical nearest-neighbour
                behaviour for every band. A method name (`"bilinear"`,
                `"cubic"`, `"average"`, … — any key of
                :data:`~pyramids.base._utils.INTERPOLATION_METHODS`) applies to
                every band, and a `{band name: method}` mapping sets it per
                band, so a continuous band can be interpolated while a
                categorical one (a cloud mask, a class map) stays on nearest.
                Bands a mapping leaves out keep nearest. Names are validated up
                front, and a band whose grid already matches `files[0]` skips
                the warp entirely, so its method is moot. Passing anything but
                `None` with `align=False` raises, rather than being silently
                ignored.
            no_data_value: No-data value stamped on the output bands. When
                omitted, it is inherited from the source rasters (a warning
                is issued if they disagree, and the first file's value
                wins; if no source declares one, the output has none). Pass
                an explicit value (including `None` for "no no-data
                sentinel") to override.
            path: Output path, whose extension selects the driver as it does
                for every other factory (`.tif` -> GTiff, `.nc` ->
                netCDF, …). When `None` (default) the result is an
                in-memory dataset.

                Write-by-copy-only formats (`.png`, `.jp2`) are refused. One
                of the two internal write paths could produce them --
                aligned, same-dtype inputs go through a VRT and
                `CreateCopy` -- but which path runs depends on `align` and
                on whether the sources share a dtype, neither of which says
                anything about the destination format. Accepting `.png` only
                sometimes would make the destination's legality depend on an
                unrelated argument, so both paths answer alike.

        Returns:
            Dataset: A multi-band dataset with `band_count == len(files)`
            and `band_names` set.

        Raises:
            ValueError: `files` is empty, `band_names` length does not
                match `files`, an input has more than one band, or
                `resampling` names an unsupported algorithm / a band that is
                not being stacked.
            TypeError: `resampling` is neither a string, a mapping nor `None`.
            AlignmentError: `align=False` and the inputs do not share a
                grid/CRS.
            CRSError: An input raster has no CRS.
            DriverNotExistError: `path` has no extension, or one the driver
                catalog does not know.
            FileFormatNotSupportedError: `path`'s extension maps to a
                write-by-copy-only format, whichever write path the inputs
                take.

        Examples:
            - Stack three per-band GeoTIFFs into one 3-band dataset; band
              names come from the file names:
                ```python
                >>> import numpy as np
                >>> import tempfile, os
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> d = tempfile.mkdtemp()
                >>> paths = []
                >>> triples = [("scene.B2.tif", 2), ("scene.B3.tif", 3), ("scene.B4.tif", 4)]
                >>> for name, val in triples:
                ...     p = os.path.join(d, name)
                ...     _ = Dataset.from_array(
                ...         np.full((4, 5), val, dtype="int16"),
                ...         geo_ref=GeoReference(
                ...             top_left_corner=(0, 0), cell_size=1.0, epsg=4326
                ...         ),
                ...         path=p,
                ...     ).close()
                ...     paths.append(p)
                >>> ds = Dataset.from_band_files(paths)
                >>> ds.band_count
                3
                >>> ds.band_names
                ['B2', 'B3', 'B4']
                >>> [int(ds.read_array(band=i).flat[0]) for i in range(3)]
                [2, 3, 4]

                ```
            - Override the band names explicitly:
                ```python
                >>> ds = Dataset.from_band_files(paths, band_names=["blue", "green", "red"])
                >>> ds.band_names
                ['blue', 'green', 'red']

                ```
            - Mismatched grids are rejected unless `align=True`:
                ```python
                >>> odd = os.path.join(d, "odd.tif")
                >>> _ = Dataset.from_array(
                ...     np.zeros((8, 9), dtype="int16"),
                ...     geo_ref=GeoReference(
                ...         top_left_corner=(0, 0), cell_size=0.5, epsg=4326
                ...     ),
                ...     path=odd,
                ... ).close()
                >>> try:
                ...     Dataset.from_band_files([paths[0], odd])
                ... except AlignmentError as exc:
                ...     print("align=True" in str(exc))
                True
                >>> aligned = Dataset.from_band_files([paths[0], odd], align=True)
                >>> aligned.band_count
                2
                >>> (aligned.rows, aligned.columns) == (
                ...     Dataset.read_file(paths[0]).rows,
                ...     Dataset.read_file(paths[0]).columns,
                ... )
                True

                ```
            - Pick the resampling per band — interpolate the mismatched band
              while everything else stays on nearest:
                ```python
                >>> mixed = Dataset.from_band_files(
                ...     [paths[0], odd], align=True, resampling={"odd": "bilinear"}
                ... )
                >>> mixed.band_names
                ['B2', 'odd']

                ```

        See Also:
            - :meth:`align`: resample one dataset onto another's grid.
            - :meth:`from_array`: build a dataset from a numpy array.
            - :meth:`pyramids.dataset.DatasetCollection.from_files`: stack
              rasters along *time* instead of along *bands*.
        """
        resolved_paths = [str(_io._parse_path(str(p))) for p in files]
        if not resolved_paths:
            raise ValueError("from_band_files requires at least one file")

        datasets = [cls.read_file(p) for p in resolved_paths]
        for p, ds in zip(resolved_paths, datasets):
            if ds.band_count != 1:
                raise ValueError(
                    f"{p!r} has {ds.band_count} bands; from_band_files expects exactly "
                    "one band per file"
                )
            if not ds.crs:
                raise CRSError(f"{p!r} has no CRS; cannot stack rasters without a CRS")

        template = datasets[0]

        if band_names is not None:
            out_names = list(band_names)
            if len(out_names) != len(resolved_paths):
                raise ValueError(
                    f"band_names has {len(out_names)} entries but {len(resolved_paths)} "
                    "files were given"
                )
        else:
            out_names = _derive_band_names(resolved_paths)

        if resampling is not None and not align:
            raise ValueError(
                "resampling only applies to the align=True path, which is what "
                "resamples mismatched inputs onto the first file's grid; with "
                "align=False a mismatch raises instead. Pass align=True, or drop "
                "resampling."
            )
        band_methods = _resolve_band_resampling(resampling, out_names)

        if no_data_value is INHERIT_NO_DATA:
            resolved_nd: Any | None = inherit_no_data(
                [ds.no_data_value[0] for ds in datasets]
            )
        else:
            resolved_nd = no_data_value

        if not align:
            for p, ds in zip(resolved_paths[1:], datasets[1:]):
                if not template.spatial.same_grid(ds):
                    raise AlignmentError(
                        f"{p!r} does not share the grid/CRS of {resolved_paths[0]!r}; "
                        "pass align=True to resample mismatched rasters onto the first "
                        "file's grid"
                    )

        # gdal.BuildVRT(separate=True) does not promote dtypes (it truncates the
        # wider bands) — take that low-memory band-by-band path only when the
        # grids already match and every input shares one dtype. Otherwise read
        # the (possibly resampled) band arrays and let numpy pick the common dtype.
        uniform_dtype = len({ds.gdal_dtype[0] for ds in datasets}) == 1

        if align or not uniform_dtype:
            # Resolve the common output dtype up front so the output can be
            # allocated once and written band-by-band, instead of reading every
            # band, np.stacking them into a second full-cube copy, and writing the
            # lot — peak drops from ~O(N·grid) to one band + the output (ARC-50).
            target_np_dtype = np.result_type(*(ds.numpy_dtype[0] for ds in datasets))
            grid_template = None
            if align:
                # Resample every input onto the first file's grid in the promoted
                # dtype. Dataset.align adopts the alignment source's dtype, so cast
                # the template first to avoid truncating wider inputs (e.g. a float
                # band onto an int template).
                # `Dataset.from_array`, not `cls.from_array`: same reason as
                # `convert_units`. On a NetCDF subclass the override returns a
                # bandless Container, and this template is then read band-wise.
                grid_template = Dataset.from_array(
                    template.read_array(band=0, unpack=False).astype(
                        target_np_dtype, copy=False
                    ),
                    # epsg is None only for a no-EPSG CRS reported as such (a NetCDF
                    # geostationary grid); from_array raises CRSError on None, so
                    # fall back to the WKT. No-op for a plain Dataset (#706).
                    geo_ref=GeoReference(
                        geo=template.geotransform,
                        epsg=crs_spec(template.epsg, template.crs),
                    ),
                    no_data_value=resolved_nd,
                )
            obj = cls._build_dataset(
                template.columns,
                template.rows,
                len(resolved_paths),
                numpy_to_gdal_dtype(target_np_dtype),
                template.geotransform,
                template.crs,
                resolved_nd,
                path=path,
                array=None,
            )
            for band_i, ds_i in enumerate(datasets):
                # `unpack=False` throughout: this branch stacks the sources' stored
                # bands into one raster and carries each band's packing over below, which
                # is what the `BuildVRT` branch gets for free from `CreateCopy`. Reading
                # physical values instead would truncate them back into the promoted
                # *stored* dtype -- an int16 stack of packed inputs losing everything
                # after the point -- and leave the two branches disagreeing.
                if align and not template.spatial.same_grid(ds_i):
                    arr = ds_i.align(
                        grid_template, method=band_methods[band_i]
                    ).read_array(band=0, unpack=False)
                else:
                    # Same grid (or the non-align mixed-dtype path): just cast to
                    # the promoted dtype, which is lossless.
                    arr = ds_i.read_array(band=0, unpack=False).astype(
                        target_np_dtype, copy=False
                    )
                if align:
                    # Dataset.align fills the warp fringe with the SOURCE's sentinel;
                    # when sources disagree on nodata (first-wins resolved_nd + a
                    # UserWarning) remap so the array matches the band's declared
                    # nodata. A same-grid source skips the warp and is lossless.
                    arr = _remap_nodata_to(arr, ds_i.no_data_value[0], resolved_nd)
                obj.raster.GetRasterBand(band_i + 1).WriteArray(arr)
                carry_band_packing(
                    ds_i.raster.GetRasterBand(1),
                    obj.raster.GetRasterBand(band_i + 1),
                )
                del arr
            obj._raster.FlushCache()
        else:
            vrt = gdal.BuildVRT("", resolved_paths, separate=True)
            if (
                vrt is None
            ):  # pragma: no cover - BuildVRT returns None only on bad input
                raise AlignmentError(
                    f"gdal.BuildVRT could not stack {resolved_paths!r}"
                )
            if path is not None:
                # Resolve the driver from the extension like every other
                # factory. Hardcoding GTiff here is what forced the `.tif`-only
                # guard above: without it a `.nc` destination produced a GTiff
                # carrying a netCDF name, a file whose extension lies about its
                # contents. LZW is GTiff-specific, so it is applied only there.
                # Deliberately NOT `for_copy`, though this branch does use
                # `CreateCopy`. Which branch runs depends on `align` and on
                # whether the sources share a dtype -- things the caller cannot
                # easily predict -- so accepting `.png` here and refusing it on
                # the `Create` branch would make the destination's legality
                # depend on an unrelated argument. That is the same defect this
                # branch removed from `merge_rasters`; one gate for both paths.
                driver = resolve_output_driver(path)
                options = ["COMPRESS=LZW"] if driver == "GTiff" else []
                dst = gdal.GetDriverByName(driver).CreateCopy(
                    str(path), vrt, strict=1, options=options
                )
            else:
                dst = gdal.GetDriverByName(MEMORY_DRIVER).CreateCopy("", vrt, strict=1)
            vrt = None
            # BuildVRT(separate=True) carries each source band's no-data through;
            # honour an explicit override (including ``None`` = drop it).
            for i in range(dst.RasterCount):
                band = dst.GetRasterBand(i + 1)
                if resolved_nd is None:
                    band.DeleteNoDataValue()
                else:
                    band.SetNoDataValue(float(resolved_nd))
            obj = cls(dst, access="write")

        obj.band_names = out_names
        obj._raster.FlushCache()
        return obj

    @classmethod
    def from_archive(
        cls,
        url_or_path: str | Path,
        *,
        kind: str = "auto",
        member_glob: str = "*",
        band_names: list[str] | None = None,
        align: bool = False,
        no_data_value: Any = INHERIT_NO_DATA,
        path: str | Path | None = None,
    ) -> Dataset:
        """Open every raster in an archive and merge them into one multi-band Dataset.

        Lists the archive's members (locally or over the network — a remote ZIP
        is read via the chained ``/vsizip//vsicurl/…`` path) and hands them to
        :meth:`from_band_files`. For "one Dataset per member" (a temporal stack)
        use :meth:`pyramids.dataset.DatasetCollection.from_archive` instead.

        GDAL driver ``open_options`` are **not** threaded through this
        band-stacking entry point; if a member needs a driver option, open it
        directly with :meth:`read_file` (which accepts ``open_options=``).

        The archive's file name must carry a recognised extension (``.zip`` /
        ``.tar`` / ``.tar.gz`` / ``.gz``) — GDAL's archive handlers key off the
        extension. An extension-less download URL (e.g. an Earth Engine
        ``getDownloadURL`` ending in ``:getPixels``) must first be fetched and
        saved with a ``.zip`` name (or written to ``/vsimem/<name>.zip`` via
        :func:`osgeo.gdal.FileFromMemBuffer`) before calling this.

        Args:
            url_or_path: Path or URL of the archive (``.zip`` / ``.tar`` /
                ``.tar.gz`` / ``.gz``).
            kind: Archive kind — ``"zip"``, ``"tar"`` (also ``"tar.gz"`` /
                ``"tgz"``), ``"gzip"`` (also ``"gz"``), or ``"auto"`` (default,
                infer from the extension).
            member_glob: :mod:`fnmatch` pattern selecting which members to stack.
                Default ``"*"`` (all top-level members, sorted by name). Pass e.g.
                ``"*.tif"`` for an archive that also ships sidecar files.
            band_names: Explicit per-band names; ``None`` derives them from the
                member names (see :meth:`from_band_files`).
            align: When ``True``, resample mismatched members onto the first
                member's grid instead of raising :class:`AlignmentError`.
            no_data_value: No-data value for the output bands; omitted means
                "inherit from the members".
            path: Output ``.tif`` path; ``None`` keeps the result in memory.

        Returns:
            Dataset: A multi-band dataset, one band per matching archive member.

        Raises:
            FileFormatNotSupportedError: ``kind="auto"`` and the extension is
                not recognised, or the archive could not be listed.
            FileNotFoundError: No member matched ``member_glob``.
            ValueError / AlignmentError / CRSError: As for :meth:`from_band_files`.

        Examples:
            - Stack the raster members of a local ZIP into one multi-band dataset
              (band names come from the member names):
                ```python
                >>> import os, tempfile, zipfile
                >>> import numpy as np
                >>> from pyramids.dataset import Dataset, GeoReference
                >>> d = tempfile.mkdtemp()
                >>> members = []
                >>> pairs = [("scene.B2.tif", 2), ("scene.B3.tif", 3)]
                >>> for name, val in pairs:
                ...     p = os.path.join(d, name)
                ...     _ = Dataset.from_array(
                ...         np.full((4, 5), val, dtype="int16"),
                ...         geo_ref=GeoReference(
                ...             top_left_corner=(0, 0), cell_size=1.0, epsg=4326
                ...         ),
                ...         path=p,
                ...     ).close()
                ...     members.append(p)
                >>> zip_path = os.path.join(d, "download.zip")
                >>> with zipfile.ZipFile(zip_path, "w") as zf:
                ...     for m in members:
                ...         zf.write(m, arcname=os.path.basename(m))
                >>> ds = Dataset.from_archive(zip_path, member_glob="*.tif")
                >>> ds.band_count
                2
                >>> ds.band_names
                ['B2', 'B3']
                >>> [int(ds.read_array(band=i).flat[0]) for i in range(2)]
                [2, 3]

                ```

        See Also:
            - :meth:`from_band_files`: stack a known list of single-band rasters.
            - :meth:`pyramids.dataset.DatasetCollection.from_archive`: open each
              member as a separate timestep instead of merging them into bands.
        """
        dir_vsi = _io._archive_dir_vsi(url_or_path, kind)
        members = _io._archive_members(dir_vsi, member_glob)
        member_paths = [f"{dir_vsi}/{m}" for m in members]
        return cls.from_band_files(
            member_paths,
            band_names=band_names,
            align=align,
            no_data_value=no_data_value,
            path=path,
        )

is_cog property

Facade — delegates to :attr:COG.is_cog <pyramids.dataset.engines.COG.is_cog>.

gcps property

Facade — :attr:Georef.gcps <pyramids.dataset.engines.Georef.gcps>.

gcp_count property

Facade — :attr:Georef.gcp_count <pyramids.dataset.engines.Georef.gcp_count>.

gcp_projection property

Facade — :attr:Georef.gcp_projection <pyramids.dataset.engines.Georef.gcp_projection>.

has_gcps property

Facade — :attr:Georef.has_gcps <pyramids.dataset.engines.Georef.has_gcps>.

rpcs property

Facade — :attr:Georef.rpcs <pyramids.dataset.engines.Georef.rpcs>.

has_rpcs property

Facade — :attr:Georef.has_rpcs <pyramids.dataset.engines.Georef.has_rpcs>.

geolocation property

Facade — :attr:Georef.geolocation <pyramids.dataset.engines.Georef.geolocation>.

has_geolocation property

Facade — :attr:Georef.has_geolocation <pyramids.dataset.engines.Georef.has_geolocation>.

overview_count property

Facade — delegates to :attr:IO.overview_count <pyramids.dataset.engines.IO.overview_count>.

band_color property writable

Facade — delegates to :attr:Bands.band_color <pyramids.dataset.engines.Bands.band_color>.

color_table property writable

Facade — delegates to :attr:Bands.color_table <pyramids.dataset.engines.Bands.color_table>.

access property

Access mode.

Returns:

Name	Type	Description
str	str	The access mode of the dataset (read_only/write).

raster property

Base GDAL Dataset (read-only).

rows property

Number of rows in the raster array.

columns property

Number of columns in the raster array.

shape property

Shape (bands, rows, columns).

epsg property writable

EPSG number, or None.

None means either the raster has no CRS at all — pyramids does not assume WGS 84 for an unprojected grid (ARC-26) — or its CRS carries no EPSG authority code (a geostationary fixed-grid projection, say). Read :attr:crs to tell the two apart: it is empty in the first case and a WKT string in the second.

crs property writable

Coordinate reference system.

Returns:

Name	Type	Description
str	str	the coordinate reference system of the dataset.

See Also

Dataset.set_crs : Set the Coordinate Reference System (CRS). Dataset.to_crs : Reproject the dataset to any projection. Dataset.epsg : epsg number of the dataset coordinate reference system.

cell_size property

Cell size.

band_count property

Number of bands in the raster.

band_names property writable

Band names.

band_units property writable

Facade — delegates to :attr:Bands.band_units <pyramids.dataset.engines.Bands.band_units>.

no_data_value property writable

Per-band nodata markers as an immutable tuple.

Returns a tuple (not a list) to make the read-only contract explicit — assign through the setter to change values; mutating the returned object never propagates to the underlying state.

The entries are numbers, not necessarily Python ints. No dtype fabricates a sentinel on a caller's behalf: a NaN asked of an integer band is reported back as NaN and an unset no-data as None, whatever the dtype, rather than being answered with a number the band's real data may already hold. Writing such a sentinel to the band is the step that refuses — change_no_data_value(None) on any integer raster raises NoDataValueError, since there is nothing storable to write.

A sentinel that is set still round-trips through GDAL's SetNoDataValue, which takes a C double, so a uint16 band asked for 65535 reports (np.float64(65535.0),). Compare with == rather than is, and call float(...) / int(...) before anything that needs a builtin (JSON, % formatting of an int). uint64 is the one row that stays a numpy integer, since its maximum has no exact float64: it reports np.uint64(2**64 - 1). See docs/migration.md, dataset / unreleased.

Returns:

Name	Type	Description
tuple	tuple	One entry per band, in band order -- a number, or None for
	tuple	a band that declares no sentinel.

Examples:

• A band created with a sentinel reports it, through GDAL's C double:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
  >>> raster = Dataset.from_array(
  ...     np.ones((4, 4), "float32"), geo_ref=geo_ref, no_data_value=-9999.0
  ... )
  >>> raster.no_data_value
  (np.float64(-9999.0),)
  

• An integer band asked for NaN reports NaN, not a fabricated maximum, so nothing in it is marked absent:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
  >>> raster = Dataset.create(
  ...     rows=4, columns=4, bands=1, dtype="uint16",
  ...     no_data_value=np.nan, geo_ref=geo_ref,
  ... )
  >>> bool(np.isnan(raster.no_data_value[0]))
  True
  

• One entry per band, so a two-band raster reports a pair:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
  >>> raster = Dataset.from_array(
  ...     np.ones((2, 4, 4), "float32"), geo_ref=geo_ref, no_data_value=0.0
  ... )
  >>> len(raster.no_data_value)
  2
  

See Also

change_no_data_value: Rewrites the cells as well as the declaration, and refuses a sentinel the band cannot store.

meta_data property writable

Meta-data.

band_meta_data property writable

Per-band metadata, one mapping per band, in band order.

The per-band sibling of :attr:meta_data. Facade — delegates to :attr:Bands.metadata <pyramids.dataset.engines.Bands.metadata>; see it for the empty-band and default-domain conventions.

Returns:

Type	Description
list[dict[str, str]]	list[dict[str, str]]: One mapping per band (0-based, band order); an empty
list[dict[str, str]]	dict for a band with no metadata.

file_name property

File name.

driver_type property

Driver Type.

scale property writable

Facade — delegates to :attr:Bands.scale <pyramids.dataset.engines.Bands.scale>.

The CF packing factor: how the real-world values are stored, not what the values you hold already mean. real = stored * scale + offset.

Since #1124 a read applies it, so :meth:read_array hands back real-world values and this stays the recipe describing the file. The two must not be applied twice: an array that has already been unpacked belongs in a dataset that declares no packing (scale == 1), which is what :meth:apply and :meth:from_array produce. An operation that copies the stored bytes -- :meth:copy, a CreateCopy write -- carries the recipe along with them instead, and stays consistent that way.

This reports each GDAL band's own slot. NetCDF overrides it to report the variable's own _scale when it carries one, since a read applies that ahead of the band's (see _effective_packing) -- so on every class the property names the factor the values are actually unpacked with.

Returns:

Type	Description
list[float]	list[float]: One factor per band; 1.0 where a band is not packed.

offset property writable

Facade — delegates to :attr:Bands.offset <pyramids.dataset.engines.Bands.offset>.

The additive half of the CF packing, real = stored * scale + offset. See :attr:scale for how the stored form and the values' meaning are kept apart; like it, NetCDF reports the variable's own _offset when it carries one.

Returns:

Type	Description
	list[float]: One offset per band; 0 where a band is not packed.

top_left_corner property

Top left corner coordinates.

See Also

• Dataset.geotransform: Dataset geotransform.

bounds property

Bounds - the bbox as a geodataframe with a polygon geometry.

See Also

• Dataset.bbox: Dataset bounding box.

bbox property

The raster's map-space bounding box, [xmin, ymin, xmax, ymax].

Always normalised min-before-max on each axis, whatever the geotransform's orientation: a south-up (positive geotransform[5]), east-left (negative geotransform[1]) or rotated grid returns a proper box, not an inverted one. Derived from :meth:~pyramids.dataset.transform.GeoTransform.extent.

Examples:

• A north-up raster spans its cells:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=3857),
  ... )
  >>> ds.bbox
  [0.0, 0.0, 3.0, 2.0]
  

• A south-up raster (positive y step) reports the same box, not an inverted one:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 0.0, 0.0, 1.0), epsg=3857),
  ... )
  >>> ds.bbox
  [0.0, 0.0, 3.0, 2.0]
  

See Also

• Dataset.bounds: Dataset bounding polygon.

total_bounds property

Bounding box [minx, miny, maxx, maxy] as a NumPy array.

introduced this property so that Dataset and :class:pyramids.feature.FeatureCollection expose the same shape (GeoDataFrame.total_bounds is the geopandas name for exactly this array), letting both classes satisfy the :class:pyramids.base.protocols.SpatialObject protocol.

lon property

Longitude / x cell-centre coordinates.

Uses the geotransform's pixel width (geotransform[1]) so the axis is correct even when cells are not square (pixel width != pixel height). Reads the cached _geotransform (like :attr:top_left_corner) rather than the geotransform property, so subclasses that derive geotransform from lon/lat (e.g. :class:~pyramids.netcdf.NetCDF) do not recurse.

Examples:

• Read the column-centre longitudes of a small raster:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
  ... )
  >>> ds.lon.tolist()
  [0.25, 0.75, 1.25]
  

See Also

• Dataset.x: Dataset x coordinates.
• Dataset.lat: Dataset latitude.

lat property

Latitude / y cell-centre coordinates.

Uses the geotransform's signed pixel height (geotransform[5]) rather than :attr:cell_size (which only tracks pixel width), so the axis is correct for non-square cells and honours the step's sign — a north-up raster (negative geotransform[5]) descends from north to south and a south-up one (positive geotransform[5]) ascends, mirroring how :attr:lon honours geotransform[1]. Reads the cached _geotransform (like :attr:top_left_corner) rather than the geotransform property, so subclasses that derive geotransform from lon/lat (e.g. :class:~pyramids.netcdf.NetCDF) do not recurse.

Examples:

• A north-up raster's row-centre latitudes decrease from north to south:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
  ... )
  >>> ds.lat.tolist()
  [-0.25, -0.75]
  

• A south-up raster (positive geotransform[5]) ascends instead:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 0.0, 0.0, 1.0), epsg=3857),
  ... )
  >>> ds.lat.tolist()
  [0.5, 1.5]
  

• With non-square cells the latitude axis uses the pixel height, not the pixel width:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(geo=(10.0, 2.0, 0.0, 50.0, 0.0, -1.0), epsg=4326),
  ... )
  >>> ds.lat.tolist()
  [49.5, 48.5]
  

See Also

• Dataset.x: Dataset x coordinates.
• Dataset.y: Dataset y coordinates.
• Dataset.lon: Dataset longitude.

x property

X cell-centre coordinates (alias of :attr:lon).

Examples:

• x mirrors lon for the same raster:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
  ... )
  >>> ds.x.tolist()
  [0.25, 0.75, 1.25]
  

See Also

• Dataset.lon: the longitude axis this property aliases.
• Dataset.y: Dataset y coordinates.

y property

Y cell-centre coordinates (alias of :attr:lat).

Examples:

• y mirrors lat for the same raster:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 3)),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 0.0), cell_size=0.5, epsg=4326),
  ... )
  >>> ds.y.tolist()
  [-0.25, -0.75]
  

See Also

• Dataset.lat: the latitude axis this property aliases.
• Dataset.x: Dataset x coordinates.

gdal_dtype property

Data Type.

numpy_dtype property

List of the numpy data Type of each band, the data type is a numpy function.

dtype property

The data type of each band, as a string.

numpy's spelling wherever numpy has one -- so a Byte band reports uint8, which is what STAC's raster:bands[].data_type wants and what this branch changed it to. GDAL's complex-integer and complex-half types have no numpy name (numpy's narrowest complex is a pair of float32), so those keep the catalog's own spelling rather than all collapsing onto complex64 and losing which type the band is.

Returns:

Type	Description
list[str]	list[str]: One name per band, in band order.

See Also

gdal_dtype: The raw GDAL type constants these are derived from. pyramids.base._utils.gdal_dtype_name: The per-code mapping.

__init__(src, access='read_only', *, gdal_env=None, open_options=None)

Wrap an open gdal.Dataset as a :class:Dataset.

A thin override of :meth:RasterBase.__init__ that attaches a logger and forwards every argument unchanged; see the base for the full contract. Prefer :meth:read_file over constructing directly.

Parameters:

Name	Type	Description	Default
src	Dataset	An open :class:osgeo.gdal.Dataset to wrap.	required
access	str	The mode src was opened with — "read_only" (default) or "write".	'read_only'
gdal_env	dict[str, str] | None	GDAL config captured for reopen paths; None captures nothing.	None
open_options	tuple[str, ...] | list[str] | None	GDAL open options captured for reopen paths; None captures nothing (#1025).	None

Source code in src/pyramids/dataset/dataset.py

def __init__(
    self,
    src: gdal.Dataset,
    access: str = "read_only",
    *,
    gdal_env: dict[str, str] | None = None,
    open_options: tuple[str, ...] | list[str] | None = None,
):
    """Wrap an open ``gdal.Dataset`` as a :class:`Dataset`.

    A thin override of :meth:`RasterBase.__init__` that attaches a logger and
    forwards every argument unchanged; see the base for the full contract.
    Prefer :meth:`read_file` over constructing directly.

    Args:
        src: An open :class:`osgeo.gdal.Dataset` to wrap.
        access: The mode ``src`` was opened with — ``"read_only"`` (default)
            or ``"write"``.
        gdal_env: GDAL config captured for reopen paths; ``None`` captures
            nothing.
        open_options: GDAL open options captured for reopen paths; ``None``
            captures nothing (#1025).
    """
    self.logger = logging.getLogger(__name__)
    super().__init__(
        src, access=access, gdal_env=gdal_env, open_options=open_options
    )

    self._no_data_value = [
        src.GetRasterBand(i).GetNoDataValue() for i in range(1, self.band_count + 1)
    ]
    self._band_names = self._get_band_names()
    self._band_units = [
        src.GetRasterBand(i).GetUnitType() for i in range(1, self.band_count + 1)
    ]

    # Each collaborator owns the bodies of one public-API family
    # (io, spatial, bands, analysis, cell, vectorize, cog) and
    # holds a `weakref.proxy(self)` back-reference. Dataset
    # exposes facade methods that delegate to the collaborator,
    # so both `ds.crop(mask)` and `ds.spatial.crop(mask)` are
    # equivalent.
    self.io = IO(self)
    self.spatial = Spatial(self)
    self.bands = Bands(self)
    self.analysis = Analysis(self)
    self.cell = Cell(self)
    self.vectorize = Vectorize(self)
    self.cog = COG(self)
    self.georef = Georef(self)

focal_mean(radius=1, *, chunks=None, band=0)

Thin forwarder to :func:pyramids.dataset.ops._focal.focal_mean.

Source code in src/pyramids/dataset/dataset.py

def focal_mean(
    self, radius: int = 1, *, chunks=None, band: int = 0
) -> np.ndarray | da.Array:
    """Thin forwarder to :func:`pyramids.dataset.ops._focal.focal_mean`."""
    return focal_mean(self, radius=radius, chunks=chunks, band=band)

focal_std(radius=1, *, chunks=None, band=0)

Thin forwarder to :func:pyramids.dataset.ops._focal.focal_std.

Source code in src/pyramids/dataset/dataset.py

def focal_std(
    self, radius: int = 1, *, chunks=None, band: int = 0
) -> np.ndarray | da.Array:
    """Thin forwarder to :func:`pyramids.dataset.ops._focal.focal_std`."""
    return focal_std(self, radius=radius, chunks=chunks, band=band)

focal_apply(func, radius=1, *, chunks=None, band=0)

Thin forwarder to :func:pyramids.dataset.ops._focal.focal_apply.

Source code in src/pyramids/dataset/dataset.py

def focal_apply(
    self, func, radius: int = 1, *, chunks=None, band: int = 0
) -> np.ndarray | da.Array:
    """Thin forwarder to :func:`pyramids.dataset.ops._focal.focal_apply`."""
    return focal_apply(self, func, radius=radius, chunks=chunks, band=band)

slope(*, chunks=None, band=0, units='degrees')

Thin forwarder to :func:pyramids.dataset.ops._focal.slope.

Source code in src/pyramids/dataset/dataset.py

def slope(
    self, *, chunks=None, band: int = 0, units: str = "degrees"
) -> np.ndarray | da.Array:
    """Thin forwarder to :func:`pyramids.dataset.ops._focal.slope`."""
    return slope(self, chunks=chunks, band=band, units=units)

aspect(*, chunks=None, band=0)

Thin forwarder to :func:pyramids.dataset.ops._focal.aspect.

Source code in src/pyramids/dataset/dataset.py

def aspect(self, *, chunks=None, band: int = 0) -> np.ndarray | da.Array:
    """Thin forwarder to :func:`pyramids.dataset.ops._focal.aspect`."""
    return aspect(self, chunks=chunks, band=band)

hillshade(*, azimuth=315.0, altitude=45.0, chunks=None, band=0)

Thin forwarder to :func:pyramids.dataset.ops._focal.hillshade.

Source code in src/pyramids/dataset/dataset.py

def hillshade(
    self,
    *,
    azimuth: float = 315.0,
    altitude: float = 45.0,
    chunks=None,
    band: int = 0,
) -> np.ndarray | da.Array:
    """Thin forwarder to :func:`pyramids.dataset.ops._focal.hillshade`."""
    return hillshade(
        self,
        azimuth=azimuth,
        altitude=altitude,
        chunks=chunks,
        band=band,
    )

get_cell_coords(*args, **kwargs)

Facade — delegates to :meth:Cell.get_cell_coords <pyramids.dataset.engines.Cell.get_cell_coords>.

Source code in src/pyramids/dataset/dataset.py

def get_cell_coords(self, *args, **kwargs):
    """Facade — delegates to :meth:`Cell.get_cell_coords <pyramids.dataset.engines.Cell.get_cell_coords>`."""
    return self.cell.get_cell_coords(*args, **kwargs)

cell_area(*args, **kwargs)

Facade — delegates to :meth:Cell.cell_area <pyramids.dataset.engines.Cell.cell_area>.

Source code in src/pyramids/dataset/dataset.py

def cell_area(self, *args, **kwargs):
    """Facade — delegates to :meth:`Cell.cell_area <pyramids.dataset.engines.Cell.cell_area>`."""
    return self.cell.cell_area(*args, **kwargs)

map_to_array_coordinates(*args, **kwargs)

Facade — delegates to :meth:Cell.map_to_array_coordinates <pyramids.dataset.engines.Cell.map_to_array_coordinates>.

Source code in src/pyramids/dataset/dataset.py

def map_to_array_coordinates(self, *args, **kwargs):
    """Facade — delegates to :meth:`Cell.map_to_array_coordinates <pyramids.dataset.engines.Cell.map_to_array_coordinates>`."""
    return self.cell.map_to_array_coordinates(*args, **kwargs)

array_to_map_coordinates(*args, **kwargs)

Facade — delegates to :meth:Cell.array_to_map_coordinates <pyramids.dataset.engines.Cell.array_to_map_coordinates>.

Source code in src/pyramids/dataset/dataset.py

def array_to_map_coordinates(self, *args, **kwargs):
    """Facade — delegates to :meth:`Cell.array_to_map_coordinates <pyramids.dataset.engines.Cell.array_to_map_coordinates>`."""
    return self.cell.array_to_map_coordinates(*args, **kwargs)

to_cog(*args, **kwargs)

Facade — delegates to :meth:COG.to_cog <pyramids.dataset.engines.COG.to_cog>.

Source code in src/pyramids/dataset/dataset.py

def to_cog(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.to_cog <pyramids.dataset.engines.COG.to_cog>`."""
    return self.cog.to_cog(*args, **kwargs)

validate_cog(*args, **kwargs)

Facade — delegates to :meth:COG.validate_cog <pyramids.dataset.engines.COG.validate_cog>.

Source code in src/pyramids/dataset/dataset.py

def validate_cog(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.validate_cog <pyramids.dataset.engines.COG.validate_cog>`."""
    return self.cog.validate_cog(*args, **kwargs)

cog_info(*args, **kwargs)

Facade — delegates to :meth:COG.info <pyramids.dataset.engines.COG.info>.

Source code in src/pyramids/dataset/dataset.py

def cog_info(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.info <pyramids.dataset.engines.COG.info>`."""
    return self.cog.info(*args, **kwargs)

to_cog_bytes(*args, **kwargs)

Facade — delegates to :meth:COG.to_cog_bytes <pyramids.dataset.engines.COG.to_cog_bytes>.

Source code in src/pyramids/dataset/dataset.py

def to_cog_bytes(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.to_cog_bytes <pyramids.dataset.engines.COG.to_cog_bytes>`."""
    return self.cog.to_cog_bytes(*args, **kwargs)

read_part(*args, **kwargs)

Facade — delegates to :meth:COG.read_part <pyramids.dataset.engines.COG.read_part>.

Typed with the engine's union return -- a bare array, or an (array, geotransform) tuple when return_transform=True -- so the public entry point stays type-safe instead of erasing to Any through the *args, **kwargs passthrough. The per-flag narrowing lives on COG.read_part; duplicating its @overload stubs here bought the facade nothing over this union and only tripped the duplication gate.

Source code in src/pyramids/dataset/dataset.py

def read_part(
    self, *args, **kwargs
) -> (
    np.typing.NDArray
    | tuple[np.typing.NDArray, tuple[float, float, float, float, float, float]]
):
    """Facade — delegates to :meth:`COG.read_part <pyramids.dataset.engines.COG.read_part>`.

    Typed with the engine's union return -- a bare array, or an
    `(array, geotransform)` tuple when `return_transform=True` -- so the
    public entry point stays type-safe instead of erasing to `Any` through
    the `*args, **kwargs` passthrough. The per-flag narrowing lives on
    `COG.read_part`; duplicating its `@overload` stubs here bought the facade
    nothing over this union and only tripped the duplication gate.
    """
    # `*args`/`**kwargs` are `Any`, so the overloaded engine call resolves to
    # `Any`; cast back to the declared union to keep the facade type-safe.
    return cast(
        "np.typing.NDArray"
        " | tuple[np.typing.NDArray, tuple[float, float, float, float, float, float]]",
        self.cog.read_part(*args, **kwargs),
    )

preview(*args, **kwargs)

Facade — delegates to :meth:COG.preview <pyramids.dataset.engines.COG.preview>.

Source code in src/pyramids/dataset/dataset.py

def preview(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.preview <pyramids.dataset.engines.COG.preview>`."""
    return self.cog.preview(*args, **kwargs)

point(*args, **kwargs)

Facade — delegates to :meth:COG.point <pyramids.dataset.engines.COG.point>.

Source code in src/pyramids/dataset/dataset.py

def point(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.point <pyramids.dataset.engines.COG.point>`."""
    return self.cog.point(*args, **kwargs)

read_tile(*args, **kwargs)

Facade — delegates to :meth:COG.read_tile <pyramids.dataset.engines.COG.read_tile>.

Source code in src/pyramids/dataset/dataset.py

def read_tile(self, *args, **kwargs):
    """Facade — delegates to :meth:`COG.read_tile <pyramids.dataset.engines.COG.read_tile>`."""
    return self.cog.read_tile(*args, **kwargs)

to_geodataframe(*args, **kwargs)

Facade — delegates to :meth:Vectorize.to_geodataframe <pyramids.dataset.engines.Vectorize.to_geodataframe>.

Source code in src/pyramids/dataset/dataset.py

def to_geodataframe(self, *args, **kwargs):
    """Facade — delegates to :meth:`Vectorize.to_geodataframe <pyramids.dataset.engines.Vectorize.to_geodataframe>`."""
    return self.vectorize.to_geodataframe(*args, **kwargs)

contour(*args, **kwargs)

Facade — delegates to :meth:Vectorize.contour <pyramids.dataset.engines.Vectorize.contour>.

Source code in src/pyramids/dataset/dataset.py

def contour(self, *args, **kwargs):
    """Facade — delegates to :meth:`Vectorize.contour <pyramids.dataset.engines.Vectorize.contour>`."""
    return self.vectorize.contour(*args, **kwargs)

translate(*args, **kwargs)

Facade — delegates to :meth:Vectorize.translate <pyramids.dataset.engines.Vectorize.translate>.

Source code in src/pyramids/dataset/dataset.py

def translate(self, *args, **kwargs):
    """Facade — delegates to :meth:`Vectorize.translate <pyramids.dataset.engines.Vectorize.translate>`."""
    return self.vectorize.translate(*args, **kwargs)

cluster(*args, **kwargs)

Facade — delegates to :meth:Vectorize.cluster <pyramids.dataset.engines.Vectorize.cluster>.

Source code in src/pyramids/dataset/dataset.py

def cluster(self, *args, **kwargs):
    """Facade — delegates to :meth:`Vectorize.cluster <pyramids.dataset.engines.Vectorize.cluster>`."""
    return self.vectorize.cluster(*args, **kwargs)

to_polygons(*args, **kwargs)

Facade — delegates to :meth:Vectorize.to_polygons <pyramids.dataset.engines.Vectorize.to_polygons>.

Source code in src/pyramids/dataset/dataset.py

def to_polygons(self, *args, **kwargs):
    """Facade — delegates to :meth:`Vectorize.to_polygons <pyramids.dataset.engines.Vectorize.to_polygons>`."""
    return self.vectorize.to_polygons(*args, **kwargs)

cluster2(*args, **kwargs)

Deprecated alias for :meth:to_polygons — delegates to :meth:Vectorize.cluster2 <pyramids.dataset.engines.Vectorize.cluster2>.

Source code in src/pyramids/dataset/dataset.py

def cluster2(self, *args, **kwargs):
    """Deprecated alias for :meth:`to_polygons` — delegates to
    :meth:`Vectorize.cluster2 <pyramids.dataset.engines.Vectorize.cluster2>`."""
    return self.vectorize.cluster2(*args, **kwargs)

stats(*args, **kwargs)

Facade — delegates to :meth:Analysis.stats <pyramids.dataset.engines.Analysis.stats>.

Source code in src/pyramids/dataset/dataset.py

def stats(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.stats <pyramids.dataset.engines.Analysis.stats>`."""
    return self.analysis.stats(*args, **kwargs)

domain_area(*args, **kwargs)

Facade — delegates to :meth:Analysis.domain_area <pyramids.dataset.engines.Analysis.domain_area>.

Source code in src/pyramids/dataset/dataset.py

def domain_area(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.domain_area <pyramids.dataset.engines.Analysis.domain_area>`."""
    return self.analysis.domain_area(*args, **kwargs)

count_domain_cells(*args, **kwargs)

Facade — delegates to :meth:Analysis.count_domain_cells <pyramids.dataset.engines.Analysis.count_domain_cells>.

Source code in src/pyramids/dataset/dataset.py

def count_domain_cells(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.count_domain_cells <pyramids.dataset.engines.Analysis.count_domain_cells>`."""
    return self.analysis.count_domain_cells(*args, **kwargs)

apply(*args, **kwargs)

Facade — delegates to :meth:Analysis.apply <pyramids.dataset.engines.Analysis.apply>.

The collaborator returns None for inplace=True so the facade can substitute the actual self (preserving identity); the proxy used by the collaborator's back-reference would otherwise fail result is ds checks.

Source code in src/pyramids/dataset/dataset.py

def apply(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.apply <pyramids.dataset.engines.Analysis.apply>`.

    The collaborator returns `None` for `inplace=True` so the facade
    can substitute the actual `self` (preserving identity); the proxy
    used by the collaborator's back-reference would otherwise fail
    `result is ds` checks.
    """
    result = self.analysis.apply(*args, **kwargs)
    return self if result is None else result

combine(other, func, *, band=None, no_data_value=_DERIVE_NO_DATA)

Facade — delegates to :meth:Analysis.combine <pyramids.dataset.engines.Analysis.combine>.

Spelled out rather than *args, **kwargs like its neighbours: combine has keyword-only options and a no_data_value default that is neither None nor a value, so a bare forwarding signature tells an IDE or mypy user nothing — and a typo like no_data= would reach the engine as an unexpected keyword instead of being caught here.

Parameters:

Name	Type	Description	Default
other	Dataset	The second operand, on this dataset's grid.	required
func	Callable[[ndarray, ndarray], ndarray]	Binary callable applied to the operands' matching cells.	required
band	int | None	Zero-based band to combine, or None for every band.	None
no_data_value	Any	Sentinel for the result, as documented on the engine method. Left unset it is derived from the computed values.	_DERIVE_NO_DATA

Returns:

Name	Type	Description
Dataset	Dataset	The combined raster, on this dataset's grid.

Source code in src/pyramids/dataset/dataset.py

def combine(
    self,
    other: Dataset,
    func: Callable[[np.ndarray, np.ndarray], np.ndarray],
    *,
    band: int | None = None,
    no_data_value: Any = _DERIVE_NO_DATA,
) -> Dataset:
    """Facade — delegates to :meth:`Analysis.combine <pyramids.dataset.engines.Analysis.combine>`.

    Spelled out rather than `*args, **kwargs` like its neighbours: `combine`
    has keyword-only options and a `no_data_value` default that is neither
    `None` nor a value, so a bare forwarding signature tells an IDE or mypy
    user nothing — and a typo like `no_data=` would reach the engine as an
    unexpected keyword instead of being caught here.

    Args:
        other: The second operand, on this dataset's grid.
        func: Binary callable applied to the operands' matching cells.
        band: Zero-based band to combine, or `None` for every band.
        no_data_value: Sentinel for the result, as documented on the engine
            method. Left unset it is derived from the computed values.

    Returns:
        Dataset: The combined raster, on this dataset's grid.
    """
    return self.analysis.combine(
        other, func, band=band, no_data_value=no_data_value
    )

fill(*args, **kwargs)

Facade — delegates to :meth:Analysis.fill <pyramids.dataset.engines.Analysis.fill>.

The collaborator returns None for inplace=True; see :meth:apply for the rationale.

Source code in src/pyramids/dataset/dataset.py

def fill(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.fill <pyramids.dataset.engines.Analysis.fill>`.

    The collaborator returns `None` for `inplace=True`; see
    :meth:`apply` for the rationale.
    """
    result = self.analysis.fill(*args, **kwargs)
    return self if result is None else result

where(*args, **kwargs)

Facade — delegates to :meth:Analysis.where <pyramids.dataset.engines.Analysis.where>.

Keeps the cells a condition selects and masks the rest — the inverse of :meth:fill, which writes to the cells that are data rather than deciding which ones stay data.

Source code in src/pyramids/dataset/dataset.py

def where(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.where <pyramids.dataset.engines.Analysis.where>`.

    Keeps the cells a condition selects and masks the rest — the inverse of
    :meth:`fill`, which writes to the cells that are data rather than deciding which
    ones stay data.
    """
    return self.analysis.where(*args, **kwargs)

fillna(*args, **kwargs)

Facade — delegates to :meth:Analysis.fillna <pyramids.dataset.engines.Analysis.fillna>.

Writes to the gaps, where :meth:fill writes to the cells that already hold data. One letter apart, opposite effects.

Source code in src/pyramids/dataset/dataset.py

def fillna(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.fillna <pyramids.dataset.engines.Analysis.fillna>`.

    Writes to the **gaps**, where :meth:`fill` writes to the cells that already hold
    data. One letter apart, opposite effects.
    """
    return self.analysis.fillna(*args, **kwargs)

isnull(*args, **kwargs)

Facade — delegates to :meth:Analysis.isnull <pyramids.dataset.engines.Analysis.isnull>.

Source code in src/pyramids/dataset/dataset.py

def isnull(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.isnull <pyramids.dataset.engines.Analysis.isnull>`."""
    return self.analysis.isnull(*args, **kwargs)

equals(*args, **kwargs)

Facade — delegates to :meth:Analysis.equals <pyramids.dataset.engines.Analysis.equals>.

Value equality, which :meth:same_grid does not provide: that says two rasters could be combined, this says they agree.

Source code in src/pyramids/dataset/dataset.py

def equals(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.equals <pyramids.dataset.engines.Analysis.equals>`.

    Value equality, which :meth:`same_grid` does not provide: that says two rasters
    *could* be combined, this says they agree.
    """
    return self.analysis.equals(*args, **kwargs)

identical(*args, **kwargs)

Facade — delegates to :meth:Analysis.identical <pyramids.dataset.engines.Analysis.identical>.

:meth:equals with the attributes read too.

Source code in src/pyramids/dataset/dataset.py

def identical(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.identical <pyramids.dataset.engines.Analysis.identical>`.

    :meth:`equals` with the attributes read too.
    """
    return self.analysis.identical(*args, **kwargs)

clip(*args, **kwargs)

Facade — delegates to :meth:Analysis.clip <pyramids.dataset.engines.Analysis.clip>.

Source code in src/pyramids/dataset/dataset.py

def clip(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.clip <pyramids.dataset.engines.Analysis.clip>`."""
    return self.analysis.clip(*args, **kwargs)

round(*args, **kwargs)

Facade — delegates to :meth:Analysis.round <pyramids.dataset.engines.Analysis.round>.

Source code in src/pyramids/dataset/dataset.py

def round(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.round <pyramids.dataset.engines.Analysis.round>`."""
    return self.analysis.round(*args, **kwargs)

astype(*args, **kwargs)

Facade — delegates to :meth:Analysis.astype <pyramids.dataset.engines.Analysis.astype>.

Source code in src/pyramids/dataset/dataset.py

def astype(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.astype <pyramids.dataset.engines.Analysis.astype>`."""
    return self.analysis.astype(*args, **kwargs)

isin(*args, **kwargs)

Facade — delegates to :meth:Analysis.isin <pyramids.dataset.engines.Analysis.isin>.

Source code in src/pyramids/dataset/dataset.py

def isin(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.isin <pyramids.dataset.engines.Analysis.isin>`."""
    return self.analysis.isin(*args, **kwargs)

notnull(*args, **kwargs)

Facade — delegates to :meth:Analysis.notnull <pyramids.dataset.engines.Analysis.notnull>.

Source code in src/pyramids/dataset/dataset.py

def notnull(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.notnull <pyramids.dataset.engines.Analysis.notnull>`."""
    return self.analysis.notnull(*args, **kwargs)

extract(*args, **kwargs)

Facade — delegates to :meth:Analysis.extract <pyramids.dataset.engines.Analysis.extract>.

Source code in src/pyramids/dataset/dataset.py

def extract(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.extract <pyramids.dataset.engines.Analysis.extract>`."""
    return self.analysis.extract(*args, **kwargs)

sample(*args, **kwargs)

Facade — delegates to :meth:Analysis.sample <pyramids.dataset.engines.Analysis.sample>.

Source code in src/pyramids/dataset/dataset.py

def sample(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.sample <pyramids.dataset.engines.Analysis.sample>`."""
    return self.analysis.sample(*args, **kwargs)

transect(*args, **kwargs)

Facade — delegates to :meth:Analysis.transect <pyramids.dataset.engines.Analysis.transect>.

Source code in src/pyramids/dataset/dataset.py

def transect(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.transect <pyramids.dataset.engines.Analysis.transect>`."""
    return self.analysis.transect(*args, **kwargs)

sieve(*args, **kwargs)

Facade — delegates to :meth:Analysis.sieve <pyramids.dataset.engines.Analysis.sieve>.

Source code in src/pyramids/dataset/dataset.py

def sieve(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.sieve <pyramids.dataset.engines.Analysis.sieve>`."""
    return self.analysis.sieve(*args, **kwargs)

proximity(*args, **kwargs)

Facade — delegates to :meth:Analysis.proximity <pyramids.dataset.engines.Analysis.proximity>.

Source code in src/pyramids/dataset/dataset.py

def proximity(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.proximity <pyramids.dataset.engines.Analysis.proximity>`."""
    return self.analysis.proximity(*args, **kwargs)

pan_sharpen(*args, **kwargs)

Facade — delegates to :meth:Analysis.pan_sharpen <pyramids.dataset.engines.Analysis.pan_sharpen>.

Source code in src/pyramids/dataset/dataset.py

def pan_sharpen(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.pan_sharpen <pyramids.dataset.engines.Analysis.pan_sharpen>`."""
    return self.analysis.pan_sharpen(*args, **kwargs)

match_histogram(*args, **kwargs)

Facade — delegates to :meth:Analysis.match_histogram <pyramids.dataset.engines.Analysis.match_histogram>.

Source code in src/pyramids/dataset/dataset.py

def match_histogram(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.match_histogram <pyramids.dataset.engines.Analysis.match_histogram>`."""
    return self.analysis.match_histogram(*args, **kwargs)

percentile_stretch(*args, **kwargs)

Facade — delegates to :meth:Analysis.percentile_stretch <pyramids.dataset.engines.Analysis.percentile_stretch>.

Source code in src/pyramids/dataset/dataset.py

def percentile_stretch(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.percentile_stretch <pyramids.dataset.engines.Analysis.percentile_stretch>`."""
    return self.analysis.percentile_stretch(*args, **kwargs)

overlay(*args, **kwargs)

Facade — delegates to :meth:Analysis.overlay <pyramids.dataset.engines.Analysis.overlay>.

Source code in src/pyramids/dataset/dataset.py

def overlay(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.overlay <pyramids.dataset.engines.Analysis.overlay>`."""
    return self.analysis.overlay(*args, **kwargs)

get_mask(*args, **kwargs)

Facade — delegates to :meth:Analysis.get_mask <pyramids.dataset.engines.Analysis.get_mask>.

Source code in src/pyramids/dataset/dataset.py

def get_mask(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.get_mask <pyramids.dataset.engines.Analysis.get_mask>`."""
    return self.analysis.get_mask(*args, **kwargs)

mask_flags(*args, **kwargs)

Facade — :meth:Analysis.mask_flags <pyramids.dataset.engines.Analysis.mask_flags>.

Source code in src/pyramids/dataset/dataset.py

def mask_flags(self, *args, **kwargs):
    """Facade — :meth:`Analysis.mask_flags <pyramids.dataset.engines.Analysis.mask_flags>`."""
    return self.analysis.mask_flags(*args, **kwargs)

read_masks(*args, **kwargs)

Facade — :meth:Analysis.read_masks <pyramids.dataset.engines.Analysis.read_masks>.

Source code in src/pyramids/dataset/dataset.py

def read_masks(self, *args, **kwargs):
    """Facade — :meth:`Analysis.read_masks <pyramids.dataset.engines.Analysis.read_masks>`."""
    return self.analysis.read_masks(*args, **kwargs)

create_mask_band(*args, **kwargs)

Facade — :meth:Analysis.create_mask_band <pyramids.dataset.engines.Analysis.create_mask_band>.

Source code in src/pyramids/dataset/dataset.py

def create_mask_band(self, *args, **kwargs):
    """Facade — :meth:`Analysis.create_mask_band <pyramids.dataset.engines.Analysis.create_mask_band>`."""
    return self.analysis.create_mask_band(*args, **kwargs)

footprint(*args, **kwargs)

Facade — delegates to :meth:Analysis.footprint <pyramids.dataset.engines.Analysis.footprint>.

Source code in src/pyramids/dataset/dataset.py

def footprint(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.footprint <pyramids.dataset.engines.Analysis.footprint>`."""
    return self.analysis.footprint(*args, **kwargs)

get_histogram(*args, **kwargs)

Facade — delegates to :meth:Analysis.get_histogram <pyramids.dataset.engines.Analysis.get_histogram>.

Source code in src/pyramids/dataset/dataset.py

def get_histogram(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.get_histogram <pyramids.dataset.engines.Analysis.get_histogram>`."""
    return self.analysis.get_histogram(*args, **kwargs)

plot_histogram(*args, **kwargs)

Facade — delegates to :meth:Analysis.plot_histogram <pyramids.dataset.engines.Analysis.plot_histogram>.

Source code in src/pyramids/dataset/dataset.py

def plot_histogram(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.plot_histogram <pyramids.dataset.engines.Analysis.plot_histogram>`."""
    return self.analysis.plot_histogram(*args, **kwargs)

to_image(*args, **kwargs)

Facade — delegates to :meth:Analysis.to_image <pyramids.dataset.engines.Analysis.to_image>.

Source code in src/pyramids/dataset/dataset.py

def to_image(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.to_image <pyramids.dataset.engines.Analysis.to_image>`."""
    return self.analysis.to_image(*args, **kwargs)

plot_vector_field(*args, **kwargs)

Facade — delegates to :meth:Analysis.plot_vector_field <pyramids.dataset.engines.Analysis.plot_vector_field>.

Source code in src/pyramids/dataset/dataset.py

def plot_vector_field(self, *args, **kwargs):
    """Facade — delegates to :meth:`Analysis.plot_vector_field <pyramids.dataset.engines.Analysis.plot_vector_field>`."""
    return self.analysis.plot_vector_field(*args, **kwargs)

plot(band=None, exclude_value=None, overview=False, overview_index=0, basemap=None, colorbar=None, points=None, kind='auto', title=None, color=None, contour=None, cells=None, data_style=None, rgb_options=None, *, fig=None, ax=None, **kwargs)

Plot the values/overviews of a band.

Facade for :meth:Analysis.plot <pyramids.dataset.engines.Analysis.plot>. Resolves the band index via :meth:_resolve_plot_band (GeoTIFF/Sentinel semantics) and then forwards the call to the generic rendering engine.

When band is None and the dataset looks like an RGB image — i.e. it has at least 3 bands and at least one band is tagged as an RGB channel (red/green/blue) — the red band is auto-selected (either from rgb[0] or by resolving the colour tags). A palette_index, gray_index or other non-RGB interpretation does not count as RGB imagery. Otherwise the facade defaults to band 0. See :meth:Analysis.plot for the full kwargs surface.

The four satellite-imagery options (rgb, surface_reflectance, cutoff, percentile) are passed through the single rgb_options= dict.

Parameters:

Name	Type	Description	Default
band	int	Band index to render. When None, the index is resolved by :meth:_resolve_plot_band.	None
exclude_value	Any	Pixel value to mask out before plotting. Default is None.	None
overview	bool	If True, plot the overview pyramid level instead of the full-resolution array. Default is False.	False
overview_index	int	Index of the overview level to plot when overview=True. Default is 0.	0
basemap	bool, str, or Basemap	Reference layer, dispatched by type. True or a tile-provider string (e.g. "CartoDB.Positron") overlays a pyramids web-tile basemap. A pyramids.plot.Basemap(relief=..., features=...) draws a shaded-relief / coastline layer instead. Passing a dict here is a deprecated alias for Basemap (emits a DeprecationWarning). Default is None. Requires the [viz] extra.	None
colorbar	bool or ColorBar	Colour-bar spec. A pyramids.plot.ColorBar(label=…, length=…, orientation=…, …) draws a configured bar. The loose cbar_* / ticks_spacing kwargs it replaces were removed — passing one now raises a :class:ValueError pointing here. False hides the bar, None uses cleopatra's default. Default is None.	None
points	ndarray or PointOverlay	Point overlay. A 3-column array (value, row, col) draws unstyled points; pass a pyramids.plot.PointOverlay(points, color=…, size=…, …) to style them. Default is None.	None
kind	str	Renderer to use. "auto" (default) picks per data; otherwise one of "imshow" / "pcolormesh" / "contour" / "contourf".	'auto'
title	str	Axes title. Default is None (cleopatra's default title).	None
color	ColorScaling	Colour-scale spec pyramids.plot.ColorScaling (linear / power / sym-log / boundary / midpoint norm), e.g. ColorScaling.power(gamma=0.7) or ColorScaling.boundary(bounds=[0, 0.5, 1]). Default None.	None
contour	Contour	Contour-line spec pyramids.plot.Contour(levels=…, labels=…, label_kw=…). Default None.	None
cells	CellValues	Per-cell value annotation pyramids.plot.CellValues(show=…, size=…, background_threshold=…). Default None.	None
data_style	DataStyle	Data-style / relief spec pyramids.plot.DataStyle(style=…, hillshade=…). Default None.	None
rgb_options	dict	Grouped Sentinel-imagery options for a true-colour composite. Accepted keys: "rgb" (3- or 4-element band-index list [r, g, b(, a)], only honoured when the dataset has >= 3 bands and a colour interpretation), "surface_reflectance" (reflectance scale factor, e.g. 10000 for Sentinel-2), "cutoff" (per-band clip values), "percentile" (percentile stretch). Default is None.	None
fig	Figure	Draw into this figure instead of creating one. Pass it alongside ax; supplying fig on its own currently raises inside cleopatra (serapeum-org/cleopatra#326). Default is None.	None
ax	Axes	Draw into these axes instead of creating them. This is what lets several rasters share one figure — a plt.subplots grid of side-by-side panels — while every panel keeps the georeferenced extent and nodata masking that plot applies. An axes already carries its figure, so ax on its own is sufficient. A shared colour range across panels is then applied through the returned glyph, whose colour bar tracks its mappable (glyph.cbar.mappable is glyph.im), e.g. glyph.im.set_clim(0, vmax). Default is None. >>> import matplotlib.pyplot as plt # doctest: +SKIP >>> fig, axes = plt.subplots(1, 3) # doctest: +SKIP >>> panels = [ds.plot(fig=fig, ax=a) for a in axes] # doctest: +SKIP	None
**kwargs	Unpack[PlotKwargs]	Additional keyword arguments forwarded verbatim to :meth:Analysis.plot. See that method for the full kwargs surface (figure size, color scale, color bar, basemap, etc.). Notably add_colorbar (bool, default True) is a cleopatra pass-through: set add_colorbar=False to suppress the auto-generated colorbar (the returned glyph's cbar is then None).	{}

Returns:

Name	Type	Description
ArrayGlyph		A cleopatra ArrayGlyph wrapping the rendered figure. Use it to drop down to raw matplotlib: glyph.fig / glyph.ax — the :class:matplotlib.figure.Figure and :class:matplotlib.axes.Axes. glyph.im — the colour-mapped mappable (populated for every kind=: imshow/pcolormesh/contour/contourf). Use it to tweak colour limits after the fact, e.g. glyph.im.set_clim(0, 100). glyph.cbar — the auto-created :class:matplotlib.colorbar.Colorbar, or None when add_colorbar=False (or for RGB renders). >>> glyph = dataset.plot(band=0, kind="pcolormesh") # doctest: +SKIP >>> glyph.im.set_clim(0, 100) # doctest: +SKIP >>> _ = glyph.cbar.set_label("elevation [m]") # doctest: +SKIP

Examples:

• Render the first band of a single-band MEM raster. Tagged +SKIP because the call requires the optional [viz] extra (cleopatra + matplotlib):

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> arr = np.random.rand(8, 8).astype(np.float32)
>>> ds = Dataset.from_array(
...     arr,
...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
... )
>>> cleo = ds.plot()  # doctest: +SKIP
>>> cleo.fig          # doctest: +SKIP
<Figure size 800x800 with 2 Axes>

• Override the resolved band index. The facade forwards band=1 straight to the engine without consulting the heuristic:

>>> cleo = ds.plot(band=1)  # doctest: +SKIP

• Render a multi-band raster as a true-colour composite via the recommended rgb_options= group:

>>> arr3 = np.random.rand(3, 8, 8).astype(np.float32)
>>> rgb_ds = Dataset.from_array(
...     arr3,
...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
... )
>>> cleo = rgb_ds.plot(  # doctest: +SKIP
...     rgb_options={"rgb": [0, 1, 2], "surface_reflectance": 255},
... )

Source code in src/pyramids/dataset/dataset.py

def plot(  # type: ignore[override]
    self,
    band: int | None = None,
    exclude_value: Any | None = None,
    overview: bool | None = False,
    overview_index: int | None = 0,
    basemap: bool | str | dict[str, Any] | Basemap | None = None,
    colorbar: bool | ColorBar | None = None,
    points: np.ndarray | PointOverlay | None = None,
    kind: str = "auto",
    title: str | None = None,
    color: ColorScaling | None = None,
    contour: Contour | None = None,
    cells: CellValues | None = None,
    data_style: DataStyle | None = None,
    rgb_options: dict | None = None,
    *,
    fig: Figure | None = None,
    ax: Axes | None = None,
    **kwargs: Unpack[PlotKwargs],
):
    """Plot the values/overviews of a band.

    Facade for :meth:`Analysis.plot <pyramids.dataset.engines.Analysis.plot>`. Resolves
    the band index via :meth:`_resolve_plot_band` (GeoTIFF/Sentinel semantics) and then
    forwards the call to the generic rendering engine.

    When ``band`` is ``None`` and the dataset looks like an RGB image — i.e. it has
    at least 3 bands **and** at least one band is tagged as an RGB channel
    (``red``/``green``/``blue``) — the red band is auto-selected (either from
    ``rgb[0]`` or by resolving the colour tags). A ``palette_index``, ``gray_index``
    or other non-RGB interpretation does **not** count as RGB imagery. Otherwise the
    facade defaults to band ``0``. See :meth:`Analysis.plot` for the full kwargs
    surface.

    The four satellite-imagery options (``rgb``, ``surface_reflectance``, ``cutoff``,
    ``percentile``) are passed through the single ``rgb_options=`` dict.

    Args:
        band (int, optional):
            Band index to render. When ``None``, the index is resolved by
            :meth:`_resolve_plot_band`.
        exclude_value (Any, optional):
            Pixel value to mask out before plotting. Default is ``None``.
        overview (bool, optional):
            If ``True``, plot the overview pyramid level instead of the full-resolution
            array. Default is ``False``.
        overview_index (int, optional):
            Index of the overview level to plot when ``overview=True``. Default is ``0``.
        basemap (bool, str, or Basemap, optional):
            Reference layer, dispatched by type. ``True`` or a tile-provider string
            (e.g. ``"CartoDB.Positron"``) overlays a pyramids web-tile basemap. A
            ``pyramids.plot.Basemap(relief=..., features=...)``
            draws a shaded-relief / coastline layer instead. Passing a ``dict`` here is
            a deprecated alias for ``Basemap`` (emits a ``DeprecationWarning``). Default
            is ``None``. Requires the ``[viz]`` extra.
        colorbar (bool or ColorBar, optional):
            Colour-bar spec. A ``pyramids.plot.ColorBar(label=…, length=…,
            orientation=…, …)`` draws a configured bar. The loose ``cbar_*`` /
            ``ticks_spacing`` kwargs it replaces were removed — passing one now raises a
            :class:`ValueError` pointing here. ``False`` hides the bar, ``None`` uses
            cleopatra's default. Default is ``None``.
        points (np.ndarray or PointOverlay, optional):
            Point overlay. A 3-column array ``(value, row, col)`` draws unstyled
            points; pass a ``pyramids.plot.PointOverlay(points, color=…, size=…, …)``
            to style them. Default is ``None``.
        kind (str, optional):
            Renderer to use. ``"auto"`` (default) picks per data; otherwise one of
            ``"imshow"`` / ``"pcolormesh"`` / ``"contour"`` / ``"contourf"``.
        title (str, optional):
            Axes title. Default is ``None`` (cleopatra's default title).
        color (ColorScaling, optional):
            Colour-scale spec ``pyramids.plot.ColorScaling`` (linear / power / sym-log /
            boundary / midpoint norm), e.g. ``ColorScaling.power(gamma=0.7)`` or
            ``ColorScaling.boundary(bounds=[0, 0.5, 1])``. Default ``None``.
        contour (Contour, optional):
            Contour-line spec ``pyramids.plot.Contour(levels=…, labels=…, label_kw=…)``.
            Default ``None``.
        cells (CellValues, optional):
            Per-cell value annotation ``pyramids.plot.CellValues(show=…, size=…,
            background_threshold=…)``. Default ``None``.
        data_style (DataStyle, optional):
            Data-style / relief spec ``pyramids.plot.DataStyle(style=…, hillshade=…)``.
            Default ``None``.
        rgb_options (dict, optional):
            Grouped Sentinel-imagery options for a true-colour composite. Accepted
            keys: ``"rgb"`` (3- or 4-element band-index list ``[r, g, b(, a)]``, only
            honoured when the dataset has >= 3 bands and a colour interpretation),
            ``"surface_reflectance"`` (reflectance scale factor, e.g. ``10000`` for
            Sentinel-2), ``"cutoff"`` (per-band clip values), ``"percentile"``
            (percentile stretch). Default is ``None``.
        fig (matplotlib.figure.Figure, optional):
            Draw into this figure instead of creating one. Pass it alongside ``ax``;
            supplying ``fig`` on its own currently raises inside cleopatra
            (serapeum-org/cleopatra#326). Default is ``None``.
        ax (matplotlib.axes.Axes, optional):
            Draw into these axes instead of creating them. This is what lets several
            rasters share one figure — a ``plt.subplots`` grid of side-by-side panels —
            while every panel keeps the georeferenced extent and nodata masking that
            ``plot`` applies. An axes already carries its figure, so ``ax`` on its own
            is sufficient. A shared colour range across panels is then applied through
            the returned glyph, whose colour bar tracks its mappable
            (``glyph.cbar.mappable is glyph.im``), e.g. ``glyph.im.set_clim(0, vmax)``.
            Default is ``None``.

            ```python
            >>> import matplotlib.pyplot as plt  # doctest: +SKIP
            >>> fig, axes = plt.subplots(1, 3)  # doctest: +SKIP
            >>> panels = [ds.plot(fig=fig, ax=a) for a in axes]  # doctest: +SKIP

            ```
        **kwargs:
            Additional keyword arguments forwarded verbatim to
            :meth:`Analysis.plot`. See that method for the full kwargs surface
            (figure size, color scale, color bar, basemap, etc.). Notably
            ``add_colorbar`` (``bool``, default ``True``) is a cleopatra
            pass-through: set ``add_colorbar=False`` to suppress the
            auto-generated colorbar (the returned glyph's ``cbar`` is then
            ``None``).

    Returns:
        ArrayGlyph: A cleopatra ``ArrayGlyph`` wrapping the rendered figure.
            Use it to drop down to raw matplotlib:

            - ``glyph.fig`` / ``glyph.ax`` — the :class:`matplotlib.figure.Figure`
              and :class:`matplotlib.axes.Axes`.
            - ``glyph.im`` — the colour-mapped mappable (populated for every
              ``kind=``: imshow/pcolormesh/contour/contourf). Use it to tweak
              colour limits after the fact, e.g. ``glyph.im.set_clim(0, 100)``.
            - ``glyph.cbar`` — the auto-created :class:`matplotlib.colorbar.Colorbar`,
              or ``None`` when ``add_colorbar=False`` (or for RGB renders).

            ```python
            >>> glyph = dataset.plot(band=0, kind="pcolormesh")  # doctest: +SKIP
            >>> glyph.im.set_clim(0, 100)  # doctest: +SKIP
            >>> _ = glyph.cbar.set_label("elevation [m]")  # doctest: +SKIP

            ```

    Examples:
        - Render the first band of a single-band MEM raster. Tagged ``+SKIP`` because
          the call requires the optional ``[viz]`` extra (cleopatra + matplotlib):

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> arr = np.random.rand(8, 8).astype(np.float32)
          >>> ds = Dataset.from_array(
          ...     arr,
          ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
          ... )
          >>> cleo = ds.plot()  # doctest: +SKIP
          >>> cleo.fig          # doctest: +SKIP
          <Figure size 800x800 with 2 Axes>

          ```

        - Override the resolved band index. The facade forwards ``band=1`` straight
          to the engine without consulting the heuristic:

          ```python
          >>> cleo = ds.plot(band=1)  # doctest: +SKIP

          ```

        - Render a multi-band raster as a true-colour composite via the
          recommended ``rgb_options=`` group:

          ```python
          >>> arr3 = np.random.rand(3, 8, 8).astype(np.float32)
          >>> rgb_ds = Dataset.from_array(
          ...     arr3,
          ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=0.1, epsg=4326),
          ... )
          >>> cleo = rgb_ds.plot(  # doctest: +SKIP
          ...     rgb_options={"rgb": [0, 1, 2], "surface_reflectance": 255},
          ... )

          ```
    """
    rgb, surface_reflectance, cutoff, percentile = self._unpack_rgb_options(
        rgb_options
    )
    resolved_band, resolved_rgb = self._resolve_plot_band(band, rgb)
    # Spread the explicitly-set cleopatra render groups as their own ``**`` (not merged
    # into the typed ``**kwargs``, whose PlotKwargs TypedDict has no group keys); the
    # unset ones are dropped so they do not override cleopatra's backend default for
    # that group.
    group_kwargs = nonnull_group_kwargs(
        color=color, contour=contour, cells=cells, data_style=data_style
    )
    return self.analysis.plot(
        band=resolved_band,
        exclude_value=exclude_value,
        rgb=resolved_rgb,
        surface_reflectance=surface_reflectance,
        cutoff=cutoff,
        overview=overview,
        overview_index=overview_index,
        percentile=percentile,
        basemap=basemap,
        colorbar=colorbar,
        points=points,
        kind=kind,
        title=title,
        fig=fig,
        ax=ax,
        **group_kwargs,
        **kwargs,
    )

crop(*args, **kwargs)

Facade — delegates to :meth:Spatial.crop <pyramids.dataset.engines.Spatial.crop>.

Source code in src/pyramids/dataset/dataset.py

def crop(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.crop <pyramids.dataset.engines.Spatial.crop>`."""
    return self.spatial.crop(*args, **kwargs)

to_crs(*args, **kwargs)

Facade — delegates to :meth:Spatial.to_crs <pyramids.dataset.engines.Spatial.to_crs>.

Source code in src/pyramids/dataset/dataset.py

def to_crs(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.to_crs <pyramids.dataset.engines.Spatial.to_crs>`."""
    return self.spatial.to_crs(*args, **kwargs)

set_gcps(*args, **kwargs)

Facade — delegates to :meth:Georef.set_gcps <pyramids.dataset.engines.Georef.set_gcps>.

Source code in src/pyramids/dataset/dataset.py

def set_gcps(self, *args, **kwargs):
    """Facade — delegates to :meth:`Georef.set_gcps <pyramids.dataset.engines.Georef.set_gcps>`."""
    return self.georef.set_gcps(*args, **kwargs)

georeference(*args, **kwargs)

Facade — :meth:Georef.georeference <pyramids.dataset.engines.Georef.georeference>.

Source code in src/pyramids/dataset/dataset.py

def georeference(self, *args, **kwargs):
    """Facade — :meth:`Georef.georeference <pyramids.dataset.engines.Georef.georeference>`."""
    return self.georef.georeference(*args, **kwargs)

set_rpcs(*args, **kwargs)

Facade — :meth:Georef.set_rpcs <pyramids.dataset.engines.Georef.set_rpcs>.

Source code in src/pyramids/dataset/dataset.py

def set_rpcs(self, *args, **kwargs):
    """Facade — :meth:`Georef.set_rpcs <pyramids.dataset.engines.Georef.set_rpcs>`."""
    return self.georef.set_rpcs(*args, **kwargs)

orthorectify(*args, **kwargs)

Facade — :meth:Georef.orthorectify <pyramids.dataset.engines.Georef.orthorectify>.

Source code in src/pyramids/dataset/dataset.py

def orthorectify(self, *args, **kwargs):
    """Facade — :meth:`Georef.orthorectify <pyramids.dataset.engines.Georef.orthorectify>`."""
    return self.georef.orthorectify(*args, **kwargs)

geolocate(*args, **kwargs)

Facade — :meth:Georef.geolocate <pyramids.dataset.engines.Georef.geolocate>.

Source code in src/pyramids/dataset/dataset.py

def geolocate(self, *args, **kwargs):
    """Facade — :meth:`Georef.geolocate <pyramids.dataset.engines.Georef.geolocate>`."""
    return self.georef.geolocate(*args, **kwargs)

warped_view(*args, **kwargs)

Facade — delegates to :meth:Spatial.warped_view <pyramids.dataset.engines.Spatial.warped_view>.

Source code in src/pyramids/dataset/dataset.py

def warped_view(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.warped_view <pyramids.dataset.engines.Spatial.warped_view>`."""
    return self.spatial.warped_view(*args, **kwargs)

set_crs(*args, **kwargs)

Facade — delegates to :meth:Spatial.set_crs <pyramids.dataset.engines.Spatial.set_crs>.

Source code in src/pyramids/dataset/dataset.py

def set_crs(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.set_crs <pyramids.dataset.engines.Spatial.set_crs>`."""
    return self.spatial.set_crs(*args, **kwargs)

wrap_longitude(*args, **kwargs)

Facade — delegates to :meth:Spatial.wrap_longitude <pyramids.dataset.engines.Spatial.wrap_longitude>.

Source code in src/pyramids/dataset/dataset.py

def wrap_longitude(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.wrap_longitude <pyramids.dataset.engines.Spatial.wrap_longitude>`."""
    return self.spatial.wrap_longitude(*args, **kwargs)

resample(*args, **kwargs)

Facade — delegates to :meth:Spatial.resample <pyramids.dataset.engines.Spatial.resample>.

Source code in src/pyramids/dataset/dataset.py

def resample(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.resample <pyramids.dataset.engines.Spatial.resample>`."""
    return self.spatial.resample(*args, **kwargs)

align(*args, **kwargs)

Facade — delegates to :meth:Spatial.align <pyramids.dataset.engines.Spatial.align>.

Source code in src/pyramids/dataset/dataset.py

def align(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.align <pyramids.dataset.engines.Spatial.align>`."""
    return self.spatial.align(*args, **kwargs)

same_grid(other, *, compare_crs=True)

Facade — delegates to :meth:Spatial.same_grid <pyramids.dataset.engines.Spatial.same_grid>.

Spelled out for the same reason as :meth:combine, whose contract it states: the keyword-only compare_crs is invisible in a bare forwarding signature.

Parameters:

Name	Type	Description	Default
other	Dataset	Dataset to compare against this one.	required
compare_crs	bool	Whether the CRSes must agree too. Default True.	True

Returns:

Name	Type	Description
bool	bool	True iff both rasters occupy the same pixel grid.

Source code in src/pyramids/dataset/dataset.py

def same_grid(self, other: Dataset, *, compare_crs: bool = True) -> bool:
    """Facade — delegates to :meth:`Spatial.same_grid <pyramids.dataset.engines.Spatial.same_grid>`.

    Spelled out for the same reason as :meth:`combine`, whose contract it
    states: the keyword-only `compare_crs` is invisible in a bare forwarding
    signature.

    Args:
        other: Dataset to compare against this one.
        compare_crs: Whether the CRSes must agree too. Default `True`.

    Returns:
        bool: `True` iff both rasters occupy the same pixel grid.
    """
    return self.spatial.same_grid(other, compare_crs=compare_crs)

fill_gaps(*args, **kwargs)

Facade — delegates to :meth:Spatial.fill_gaps <pyramids.dataset.engines.Spatial.fill_gaps>.

Source code in src/pyramids/dataset/dataset.py

def fill_gaps(self, *args, **kwargs):
    """Facade — delegates to :meth:`Spatial.fill_gaps <pyramids.dataset.engines.Spatial.fill_gaps>`."""
    return self.spatial.fill_gaps(*args, **kwargs)

read_array(*args, **kwargs)

Facade — delegates to :meth:IO.read_array <pyramids.dataset.engines.IO.read_array>.

Source code in src/pyramids/dataset/dataset.py

def read_array(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.read_array <pyramids.dataset.engines.IO.read_array>`."""
    return self.io.read_array(*args, **kwargs)

read_windows(*args, **kwargs)

Facade — delegates to :meth:IO.read_windows <pyramids.dataset.engines.IO.read_windows>.

Source code in src/pyramids/dataset/dataset.py

def read_windows(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.read_windows <pyramids.dataset.engines.IO.read_windows>`."""
    return self.io.read_windows(*args, **kwargs)

write_array(*args, **kwargs)

Facade — delegates to :meth:IO.write_array <pyramids.dataset.engines.IO.write_array>.

Source code in src/pyramids/dataset/dataset.py

def write_array(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.write_array <pyramids.dataset.engines.IO.write_array>`."""
    return self.io.write_array(*args, **kwargs)

to_file(*args, **kwargs)

Facade — delegates to :meth:IO.to_file <pyramids.dataset.engines.IO.to_file>.

Source code in src/pyramids/dataset/dataset.py

def to_file(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.to_file <pyramids.dataset.engines.IO.to_file>`."""
    return self.io.to_file(*args, **kwargs)

to_bytes(*args, **kwargs)

Facade — delegates to :meth:IO.to_bytes <pyramids.dataset.engines.IO.to_bytes>.

Source code in src/pyramids/dataset/dataset.py

def to_bytes(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.to_bytes <pyramids.dataset.engines.IO.to_bytes>`."""
    return self.io.to_bytes(*args, **kwargs)

to_raster(*args, **kwargs)

Facade — delegates to :meth:IO.to_raster <pyramids.dataset.engines.IO.to_raster>.

Source code in src/pyramids/dataset/dataset.py

def to_raster(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.to_raster <pyramids.dataset.engines.IO.to_raster>`."""
    return self.io.to_raster(*args, **kwargs)

get_block_arrangement(*args, **kwargs)

Facade — delegates to :meth:IO.get_block_arrangement <pyramids.dataset.engines.IO.get_block_arrangement>.

Source code in src/pyramids/dataset/dataset.py

def get_block_arrangement(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.get_block_arrangement <pyramids.dataset.engines.IO.get_block_arrangement>`."""
    return self.io.get_block_arrangement(*args, **kwargs)

get_tile(*args, **kwargs)

Facade — delegates to :meth:IO.get_tile <pyramids.dataset.engines.IO.get_tile>.

Source code in src/pyramids/dataset/dataset.py

def get_tile(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.get_tile <pyramids.dataset.engines.IO.get_tile>`."""
    return self.io.get_tile(*args, **kwargs)

map_blocks(*args, **kwargs)

Facade — delegates to :meth:IO.map_blocks <pyramids.dataset.engines.IO.map_blocks>.

Source code in src/pyramids/dataset/dataset.py

def map_blocks(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.map_blocks <pyramids.dataset.engines.IO.map_blocks>`."""
    return self.io.map_blocks(*args, **kwargs)

to_xyz(*args, **kwargs)

Facade — delegates to :meth:IO.to_xyz <pyramids.dataset.engines.IO.to_xyz>.

Source code in src/pyramids/dataset/dataset.py

def to_xyz(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.to_xyz <pyramids.dataset.engines.IO.to_xyz>`."""
    return self.io.to_xyz(*args, **kwargs)

to_terrain_rgb(*args, **kwargs)

Facade — delegates to :meth:IO.to_terrain_rgb <pyramids.dataset.engines.IO.to_terrain_rgb>.

Source code in src/pyramids/dataset/dataset.py

def to_terrain_rgb(self, *args, **kwargs):
    """Facade — delegates to
    :meth:`IO.to_terrain_rgb <pyramids.dataset.engines.IO.to_terrain_rgb>`."""
    return self.io.to_terrain_rgb(*args, **kwargs)

create_overviews(*args, **kwargs)

Facade — delegates to :meth:IO.create_overviews <pyramids.dataset.engines.IO.create_overviews>.

Source code in src/pyramids/dataset/dataset.py

def create_overviews(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.create_overviews <pyramids.dataset.engines.IO.create_overviews>`."""
    return self.io.create_overviews(*args, **kwargs)

recreate_overviews(*args, **kwargs)

Facade — delegates to :meth:IO.recreate_overviews <pyramids.dataset.engines.IO.recreate_overviews>.

Source code in src/pyramids/dataset/dataset.py

def recreate_overviews(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.recreate_overviews <pyramids.dataset.engines.IO.recreate_overviews>`."""
    return self.io.recreate_overviews(*args, **kwargs)

get_overview(*args, **kwargs)

Facade — delegates to :meth:IO.get_overview <pyramids.dataset.engines.IO.get_overview>.

Source code in src/pyramids/dataset/dataset.py

def get_overview(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.get_overview <pyramids.dataset.engines.IO.get_overview>`."""
    return self.io.get_overview(*args, **kwargs)

get_overview_dataset(*args, **kwargs)

Facade — delegates to :meth:IO.get_overview_dataset <pyramids.dataset.engines.IO.get_overview_dataset>.

Source code in src/pyramids/dataset/dataset.py

def get_overview_dataset(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.get_overview_dataset <pyramids.dataset.engines.IO.get_overview_dataset>`."""
    return self.io.get_overview_dataset(*args, **kwargs)

read_overview_array(*args, **kwargs)

Facade — delegates to :meth:IO.read_overview_array <pyramids.dataset.engines.IO.read_overview_array>.

Source code in src/pyramids/dataset/dataset.py

def read_overview_array(self, *args, **kwargs):
    """Facade — delegates to :meth:`IO.read_overview_array <pyramids.dataset.engines.IO.read_overview_array>`."""
    return self.io.read_overview_array(*args, **kwargs)

get_attribute_table(*args, **kwargs)

Facade — delegates to :meth:Bands.get_attribute_table <pyramids.dataset.engines.Bands.get_attribute_table>.

Source code in src/pyramids/dataset/dataset.py

def get_attribute_table(self, *args, **kwargs):
    """Facade — delegates to :meth:`Bands.get_attribute_table <pyramids.dataset.engines.Bands.get_attribute_table>`."""
    return self.bands.get_attribute_table(*args, **kwargs)

set_attribute_table(*args, **kwargs)

Facade — delegates to :meth:Bands.set_attribute_table <pyramids.dataset.engines.Bands.set_attribute_table>.

Source code in src/pyramids/dataset/dataset.py

def set_attribute_table(self, *args, **kwargs):
    """Facade — delegates to :meth:`Bands.set_attribute_table <pyramids.dataset.engines.Bands.set_attribute_table>`."""
    return self.bands.set_attribute_table(*args, **kwargs)

add_band(*args, **kwargs)

Facade — delegates to :meth:Bands.add_band <pyramids.dataset.engines.Bands.add_band>.

Source code in src/pyramids/dataset/dataset.py

def add_band(self, *args, **kwargs):
    """Facade — delegates to :meth:`Bands.add_band <pyramids.dataset.engines.Bands.add_band>`."""
    return self.bands.add_band(*args, **kwargs)

get_band_by_color(*args, **kwargs)

Facade — delegates to :meth:Bands.get_band_by_color <pyramids.dataset.engines.Bands.get_band_by_color>.

Source code in src/pyramids/dataset/dataset.py

def get_band_by_color(self, *args, **kwargs):
    """Facade — delegates to :meth:`Bands.get_band_by_color <pyramids.dataset.engines.Bands.get_band_by_color>`."""
    return self.bands.get_band_by_color(*args, **kwargs)

select_bands(*args, **kwargs)

Facade — delegates to :meth:Bands.select <pyramids.dataset.engines.Bands.select>.

Source code in src/pyramids/dataset/dataset.py

def select_bands(self, *args, **kwargs):
    """Facade — delegates to :meth:`Bands.select <pyramids.dataset.engines.Bands.select>`."""
    return self.bands.select(*args, **kwargs)

change_no_data_value(*args, **kwargs)

Facade — concrete override of the abstract :meth:RasterBase.change_no_data_value.

The collaborator returns None for the inplace=True path; the facade substitutes self for identity preservation, matching :meth:apply and :meth:fill.

Source code in src/pyramids/dataset/dataset.py

def change_no_data_value(self, *args, **kwargs):
    """Facade — concrete override of the abstract :meth:`RasterBase.change_no_data_value`.

    The collaborator returns `None` for the `inplace=True` path; the
    facade substitutes `self` for identity preservation, matching
    :meth:`apply` and :meth:`fill`.
    """
    result = self.bands.change_no_data_value(*args, **kwargs)
    return self if result is None else result

set_color_ramp(band=1, *, start_value, end_value, start_color=None, end_color=None, colormap=None)

Facade — delegates to :meth:Bands.set_color_ramp <pyramids.dataset.engines.Bands.set_color_ramp>.

Raises:

Type	Description
ReadOnlyError	The dataset is opened read-only on-disk (writing the palette would otherwise silently spill a PAM sidecar).

Source code in src/pyramids/dataset/dataset.py

def set_color_ramp(
    self,
    band: int = 1,
    *,
    start_value: int,
    end_value: int,
    start_color: str | None = None,
    end_color: str | None = None,
    colormap: str | None = None,
) -> None:
    """Facade — delegates to :meth:`Bands.set_color_ramp <pyramids.dataset.engines.Bands.set_color_ramp>`.

    Raises:
        ReadOnlyError: The dataset is opened read-only on-disk (writing the palette
            would otherwise silently spill a PAM sidecar).
    """
    self._require_writable("set a color ramp")
    return self.bands.set_color_ramp(
        band,
        start_value=start_value,
        end_value=end_value,
        start_color=start_color,
        end_color=end_color,
        colormap=colormap,
    )

zonal_stats(fc, *, stats=('mean',), method='rasterize', band=0)

Compute zonal statistics of this dataset over a polygon FeatureCollection.

Thin forwarder to :func:pyramids.dataset.ops._zonal.zonal_stats; see that function for the full argument contract. The statistics are in physical units (a CF-packed band is unpacked), and the band's no-data cells, found in its stored values, are left out.

Parameters:

Name	Type	Description	Default
fc		A :class:pyramids.feature.FeatureCollection of polygons sharing this dataset's CRS.	required
stats		Sequence of stat names ("mean", "sum", "min", "max", "std", "var", "count").	('mean',)
method	str	"rasterize" is the only supported value today; an area-weighted "fractional" method is planned.	'rasterize'
band	int	Zero-based band index.	0

Returns:

Type	Description
	pandas.DataFrame: Indexed by fc.index; one column per stat.

Source code in src/pyramids/dataset/dataset.py

def zonal_stats(
    self,
    fc,
    *,
    stats=("mean",),
    method: str = "rasterize",
    band: int = 0,
):
    """Compute zonal statistics of this dataset over a polygon FeatureCollection.

    Thin forwarder to
    :func:`pyramids.dataset.ops._zonal.zonal_stats`; see that
    function for the full argument contract. The statistics are in
    physical units (a CF-packed band is unpacked), and the band's
    no-data cells, found in its stored values, are left out.

    Args:
        fc: A :class:`pyramids.feature.FeatureCollection` of
            polygons sharing this dataset's CRS.
        stats: Sequence of stat names (`"mean"`, `"sum"`,
            `"min"`, `"max"`, `"std"`, `"var"`,
            `"count"`).
        method: `"rasterize"` is the only supported value today;
            an area-weighted `"fractional"` method is planned.
        band: Zero-based band index.

    Returns:
        pandas.DataFrame: Indexed by `fc.index`; one column per stat.
    """
    return _zonal_stats(self, fc, stats=stats, method=method, band=band)

to_zarr(store, *, compute=True, mode='w', chunks=None, storage_options=None, compressor='auto', overview_factors=None, overview_resampling='average')

Serialise this Dataset to a Zarr store (parallel writes per chunk).

Thin forwarder to :func:pyramids.dataset.ops._zarr.write_dataset_to_zarr; see that function for the full argument contract. Zarr is the only raster output format where pyramids can write in true parallel — each dask chunk becomes an independent Zarr chunk file. Requires the [lazy] optional extra, and a dataset backed by a file the chunk reader can reopen.

The values written are the physical ones read_array returns, and pyramids' Zarr metadata has no scale_factor / add_offset, so a CF-packed source is written materialised: the store's data array holds float64 values, its dtype attribute says so, and its no-data is the sentinel in physical units (-9999 at scale=0.5 is recorded as -4999.5). Read back, it declares no packing.

Parameters:

Name	Type	Description	Default
store		Target store (path / fsspec URL / zarr.Store).	required
compute	bool	True writes immediately; False returns a :class:dask.delayed.Delayed.	True
mode	str	Zarr open mode, usually "w" or "a".	'w'
chunks		Chunk spec forwarded to :meth:read_array. None defaults to "auto" via the zarr helper.	None
storage_options	dict | None	fsspec options for cloud stores.	None
compressor		Zarr codec(s) for the data array. "auto" (default) keeps zarr's default codec; pass a zarr-v3 codec or list of them (e.g. zarr.codecs.BloscCodec(cname="zstd")) to override, or None for an uncompressed array.	'auto'
overview_factors	list | None	Optional downsample factors (e.g. [2, 4, 8]) to also write decimated multiscale pyramid levels as data_<factor> arrays plus a multiscales attribute. Requires compute=True. Read a level back with Dataset.from_zarr(store, level=factor).	None
overview_resampling	str	GDAL resampling for the pyramid levels ("average" default, "nearest", "bilinear", ...).	'average'

Returns:

Type	Description
	None when compute=True; a :class:dask.delayed.Delayed that
	performs the write when compute=False.

Raises:

Type	Description
OverviewTargetError	overview_factors was given and this dataset cannot hold overviews — a plain VRT whose description is not a path: an empty one, a blank one, or inline VRT XML. The levels are built through create_overviews, which refuses that shape, so the target is checked pre-flight and no store is written at all. The check runs before the compute one, so a call that is wrong in both ways reports this rather than the ValueError below — passing compute=True would still leave the dataset refused. Save it with to_file(path) and write the Zarr from the saved raster.
ValueError	overview_factors was given with compute=False; the pyramid levels are written eagerly.

Examples:

• A packed raster is stored as its physical values, with the sentinel in the same units, and reads back declaring no packing:

  >>> import os, tempfile
  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> folder = tempfile.mkdtemp()
  >>> source = Dataset.from_array(
  ...     np.array([[100, -9999], [300, 400]], dtype="int16"),
  ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
  ...     no_data_value=-9999,
  ...     path=os.path.join(folder, "packed.tif"),
  ... )
  >>> source.scale = [0.5]
  >>> source.close()
  >>> packed = Dataset.read_file(os.path.join(folder, "packed.tif"))
  >>> packed.to_zarr(os.path.join(folder, "packed.zarr"))
  >>> store = Dataset.from_zarr(os.path.join(folder, "packed.zarr"))
  >>> store.read_array().tolist(), store.dtype, store.scale
  ([[50.0, -4999.5], [150.0, 200.0]], ['float64'], [1.0])
  >>> float(store.no_data_value[0])
  -4999.5
  

Source code in src/pyramids/dataset/dataset.py

def to_zarr(
    self,
    store,
    *,
    compute: bool = True,
    mode: str = "w",
    chunks=None,
    storage_options: dict | None = None,
    compressor="auto",
    overview_factors: list | None = None,
    overview_resampling: str = "average",
):
    """Serialise this Dataset to a Zarr store (parallel writes per chunk).

    Thin forwarder to
    :func:`pyramids.dataset.ops._zarr.write_dataset_to_zarr`; see
    that function for the full argument contract. Zarr is the
    only raster output format where pyramids can write in true
    parallel — each dask chunk becomes an independent Zarr chunk
    file. Requires the `[lazy]` optional extra, and a dataset backed
    by a file the chunk reader can reopen.

    The values written are the physical ones `read_array` returns, and
    pyramids' Zarr metadata has no `scale_factor` / `add_offset`, so a
    CF-packed source is written materialised: the store's `data` array
    holds `float64` values, its `dtype` attribute says so, and its no-data
    is the sentinel in physical units (`-9999` at `scale=0.5` is recorded
    as `-4999.5`). Read back, it declares no packing.

    Args:
        store: Target store (path / fsspec URL / zarr.Store).
        compute: `True` writes immediately; `False` returns a
            :class:`dask.delayed.Delayed`.
        mode: Zarr open mode, usually `"w"` or `"a"`.
        chunks: Chunk spec forwarded to :meth:`read_array`.
            `None` defaults to `"auto"` via the zarr helper.
        storage_options: fsspec options for cloud stores.
        compressor: Zarr codec(s) for the `data` array. `"auto"` (default)
            keeps zarr's default codec; pass a zarr-v3 codec or list of them
            (e.g. `zarr.codecs.BloscCodec(cname="zstd")`) to override, or
            `None` for an uncompressed array.
        overview_factors: Optional downsample factors (e.g. `[2, 4, 8]`) to
            also write decimated multiscale pyramid levels as `data_<factor>`
            arrays plus a `multiscales` attribute. Requires `compute=True`.
            Read a level back with `Dataset.from_zarr(store, level=factor)`.
        overview_resampling: GDAL resampling for the pyramid levels
            (`"average"` default, `"nearest"`, `"bilinear"`, ...).

    Returns:
        `None` when `compute=True`; a :class:`dask.delayed.Delayed` that
        performs the write when `compute=False`.

    Raises:
        OverviewTargetError: `overview_factors` was given and this dataset cannot
            hold overviews — a plain VRT whose description is not a path: an empty
            one, a blank one, or inline VRT XML. The levels are built through
            `create_overviews`, which refuses that shape, so the target is checked
            pre-flight and no store is written at all. The check runs *before* the
            `compute` one, so a call that is wrong in both ways reports this rather
            than the `ValueError` below — passing `compute=True` would still leave
            the dataset refused. Save it with `to_file(path)` and write the Zarr
            from the saved raster.
        ValueError: `overview_factors` was given with `compute=False`; the pyramid
            levels are written eagerly.

    Examples:
        - A packed raster is stored as its physical values, with the sentinel in the
          same units, and reads back declaring no packing:
            ```python
            >>> import os, tempfile
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> folder = tempfile.mkdtemp()
            >>> source = Dataset.from_array(
            ...     np.array([[100, -9999], [300, 400]], dtype="int16"),
            ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
            ...     no_data_value=-9999,
            ...     path=os.path.join(folder, "packed.tif"),
            ... )
            >>> source.scale = [0.5]
            >>> source.close()
            >>> packed = Dataset.read_file(os.path.join(folder, "packed.tif"))
            >>> packed.to_zarr(os.path.join(folder, "packed.zarr"))
            >>> store = Dataset.from_zarr(os.path.join(folder, "packed.zarr"))
            >>> store.read_array().tolist(), store.dtype, store.scale
            ([[50.0, -4999.5], [150.0, 200.0]], ['float64'], [1.0])
            >>> float(store.no_data_value[0])
            -4999.5

            ```
    """
    resolved_chunks = chunks if chunks is not None else "auto"
    return write_dataset_to_zarr(
        self,
        store,
        compute=compute,
        mode=mode,
        chunks=resolved_chunks,
        storage_options=storage_options,
        compressor=compressor,
        overview_factors=overview_factors,
        overview_resampling=overview_resampling,
    )

from_zarr(store, *, chunks=None, storage_options=None, level=1, data_name=None) classmethod

Load a pyramids-written Zarr store into a new :class:Dataset.

Thin forwarder to :func:pyramids.dataset.ops._zarr.read_dataset_from_zarr.

Parameters:

Name	Type	Description	Default
store		Input store (path / fsspec URL / zarr.Store).	required
chunks		If non-None, the loaded Dataset is flagged as dask-backed so downstream read_array calls return lazy arrays.	None
storage_options	dict | None	fsspec options for cloud stores.	None
level	int	Pyramid downsample factor to read (1 = full resolution). Pass a factor written via to_zarr(overview_factors=...) to read that decimated overview level.	1
data_name	str | None	Explicit name of the data array. None (default) auto-detects; pass an explicit name to read a specific variable from a foreign GeoZarr store whose auto-detect picks the wrong array.	None

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_zarr(
    cls,
    store,
    *,
    chunks=None,
    storage_options: dict | None = None,
    level: int = 1,
    data_name: str | None = None,
) -> Dataset:
    """Load a pyramids-written Zarr store into a new :class:`Dataset`.

    Thin forwarder to
    :func:`pyramids.dataset.ops._zarr.read_dataset_from_zarr`.

    Args:
        store: Input store (path / fsspec URL / zarr.Store).
        chunks: If non-None, the loaded Dataset is flagged as
            dask-backed so downstream `read_array` calls return
            lazy arrays.
        storage_options: fsspec options for cloud stores.
        level: Pyramid downsample factor to read (`1` = full resolution).
            Pass a factor written via `to_zarr(overview_factors=...)` to read
            that decimated overview level.
        data_name: Explicit name of the data array. ``None`` (default)
            auto-detects; pass an explicit name to read a specific variable
            from a foreign GeoZarr store whose auto-detect picks the wrong
            array.
    """
    return read_dataset_from_zarr(
        store,
        chunks=chunks,
        storage_options=storage_options,
        level=level,
        data_name=data_name,
    )

__str__()

Human-readable multi-line summary, or a <Dataset: closed> sentinel.

repr() / str() run in debuggers, logging, and pytest introspection, so a closed dataset returns a sentinel rather than raising (a raising __repr__ would mask the surrounding error). Reads that must fail loudly use _require_open instead.

Source code in src/pyramids/dataset/dataset.py

def __str__(self) -> str:
    """Human-readable multi-line summary, or a `<Dataset: closed>` sentinel.

    `repr()` / `str()` run in debuggers, logging, and pytest introspection, so a
    closed dataset returns a sentinel rather than raising (a raising `__repr__`
    would mask the surrounding error). Reads that must fail loudly use
    `_require_open` instead.
    """
    message = "<Dataset: closed>"
    if self._raster is not None:
        message = f"""
        Top Left Corner: {self.top_left_corner}
        Cell size: {self.cell_size}
        Dimension: {self.rows} * {self.columns}
        EPSG: {self.epsg}
        Number of Bands: {self.band_count}
        Band names: {self.band_names}
        Band colors: {self.band_color}
        Band units: {self.band_units}
        Scale: {self.scale}
        Offset: {self.offset}
        Mask: {self.no_data_value[0]}
        Data type: {self.dtype[0]}
        File: {self.file_name}
    """
    return message

__repr__()

GDAL info string, or a <Dataset: closed> sentinel on a closed dataset.

The info string's Files: section lists every source a VRT references, and for a mosaic built by :func:pyramids.stac.build_vrt_from_stac with a bearer signer those paths carry the live token — so the text goes through :func:~pyramids.base.remote.redact_credentials first. repr is called far more often than deliberately: pytest prints it for every operand of a failing assertion, logging.error("%r", ds) is idiomatic, and a notebook auto-displays it.

Source code in src/pyramids/dataset/dataset.py

def __repr__(self) -> str:
    """GDAL info string, or a `<Dataset: closed>` sentinel on a closed dataset.

    The info string's ``Files:`` section lists every source a VRT
    references, and for a mosaic built by
    :func:`pyramids.stac.build_vrt_from_stac` with a bearer signer those
    paths carry the live token — so the text goes through
    :func:`~pyramids.base.remote.redact_credentials` first. ``repr`` is
    called far more often than deliberately: pytest prints it for every
    operand of a failing assertion, ``logging.error("%r", ds)`` is idiomatic,
    and a notebook auto-displays it.
    """
    info = "<Dataset: closed>"
    if self._raster is not None:
        info = redact_credentials(str(gdal.Info(self.raster)))
    return info

__add__(other)

Add another raster, or a real scalar, cell by cell.

Routed through :meth:_arithmetic, so both operand kinds land in :meth:combine and agree on band span, dtype and derived sentinel. ds + 0 is the one exception: it short-circuits to :meth:copy, which is why a no-op keeps the band's declared no-data value where a computed integer result that masked nothing declares none.

Parameters:

Name	Type	Description	Default
other	Any	Another raster on this one's grid, or a real, non-boolean scalar.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The summed raster, or NotImplemented for
Any	any other operand, which makes Python raise its own TypeError.

Raises:

Type	Description
AlignmentError	other is a raster on a different grid or CRS.

Examples:

• Add two aligned rasters, then a constant to one of them:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> rain = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
>>> melt = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((rain + melt).read_array()).mean())
52.0

- A constant keeps an integer band integer, and the computed result declares no sentinel because it masked nothing:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
>>> (counts + 5).dtype
['int16']
>>> int(np.asarray((counts + 5).read_array())[0, 0])
15
>>> (counts + 5).no_data_value
(None,)

- Adding zero is a no-op, so it hands back a copy that still carries the source's no-data value:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
>>> (counts + 0).no_data_value == counts.no_data_value
True

- A non-numeric operand is declined, so Python reports the pair:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> Dataset.from_array(np.full((3, 3), 1.0, "float32"), geo_ref=geo_ref) + "2"
Traceback (most recent call last):
    ...
TypeError: unsupported operand type(s) for +: 'Dataset' and 'str'

See Also

Dataset._arithmetic: The shared router, with the full operand rules. Analysis.combine: The engine method that does the work.

Source code in src/pyramids/dataset/dataset.py

def __add__(self, other: Any) -> Any:
    """Add another raster, or a real scalar, cell by cell.

    Routed through :meth:`_arithmetic`, so both operand kinds land in
    :meth:`combine` and agree on band span, dtype and derived sentinel.
    `ds + 0` is the one exception: it short-circuits to :meth:`copy`, which
    is why a no-op keeps the band's declared no-data value where a computed
    integer result that masked nothing declares none.

    Args:
        other: Another raster on this one's grid, or a real, non-boolean
            scalar.

    Returns:
        Dataset | NotImplemented: The summed raster, or `NotImplemented` for
        any other operand, which makes Python raise its own `TypeError`.

    Raises:
        AlignmentError: `other` is a raster on a different grid or CRS.

    Examples:
        - Add two aligned rasters, then a constant to one of them:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> rain = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
          >>> melt = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((rain + melt).read_array()).mean())
          52.0

          ```
        - A constant keeps an integer band integer, and the computed result
          declares no sentinel because it masked nothing:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
          >>> (counts + 5).dtype
          ['int16']
          >>> int(np.asarray((counts + 5).read_array())[0, 0])
          15
          >>> (counts + 5).no_data_value
          (None,)

          ```
        - Adding zero is a no-op, so it hands back a copy that still carries
          the source's no-data value:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
          >>> (counts + 0).no_data_value == counts.no_data_value
          True

          ```
        - A non-numeric operand is declined, so Python reports the pair:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> Dataset.from_array(np.full((3, 3), 1.0, "float32"), geo_ref=geo_ref) + "2"
          Traceback (most recent call last):
              ...
          TypeError: unsupported operand type(s) for +: 'Dataset' and 'str'

          ```

    See Also:
        Dataset._arithmetic: The shared router, with the full operand rules.
        Analysis.combine: The engine method that does the work.
    """
    return self._arithmetic(other, operator.add)

__sub__(other)

Subtract another raster, or a real scalar, cell by cell.

Routed through :meth:_arithmetic into :meth:combine. Subtraction has no identity to short-circuit on this side, so every operand computes; 100 - ds is the reflected spelling and lives in :meth:__rsub__.

Parameters:

Name	Type	Description	Default
other	Any	Another raster on this one's grid, or a real, non-boolean scalar.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The difference raster, or NotImplemented
Any	for any other operand.

Raises:

Type	Description
AlignmentError	other is a raster on a different grid or CRS.

Examples:

• Difference two aligned surfaces — a canopy height model:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> surface = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
>>> bare = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((surface - bare).read_array()).mean())
8.0

- Subtract a constant offset from every cell:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> gauge = Dataset.from_array(np.full((3, 3), 20.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((gauge - 5).read_array()).mean())
15.0

See Also

Dataset.rsub: The reflected form, scalar - ds. Analysis.combine: The engine method that does the work.

Source code in src/pyramids/dataset/dataset.py

def __sub__(self, other: Any) -> Any:
    """Subtract another raster, or a real scalar, cell by cell.

    Routed through :meth:`_arithmetic` into :meth:`combine`. Subtraction has
    no identity to short-circuit on this side, so every operand computes;
    `100 - ds` is the reflected spelling and lives in :meth:`__rsub__`.

    Args:
        other: Another raster on this one's grid, or a real, non-boolean
            scalar.

    Returns:
        Dataset | NotImplemented: The difference raster, or `NotImplemented`
        for any other operand.

    Raises:
        AlignmentError: `other` is a raster on a different grid or CRS.

    Examples:
        - Difference two aligned surfaces — a canopy height model:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> surface = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
          >>> bare = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((surface - bare).read_array()).mean())
          8.0

          ```
        - Subtract a constant offset from every cell:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> gauge = Dataset.from_array(np.full((3, 3), 20.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((gauge - 5).read_array()).mean())
          15.0

          ```

    See Also:
        Dataset.__rsub__: The reflected form, `scalar - ds`.
        Analysis.combine: The engine method that does the work.
    """
    return self._arithmetic(other, operator.sub)

__mul__(other)

Multiply by another raster, or by a real scalar, cell by cell.

Routed through :meth:_arithmetic into :meth:combine. A scalar keeps its own NumPy type, so scaling an integer band by an integer stays in that band's dtype; ds * 1 short-circuits to :meth:copy.

Parameters:

Name	Type	Description	Default
other	Any	Another raster on this one's grid, or a real, non-boolean scalar.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The product raster, or NotImplemented
Any	for any other operand.

Raises:

Type	Description
AlignmentError	other is a raster on a different grid or CRS.

Examples:

• Scale an integer band by a constant without widening its dtype:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
>>> (counts * 2).dtype
['int16']
>>> int(np.asarray((counts * 2).read_array())[0, 0])
20

- A scalar spans every band, unlike :meth:apply, which transforms one:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> stack = np.stack(
...     [np.full((3, 3), 1.0, "float32"), np.full((3, 3), 2.0, "float32")]
... )
>>> scaled = Dataset.from_array(stack, geo_ref=geo_ref) * 3
>>> scaled.shape
(2, 3, 3)
>>> [float(band.mean()) for band in np.asarray(scaled.read_array())]
[3.0, 6.0]

- Weight one raster by another, cell by cell:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> depth = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
>>> weight = Dataset.from_array(np.full((3, 3), 0.5, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((depth * weight).read_array()).mean())
1.5

- A bool is declined on purpose, so ds * True does not quietly succeed:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> Dataset.from_array(np.full((3, 3), 1.0, "float32"), geo_ref=geo_ref) * True
Traceback (most recent call last):
    ...
TypeError: unsupported operand type(s) for *: 'Dataset' and 'bool'

See Also

Dataset._arithmetic: The shared router, with the full operand rules. Analysis.apply: The single-band, sentinel-preserving alternative.

Source code in src/pyramids/dataset/dataset.py

def __mul__(self, other: Any) -> Any:
    """Multiply by another raster, or by a real scalar, cell by cell.

    Routed through :meth:`_arithmetic` into :meth:`combine`. A scalar keeps
    its own NumPy type, so scaling an integer band by an integer stays in
    that band's dtype; `ds * 1` short-circuits to :meth:`copy`.

    Args:
        other: Another raster on this one's grid, or a real, non-boolean
            scalar.

    Returns:
        Dataset | NotImplemented: The product raster, or `NotImplemented`
        for any other operand.

    Raises:
        AlignmentError: `other` is a raster on a different grid or CRS.

    Examples:
        - Scale an integer band by a constant without widening its dtype:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
          >>> (counts * 2).dtype
          ['int16']
          >>> int(np.asarray((counts * 2).read_array())[0, 0])
          20

          ```
        - A scalar spans every band, unlike :meth:`apply`, which transforms one:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> stack = np.stack(
          ...     [np.full((3, 3), 1.0, "float32"), np.full((3, 3), 2.0, "float32")]
          ... )
          >>> scaled = Dataset.from_array(stack, geo_ref=geo_ref) * 3
          >>> scaled.shape
          (2, 3, 3)
          >>> [float(band.mean()) for band in np.asarray(scaled.read_array())]
          [3.0, 6.0]

          ```
        - Weight one raster by another, cell by cell:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> depth = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
          >>> weight = Dataset.from_array(np.full((3, 3), 0.5, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((depth * weight).read_array()).mean())
          1.5

          ```
        - A `bool` is declined on purpose, so `ds * True` does not quietly
          succeed:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> Dataset.from_array(np.full((3, 3), 1.0, "float32"), geo_ref=geo_ref) * True
          Traceback (most recent call last):
              ...
          TypeError: unsupported operand type(s) for *: 'Dataset' and 'bool'

          ```

    See Also:
        Dataset._arithmetic: The shared router, with the full operand rules.
        Analysis.apply: The single-band, sentinel-preserving alternative.
    """
    return self._arithmetic(other, operator.mul)

__truediv__(other)

Divide by another raster, or by a real scalar, cell by cell.

Routed through :meth:_arithmetic into :meth:combine. A true divide always produces a floating result, so the sentinel :meth:combine derives is NaN; a division by zero stores an infinity as a value rather than masking it, and numpy's own RuntimeWarning reaches the caller — only 0/0, which is NaN, reads back as a gap.

Parameters:

Name	Type	Description	Default
other	Any	Another raster on this one's grid, or a real, non-boolean scalar.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The quotient raster, or NotImplemented
Any	for any other operand.

Raises:

Type	Description
AlignmentError	other is a raster on a different grid or CRS.

Warns:

Type	Description
RuntimeWarning	numpy's own divide by zero / invalid value warning, raised where a divisor cell holds zero. The infinity (or NaN) it produces is stored, so mask the zeros first if that is not what you want downstream.

Examples:

• Turn a count raster into a rate by dividing by a constant:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> counts = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((counts / 0.5).read_array()).mean())
6.0

- A band ratio between two aligned rasters, and the NaN sentinel a floating result declares:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> nir = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
>>> red = Dataset.from_array(np.full((3, 3), 0.5, "float32"), geo_ref=geo_ref)
>>> ratio = nir / red
>>> float(np.asarray(ratio.read_array()).mean())
6.0
>>> float(ratio.no_data_value[0])
nan

See Also

Dataset.rtruediv: The reflected form, scalar / ds. Analysis.combine: The engine method that derives the sentinel.

Source code in src/pyramids/dataset/dataset.py

def __truediv__(self, other: Any) -> Any:
    """Divide by another raster, or by a real scalar, cell by cell.

    Routed through :meth:`_arithmetic` into :meth:`combine`. A true divide
    always produces a floating result, so the sentinel :meth:`combine`
    derives is `NaN`; a division by zero stores an infinity as a **value**
    rather than masking it, and numpy's own `RuntimeWarning` reaches the
    caller — only `0/0`, which is `NaN`, reads back as a gap.

    Args:
        other: Another raster on this one's grid, or a real, non-boolean
            scalar.

    Returns:
        Dataset | NotImplemented: The quotient raster, or `NotImplemented`
        for any other operand.

    Raises:
        AlignmentError: `other` is a raster on a different grid or CRS.

    Warns:
        RuntimeWarning: numpy's own `divide by zero` / `invalid value`
            warning, raised where a divisor cell holds zero. The infinity
            (or `NaN`) it produces is stored, so mask the zeros first if that
            is not what you want downstream.

    Examples:
        - Turn a count raster into a rate by dividing by a constant:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> counts = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((counts / 0.5).read_array()).mean())
          6.0

          ```
        - A band ratio between two aligned rasters, and the `NaN` sentinel a
          floating result declares:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> nir = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
          >>> red = Dataset.from_array(np.full((3, 3), 0.5, "float32"), geo_ref=geo_ref)
          >>> ratio = nir / red
          >>> float(np.asarray(ratio.read_array()).mean())
          6.0
          >>> float(ratio.no_data_value[0])
          nan

          ```

    See Also:
        Dataset.__rtruediv__: The reflected form, `scalar / ds`.
        Analysis.combine: The engine method that derives the sentinel.
    """
    return self._arithmetic(other, operator.truediv)

__pow__(other)

Raise each cell to a power — another raster's, or a real scalar's.

Routed through :meth:_arithmetic into :meth:combine, so it inherits the same operand rules, no-data domain, band-dimension labelling and dtype behaviour as * and /: ds ** 2 on an int16 band stays int16, and a scalar spans every band. A fractional power follows NumPy's own casting — int16 ** 0.5 widens to float64 — and where NumPy yields a non-finite cell (a negative base raised to a fractional power, or a zero raised to a negative power) that value is stored as-is and NumPy's RuntimeWarning reaches the caller. The one power NumPy refuses outright is a negative integer power of an integer band, which raises ValueError; cast the band to a floating dtype first. ** 1 is the exception to the widening rule: it is a no-op, absorbed to a copy() that keeps the source dtype and sentinel (like * 1), so int16 ** 1.0 stays int16 where int16 ** 2.0 widens to float64.

Parameters:

Name	Type	Description	Default
other	Any	Another raster on this one's grid, or a real, non-boolean scalar.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The powered raster, or NotImplemented for any
Any	other operand.

Raises:

Type	Description
AlignmentError	other is a raster on a different grid or CRS.
ValueError	numpy refuses a negative integer power of an integer band (Integers to negative integer powers are not allowed); cast the band to a floating dtype first.

Warns:

Type	Description
RuntimeWarning	numpy's own invalid value / divide by zero warning, raised where a power yields a non-finite cell — a negative base to a fractional power, or a zero to a negative power. The non-finite value is stored, not masked.

Examples:

• Square a band, the common use — its dtype is kept:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), 3, "int16"), geo_ref=geo_ref)
>>> squared = ds ** 2
>>> int(np.asarray(squared.read_array())[0, 0]), squared.dtype
(9, ['int16'])

- A negative integer power of an integer band is refused by numpy; give it a floating band (or use a floating power) to get the reciprocal instead:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> Dataset.from_array(np.full((3, 3), 4, "int16"), geo_ref=geo_ref) ** -1
Traceback (most recent call last):
    ...
ValueError: Integers to negative integer powers are not allowed.
>>> recip = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref) ** -1
>>> float(np.asarray(recip.read_array())[0, 0])
0.25

See Also

Dataset.rpow: The reflected form, scalar ** ds. Dataset._arithmetic: The shared router, with the full operand rules.

Source code in src/pyramids/dataset/dataset.py

def __pow__(self, other: Any) -> Any:
    """Raise each cell to a power — another raster's, or a real scalar's.

    Routed through :meth:`_arithmetic` into :meth:`combine`, so it inherits the same
    operand rules, no-data domain, band-dimension labelling and dtype behaviour as
    `*` and `/`: `ds ** 2` on an `int16` band stays `int16`, and a scalar spans every
    band. A fractional power follows NumPy's own casting — `int16 ** 0.5` widens to
    `float64` — and where NumPy yields a non-finite cell (a negative base raised to a
    fractional power, or a zero raised to a negative power) that value is stored as-is
    and NumPy's `RuntimeWarning` reaches the caller. The one power NumPy refuses
    outright is a negative integer power of an integer band, which raises `ValueError`;
    cast the band to a floating dtype first. `** 1` is the exception to the widening
    rule: it is a no-op, absorbed to a `copy()` that keeps the source dtype and
    sentinel (like `* 1`), so `int16 ** 1.0` stays `int16` where `int16 ** 2.0`
    widens to `float64`.

    Args:
        other: Another raster on this one's grid, or a real, non-boolean scalar.

    Returns:
        Dataset | NotImplemented: The powered raster, or `NotImplemented` for any
        other operand.

    Raises:
        AlignmentError: `other` is a raster on a different grid or CRS.
        ValueError: numpy refuses a negative integer power of an integer band
            (`Integers to negative integer powers are not allowed`); cast the band to a
            floating dtype first.

    Warns:
        RuntimeWarning: numpy's own `invalid value` / `divide by zero` warning, raised
            where a power yields a non-finite cell — a negative base to a fractional
            power, or a zero to a negative power. The non-finite value is stored, not
            masked.

    Examples:
        - Square a band, the common use — its dtype is kept:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), 3, "int16"), geo_ref=geo_ref)
          >>> squared = ds ** 2
          >>> int(np.asarray(squared.read_array())[0, 0]), squared.dtype
          (9, ['int16'])

          ```
        - A negative integer power of an integer band is refused by numpy; give it a
          floating band (or use a floating power) to get the reciprocal instead:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> Dataset.from_array(np.full((3, 3), 4, "int16"), geo_ref=geo_ref) ** -1
          Traceback (most recent call last):
              ...
          ValueError: Integers to negative integer powers are not allowed.
          >>> recip = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref) ** -1
          >>> float(np.asarray(recip.read_array())[0, 0])
          0.25

          ```

    See Also:
        Dataset.__rpow__: The reflected form, `scalar ** ds`.
        Dataset._arithmetic: The shared router, with the full operand rules.
    """
    return self._arithmetic(other, operator.pow)

__radd__(other)

Add from the right, so a list of rasters can be sum()-ed.

sum() seeds its accumulator with the integer 0 and only then starts adding, so 0 + ds has to succeed for a list of rasters to be summable at all. Zero is the additive identity, so the answer is this dataset's values — returned as a copy, not as self. Otherwise sum([one]) would hand back the very raster it was given while sum([a, b]) hands back a fresh one, and an in-place write to "the total" would reach into the input in the one-element case only. numpy makes the same choice: sum([arr]) is arr is False.

Zero is absorbed from either side — ds + 0 is the same copy — so the two spellings of one commutative expression cannot disagree. Every other real scalar computes through :meth:combine, so 1 + ds is ds + 1. False + ds still raises (a bool is not a numeric seed) and so does 0j + ds (no band holds an imaginary part).

Two wrinkles worth knowing. sum() of a single raster never reaches :meth:combine, so it returns that raster's values and sentinel verbatim, while sum() of two or more goes through combine and takes combine's derived sentinel (NaN for a floating result) — a fold over a glob can therefore report a different no-data value depending on how many files matched. And the one-element answer is a :meth:copy, so it carries whatever copy carries: the grid, CRS, band names and sentinel, but not derived products such as overviews. Pass no_data_value= to :meth:combine <pyramids.dataset.engines.Analysis.combine> and rebuild overviews explicitly when either matters.

Parameters:

Name	Type	Description	Default
other	Any	The left-hand operand, which reached here because its own __add__ declined this dataset.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: A copy of this dataset when other is
Any	zero, the computed raster for any other real scalar, else
Any	NotImplemented so Python raises its own TypeError.

Examples:

• Fold a list of aligned rasters into their total:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> rasters = [
...     Dataset.from_array(np.full((4, 4), value, "float32"), geo_ref=geo_ref)
...     for value in (1.0, 2.0, 3.0)
... ]
>>> float(np.asarray(sum(rasters).read_array()).mean())
6.0

• A scalar on the left computes the same raster as one on the right, because addition commutes:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((10 + ds).read_array()).mean())
14.0

See Also

Dataset.add: The same router from the other side. Analysis.combine: The engine method every non-zero seed goes through.

Source code in src/pyramids/dataset/dataset.py

def __radd__(self, other: Any) -> Any:
    """Add from the right, so a list of rasters can be `sum()`-ed.

    `sum()` seeds its accumulator with the integer `0` and only then
    starts adding, so `0 + ds` has to succeed for a list of rasters to be
    summable at all. Zero is the additive identity, so the answer is this
    dataset's values — returned as a copy, not as `self`. Otherwise
    `sum([one])` would hand back the very raster it was given while
    `sum([a, b])` hands back a fresh one, and an in-place write to "the
    total" would reach into the input in the one-element case only. numpy
    makes the same choice: `sum([arr]) is arr` is `False`.

    Zero is absorbed from **either** side — `ds + 0` is the same copy — so
    the two spellings of one commutative expression cannot disagree. Every
    other real scalar computes through :meth:`combine`, so `1 + ds` is
    `ds + 1`. `False + ds` still raises (a bool is not a numeric seed) and
    so does `0j + ds` (no band holds an imaginary part).

    Two wrinkles worth knowing. `sum()` of a **single** raster never reaches
    :meth:`combine`, so it returns that raster's values and sentinel
    verbatim, while `sum()` of two or more goes through `combine` and takes
    `combine`'s derived sentinel (`NaN` for a floating result) — a fold over
    a glob can therefore report a different no-data value depending on how
    many files matched. And the one-element answer is a :meth:`copy`, so it
    carries whatever `copy` carries: the grid, CRS, band names and sentinel,
    but not derived products such as overviews. Pass `no_data_value=` to
    :meth:`combine <pyramids.dataset.engines.Analysis.combine>` and rebuild
    overviews explicitly when either matters.

    Args:
        other: The left-hand operand, which reached here because its own
            `__add__` declined this dataset.

    Returns:
        Dataset | NotImplemented: A copy of this dataset when `other` is
        zero, the computed raster for any other real scalar, else
        `NotImplemented` so Python raises its own `TypeError`.

    Examples:
        - Fold a list of aligned rasters into their total:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> rasters = [
          ...     Dataset.from_array(np.full((4, 4), value, "float32"), geo_ref=geo_ref)
          ...     for value in (1.0, 2.0, 3.0)
          ... ]
          >>> float(np.asarray(sum(rasters).read_array()).mean())
          6.0

          ```

        - A scalar on the left computes the same raster as one on the right,
          because addition commutes:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((10 + ds).read_array()).mean())
          14.0

          ```

    See Also:
        Dataset.__add__: The same router from the other side.
        Analysis.combine: The engine method every non-zero seed goes through.
    """
    # Addition commutes, so this is `ds + other` outright. `_arithmetic` owns both
    # halves of what used to be duplicated here: the `Real`-and-not-`bool` guard
    # that turns away `False` and `0j`, and the zero short-circuit to `copy()` --
    # which it applies from either side, so the two spellings cannot disagree.
    return self._arithmetic(other, operator.add)

__rmul__(other)

Multiply from the right, so math.prod() folds a list of rasters.

The multiplicative twin of :meth:__radd__: math.prod seeds its accumulator with the integer 1, so 1 * ds has to succeed for a list of rasters to be multipliable at all. One is the multiplicative identity, so the answer is this dataset's values, as a copy — for the aliasing reason :meth:__radd__ gives.

Parameters:

Name	Type	Description	Default
other	Any	The left-hand operand, which reached here because its own __mul__ declined this dataset.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: A copy of this dataset when other is a
Any	real numeric one, the computed raster for any other real scalar,
Any	else NotImplemented.

Examples:

• Fold a list of aligned rasters into their product:

>>> import math
>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> rasters = [
...     Dataset.from_array(np.full((3, 3), value, "float32"), geo_ref=geo_ref)
...     for value in (2.0, 3.0)
... ]
>>> float(np.asarray(math.prod(rasters).read_array()).mean())
6.0

- Multiplying by one is a no-op, so it hands back a copy that still carries the source's no-data value:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
>>> (1 * counts).no_data_value == counts.no_data_value
True

See Also

Dataset.radd: The additive twin, and the aliasing reason both return a copy rather than self.

Source code in src/pyramids/dataset/dataset.py

def __rmul__(self, other: Any) -> Any:
    """Multiply from the right, so `math.prod()` folds a list of rasters.

    The multiplicative twin of :meth:`__radd__`: `math.prod` seeds its
    accumulator with the integer `1`, so `1 * ds` has to succeed for a list
    of rasters to be multipliable at all. One is the multiplicative
    identity, so the answer is this dataset's values, as a copy — for the
    aliasing reason :meth:`__radd__` gives.

    Args:
        other: The left-hand operand, which reached here because its own
            `__mul__` declined this dataset.

    Returns:
        Dataset | NotImplemented: A copy of this dataset when `other` is a
        real numeric one, the computed raster for any other real scalar,
        else `NotImplemented`.

    Examples:
        - Fold a list of aligned rasters into their product:

          ```python
          >>> import math
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> rasters = [
          ...     Dataset.from_array(np.full((3, 3), value, "float32"), geo_ref=geo_ref)
          ...     for value in (2.0, 3.0)
          ... ]
          >>> float(np.asarray(math.prod(rasters).read_array()).mean())
          6.0

          ```
        - Multiplying by one is a no-op, so it hands back a copy that still
          carries the source's no-data value:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> counts = Dataset.from_array(np.full((3, 3), 10, "int16"), geo_ref=geo_ref)
          >>> (1 * counts).no_data_value == counts.no_data_value
          True

          ```

    See Also:
        Dataset.__radd__: The additive twin, and the aliasing reason both
            return a copy rather than `self`.
    """
    # `ds * other`, for the reason `__radd__` gives: multiplication commutes and
    # `_arithmetic` already short-circuits the multiplicative identity to `copy()`.
    return self._arithmetic(other, operator.mul)

__rsub__(other)

Subtract this raster from a scalar — 100 - ds, not ds - 100.

Subtraction does not commute, so this cannot defer to :meth:__sub__; the operands keep the order the caller wrote them in.

Parameters:

Name	Type	Description	Default
other	Any	The left-hand operand, which reached here because its own __sub__ declined this dataset.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The computed raster, or NotImplemented when
Any	other is not a real, non-boolean scalar.

Examples:

• Invert a normalised band, the common use for a reflected subtraction:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), 0.25, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((1 - ds).read_array()).mean())
0.75

Source code in src/pyramids/dataset/dataset.py

def __rsub__(self, other: Any) -> Any:
    """Subtract this raster from a scalar — `100 - ds`, not `ds - 100`.

    Subtraction does not commute, so this cannot defer to :meth:`__sub__`; the
    operands keep the order the caller wrote them in.

    Args:
        other: The left-hand operand, which reached here because its own
            `__sub__` declined this dataset.

    Returns:
        Dataset | NotImplemented: The computed raster, or `NotImplemented` when
        `other` is not a real, non-boolean scalar.

    Examples:
        - Invert a normalised band, the common use for a reflected subtraction:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), 0.25, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((1 - ds).read_array()).mean())
          0.75

          ```
    """
    return self._reflected_arithmetic(other, operator.sub)

__rtruediv__(other)

Divide a scalar by this raster — 1000 / ds, not ds / 1000.

Division does not commute, so this cannot defer to :meth:__truediv__.

A cell holding zero divides to an infinity, and that infinity is stored as a value, not masked: :meth:combine derives NaN as the result's sentinel but has no non-finite handling, so only a 0/0 — which is NaN — reads as a gap. numpy's own RuntimeWarning: divide by zero reaches the caller. Mask the zeros first, or post-process with :meth:apply, if an infinity is not what you want downstream.

Parameters:

Name	Type	Description	Default
other	Any	The left-hand operand, which reached here because its own __truediv__ declined this dataset.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The computed raster, or NotImplemented when
Any	other is not a real, non-boolean scalar.

Warns:

Type	Description
RuntimeWarning	numpy's own divide by zero / invalid value warning, raised where a cell of this raster holds zero.

Examples:

• Turn a rate into its reciprocal:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((1 / ds).read_array()).mean())
0.25

Source code in src/pyramids/dataset/dataset.py

def __rtruediv__(self, other: Any) -> Any:
    """Divide a scalar by this raster — `1000 / ds`, not `ds / 1000`.

    Division does not commute, so this cannot defer to :meth:`__truediv__`.

    A cell holding zero divides to an infinity, and that infinity is **stored as a
    value**, not masked: :meth:`combine` derives `NaN` as the result's sentinel but
    has no non-finite handling, so only a `0/0` — which is `NaN` — reads as a gap.
    numpy's own `RuntimeWarning: divide by zero` reaches the caller. Mask the zeros
    first, or post-process with :meth:`apply`, if an infinity is not what you want
    downstream.

    Args:
        other: The left-hand operand, which reached here because its own
            `__truediv__` declined this dataset.

    Returns:
        Dataset | NotImplemented: The computed raster, or `NotImplemented` when
        `other` is not a real, non-boolean scalar.

    Warns:
        RuntimeWarning: numpy's own `divide by zero` / `invalid value`
            warning, raised where a cell of this raster holds zero.

    Examples:
        - Turn a rate into its reciprocal:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), 4.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((1 / ds).read_array()).mean())
          0.25

          ```
    """
    return self._reflected_arithmetic(other, operator.truediv)

__rpow__(other)

Raise a scalar to this raster's cells — 2 ** ds, not ds ** 2.

Exponentiation does not commute, so this cannot defer to :meth:__pow__; the operands keep the order the caller wrote them in, computed through :meth:Analysis._fold (one read of this raster). 2 ** ds takes whatever dtype NumPy makes of the base and the cells, exactly as ds ** other does.

Parameters:

Name	Type	Description	Default
other	Any	The left-hand operand, which reached here because its own __pow__ declined this dataset.	required

Returns:

Type	Description
Any	Dataset | NotImplemented: The computed raster, or NotImplemented when
Any	other is not a real, non-boolean scalar.

Raises:

Type	Description
ValueError	The base is an integer and this raster is an integer band holding a negative cell — 2 ** int16(-3) — which numpy forbids, as ds ** other does.

Warns:

Type	Description
RuntimeWarning	numpy's own warning where the result is non-finite — a negative base to a fractional cell gives nan ((-2.0) ** ds), stored as-is, exactly as on __pow__.

Examples:

• Two raised to an exponent field:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((2 ** ds).read_array())[0, 0])
8.0

Source code in src/pyramids/dataset/dataset.py

def __rpow__(self, other: Any) -> Any:
    """Raise a scalar to this raster's cells — `2 ** ds`, not `ds ** 2`.

    Exponentiation does not commute, so this cannot defer to :meth:`__pow__`; the
    operands keep the order the caller wrote them in, computed through
    :meth:`Analysis._fold` (one read of this raster). `2 ** ds` takes whatever dtype
    NumPy makes of the base and the cells, exactly as `ds ** other` does.

    Args:
        other: The left-hand operand, which reached here because its own `__pow__`
            declined this dataset.

    Returns:
        Dataset | NotImplemented: The computed raster, or `NotImplemented` when
        `other` is not a real, non-boolean scalar.

    Raises:
        ValueError: The base is an integer and this raster is an integer band
            holding a negative cell — `2 ** int16(-3)` — which numpy forbids, as
            `ds ** other` does.

    Warns:
        RuntimeWarning: numpy's own warning where the result is non-finite — a
            negative base to a fractional cell gives `nan` (`(-2.0) ** ds`), stored
            as-is, exactly as on `__pow__`.

    Examples:
        - Two raised to an exponent field:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), 3.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((2 ** ds).read_array())[0, 0])
          8.0

          ```
    """
    return self._reflected_arithmetic(other, operator.pow)

__neg__()

Negate every cell, -ds, keeping gaps and band dimensions.

A one-operand transform run through :meth:Analysis._fold, so it inherits the same no-data domain, band-dimension labelling and dtype behaviour as the binary operators: a masked cell stays masked, every band is negated, and a signed band keeps its dtype.

On an unsigned band -ds wraps modulo the dtype range — -uint8(3) is 253, not -3 — matching numpy and 0 - ds (its arithmetic equal, folded the same way), and unlike ds * -1, whose scalar path rejects -1 as out of range for the band. Negate a signed or float band if a true sign flip is wanted.

Returns:

Name	Type	Description
Dataset	Any	The negated raster, on this one's grid.

Examples:

• Flip the sign of a band:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), 2.5, "float32"), geo_ref=geo_ref)
>>> float(np.asarray((-ds).read_array())[0, 0])
-2.5

See Also

Dataset.abs: The magnitude, the other unary transform. Analysis._fold: The single-read path the result comes back through.

Source code in src/pyramids/dataset/dataset.py

def __neg__(self) -> Any:
    """Negate every cell, `-ds`, keeping gaps and band dimensions.

    A one-operand transform run through :meth:`Analysis._fold`, so it inherits the
    same no-data domain, band-dimension labelling and dtype behaviour as the binary
    operators: a masked cell stays masked, every band is negated, and a signed band
    keeps its dtype.

    On an **unsigned** band `-ds` wraps modulo the dtype range — `-uint8(3)` is
    `253`, not `-3` — matching numpy and `0 - ds` (its arithmetic equal, folded the
    same way), and unlike `ds * -1`, whose scalar path rejects `-1` as out of range
    for the band. Negate a signed or float band if a true sign flip is wanted.

    Returns:
        Dataset: The negated raster, on this one's grid.

    Examples:
        - Flip the sign of a band:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), 2.5, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray((-ds).read_array())[0, 0])
          -2.5

          ```

    See Also:
        Dataset.__abs__: The magnitude, the other unary transform.
        Analysis._fold: The single-read path the result comes back through.
    """
    return self.analysis._fold(operator.neg)

__abs__()

Take the magnitude of every cell, abs(ds), keeping gaps and band dimensions.

A one-operand transform run through :meth:Analysis._fold, so it inherits the same no-data domain, band-dimension labelling and dtype behaviour as the binary operators: a masked cell stays masked and every band is folded.

Two numpy-native edges to know: on an unsigned band abs(ds) is a no-op (every value is already non-negative), and the magnitude of a signed dtype's minimum overflows and stays negative — abs(int16(-32768)) is -32768, since 32768 does not fit int16. Cast to a wider or float band first if that matters.

Returns:

Name	Type	Description
Dataset	Any	The magnitude raster, on this one's grid.

Examples:

• The magnitude of a signed band:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> ds = Dataset.from_array(np.full((3, 3), -4.0, "float32"), geo_ref=geo_ref)
>>> float(np.asarray(abs(ds).read_array())[0, 0])
4.0

See Also

Dataset.neg: The sign flip, the other unary transform. Analysis._fold: The single-read path the result comes back through.

Source code in src/pyramids/dataset/dataset.py

def __abs__(self) -> Any:
    """Take the magnitude of every cell, `abs(ds)`, keeping gaps and band dimensions.

    A one-operand transform run through :meth:`Analysis._fold`, so it inherits the
    same no-data domain, band-dimension labelling and dtype behaviour as the binary
    operators: a masked cell stays masked and every band is folded.

    Two numpy-native edges to know: on an unsigned band `abs(ds)` is a no-op (every
    value is already non-negative), and the magnitude of a signed dtype's minimum
    overflows and stays negative — `abs(int16(-32768))` is `-32768`, since `32768`
    does not fit `int16`. Cast to a wider or float band first if that matters.

    Returns:
        Dataset: The magnitude raster, on this one's grid.

    Examples:
        - The magnitude of a signed band:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> ds = Dataset.from_array(np.full((3, 3), -4.0, "float32"), geo_ref=geo_ref)
          >>> float(np.asarray(abs(ds).read_array())[0, 0])
          4.0

          ```

    See Also:
        Dataset.__neg__: The sign flip, the other unary transform.
        Analysis._fold: The single-read path the result comes back through.
    """
    return self.analysis._fold(operator.abs)

__lt__(other)

Cell-by-cell < against another raster or a real scalar — see :meth:_arithmetic.

Source code in src/pyramids/dataset/dataset.py

def __lt__(self, other: Any) -> Any:
    """Cell-by-cell `<` against another raster or a real scalar — see :meth:`_arithmetic`."""
    return self._arithmetic(other, operator.lt)

__le__(other)

Cell-by-cell <= against another raster or a real scalar — see :meth:_arithmetic.

Source code in src/pyramids/dataset/dataset.py

def __le__(self, other: Any) -> Any:
    """Cell-by-cell `<=` against another raster or a real scalar — see :meth:`_arithmetic`."""
    return self._arithmetic(other, operator.le)

__gt__(other)

Cell-by-cell > against another raster or a real scalar — see :meth:_arithmetic.

Source code in src/pyramids/dataset/dataset.py

def __gt__(self, other: Any) -> Any:
    """Cell-by-cell `>` against another raster or a real scalar — see :meth:`_arithmetic`."""
    return self._arithmetic(other, operator.gt)

__ge__(other)

Cell-by-cell >= against another raster or a real scalar, as a Byte mask.

See :meth:_arithmetic for the mask's dtype, sentinel and NaN rules.

Examples:

• Where does the surface stand at least as high as the bare earth:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> surface = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
>>> bare = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
>>> mask = surface >= bare
>>> np.asarray(mask.read_array()).dtype.name, int(mask.no_data_value[0])
('uint8', 255)
>>> bool((np.asarray(mask.read_array()) == 1).all())
True

Source code in src/pyramids/dataset/dataset.py

def __ge__(self, other: Any) -> Any:
    """Cell-by-cell `>=` against another raster or a real scalar, as a Byte mask.

    See :meth:`_arithmetic` for the mask's dtype, sentinel and NaN rules.

    Examples:
        - Where does the surface stand at least as high as the bare earth:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> surface = Dataset.from_array(np.full((3, 3), 30.0, "float32"), geo_ref=geo_ref)
          >>> bare = Dataset.from_array(np.full((3, 3), 22.0, "float32"), geo_ref=geo_ref)
          >>> mask = surface >= bare
          >>> np.asarray(mask.read_array()).dtype.name, int(mask.no_data_value[0])
          ('uint8', 255)
          >>> bool((np.asarray(mask.read_array()) == 1).all())
          True

          ```
    """
    return self._arithmetic(other, operator.ge)

__bool__()

Refuse to collapse a raster into a single true/false.

if surface >= bare: reads like a question, but a comparison between two rasters is a raster — one answer per cell — so there is no honest single truth value to give back. sorted, min, max and bisect compare and then reduce the same way, and before the comparison operators existed they raised TypeError on a list of rasters. Letting them quietly return the wrong element instead would be strictly worse than raising.

The refusal is class-wide rather than scoped to comparison results, which is the choice numpy, pandas and xarray all make. A scoped version was tried: mark the raster a comparison produced and refuse only that. It fails in both directions — the mark is lost by copy, crop, to_crs, align, resample, a to_file/read_file round trip and pickling, so the hazard returns after one operation; and it survives apply(inplace=True) and write_array, so a raster holding ordinary measurements starts refusing. A property that cannot be carried correctly is not worth carrying.

Use ds is not None for a presence check, and reduce a comparison explicitly — bool(np.asarray((a >= b).read_array()).all()) — for a yes/no.

Returns:

Name	Type	Description
bool	bool	Never returns; the annotation is what __bool__ must declare.

Raises:

Type	Description
ValueError	Always.

Examples:

• A comparison has to be reduced before it can be a condition:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
>>> a = Dataset.from_array(np.ones((3, 3), "float32"), geo_ref=geo_ref)
>>> b = Dataset.from_array(np.zeros((3, 3), "float32"), geo_ref=geo_ref)
>>> bool(a >= b)
Traceback (most recent call last):
    ...
ValueError: the truth value of a Dataset is ambiguous ...
>>> bool(np.asarray((a >= b).read_array()).all())
True

Source code in src/pyramids/dataset/dataset.py

def __bool__(self) -> bool:
    """Refuse to collapse a raster into a single true/false.

    `if surface >= bare:` reads like a question, but a comparison between
    two rasters is a *raster* — one answer per cell — so there is no honest
    single truth value to give back. `sorted`, `min`, `max` and `bisect`
    compare and then reduce the same way, and before the comparison
    operators existed they raised `TypeError` on a list of rasters. Letting
    them quietly return the wrong element instead would be strictly worse
    than raising.

    The refusal is class-wide rather than scoped to comparison results,
    which is the choice numpy, pandas and xarray all make. A scoped version
    was tried: mark the raster a comparison produced and refuse only that.
    It fails in both directions — the mark is lost by `copy`, `crop`,
    `to_crs`, `align`, `resample`, a `to_file`/`read_file` round trip and
    pickling, so the hazard returns after one operation; and it survives
    `apply(inplace=True)` and `write_array`, so a raster holding ordinary
    measurements starts refusing. A property that cannot be carried
    correctly is not worth carrying.

    Use `ds is not None` for a presence check, and reduce a comparison
    explicitly — `bool(np.asarray((a >= b).read_array()).all())` — for a
    yes/no.

    Returns:
        bool: Never returns; the annotation is what `__bool__` must declare.

    Raises:
        ValueError: Always.

    Examples:
        - A comparison has to be reduced before it can be a condition:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> geo_ref = GeoReference(top_left_corner=(0.0, 5.0), cell_size=0.25, epsg=4326)
          >>> a = Dataset.from_array(np.ones((3, 3), "float32"), geo_ref=geo_ref)
          >>> b = Dataset.from_array(np.zeros((3, 3), "float32"), geo_ref=geo_ref)
          >>> bool(a >= b)
          Traceback (most recent call last):
              ...
          ValueError: the truth value of a Dataset is ambiguous ...
          >>> bool(np.asarray((a >= b).read_array()).all())
          True

          ```
    """
    raise ValueError(
        "the truth value of a Dataset is ambiguous — a raster holds one "
        "value per cell, and a comparison between two rasters is itself a "
        "raster. Reduce it, e.g. "
        "`bool(np.asarray((a >= b).read_array()).all())`; use "
        "`ds is not None` for a presence check. This is also why `sorted`, "
        "`min` and `max` refuse a list of rasters"
    )

convert_units(target, band=None)

Convert band values to target units, returning a new Dataset.

Unlike the :attr:band_units setter — which only relabels bands — this actually transforms the values using a small affine conversion table (see :func:pyramids.dataset.ops.units.convert_array) and records the new unit on the result. The output is a new in-memory float64 Dataset; the source is left untouched.

The values converted are the physical ones read_array returns, so a CF-packed band (scale_factor / add_offset) is unpacked first and the result, holding computed values, declares no packing. No-data cells are found in the stored values, where the sentinel lives, and keep the declared no_data_value unchanged rather than being converted as if they were data.

Parameters:

Name	Type	Description	Default
target	str	Target unit label (e.g. "celsius", "hPa", "knots").	required
band	int | None	Zero-based band index to convert. None (default) converts every band; bands already in target units are passed through unchanged.	None

Returns:

Type	Description
Dataset	A new :class:Dataset with converted values and updated
Dataset	attr:band_units.

Raises:

Type	Description
ValueError	band is out of range, a converted band has no source unit set, or the (source, target) pair is unsupported.

Examples:

• Convert a Kelvin raster to Celsius and read the new values:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.array([[273.15, 283.15], [293.15, 303.15]]),
  ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
  ... )
  >>> ds.band_units = ["K"]
  >>> converted = ds.convert_units("celsius")
  >>> converted.read_array().tolist()
  [[0.0, 10.0], [20.0, 30.0]]
  >>> converted.band_units
  ['celsius']
  

• An unsupported target raises a clear error:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset
  >>> ds = Dataset.from_array(
  ...     np.array([[273.15]]),
  ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
  ... )
  >>> ds.band_units = ["K"]
  >>> try:
  ...     ds.convert_units("furlongs")
  ... except ValueError as exc:
  ...     print("No unit conversion" in str(exc))
  True
  

• A packed band is converted from its physical values, and its gap keeps the sentinel:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> packed = Dataset.from_array(
  ...     np.array([[10, -9999]], dtype="int16"),
  ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
  ...     no_data_value=-9999,
  ... )
  >>> packed.offset = [273.15]
  >>> packed.band_units = ["K"]
  >>> converted = packed.convert_units("celsius")
  >>> [round(value, 6) for value in converted.read_array().ravel().tolist()]
  [10.0, -9999.0]
  >>> converted.scale, converted.offset
  ([1.0], [0])
  

Source code in src/pyramids/dataset/dataset.py

def convert_units(self, target: str, band: int | None = None) -> Dataset:
    """Convert band values to ``target`` units, returning a new Dataset.

    Unlike the :attr:`band_units` setter — which only relabels bands — this
    actually transforms the values using a small affine conversion table
    (see :func:`pyramids.dataset.ops.units.convert_array`) and records the new
    unit on the result. The output is a new in-memory `float64` Dataset; the
    source is left untouched.

    The values converted are the physical ones `read_array` returns, so a
    CF-packed band (`scale_factor` / `add_offset`) is unpacked first and the
    result, holding computed values, declares no packing. No-data cells are
    found in the stored values, where the sentinel lives, and keep the declared
    `no_data_value` unchanged rather than being converted as if they were data.

    Args:
        target: Target unit label (e.g. ``"celsius"``, ``"hPa"``, ``"knots"``).
        band: Zero-based band index to convert. ``None`` (default) converts every
            band; bands already in ``target`` units are passed through unchanged.

    Returns:
        A new :class:`Dataset` with converted values and updated
        :attr:`band_units`.

    Raises:
        ValueError: ``band`` is out of range, a converted band has no source unit
            set, or the ``(source, target)`` pair is unsupported.

    Examples:
        - Convert a Kelvin raster to Celsius and read the new values:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.from_array(
            ...     np.array([[273.15, 283.15], [293.15, 303.15]]),
            ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
            ... )
            >>> ds.band_units = ["K"]
            >>> converted = ds.convert_units("celsius")
            >>> converted.read_array().tolist()
            [[0.0, 10.0], [20.0, 30.0]]
            >>> converted.band_units
            ['celsius']

            ```
        - An unsupported target raises a clear error:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset
            >>> ds = Dataset.from_array(
            ...     np.array([[273.15]]),
            ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
            ... )
            >>> ds.band_units = ["K"]
            >>> try:
            ...     ds.convert_units("furlongs")
            ... except ValueError as exc:
            ...     print("No unit conversion" in str(exc))
            True

            ```
        - A packed band is converted from its physical values, and its gap keeps
          the sentinel:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> packed = Dataset.from_array(
            ...     np.array([[10, -9999]], dtype="int16"),
            ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
            ...     no_data_value=-9999,
            ... )
            >>> packed.offset = [273.15]
            >>> packed.band_units = ["K"]
            >>> converted = packed.convert_units("celsius")
            >>> [round(value, 6) for value in converted.read_array().ravel().tolist()]
            [10.0, -9999.0]
            >>> converted.scale, converted.offset
            ([1.0], [0])

            ```
    """
    if band is not None and not 0 <= band < self.band_count:
        raise ValueError(
            f"band {band} is out of range for a {self.band_count}-band dataset."
        )

    band_indices = range(self.band_count) if band is None else [band]
    source_units = list(self.band_units)
    new_units = list(self.band_units)

    # `squeeze=True` keeps the classic flattened `(bands, rows, cols)` this per-band unit
    # conversion expects, not the dimension-preserving default (#1241).
    full = self.read_array(squeeze=True)
    # The gaps are found in the stored counts, where the sentinel lives; the values
    # converted are the physical ones. Comparing the physical read against the
    # stored `-9999` matched nothing, so a packed band's gap was converted as if it
    # were a temperature (-98.49 K came out -371.64 degC) under a declared -9999.
    stored = np.asarray(self.read_array(unpack=False, squeeze=True))
    single_band = self.band_count == 1
    stack = full[np.newaxis, ...] if single_band else full
    stored_stack = stored[np.newaxis, ...] if single_band else stored
    # astype(copy=True by default) already returns a fresh writable array;
    # the trailing .copy() was a redundant second full-cube copy.
    out = stack.astype("float64")
    no_data = self.no_data_value

    for index in band_indices:
        layer = out[index]
        nodata_value = no_data[index]
        mask = (
            stored_stack[index] == nodata_value
            if nodata_value is not None
            else None
        )
        converted = convert_array(layer, source_units[index], target)
        if mask is not None:
            converted[mask] = nodata_value
        out[index] = converted
        new_units[index] = target

    result_array = out[0] if single_band else out
    # `Dataset.from_array`, not `self.from_array`: this method is inherited
    # by NetCDF / Container / Variable, whose override returns a *bandless*
    # Container -- so the `band_units` assignment below died with
    # `IndexError: index 0 is out of bounds for axis 0 with size 0`, three
    # frames from the cause. A unit conversion yields a plain raster in
    # every case, so the base constructor is the right one to name.
    result = Dataset.from_array(
        result_array,
        no_data_value=list(no_data),
        geo_ref=GeoReference(
            geo=self.geotransform, epsg=crs_spec(self.epsg, self.crs)
        ),
    )
    result.band_units = new_units
    return result

set_meta_data(value, domain='')

Replace a named GDAL metadata domain.

Writes value into domain with SetMetadata — a replace, not a merge (the replace semantics match the band-level :meth:Bands.set_metadata <pyramids.dataset.engines.Bands.set_metadata>; unlike it, this method refuses the default domain — see below). Assigning {} (or []) empties the domain's keys, though the domain name itself may still be listed by :attr:meta_data_domains.

Most domains take a KEY=VALUE mapping; an xml:* domain instead takes a single-element list[str] of one XML document, mirroring what :meth:get_meta_data returns for it (passing a dict to an xml:* domain is a mistake — GDAL flattens it to ["KEY=VALUE"]).

The default domain ("") is deliberately rejected: it holds GDAL/CF-managed keys — AREA_OR_POINT and the CF axis metadata that drives CRS inference — and a whole-domain replace would silently drop them (and the CRS/EPSG caches would then re-derive from the corrupted state). Use the :attr:meta_data setter for the default domain; it merges per key and refreshes those caches.

Parameters:

Name	Type	Description	Default
value	dict[str, str] | list[str]	The metadata to write into domain — a dict[str, str] mapping for a KEY=VALUE domain, or a single-element list[str] for an xml:* domain.	required
domain	str	The named GDAL metadata domain to write (for example "IMAGE_STRUCTURE", "RPC", or a custom domain). The empty default domain is not accepted.	''

Raises:

Type	Description
ValueError	domain is the empty default domain — use the :attr:meta_data setter instead.
ReadOnlyError	The dataset is a read-only on-disk file.

Source code in src/pyramids/dataset/dataset.py

def set_meta_data(
    self, value: dict[str, str] | list[str], domain: str = ""
) -> None:
    """Replace a *named* GDAL metadata domain.

    Writes ``value`` into ``domain`` with ``SetMetadata`` — a **replace**, not a
    merge (the replace semantics match the band-level
    :meth:`Bands.set_metadata <pyramids.dataset.engines.Bands.set_metadata>`;
    unlike it, this method **refuses the default domain** — see below). Assigning
    ``{}`` (or ``[]``) empties the domain's keys, though the domain name itself may
    still be listed by :attr:`meta_data_domains`.

    Most domains take a ``KEY=VALUE`` mapping; an ``xml:*`` domain instead takes a
    single-element ``list[str]`` of one XML document, mirroring what
    :meth:`get_meta_data` returns for it (passing a ``dict`` to an ``xml:*`` domain
    is a mistake — GDAL flattens it to ``["KEY=VALUE"]``).

    The **default** domain (``""``) is deliberately rejected: it holds
    GDAL/CF-managed keys — ``AREA_OR_POINT`` and the CF axis metadata that drives
    CRS inference — and a whole-domain replace would silently drop them (and the
    CRS/EPSG caches would then re-derive from the corrupted state). Use the
    :attr:`meta_data` setter for the default domain; it merges per key and
    refreshes those caches.

    Args:
        value: The metadata to write into ``domain`` — a ``dict[str, str]``
            mapping for a ``KEY=VALUE`` domain, or a single-element ``list[str]``
            for an ``xml:*`` domain.
        domain: The named GDAL metadata domain to write (for example
            ``"IMAGE_STRUCTURE"``, ``"RPC"``, or a custom domain). The empty
            default domain is not accepted.

    Raises:
        ValueError: ``domain`` is the empty default domain — use the
            :attr:`meta_data` setter instead.
        ReadOnlyError: The dataset is a read-only on-disk file.
    """
    if not domain:
        raise ValueError(
            "set_meta_data writes named domains only; use the `meta_data` setter "
            "for the default domain (it merges per key and refreshes CRS caches)."
        )
    self._require_writable("set metadata")
    self._raster.SetMetadata(value, domain)

open_subdataset(key)

Open one of this container's subdatasets, carrying its open context.

Resolves key against :attr:subdatasets and reopens the chosen nested raster with this dataset's access mode, GDAL environment, and open options.

The result is a base :class:Dataset: a subdataset connection string is a classic-mode raster reference, so it is opened as an ordinary raster (unlike :meth:SubDataset.open, this carries the parent's access mode, GDAL env, and open options). The parent's open options are reapplied verbatim to the child open. If the parent is open in update mode the child is opened in update mode too; not every driver supports updating a subdataset connection string, so a write-mode open can fail for some containers. For a NetCDF container, use :meth:~pyramids.netcdf.netcdf.NetCDF.get_variable / NetCDF.variables instead when you want the multidimensional, NetCDF-preserving view of a variable — those handle the multidim open a raw subdataset string cannot.

Parameters:

Name	Type	Description	Default
key	int | str	An index into :attr:subdatasets (0-based; negative indices count from the end, per Python list semantics), or a subdataset's full name (its GDAL connection string).	required

Returns:

Name	Type	Description
Dataset	Dataset	The opened subdataset as a base Dataset.

Raises:

Type	Description
TypeError	key is neither an int index nor a str name.
IndexError	key is an out-of-range index.
ValueError	key is a name that is not among this container's subdatasets.

Source code in src/pyramids/dataset/dataset.py

def open_subdataset(self, key: int | str) -> Dataset:
    """Open one of this container's subdatasets, carrying its open context.

    Resolves ``key`` against :attr:`subdatasets` and reopens the chosen nested
    raster with this dataset's access mode, GDAL environment, and open options.

    The result is a **base** :class:`Dataset`: a subdataset connection string is
    a classic-mode raster reference, so it is opened as an ordinary raster
    (unlike :meth:`SubDataset.open`, this carries the parent's access mode, GDAL
    env, and open options). The parent's open options are reapplied verbatim to
    the child open. If the parent is open in update mode the child is opened in
    update mode too; not every driver supports updating a subdataset connection
    string, so a write-mode open can fail for some containers. For a ``NetCDF``
    container, use
    :meth:`~pyramids.netcdf.netcdf.NetCDF.get_variable` / ``NetCDF.variables``
    instead when you want the multidimensional, ``NetCDF``-preserving view of a
    variable — those handle the multidim open a raw subdataset string cannot.

    Args:
        key: An index into :attr:`subdatasets` (0-based; negative indices count
            from the end, per Python list semantics), or a subdataset's full
            ``name`` (its GDAL connection string).

    Returns:
        Dataset: The opened subdataset as a base ``Dataset``.

    Raises:
        TypeError: ``key`` is neither an ``int`` index nor a ``str`` name.
        IndexError: ``key`` is an out-of-range index.
        ValueError: ``key`` is a name that is not among this container's
            subdatasets.
    """
    subs = self.subdatasets
    if isinstance(key, bool):
        raise TypeError(
            f"key must be an int index or a str name, not bool: {key!r}"
        )
    if isinstance(key, int):
        name = subs[key].name  # negative indices follow Python list semantics
    elif isinstance(key, str):
        if key not in {sub.name for sub in subs}:
            # Connection strings can embed credentials (signed URLs, SAS tokens);
            # redact before echoing them in the error.
            available = [redact_credentials(sub.name) for sub in subs]
            raise ValueError(
                f"{redact_credentials(key)!r} is not a subdataset of this "
                f"dataset; available: {available}"
            )
        name = key
    else:
        raise TypeError(
            f"key must be an int index or a str name, got {type(key).__name__}"
        )
    # Open the classic-mode subdataset string as a base Dataset. read_file both
    # installs the captured GDAL env around the open (so remote credentials apply)
    # and re-attaches it to the result, so no separate context/attach is needed.
    # warn_on_container=False: the caller deliberately drilled into a subdataset, so
    # a container warning here (if the target is itself a nested container) is noise.
    return Dataset.read_file(
        name,
        read_only=self.access == "read_only",
        gdal_env=self._gdal_env or None,
        open_options=list(self._open_options) or None,
        warn_on_container=False,
    )

to_stac_item(item_id, *, asset_href, datetime=None, start_datetime=None, end_datetime=None, asset_key='data', asset_media_type=None, asset_roles=('data',), bands=None, footprint=None, extensions=None)

Describe this raster as a STAC Item dict (proj + raster extensions).

Thin forwarder to :func:pyramids.dataset._stac.to_stac_item — the inverse of :meth:DatasetCollection.from_stac. Returns a plain STAC-JSON dict (pystac not required); the footprint is this dataset's bounding rectangle reprojected to EPSG:4326, or the polygonised extent of its valid pixels with footprint=Footprint(mode="data").

Parameters:

Name	Type	Description	Default
item_id	str	The STAC Item id.	required
asset_href	str	Href to record for the single data asset.	required
datetime		Item datetime (datetime.datetime or RFC 3339 string). None with no range defaults to the current UTC time; None with start_datetime/end_datetime writes a null datetime plus the range (the STAC-valid null-datetime form).	None
start_datetime		Optional range start, written to properties.start_datetime.	None
end_datetime		Optional range end, written to properties.end_datetime.	None
asset_key	str	Key for the data asset (default "data").	'data'
asset_media_type	str | None	Optional media type for the asset.	None
asset_roles	Sequence[str]	STAC roles for the asset (default ("data",)).	('data',)
bands	BandMetadata | None	How much per-band metadata the asset publishes — the statistics / histogram / eo:bands blocks that make GDAL look at the bands. See :class:~pyramids.dataset.stac_options.BandMetadata; None (default) measures nothing.	None
footprint	Footprint | None	How the Item's geometry and bbox are derived from this dataset's extent, and to how many decimals the result is rounded. See :class:~pyramids.dataset.stac_options.Footprint; None (default) is the bounding rectangle at 6 decimals.	None
extensions	StacExtensions | None	Which STAC extension blocks are stamped onto the Item. See :class:~pyramids.dataset.stac_options.StacExtensions; None (default) populates both proj and raster.	None

Returns:

Name	Type	Description
dict	dict	The STAC Item (a GeoJSON Feature).

Examples:

• Describe an in-memory raster: the Item is a GeoJSON Feature whose bbox is the dataset's extent in EPSG:4326, and both extensions are stamped on:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
  ... )
  >>> item = ds.to_stac_item(
  ...     "scene-1", asset_href="scene.tif", datetime="2023-06-01T00:00:00Z"
  ... )
  >>> item["type"], item["id"]
  ('Feature', 'scene-1')
  >>> item["bbox"]
  [0.0, 0.0, 2.0, 2.0]
  >>> item["properties"]["proj:epsg"], item["properties"]["proj:shape"]
  (4326, [2, 2])
  >>> item["assets"]["data"]["href"]
  'scene.tif'
  

• Name the asset and its media type, and give it extra roles:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
  ... )
  >>> item = ds.to_stac_item(
  ...     "scene-1",
  ...     asset_href="red.tif",
  ...     datetime="2023-06-01T00:00:00Z",
  ...     asset_key="red",
  ...     asset_media_type="image/tiff; application=geotiff",
  ...     asset_roles=("data", "reflectance"),
  ... )
  >>> sorted(item["assets"])
  ['red']
  >>> item["assets"]["red"]["type"]
  'image/tiff; application=geotiff'
  >>> item["assets"]["red"]["roles"]
  ['data', 'reflectance']
  

• A datetime range with no instant writes the STAC-valid null datetime plus the range:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
  ... )
  >>> item = ds.to_stac_item(
  ...     "scene-1",
  ...     asset_href="scene.tif",
  ...     start_datetime="2023-06-01T00:00:00Z",
  ...     end_datetime="2023-06-02T00:00:00Z",
  ... )
  >>> item["properties"]["datetime"] is None
  True
  >>> item["properties"]["start_datetime"], item["properties"]["end_datetime"]
  ('2023-06-01T00:00:00Z', '2023-06-02T00:00:00Z')
  

See Also

• pyramids.dataset.stac_options.BandMetadata: the opt-in band blocks.
• pyramids.dataset.stac_options.Footprint: how the geometry is derived.
• pyramids.dataset.stac_options.StacExtensions: which extensions are stamped on.
• DatasetCollection.from_stac: the inverse — Items back into a cube.

Source code in src/pyramids/dataset/dataset.py

def to_stac_item(
    self,
    item_id: str,
    *,
    asset_href: str,
    datetime=None,
    start_datetime=None,
    end_datetime=None,
    asset_key: str = "data",
    asset_media_type: str | None = None,
    asset_roles: Sequence[str] = ("data",),
    bands: BandMetadata | None = None,
    footprint: Footprint | None = None,
    extensions: StacExtensions | None = None,
) -> dict:
    """Describe this raster as a STAC Item dict (proj + raster extensions).

    Thin forwarder to :func:`pyramids.dataset._stac.to_stac_item` — the
    inverse of :meth:`DatasetCollection.from_stac`. Returns a plain
    STAC-JSON dict (pystac not required); the footprint is this dataset's
    bounding rectangle reprojected to EPSG:4326, or the polygonised extent
    of its valid pixels with `footprint=Footprint(mode="data")`.

    Args:
        item_id: The STAC Item id.
        asset_href: Href to record for the single data asset.
        datetime: Item datetime (`datetime.datetime` or RFC 3339 string).
            `None` with no range defaults to the current UTC time; `None`
            with `start_datetime`/`end_datetime` writes a null `datetime`
            plus the range (the STAC-valid null-datetime form).
        start_datetime: Optional range start, written to
            `properties.start_datetime`.
        end_datetime: Optional range end, written to
            `properties.end_datetime`.
        asset_key: Key for the data asset (default `"data"`).
        asset_media_type: Optional media type for the asset.
        asset_roles: STAC `roles` for the asset (default `("data",)`).
        bands: How much per-band metadata the asset publishes — the
            `statistics` / `histogram` / `eo:bands` blocks that make GDAL
            look at the bands. See
            :class:`~pyramids.dataset.stac_options.BandMetadata`; `None`
            (default) measures nothing.
        footprint: How the Item's geometry and bbox are derived from this
            dataset's extent, and to how many decimals the result is
            rounded. See
            :class:`~pyramids.dataset.stac_options.Footprint`; `None`
            (default) is the bounding rectangle at 6 decimals.
        extensions: Which STAC extension blocks are stamped onto the Item.
            See :class:`~pyramids.dataset.stac_options.StacExtensions`;
            `None` (default) populates both `proj` and `raster`.

    Returns:
        dict: The STAC Item (a GeoJSON Feature).

    Examples:
        - Describe an in-memory raster: the Item is a GeoJSON Feature whose bbox is
          the dataset's extent in EPSG:4326, and both extensions are stamped on:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.from_array(
            ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
            ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
            ... )
            >>> item = ds.to_stac_item(
            ...     "scene-1", asset_href="scene.tif", datetime="2023-06-01T00:00:00Z"
            ... )
            >>> item["type"], item["id"]
            ('Feature', 'scene-1')
            >>> item["bbox"]
            [0.0, 0.0, 2.0, 2.0]
            >>> item["properties"]["proj:epsg"], item["properties"]["proj:shape"]
            (4326, [2, 2])
            >>> item["assets"]["data"]["href"]
            'scene.tif'

            ```
        - Name the asset and its media type, and give it extra roles:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.from_array(
            ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
            ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
            ... )
            >>> item = ds.to_stac_item(
            ...     "scene-1",
            ...     asset_href="red.tif",
            ...     datetime="2023-06-01T00:00:00Z",
            ...     asset_key="red",
            ...     asset_media_type="image/tiff; application=geotiff",
            ...     asset_roles=("data", "reflectance"),
            ... )
            >>> sorted(item["assets"])
            ['red']
            >>> item["assets"]["red"]["type"]
            'image/tiff; application=geotiff'
            >>> item["assets"]["red"]["roles"]
            ['data', 'reflectance']

            ```
        - A datetime range with no instant writes the STAC-valid null `datetime`
          plus the range:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.from_array(
            ...     np.array([[1.0, 2.0], [3.0, 4.0]], dtype="float32"),
            ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0, epsg=4326),
            ... )
            >>> item = ds.to_stac_item(
            ...     "scene-1",
            ...     asset_href="scene.tif",
            ...     start_datetime="2023-06-01T00:00:00Z",
            ...     end_datetime="2023-06-02T00:00:00Z",
            ... )
            >>> item["properties"]["datetime"] is None
            True
            >>> item["properties"]["start_datetime"], item["properties"]["end_datetime"]
            ('2023-06-01T00:00:00Z', '2023-06-02T00:00:00Z')

            ```

    See Also:
        - pyramids.dataset.stac_options.BandMetadata: the opt-in band blocks.
        - pyramids.dataset.stac_options.Footprint: how the geometry is derived.
        - pyramids.dataset.stac_options.StacExtensions: which extensions are stamped on.
        - DatasetCollection.from_stac: the inverse — Items back into a cube.
    """
    # Imported here to avoid the dataset <-> stac import cycle at load time.
    from pyramids.dataset._stac import to_stac_item

    return to_stac_item(
        self,
        item_id,
        asset_href=asset_href,
        datetime=datetime,
        start_datetime=start_datetime,
        end_datetime=end_datetime,
        asset_key=asset_key,
        asset_media_type=asset_media_type,
        asset_roles=asset_roles,
        bands=bands,
        footprint=footprint,
        extensions=extensions,
    )

read_file(path, read_only=True, file_i=0, *, driver=None, vsi=None, gdal_env=None, open_options=None, warn_on_container=True) classmethod

Open a raster from a path, URL, or archive member.

Plain local paths, /vsi* paths, and URL schemes (http(s)://, s3://, gs://, az://, abfs:// / abfss://, file://) are all accepted — URLs are transparently rewritten to GDAL's virtual filesystem (GDAL fetches via HTTP range requests for http(s)). Compressed archives are detected from the extension; pass vsi= to be explicit about it (e.g. an archive with an unusual extension, or to open a specific member by index).

Parameters:

Name	Type	Description	Default
path	str | Path	Path or URL of the file to open.	required
read_only	bool	File mode; set to False to open in update mode.	True
file_i	int	Which member to open when path is (or is forced to be) a multi-file archive. Default 0. Counts file members only, in archive order, so a directory entry does not consume an index and a member inside a subdirectory has one. It counts them the same way whether the archive was recognised by its extension or forced with vsi=: those two used to select from differently built lists, so one index named two different members of one archive. A negative index is refused rather than given Python's from-the-end meaning: it names a member of an archive the caller has not listed, so it is far more likely a bug than an intent. Zip and tar used to answer -1 with the last member while gzip refused it.	0
driver	str | None	Force a specific third-party raster driver registered in the pyramids.raster_drivers entry-point group (see :mod:pyramids.dataset._drivers), bypassing GDAL — e.g. to read an Earth Engine asset or a Sentinel product a plugin provides. None (default) opens through GDAL, with two exceptions that still reach a plugin on the bare path: a driver that pre-empts GDAL for this source (declares the source's suffix/scheme in its preempts and confirms it via can_open) is tried before GDAL, and a driver whose can_open claims the source is tried after GDAL fails to recognise it. The pre-empt check consults the driver registry, so a bare install does one cached entry-point scan (finding nothing, then reused for every later read) rather than none — it never pays per-read discovery, and with no drivers registered nothing pre-empts. Raises :class:~pyramids.base._errors.DriverNotExistError when the named driver is not installed.	None
vsi	str | None	Treat path as an archive of this kind and open member file_i from inside it: "zip", "tar" (also "tar.gz" / "tgz"), "gzip" (also "gz"), or "auto" (infer from the extension). Default None — path is opened directly / extension-sniffed as before. Works for archives reachable locally or over the network (/vsizip//vsicurl/… is built automatically) provided the file name carries a recognised archive extension — GDAL's archive handlers key off the extension, so an extension-less download URL must first be fetched and saved with a .zip name (or written to /vsimem/<name>.zip via :func:osgeo.gdal.FileFromMemBuffer).	None
gdal_env	dict[str, str] | None	Optional GDAL config (cloud credentials, HTTP knobs) installed for this open and captured on the returned dataset, so it is re-installed around its reads. Needed by the read paths that open the file again instead of reusing this handle: threadsafe=True per-thread handles, lazy chunks= reads inside dask tasks, and unpickling on a worker. :func:pyramids.stac.load_asset passes a signer's gdal_env() here. It does not reach a VRT's source opens — GDAL ignores the thread-local config there, so :func:pyramids.stac.build_vrt_from_stac puts those credentials in the source path instead. Default None — no extra config, nothing captured.	None
open_options	dict[str, str] | list[str] | tuple[str, ...] | None	GDAL open options as a mapping ({"GEOREF_SOURCES": "INTERNAL"}) or GDAL's native ["KEY=VALUE"] list. Forwarded to the driver and captured on the returned :class:Dataset, so the paths that reopen the file (threadsafe=True handles, lazy chunks= reads, unpickle on a worker) reopen with the same options. Default None.	None
warn_on_container	bool	When the path opens to a container — a raster with no bands of its own whose payload is a set of nested subdatasets (NetCDF/HDF/ Zarr, GRIB, WMS/WMTS, a Sentinel product) — emit a :class:~pyramids.errors.ContainerRasterWarning naming the subdatasets, instead of silently returning a 0-band dataset. Use :attr:subdatasets to list them and :meth:open_subdataset to open one. Set False to open a container quietly (callers that open containers on purpose). Default True.	True

Returns:

Name	Type	Description
Dataset	Dataset	Opened dataset instance.

See Also

• :meth:read_array: read the values stored in a dataset band.
• :meth:from_bytes: open a raster held in memory.
• :attr:gdal_env: the config captured by gdal_env=.
• :meth:pyramids.dataset.DatasetCollection.from_archive: open every member of an archive as a temporal stack.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def read_file(
    cls,
    path: str | Path,
    read_only=True,
    file_i: int = 0,
    *,
    driver: str | None = None,
    vsi: str | None = None,
    gdal_env: dict[str, str] | None = None,
    open_options: dict[str, str] | list[str] | tuple[str, ...] | None = None,
    warn_on_container: bool = True,
) -> Dataset:
    """Open a raster from a path, URL, or archive member.

    Plain local paths, ``/vsi*`` paths, and URL schemes
    (``http(s)://``, ``s3://``, ``gs://``, ``az://``, ``abfs://`` / ``abfss://``,
    ``file://``) are all accepted — URLs are transparently rewritten to
    GDAL's virtual filesystem (GDAL fetches via HTTP range requests for
    ``http(s)``). Compressed archives are detected from the extension; pass
    ``vsi=`` to be explicit about it (e.g. an archive with an unusual
    extension, or to open a specific member by index).

    Args:
        path (str | Path):
            Path or URL of the file to open.
        read_only (bool):
            File mode; set to ``False`` to open in update mode.
        file_i (int):
            Which member to open when ``path`` is (or is forced to be) a
            multi-file archive. Default ``0``. Counts *file* members only,
            in archive order, so a directory entry does not consume an
            index and a member inside a subdirectory has one. It counts
            them the same way whether the archive was recognised by its
            extension or forced with ``vsi=``: those two used to select
            from differently built lists, so one index named two different
            members of one archive. A negative index is refused rather
            than given Python's from-the-end meaning: it names a member of
            an archive the caller has not listed, so it is far more likely
            a bug than an intent. Zip and tar used to answer ``-1`` with
            the last member while gzip refused it.
        driver (str | None):
            Force a specific third-party raster driver registered in the
            ``pyramids.raster_drivers`` entry-point group (see
            :mod:`pyramids.dataset._drivers`), bypassing GDAL — e.g. to read
            an Earth Engine asset or a Sentinel product a plugin provides.
            ``None`` (default) opens through GDAL, with two exceptions that
            still reach a plugin on the bare path: a driver that *pre-empts*
            GDAL for this source (declares the source's suffix/scheme in its
            ``preempts`` and confirms it via ``can_open``) is tried **before**
            GDAL, and a driver whose ``can_open`` claims the source is tried
            **after** GDAL fails to recognise it. The pre-empt check consults
            the driver registry, so a bare install does one cached entry-point
            scan (finding nothing, then reused for every later read) rather
            than none — it never pays per-read discovery, and with no drivers
            registered nothing pre-empts. Raises
            :class:`~pyramids.base._errors.DriverNotExistError` when the named
            driver is not installed.
        vsi (str | None):
            Treat ``path`` as an archive of this kind and open member
            ``file_i`` from inside it: ``"zip"``, ``"tar"`` (also
            ``"tar.gz"`` / ``"tgz"``), ``"gzip"`` (also ``"gz"``), or
            ``"auto"`` (infer from the extension). Default ``None`` —
            ``path`` is opened directly / extension-sniffed as before.
            Works for archives reachable locally or over the network
            (``/vsizip//vsicurl/…`` is built automatically) **provided the
            file name carries a recognised archive extension** — GDAL's
            archive handlers key off the extension, so an extension-less
            download URL must first be fetched and saved with a ``.zip``
            name (or written to ``/vsimem/<name>.zip`` via
            :func:`osgeo.gdal.FileFromMemBuffer`).
        gdal_env (dict[str, str] | None):
            Optional GDAL config (cloud credentials, HTTP knobs) installed
            for this open **and captured on the returned dataset**, so it is
            re-installed around its reads. Needed by the read paths that
            open the file again instead of reusing this handle:
            ``threadsafe=True`` per-thread handles, lazy ``chunks=`` reads
            inside dask tasks, and unpickling on a worker.
            :func:`pyramids.stac.load_asset` passes a signer's
            ``gdal_env()`` here. It does **not** reach a VRT's source opens
            — GDAL ignores the thread-local config there, so
            :func:`pyramids.stac.build_vrt_from_stac` puts those credentials
            in the source path instead. Default ``None`` — no extra config,
            nothing captured.
        open_options:
            GDAL open options as a mapping
            (``{"GEOREF_SOURCES": "INTERNAL"}``) or GDAL's native
            ``["KEY=VALUE"]`` list. Forwarded to the driver and captured on
            the returned :class:`Dataset`, so the paths that reopen the file
            (``threadsafe=True`` handles, lazy ``chunks=`` reads, unpickle on
            a worker) reopen with the same options. Default ``None``.
        warn_on_container:
            When the path opens to a *container* — a raster with no bands of
            its own whose payload is a set of nested subdatasets (NetCDF/HDF/
            Zarr, GRIB, WMS/WMTS, a Sentinel product) — emit a
            :class:`~pyramids.errors.ContainerRasterWarning` naming the
            subdatasets, instead of silently returning a 0-band dataset. Use
            :attr:`subdatasets` to list them and :meth:`open_subdataset` to open
            one. Set ``False`` to open a container quietly (callers that open
            containers on purpose). Default ``True``.

    Returns:
        Dataset:
            Opened dataset instance.

    See Also:
        - :meth:`read_array`: read the values stored in a dataset band.
        - :meth:`from_bytes`: open a raster held in memory.
        - :attr:`gdal_env`: the config captured by ``gdal_env=``.
        - :meth:`pyramids.dataset.DatasetCollection.from_archive`: open
          *every* member of an archive as a temporal stack.
    """
    # An explicit driver= routes straight to that registered third-party raster
    # driver, bypassing GDAL (resolve_driver raises DriverNotExistError if unknown).
    # open_options is passed through to the driver uninterpreted (all of dict / list /
    # tuple / None survive), and the driver's read must return a Dataset.
    if driver is not None:
        selected = resolve_driver(driver)
        _warn_ignored_gdal_args(selected.name, read_only, file_i, vsi, gdal_env)
        return _read_via_driver(selected, str(path), open_options)
    # A registered driver that declares `preempts` for this source's suffix/scheme (and whose
    # can_open confirms it) gets first refusal, *before* GDAL — so a plugin that reads a format
    # better than GDAL's generic container (a Sentinel-2 .SAFE, say) wins the bare path. This
    # is opt-in: a driver with no `preempts` is not consulted, so GDAL-first stays the default
    # and a bare install (which registers no drivers) scans nothing. An explicit `vsi=` is a
    # deliberate "open member N of this archive" intent that outranks pre-emption, so the scan
    # is skipped then (as `driver=` short-circuits above); the first registered pre-empting
    # driver wins a tie, and a debug log records which driver took the read.
    preempting = None if vsi is not None else select_preempting_driver(str(path))
    if preempting is not None:
        logging.getLogger(__name__).debug(
            "read_file: driver %r pre-empted GDAL for %s",
            preempting.name,
            str(path),
        )
        _warn_ignored_gdal_args(preempting.name, read_only, file_i, vsi, gdal_env)
        return _read_via_driver(preempting, str(path), open_options)
    # Normalize once here so the value captured on the instance below is the
    # KEY=VALUE list form (a raw dict would lose its values when the base
    # __init__ tuple-ifies it). _io.read_file re-normalizes idempotently for
    # its own direct callers — the double pass is intentional and harmless.
    options = _io.normalize_open_options(open_options)
    try:
        with cloud_config_from_env(gdal_env, path=str(path)):
            src = _io.read_file(
                path,
                read_only=read_only,
                file_i=file_i,
                vsi=vsi,
                open_options=options,
            )
    except (FileFormatNotSupportedError, FileNotFoundError, RuntimeError):
        # GDAL could not open the source. For a source with a suffix/scheme the pre-empt scan
        # above already warmed the discovery cache; for a tokenless source this failed read is
        # what warms it. Either way, give a *claiming* registered driver a chance
        # (an ``ee://`` asset id, a ``.SAFE`` directory, an FCI ``.nat`` granule); the scan
        # routes only to a driver whose can_open claims the source. ``ee://`` / ``s3://``
        # surface as a bare RuntimeError from GDAL, which is why RuntimeError is caught — a
        # claimed source is handed to its driver even then, so a driver's can_open should
        # stay specific. A source no driver claims re-raises GDAL's own error unchanged (a
        # missing file stays FileNotFoundError, a corrupt raster keeps its read error), so
        # read_file's error contract does not depend on whether a plugin is installed.
        fallback = select_driver(str(path), None)
        if fallback is None:
            raise
        _warn_ignored_gdal_args(fallback.name, read_only, file_i, vsi, gdal_env)
        return _read_via_driver(fallback, str(path), open_options)
    dataset = cls(
        src,
        access="read_only" if read_only else "write",
        gdal_env=gdal_env,
        open_options=options,
    )
    if warn_on_container and not dataset.band_count:
        subdatasets = dataset.subdatasets
        if subdatasets:
            count = len(subdatasets)
            # Cap the preview so a many-variable container (tens of NetCDF/HDF
            # variables) does not produce an unbounded warning string.
            shown = [redact_credentials(sub.name) for sub in subdatasets[:10]]
            if count > len(shown):
                shown.append(f"… and {count - 10} more")
            warnings.warn(
                f"{redact_credentials(str(path))!r} is a container raster with no "
                f"bands of its own; it has {count} subdataset(s). Use "
                f".subdatasets to list them and .open_subdataset(<index or name>) "
                f"to open one. Available: {shown}",
                ContainerRasterWarning,
                stacklevel=2,
            )
    return dataset

from_bytes(data, *, suffix='.tif', name=None, read_only=True) classmethod

Open a raster held in memory as a byte string.

Writes data to a temporary GDAL /vsimem/ path and opens it — no on-disk temp file needed. Useful for HTTP response bodies (requests.get(url).content), object-store get_object payloads, database blobs, and test fixtures.

This is not a URL helper. Reading from a URL is already supported by :meth:read_file, which rewrites http(s)://, s3://, gs://, az://, abfs:// / abfss:// and file:// to GDAL /vsi* paths. Use from_bytes only when you already hold the bytes.

The /vsimem/ entry is removed automatically when the returned :class:Dataset is garbage-collected (:func:weakref.finalize); :meth:close does not need to be called for cleanup. Note that an in-memory dataset is not picklable — :meth:__reduce__ raises TypeError for /vsimem/ paths; call :meth:to_file first to anchor it to disk before sending it to another process.

Parameters:

Name	Type	Description	Default
data	bytes | bytearray | memoryview	Raw bytes of a raster (GeoTIFF, ASCII grid, ...). For NetCDF bytes use :meth:pyramids.netcdf.NetCDF.from_bytes.	required
suffix	str	Extension hint for GDAL's driver detection. Needed only for headerless formats (e.g. ESRI ASCII grid: suffix=".asc"); GDAL sniffs anything with a magic header regardless. Defaults to ".tif".	'.tif'
name	str | None	Optional label recorded as the dataset's :attr:file_name (cosmetic only — it is still an in-memory dataset). Defaults to None.	None
read_only	bool	Open the dataset read-only. Defaults to True.	True

Returns:

Name	Type	Description
Dataset	Dataset	The opened in-memory dataset.

Raises:

Type	Description
TypeError	data is not a bytes-like object.
ValueError	GDAL could not open the bytes (corrupt / truncated payload, or a headerless format without a suffix hint).

Examples:

• Open the bytes of a downloaded GeoTIFF and inspect it (the bytes here come from a file, but they could just as well be requests.get(url).content):

  >>> from pathlib import Path
  >>> from pyramids.dataset import Dataset
  >>> data = Path("tests/data/acc4000.tif").read_bytes()
  >>> ds = Dataset.from_bytes(data, name="downloaded-scene")
  >>> ds.band_count
  1
  >>> ds.shape
  (1, 13, 14)
  >>> ds.epsg
  32618
  >>> ds.file_name
  'downloaded-scene'
  >>> ds.close()
  

• The bytes path yields the same data as opening the file directly:

  >>> from pathlib import Path
  >>> from pyramids.dataset import Dataset
  >>> data = Path("tests/data/acc4000.tif").read_bytes()
  >>> from_bytes = Dataset.from_bytes(data)
  >>> from_file = Dataset.read_file("tests/data/acc4000.tif")
  >>> from_bytes.shape == from_file.shape
  True
  >>> from_bytes.epsg == from_file.epsg
  True
  

• An in-memory dataset cannot be pickled — anchor it to disk first:

  >>> import pickle
  >>> from pathlib import Path
  >>> from pyramids.dataset import Dataset
  >>> data = Path("tests/data/acc4000.tif").read_bytes()
  >>> try:
  ...     pickle.dumps(Dataset.from_bytes(data))
  ... except TypeError as exc:
  ...     print("to_file" in str(exc))
  True
  

See Also

• :meth:read_file: open a raster from a path or URL.
• :meth:to_file: write an in-memory dataset to disk.
• :meth:pyramids.netcdf.NetCDF.from_bytes: the NetCDF variant.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_bytes(
    cls,
    data: bytes | bytearray | memoryview,
    *,
    suffix: str = ".tif",
    name: str | None = None,
    read_only: bool = True,
) -> Dataset:
    """Open a raster held in memory as a byte string.

    Writes ``data`` to a temporary GDAL ``/vsimem/`` path and opens
    it — no on-disk temp file needed. Useful for HTTP response
    bodies (``requests.get(url).content``), object-store
    ``get_object`` payloads, database blobs, and test fixtures.

    This is **not** a URL helper. Reading from a URL is already
    supported by :meth:`read_file`, which rewrites ``http(s)://``,
    ``s3://``, ``gs://``, ``az://``, ``abfs://`` / ``abfss://`` and ``file://``
    to GDAL ``/vsi*`` paths. Use ``from_bytes`` only when you
    already hold the bytes.

    The ``/vsimem/`` entry is removed automatically when the
    returned :class:`Dataset` is garbage-collected
    (:func:`weakref.finalize`); :meth:`close` does not need to be
    called for cleanup. Note that an in-memory dataset is **not
    picklable** — :meth:`__reduce__` raises ``TypeError`` for
    ``/vsimem/`` paths; call :meth:`to_file` first to anchor it to
    disk before sending it to another process.

    Args:
        data: Raw bytes of a raster (GeoTIFF, ASCII grid, ...). For
            NetCDF bytes use :meth:`pyramids.netcdf.NetCDF.from_bytes`.
        suffix: Extension hint for GDAL's driver detection. Needed
            only for headerless formats (e.g. ESRI ASCII grid:
            ``suffix=".asc"``); GDAL sniffs anything with a magic
            header regardless. Defaults to ``".tif"``.
        name: Optional label recorded as the dataset's
            :attr:`file_name` (cosmetic only — it is still an
            in-memory dataset). Defaults to ``None``.
        read_only: Open the dataset read-only. Defaults to ``True``.

    Returns:
        Dataset: The opened in-memory dataset.

    Raises:
        TypeError: ``data`` is not a bytes-like object.
        ValueError: GDAL could not open the bytes (corrupt /
            truncated payload, or a headerless format without a
            ``suffix`` hint).

    Examples:
        - Open the bytes of a downloaded GeoTIFF and inspect it (the
          bytes here come from a file, but they could just as well be
          ``requests.get(url).content``):
            ```python
            >>> from pathlib import Path
            >>> from pyramids.dataset import Dataset
            >>> data = Path("tests/data/acc4000.tif").read_bytes()
            >>> ds = Dataset.from_bytes(data, name="downloaded-scene")
            >>> ds.band_count
            1
            >>> ds.shape
            (1, 13, 14)
            >>> ds.epsg
            32618
            >>> ds.file_name
            'downloaded-scene'
            >>> ds.close()

            ```
        - The bytes path yields the same data as opening the file directly:
            ```python
            >>> from pathlib import Path
            >>> from pyramids.dataset import Dataset
            >>> data = Path("tests/data/acc4000.tif").read_bytes()
            >>> from_bytes = Dataset.from_bytes(data)
            >>> from_file = Dataset.read_file("tests/data/acc4000.tif")
            >>> from_bytes.shape == from_file.shape
            True
            >>> from_bytes.epsg == from_file.epsg
            True

            ```
        - An in-memory dataset cannot be pickled — anchor it to disk first:
            ```python
            >>> import pickle
            >>> from pathlib import Path
            >>> from pyramids.dataset import Dataset
            >>> data = Path("tests/data/acc4000.tif").read_bytes()
            >>> try:
            ...     pickle.dumps(Dataset.from_bytes(data))
            ... except TypeError as exc:
            ...     print("to_file" in str(exc))
            True

            ```

    See Also:
        - :meth:`read_file`: open a raster from a path or URL.
        - :meth:`to_file`: write an in-memory dataset to disk.
        - :meth:`pyramids.netcdf.NetCDF.from_bytes`: the NetCDF variant.
    """
    src, vsi_path = _io.bytes_to_gdal(data, suffix=suffix, read_only=read_only)
    try:
        obj = cls(src, access="read_only" if read_only else "write")
    except Exception as e:
        src = None
        _io.silent_unlink(vsi_path)
        raise ValueError(
            "could not open the supplied bytes as a raster dataset "
            f"(the data may be corrupt or truncated): {e}"
        ) from e
    obj._vsimem_path = vsi_path
    weakref.finalize(obj, _io.silent_unlink, vsi_path)
    if name is not None:
        obj._file_name = str(name)
    return obj

from_wcs(endpoint, *, coverage, bbox, crs=_DEFAULT_CRS, output_crs=None, resolution=None, version=None, coverage_crs=None, wcs_format=None, output=None, resample='nearest', auth=None, timeout=60.0, extra_params=None, direct=False, subset_axes=None) classmethod

Read a coverage subset from an OGC Web Coverage Service (WCS).

Fetches a windowed subset of a coverage from a WCS server and returns it as a :class:Dataset. The transport is GDAL's native WCS driver, so the WCS 1.0.0 vs 2.0.x dialect fork — bbox + resx/resy versus named-axis subsets + scaling — is handled inside GDAL; the caller always supplies a single lon/lat bbox (plus optional resolution and output_crs).

Two things GDAL does not do for every server, which this method adds:

• CRS shim. Some servers advertise a coverage CRS under an authority code absent from the local PROJ database (notably ISRIC SoilGrids' EPSG:152160, a custom Interrupted Goode Homolosine). GDAL then opens the coverage without a spatial reference and cannot place the request window. Pass coverage_crs with the coverage's real CRS and it is attached client-side.
• bbox reprojection. bbox is given in crs (lon/lat by default) and transformed into the coverage's native CRS with pyproj before the request, so subsetting lands on the correct pixels even when the server only honours its native CRS.

For a GetCoverage-only endpoint — a "WCS shim" that returns 502/400 for GetCapabilities/DescribeCoverage but serves GetCoverage (e.g. Copernicus EDO/GDO) — pass direct=True. That skips both discovery steps and issues a KVP GetCoverage built straight from coverage / crs / bbox / wcs_format / extra_params, so the caller owns correctness (no capabilities check). For WCS 2.0.x the SUBSET axis labels default to ("Long", "Lat") for a geographic crs — override with subset_axes if the server names its axes differently.

A non-conformant shim may also reject the spec KVP spellings themselves: the Copernicus EDO/GDO MapServer 500s on the uppercase COVERAGEID key and on SUBSETTINGCRS= (it wants a lowercase coverageID and the WCS-1.x CRS=). In direct mode extra_params can override a built-in KVP by key, so pass extra_params={"coverageID": <id>, "CRS": <crs>} to hand such a server its exact spelling — the override replaces the built-in rather than duplicating it.

Parameters:

Name	Type	Description	Default
endpoint	str	The WCS service URL, including any server-specific query prefix (e.g. "https://maps.isric.org/mapserv?map=/map/nitrogen.map"). Catalog / coverage-name routing belongs in the calling layer, not here.	required
coverage	str	The coverage identifier as advertised by GetCapabilities (e.g. "nitrogen_0-5cm_mean"). A value the server does not advertise raises :class:ValueError.	required
bbox	tuple[float, float, float, float]	(minx, miny, maxx, maxy) in crs order (lon/lat for the default "EPSG:4326"). minx > maxx reads as a window crossing the antimeridian, the same wrap :meth:crop accepts: it is fetched as two GetCoverage requests either side of the 180 degree seam and concatenated into one raster whose longitude runs on past it (170 .. 180 then 180 .. 190). Both halves are read off a single open connection, so they come from the same source lattice and stitch without resampling, and a half that misses the coverage is skipped rather than requested. output_crs, resolution and output are applied once, to the merged raster. In direct mode there is no shared connection: the halves are two separate GetCoverage requests, snapped to resolution so they land on one lattice. Pass a resolution for a wrapping direct read — without one nothing constrains the server to grid the two halves alike, and a mismatch is refused rather than stitched.	required
crs	str	CRS of bbox. Defaults to "EPSG:4326".	_DEFAULT_CRS
output_crs	str | None	Optional CRS to reproject the result into (any form :meth:to_crs accepts). None (default) keeps the coverage's native CRS.	None
resolution	float | tuple[float, float] | None	Output pixel size in the units of output_crs (or the native CRS when output_crs is None). A scalar gives square pixels; an (x_res, y_res) pair gives non-square pixels. None (default) keeps the coverage's native resolution.	None
version	str | None	Force a WCS protocol version ("1.0.0", "2.0.1", …). None (default) lets GDAL negotiate from the server's capabilities. Note that some MapServer builds silently downgrade a requested 2.0.x to 1.0.0.	None
coverage_crs	str | None	The coverage's CRS, used only when the server's advertised CRS does not resolve in PROJ (see the CRS-shim note). Any proj4 / WKT / authority string pyproj understands.	None
wcs_format	str | None	Optional GDAL PreferredFormat for the GetCoverage response (e.g. "GEOTIFF_INT16"). None lets GDAL pick from the coverage's advertised formats.	None
output	str | Path | None	Optional path to also write the result to as a GeoTIFF. The method still returns the :class:Dataset.	None
resample	str	Resampling method for the output_crs / resolution warp. Defaults to "nearest".	'nearest'
auth	tuple[str, str] | None	Optional (username, password) for Basic-authed services.	None
timeout	float	HTTP timeout in seconds for the metadata / coverage requests. Defaults to 60.0.	60.0
extra_params	dict[str, str] | None	Optional extra GetCoverage query parameters folded into the request (a workaround hook for server quirks). In direct mode a key that matches a built-in KVP (case-insensitively, with the cross-version pairs CRS/SUBSETTINGCRS and COVERAGE/COVERAGEID each treated as one) overrides it with the given spelling and value — e.g. {"coverageID": "spaST"} sends a lowercase key, {"CRS": "EPSG:4326"} sends the WCS-1.x CRS token instead of SUBSETTINGCRS. Non-matching keys are appended in caller order (e.g. a TIME axis). The fixed protocol keys SERVICE / VERSION / REQUEST / SUBSET cannot be overridden and raise :class:ValueError; because SUBSET is locked, an additional WCS-2.0 SUBSET axis (e.g. a temporal subset) cannot be added in direct mode — use discovery mode for that. Two keys targeting the same built-in parameter (e.g. both CRS and SUBSETTINGCRS) also raise.	None
direct	bool	When True, skip GetCapabilities/DescribeCoverage and issue a KVP GetCoverage directly — for shim servers that only implement GetCoverage. Defaults to False (full handshake).	False
subset_axes	tuple[str, str] | None	Direct mode, WCS 2.0.x only — the (x, y) SUBSET axis labels. None (default) derives them from crs (("Long", "Lat") for geographic, ("X", "Y") otherwise). These defaults are a best-effort guess — direct mode skips the DescribeCoverage that would reveal the coverage's real (case- sensitive) axis labels — so MapServer-family shims often need subset_axes=("x", "y") or the server's exact axis names.	None

Returns:

Name	Type	Description
Dataset	Dataset	The fetched coverage subset.

Raises:

Type	Description
ValueError	bbox is malformed — an inverted latitude range still counts, since there is no seam in latitude — coverage is not advertised (discovery mode), coverage_crs cannot be interpreted, the requested window exceeds the pixel ceiling (:data:~pyramids.base._coverage.MAX_PX; a native-resolution read over a wide bbox — pass a coarser resolution or a smaller bbox to bound it), or (direct mode) the WCS version is unsupported, 1.0.0 lacks a resolution, or an extra_params key targets a locked protocol parameter.
WCSError	The server could not be reached or returned an error / a non-raster (<ows:ExceptionReport>) body.

Examples:

Read a Netherlands subset of SoilGrids nitrogen (its native CRS needs the coverage_crs shim):

>>> ds = Dataset.from_wcs(  # doctest: +SKIP
...     "https://maps.isric.org/mapserv?map=/map/nitrogen.map",
...     coverage="nitrogen_0-5cm_mean",
...     bbox=(5.0, 51.0, 6.0, 52.0),
...     coverage_crs="+proj=igh +lat_0=0 +lon_0=0 +datum=WGS84 +units=m +no_defs",
... )

Direct mode for a GetCoverage-only endpoint (Copernicus EDO/GDO), whose GetCapabilities/DescribeCoverage return 502/400. EDO also rejects the spec KVP spellings, so override the coverage key and CRS token via extra_params to send the lowercase coverageID and the WCS-1.x CRS= it accepts:

>>> ds = Dataset.from_wcs(  # doctest: +SKIP
...     "https://drought.emergency.copernicus.eu/api/wcs?map=DO_WCS",
...     coverage="spaST",
...     bbox=(10.0, 45.0, 15.0, 48.0),
...     crs="EPSG:4326",
...     version="2.0.0",
...     wcs_format="GEOTIFF",
...     direct=True,
...     extra_params={
...         "coverageID": "spaST",
...         "CRS": "EPSG:4326",
...         "TIME": "2023-06-01",
...         "SELECTED_TIMESCALE": "01",
...     },
... )

See Also

• :meth:read_file: open a raster from a path or URL.
• :meth:from_bytes: open a raster already held in memory.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_wcs(
    cls,
    endpoint: str,
    *,
    coverage: str,
    bbox: tuple[float, float, float, float],
    crs: str = _DEFAULT_CRS,
    output_crs: str | None = None,
    resolution: float | tuple[float, float] | None = None,
    version: str | None = None,
    coverage_crs: str | None = None,
    wcs_format: str | None = None,
    output: str | Path | None = None,
    resample: str = "nearest",
    auth: tuple[str, str] | None = None,
    timeout: float = 60.0,
    extra_params: dict[str, str] | None = None,
    direct: bool = False,
    subset_axes: tuple[str, str] | None = None,
) -> Dataset:
    """Read a coverage subset from an OGC Web Coverage Service (WCS).

    Fetches a windowed subset of a coverage from a WCS server and returns it
    as a :class:`Dataset`. The transport is GDAL's native WCS driver, so the
    WCS ``1.0.0`` vs ``2.0.x`` dialect fork — ``bbox`` + ``resx/resy`` versus
    named-axis ``subsets`` + ``scaling`` — is handled inside GDAL; the caller
    always supplies a single lon/lat ``bbox`` (plus optional ``resolution``
    and ``output_crs``).

    Two things GDAL does **not** do for every server, which this method adds:

    * **CRS shim.** Some servers advertise a coverage CRS under an authority
      code absent from the local PROJ database (notably ISRIC SoilGrids'
      ``EPSG:152160``, a custom Interrupted Goode Homolosine). GDAL then opens
      the coverage without a spatial reference and cannot place the request
      window. Pass ``coverage_crs`` with the coverage's real CRS and it is
      attached client-side.
    * **bbox reprojection.** ``bbox`` is given in ``crs`` (lon/lat by
      default) and transformed into the coverage's native CRS with ``pyproj``
      before the request, so subsetting lands on the correct pixels even when
      the server only honours its native CRS.

    For a **``GetCoverage``-only endpoint** — a "WCS shim" that returns
    ``502``/``400`` for ``GetCapabilities``/``DescribeCoverage`` but serves
    ``GetCoverage`` (e.g. Copernicus EDO/GDO) — pass ``direct=True``. That skips
    both discovery steps and issues a KVP ``GetCoverage`` built straight from
    ``coverage`` / ``crs`` / ``bbox`` / ``wcs_format`` / ``extra_params``, so the
    caller owns correctness (no capabilities check). For WCS ``2.0.x`` the
    ``SUBSET`` axis labels default to ``("Long", "Lat")`` for a geographic
    ``crs`` — override with ``subset_axes`` if the server names its axes
    differently.

    A non-conformant shim may also reject the spec KVP spellings themselves: the
    Copernicus EDO/GDO MapServer ``500``s on the uppercase ``COVERAGEID`` key and
    on ``SUBSETTINGCRS=`` (it wants a lowercase ``coverageID`` and the WCS-1.x
    ``CRS=``). In direct mode ``extra_params`` can override a built-in KVP by key,
    so pass ``extra_params={"coverageID": <id>, "CRS": <crs>}`` to hand such a
    server its exact spelling — the override replaces the built-in rather than
    duplicating it.

    Args:
        endpoint: The WCS service URL, including any server-specific query
            prefix (e.g. ``"https://maps.isric.org/mapserv?map=/map/nitrogen.map"``).
            Catalog / coverage-name routing belongs in the calling layer, not
            here.
        coverage: The coverage identifier as advertised by
            ``GetCapabilities`` (e.g. ``"nitrogen_0-5cm_mean"``). A value the
            server does not advertise raises :class:`ValueError`.
        bbox: ``(minx, miny, maxx, maxy)`` in ``crs`` order (lon/lat for the
            default ``"EPSG:4326"``). ``minx > maxx`` reads as a window crossing
            the antimeridian, the same wrap :meth:`crop` accepts: it is fetched
            as two ``GetCoverage`` requests either side of the 180 degree seam
            and concatenated into one raster whose longitude runs on past it
            (``170 .. 180`` then ``180 .. 190``). Both halves are read off a
            single open connection, so they come from the same source lattice
            and stitch without resampling, and a half that misses the coverage
            is skipped rather than requested. ``output_crs``, ``resolution`` and
            ``output`` are applied once, to the merged raster. In ``direct``
            mode there is no shared connection: the halves are two separate
            ``GetCoverage`` requests, snapped to ``resolution`` so they land on
            one lattice. Pass a ``resolution`` for a wrapping ``direct`` read —
            without one nothing constrains the server to grid the two halves
            alike, and a mismatch is refused rather than stitched.
        crs: CRS of ``bbox``. Defaults to ``"EPSG:4326"``.
        output_crs: Optional CRS to reproject the result into (any form
            :meth:`to_crs` accepts). ``None`` (default) keeps the coverage's
            native CRS.
        resolution: Output pixel size in the units of ``output_crs`` (or the
            native CRS when ``output_crs`` is ``None``). A scalar gives square
            pixels; an ``(x_res, y_res)`` pair gives non-square pixels.
            ``None`` (default) keeps the coverage's native resolution.
        version: Force a WCS protocol version (``"1.0.0"``, ``"2.0.1"``, …).
            ``None`` (default) lets GDAL negotiate from the server's
            capabilities. Note that some MapServer builds silently downgrade a
            requested ``2.0.x`` to ``1.0.0``.
        coverage_crs: The coverage's CRS, used only when the server's
            advertised CRS does not resolve in PROJ (see the CRS-shim note).
            Any proj4 / WKT / authority string ``pyproj`` understands.
        wcs_format: Optional GDAL ``PreferredFormat`` for the ``GetCoverage``
            response (e.g. ``"GEOTIFF_INT16"``). ``None`` lets GDAL pick from
            the coverage's advertised formats.
        output: Optional path to also write the result to as a GeoTIFF. The
            method still returns the :class:`Dataset`.
        resample: Resampling method for the ``output_crs`` / ``resolution``
            warp. Defaults to ``"nearest"``.
        auth: Optional ``(username, password)`` for Basic-authed services.
        timeout: HTTP timeout in seconds for the metadata / coverage
            requests. Defaults to ``60.0``.
        extra_params: Optional extra ``GetCoverage`` query parameters folded
            into the request (a workaround hook for server quirks). In direct
            mode a key that matches a built-in KVP (case-insensitively, with the
            cross-version pairs ``CRS``/``SUBSETTINGCRS`` and
            ``COVERAGE``/``COVERAGEID`` each treated as one) *overrides* it with
            the given spelling and value — e.g. ``{"coverageID": "spaST"}`` sends
            a lowercase key, ``{"CRS": "EPSG:4326"}`` sends the WCS-1.x CRS token
            instead of ``SUBSETTINGCRS``. Non-matching keys are appended in caller
            order (e.g. a ``TIME`` axis). The fixed protocol keys ``SERVICE`` /
            ``VERSION`` / ``REQUEST`` / ``SUBSET`` cannot be overridden and raise
            :class:`ValueError`; because ``SUBSET`` is locked, an additional
            WCS-2.0 ``SUBSET`` axis (e.g. a temporal subset) cannot be added in
            direct mode — use discovery mode for that. Two keys targeting the
            same built-in parameter (e.g. both ``CRS`` and ``SUBSETTINGCRS``) also
            raise.
        direct: When ``True``, skip ``GetCapabilities``/``DescribeCoverage`` and
            issue a KVP ``GetCoverage`` directly — for shim servers that only
            implement ``GetCoverage``. Defaults to ``False`` (full handshake).
        subset_axes: Direct mode, WCS ``2.0.x`` only — the ``(x, y)`` ``SUBSET``
            axis labels. ``None`` (default) derives them from ``crs``
            (``("Long", "Lat")`` for geographic, ``("X", "Y")`` otherwise). These
            defaults are a best-effort guess — direct mode skips the
            ``DescribeCoverage`` that would reveal the coverage's real (case-
            sensitive) axis labels — so MapServer-family shims often need
            ``subset_axes=("x", "y")`` or the server's exact axis names.

    Returns:
        Dataset: The fetched coverage subset.

    Raises:
        ValueError: ``bbox`` is malformed — an inverted *latitude* range still
            counts, since there is no seam in latitude — ``coverage`` is not
            advertised (discovery mode), ``coverage_crs`` cannot be interpreted,
            the requested window exceeds the pixel ceiling
            (:data:`~pyramids.base._coverage.MAX_PX`; a native-resolution read
            over a wide ``bbox`` — pass a coarser ``resolution`` or a smaller
            ``bbox`` to bound it), or (direct mode) the WCS version is
            unsupported, ``1.0.0`` lacks a ``resolution``, or an ``extra_params``
            key targets a locked protocol parameter.
        pyramids.errors.WCSError: The server could not be reached or returned
            an error / a non-raster (``<ows:ExceptionReport>``) body.

    Examples:
        Read a Netherlands subset of SoilGrids nitrogen (its native CRS needs
        the ``coverage_crs`` shim):

        ```python
        >>> ds = Dataset.from_wcs(  # doctest: +SKIP
        ...     "https://maps.isric.org/mapserv?map=/map/nitrogen.map",
        ...     coverage="nitrogen_0-5cm_mean",
        ...     bbox=(5.0, 51.0, 6.0, 52.0),
        ...     coverage_crs="+proj=igh +lat_0=0 +lon_0=0 +datum=WGS84 +units=m +no_defs",
        ... )

        ```

        Direct mode for a ``GetCoverage``-only endpoint (Copernicus EDO/GDO),
        whose ``GetCapabilities``/``DescribeCoverage`` return ``502``/``400``.
        EDO also rejects the spec KVP spellings, so override the coverage key and
        CRS token via ``extra_params`` to send the lowercase ``coverageID`` and
        the WCS-1.x ``CRS=`` it accepts:

        ```python
        >>> ds = Dataset.from_wcs(  # doctest: +SKIP
        ...     "https://drought.emergency.copernicus.eu/api/wcs?map=DO_WCS",
        ...     coverage="spaST",
        ...     bbox=(10.0, 45.0, 15.0, 48.0),
        ...     crs="EPSG:4326",
        ...     version="2.0.0",
        ...     wcs_format="GEOTIFF",
        ...     direct=True,
        ...     extra_params={
        ...         "coverageID": "spaST",
        ...         "CRS": "EPSG:4326",
        ...         "TIME": "2023-06-01",
        ...         "SELECTED_TIMESCALE": "01",
        ...     },
        ... )

        ```

    See Also:
        - :meth:`read_file`: open a raster from a path or URL.
        - :meth:`from_bytes`: open a raster already held in memory.
    """
    return _from_wcs(
        cls,
        endpoint,
        coverage=coverage,
        bbox=bbox,
        crs=crs,
        output_crs=output_crs,
        resolution=resolution,
        version=version,
        coverage_crs=coverage_crs,
        wcs_format=wcs_format,
        output=output,
        resample=resample,
        auth=auth,
        timeout=timeout,
        extra_params=extra_params,
        direct=direct,
        subset_axes=subset_axes,
    )

from_wms(endpoint, *, layers, bbox, crs=_DEFAULT_CRS, size=None, resolution=None, image_format='image/png', version='1.3.0', bands=3, output_crs=None, output=None, resample='nearest', auth=None, timeout=60.0) classmethod

Render a WMS GetMap window into a :class:Dataset.

Fetches a server-rendered map image for bbox from an OGC Web Map Service via GDAL's native WMS driver, and returns it as a georeferenced raster. Because WMS renders in the requested crs, the bbox is the request window directly — no client-side reprojection is needed.

The result is rendered imagery (RGB / RGBA pixels), not data values: a WMS styles the data server-side. Use :meth:from_wcs / :meth:from_ogc_coverages when you need the underlying coverage values.

Parameters:

Name	Type	Description	Default
endpoint	str	The WMS base URL, ending with ? or & so GDAL can append the GetMap query (e.g. "https://ows.terrestris.de/osm/service?"). Layer catalogs and auth routing belong in the calling layer, not here.	required
layers	str | list[str] | tuple[str, ...]	One layer name, or several to composite, as advertised by the service GetCapabilities (joined with commas for the request).	required
bbox	tuple[float, float, float, float]	(minx, miny, maxx, maxy) in crs order (lon/lat for the default "EPSG:4326"). minx > maxx reads as a window crossing the antimeridian, the same wrap :meth:crop accepts: (170, -10, -170, 10) is the 20 degrees around Fiji, not the 340 the corners subtract to. It is served as two GetMap requests either side of the 180 degree seam and stitched into one raster whose longitude runs on past it (170 .. 180 then 180 .. 190); size is the width of the whole result, divided between the halves at one shared resolution so the pixel size does not change across the seam. Only a geographic crs has such a seam, so a wrapping bbox with a projected one is refused rather than read as inverted.	required
crs	str	CRS of bbox and of the rendered request. Defaults to "EPSG:4326" (GDAL handles the WMS 1.3.0 lat/lon axis order).	_DEFAULT_CRS
size	tuple[int, int] | None	Output image size (width, height) in pixels. Mutually exclusive with resolution; exactly one is required.	None
resolution	float | tuple[float, float] | None	Output pixel size in crs units — a scalar (square) or (x_res, y_res) pair — divided into the bbox extent to size the image. Mutually exclusive with size. The derived size is capped at :data:~pyramids.base._coverage.MAX_PX per axis; size itself is not, since a number the caller states cannot be amplified by a mistake in bbox the way a derived one can.	None
image_format	str	WMS FORMAT MIME type. Defaults to "image/png".	'image/png'
version	str	WMS protocol version. Defaults to "1.3.0".	'1.3.0'
bands	int	Number of bands to request (3 RGB, 4 RGBA). Defaults to 3.	3
output_crs	str | None	Optional CRS to reproject the result into (any form :meth:to_crs accepts). None keeps crs.	None
output	str | Path | None	Optional path to also write the result to as a GeoTIFF.	None
resample	str	Resampling method for the output_crs warp. Defaults to "nearest".	'nearest'
auth	tuple[str, str] | None	Optional (username, password) for Basic-authed services.	None
timeout	float	HTTP timeout in seconds. Defaults to 60.0.	60.0

Returns:

Name	Type	Description
Dataset	Dataset	The rendered map window.

Raises:

Type	Description
ValueError	bbox is malformed, layers is empty, size / resolution was not given exactly once, or resolution over this bbox exceeds :data:~pyramids.base._coverage.MAX_PX on either axis. A wrapping bbox is malformed when crs is projected, or when a corner falls outside -180 .. 180 and "west of the seam" stops meaning anything.
WMSError	The server could not be reached or returned a non-raster body.

Examples:

Render a small OSM window as a 512-px-wide PNG raster:

>>> ds = Dataset.from_wms(  # doctest: +SKIP
...     "https://ows.terrestris.de/osm/service?",
...     layers="OSM-WMS",
...     bbox=(5.0, 51.0, 6.0, 52.0),
...     size=(512, 512),
... )

See Also

• :meth:from_wmts: the tiled (WMTS) sibling.
• :meth:from_wcs: read coverage data values instead of imagery.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_wms(
    cls,
    endpoint: str,
    *,
    layers: str | list[str] | tuple[str, ...],
    bbox: tuple[float, float, float, float],
    crs: str = _DEFAULT_CRS,
    size: tuple[int, int] | None = None,
    resolution: float | tuple[float, float] | None = None,
    image_format: str = "image/png",
    version: str = "1.3.0",
    bands: int = 3,
    output_crs: str | None = None,
    output: str | Path | None = None,
    resample: str = "nearest",
    auth: tuple[str, str] | None = None,
    timeout: float = 60.0,
) -> Dataset:
    """Render a WMS ``GetMap`` window into a :class:`Dataset`.

    Fetches a server-rendered map image for ``bbox`` from an OGC Web Map
    Service via GDAL's native WMS driver, and returns it as a georeferenced
    raster. Because WMS renders in the requested ``crs``, the ``bbox`` is the
    request window directly — no client-side reprojection is needed.

    The result is **rendered imagery** (RGB / RGBA pixels), not data values: a
    WMS styles the data server-side. Use :meth:`from_wcs` /
    :meth:`from_ogc_coverages` when you need the underlying coverage values.

    Args:
        endpoint: The WMS base URL, ending with ``?`` or ``&`` so GDAL can
            append the ``GetMap`` query (e.g.
            ``"https://ows.terrestris.de/osm/service?"``). Layer catalogs and
            auth routing belong in the calling layer, not here.
        layers: One layer name, or several to composite, as advertised by the
            service ``GetCapabilities`` (joined with commas for the request).
        bbox: ``(minx, miny, maxx, maxy)`` in ``crs`` order (lon/lat for the
            default ``"EPSG:4326"``). ``minx > maxx`` reads as a window crossing
            the antimeridian, the same wrap :meth:`crop` accepts:
            ``(170, -10, -170, 10)`` is the 20 degrees around Fiji, not the 340
            the corners subtract to. It is served as two ``GetMap`` requests
            either side of the 180 degree seam and stitched into one raster whose
            longitude runs on past it (``170 .. 180`` then ``180 .. 190``);
            ``size`` is the width of the whole result, divided between the halves
            at one shared resolution so the pixel size does not change across the
            seam. Only a geographic ``crs`` has such a seam, so a wrapping bbox
            with a projected one is refused rather than read as inverted.
        crs: CRS of ``bbox`` and of the rendered request. Defaults to
            ``"EPSG:4326"`` (GDAL handles the WMS 1.3.0 lat/lon axis order).
        size: Output image size ``(width, height)`` in pixels. Mutually
            exclusive with ``resolution``; exactly one is required.
        resolution: Output pixel size in ``crs`` units — a scalar (square) or
            ``(x_res, y_res)`` pair — divided into the bbox extent to size the
            image. Mutually exclusive with ``size``. The derived size is capped
            at :data:`~pyramids.base._coverage.MAX_PX` per axis; ``size``
            itself is not, since a number the caller states cannot be amplified
            by a mistake in ``bbox`` the way a derived one can.
        image_format: WMS ``FORMAT`` MIME type. Defaults to ``"image/png"``.
        version: WMS protocol version. Defaults to ``"1.3.0"``.
        bands: Number of bands to request (``3`` RGB, ``4`` RGBA). Defaults to
            ``3``.
        output_crs: Optional CRS to reproject the result into (any form
            :meth:`to_crs` accepts). ``None`` keeps ``crs``.
        output: Optional path to also write the result to as a GeoTIFF.
        resample: Resampling method for the ``output_crs`` warp. Defaults to
            ``"nearest"``.
        auth: Optional ``(username, password)`` for Basic-authed services.
        timeout: HTTP timeout in seconds. Defaults to ``60.0``.

    Returns:
        Dataset: The rendered map window.

    Raises:
        ValueError: ``bbox`` is malformed, ``layers`` is empty, ``size`` /
            ``resolution`` was not given exactly once, or ``resolution`` over
            this ``bbox`` exceeds
            :data:`~pyramids.base._coverage.MAX_PX` on either axis. A wrapping
            ``bbox`` is malformed when ``crs`` is projected, or when a corner
            falls outside ``-180 .. 180`` and "west of the seam" stops meaning
            anything.
        pyramids.errors.WMSError: The server could not be reached or returned a
            non-raster body.

    Examples:
        Render a small OSM window as a 512-px-wide PNG raster:

        ```python
        >>> ds = Dataset.from_wms(  # doctest: +SKIP
        ...     "https://ows.terrestris.de/osm/service?",
        ...     layers="OSM-WMS",
        ...     bbox=(5.0, 51.0, 6.0, 52.0),
        ...     size=(512, 512),
        ... )

        ```

    See Also:
        - :meth:`from_wmts`: the tiled (WMTS) sibling.
        - :meth:`from_wcs`: read coverage *data values* instead of imagery.
    """
    return _from_wms(
        cls,
        endpoint,
        layers=layers,
        bbox=bbox,
        crs=crs,
        size=size,
        resolution=resolution,
        image_format=image_format,
        version=version,
        bands=bands,
        output_crs=output_crs,
        output=output,
        resample=resample,
        auth=auth,
        timeout=timeout,
    )

from_wmts(endpoint, *, layer, bbox, crs=_DEFAULT_CRS, tile_matrix_set=None, resolution=None, layer_crs=None, output_crs=None, output=None, resample='nearest', auth=None, timeout=60.0) classmethod

Crop a WMTS tile-pyramid layer to bbox into a :class:Dataset.

Opens a Web Map Tile Service layer as a full georeferenced tile pyramid via GDAL's native WMTS driver, then crops bbox out of it (reprojecting the bbox into the layer's native CRS with pyproj, mirroring :meth:from_wcs). The result is rendered imagery (RGB / RGBA), not data values.

Parameters:

Name	Type	Description	Default
endpoint	str	The WMTS GetCapabilities URL (e.g. "https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml").	required
layer	str	The layer identifier as advertised by the capabilities document. A value the service does not advertise raises :class:ValueError (with the available layers listed).	required
bbox	tuple[float, float, float, float]	(minx, miny, maxx, maxy) in crs order. minx > maxx reads as a window crossing the antimeridian and is read as two crops either side of the 180 degree seam, stitched into one raster whose longitude continues past it. The seam offset is measured in the layer's native CRS rather than assumed, so a layer tiled in Web Mercator crosses as cleanly as a lon/lat one; a wrapping bbox in a projected crs is still refused, since only lon/lat has the seam.	required
crs	str	CRS of bbox. Defaults to "EPSG:4326".	_DEFAULT_CRS
tile_matrix_set	str | None	Optional tile-matrix-set id to pin. None lets GDAL pick the layer's default.	None
resolution	float | tuple[float, float] | None	Output pixel size in the layer's native CRS units — GDAL reads from the matching overview level. None (default) uses the finest level, which can be very large for a wide bbox; pass resolution to coarsen a large area.	None
layer_crs	str | None	The layer's CRS, used only when the WMTS layer opens without a resolvable spatial reference (any proj4 / WKT / authority string).	None
output_crs	str | None	Optional CRS to reproject the result into. None keeps the layer's native CRS.	None
output	str | Path | None	Optional path to also write the result to as a GeoTIFF.	None
resample	str	Resampling method for the crop / warp. Defaults to "nearest".	'nearest'
auth	tuple[str, str] | None	Optional (username, password) for Basic-authed services.	None
timeout	float	HTTP timeout in seconds. Defaults to 60.0.	60.0

Returns:

Name	Type	Description
Dataset	Dataset	The cropped WMTS window.

Raises:

Type	Description
ValueError	bbox is malformed -- including a wrapping bbox with a projected crs or a corner outside -180 .. 180 -- layer is not advertised, layer_crs cannot be interpreted, or the requested window exceeds the pixel ceiling (:data:~pyramids.base._coverage.MAX_PX; a finest-level read over a wide bbox — pass a coarser resolution or a smaller bbox to bound it).
WMSError	The server could not be reached or the tile read failed.

Examples:

Crop a NASA GIBS true-colour window (coarsened to ~0.01° pixels):

>>> ds = Dataset.from_wmts(  # doctest: +SKIP
...     "https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml",
...     layer="MODIS_Terra_CorrectedReflectance_TrueColor",
...     bbox=(5.0, 51.0, 6.0, 52.0),
...     resolution=0.01,
... )

See Also

• :meth:from_wms: the untiled (WMS GetMap) sibling.
• :meth:from_wcs: read coverage data values instead of imagery.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_wmts(
    cls,
    endpoint: str,
    *,
    layer: str,
    bbox: tuple[float, float, float, float],
    crs: str = _DEFAULT_CRS,
    tile_matrix_set: str | None = None,
    resolution: float | tuple[float, float] | None = None,
    layer_crs: str | None = None,
    output_crs: str | None = None,
    output: str | Path | None = None,
    resample: str = "nearest",
    auth: tuple[str, str] | None = None,
    timeout: float = 60.0,
) -> Dataset:
    """Crop a WMTS tile-pyramid layer to ``bbox`` into a :class:`Dataset`.

    Opens a Web Map Tile Service layer as a full georeferenced tile pyramid
    via GDAL's native WMTS driver, then crops ``bbox`` out of it (reprojecting
    the bbox into the layer's native CRS with ``pyproj``, mirroring
    :meth:`from_wcs`). The result is **rendered imagery** (RGB / RGBA), not data
    values.

    Args:
        endpoint: The WMTS ``GetCapabilities`` URL (e.g.
            ``"https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml"``).
        layer: The layer identifier as advertised by the capabilities document.
            A value the service does not advertise raises :class:`ValueError`
            (with the available layers listed).
        bbox: ``(minx, miny, maxx, maxy)`` in ``crs`` order. ``minx > maxx``
            reads as a window crossing the antimeridian and is read as two crops
            either side of the 180 degree seam, stitched into one raster whose
            longitude continues past it. The seam offset is *measured* in the
            layer's native CRS rather than assumed, so a layer tiled in Web
            Mercator crosses as cleanly as a lon/lat one; a wrapping bbox in a
            projected ``crs`` is still refused, since only lon/lat has the seam.
        crs: CRS of ``bbox``. Defaults to ``"EPSG:4326"``.
        tile_matrix_set: Optional tile-matrix-set id to pin. ``None`` lets GDAL
            pick the layer's default.
        resolution: Output pixel size in the layer's native CRS units — GDAL
            reads from the matching overview level. ``None`` (default) uses the
            finest level, which can be **very large** for a wide bbox; pass
            ``resolution`` to coarsen a large area.
        layer_crs: The layer's CRS, used only when the WMTS layer opens without
            a resolvable spatial reference (any proj4 / WKT / authority string).
        output_crs: Optional CRS to reproject the result into. ``None`` keeps
            the layer's native CRS.
        output: Optional path to also write the result to as a GeoTIFF.
        resample: Resampling method for the crop / warp. Defaults to
            ``"nearest"``.
        auth: Optional ``(username, password)`` for Basic-authed services.
        timeout: HTTP timeout in seconds. Defaults to ``60.0``.

    Returns:
        Dataset: The cropped WMTS window.

    Raises:
        ValueError: ``bbox`` is malformed -- including a wrapping ``bbox`` with
            a projected ``crs`` or a corner outside ``-180 .. 180`` -- ``layer``
            is not advertised, ``layer_crs`` cannot be interpreted, or the
            requested window exceeds the pixel ceiling
            (:data:`~pyramids.base._coverage.MAX_PX`; a finest-level read over a
            wide ``bbox`` — pass a coarser ``resolution`` or a smaller ``bbox``
            to bound it).
        pyramids.errors.WMSError: The server could not be reached or the tile
            read failed.

    Examples:
        Crop a NASA GIBS true-colour window (coarsened to ~0.01° pixels):

        ```python
        >>> ds = Dataset.from_wmts(  # doctest: +SKIP
        ...     "https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/1.0.0/WMTSCapabilities.xml",
        ...     layer="MODIS_Terra_CorrectedReflectance_TrueColor",
        ...     bbox=(5.0, 51.0, 6.0, 52.0),
        ...     resolution=0.01,
        ... )

        ```

    See Also:
        - :meth:`from_wms`: the untiled (WMS ``GetMap``) sibling.
        - :meth:`from_wcs`: read coverage *data values* instead of imagery.
    """
    return _from_wmts(
        cls,
        endpoint,
        layer=layer,
        bbox=bbox,
        crs=crs,
        tile_matrix_set=tile_matrix_set,
        resolution=resolution,
        layer_crs=layer_crs,
        output_crs=output_crs,
        output=output,
        resample=resample,
        auth=auth,
        timeout=timeout,
    )

from_ogc_coverages(endpoint, *, coverage, bbox, output_crs=None, resolution=None, coverage_crs=None, output=None, resample='nearest', auth=None, timeout=60.0) classmethod

Read a coverage subset from an OGC API – Coverages service.

Fetches a windowed subset of a coverage from an OGC API – Coverages service and returns it as a :class:Dataset. OGC API – Coverages is the modern REST/JSON successor to WCS: a landing page links to /collections and each coverage exposes /collections/{id}/coverage with format negotiation. The transport is GDAL's native OGCAPI driver, so discovery, GeoTIFF negotiation and the windowed read happen inside GDAL; the caller supplies a single lon/lat bbox (plus optional resolution and output_crs). The driver exposes the coverage as an unbounded virtual raster, so the bbox is applied at read time as a native-CRS projWin window (not passed through as a service-side bbox subset). This is the OGC-API-era sibling of :meth:from_wcs.

A bbox is required. The driver exposes the coverage as an unbounded virtual raster, so a windowless read is impossible; pyramids projects the lon/lat bbox into the coverage's native CRS and reads it with an explicit output-size cap so the fetch always stays bounded.

The coverage is validated against a (cached) /collections document so an unadvertised coverage fails fast with a clear :class:ValueError rather than an opaque driver error.

Parameters:

Name	Type	Description	Default
endpoint	str	The OGC API landing-page / base URL (e.g. "https://maps.gnosis.earth/ogcapi"). Catalog / coverage-name routing belongs in the calling layer, not here.	required
coverage	str	The coverage identifier as advertised by /collections (e.g. "SRTM_ViewFinderPanorama"). A value the service does not advertise raises :class:ValueError.	required
bbox	tuple[float, float, float, float]	Required (minx, miny, maxx, maxy) spatial subset in lon/lat (CRS84). It is projected into the coverage's native CRS and read as a bounded, size-capped window; an unbounded full read is not supported (the virtual raster spans the whole coverage). minx > maxx reads as a subset crossing the antimeridian, as in :meth:from_wcs, and is read as two windows either side of the 180 degree seam. With no resolution the two are sized together — the combined span is capped once and the resulting pixel size applied to both — because sizing each half against the cap on its own gives them different pixel sizes and row counts, which cannot be concatenated at all.	required
output_crs	str | None	Optional CRS to reproject the result into (any form :meth:to_crs accepts). None (default) keeps the coverage's native CRS.	None
resolution	float | tuple[float, float] | None	Approximate pixel size of the read window, in the units of the coverage's native CRS (CRS84 degrees by default). A scalar gives square pixels; an (x_res, y_res) pair gives non-square pixels; every axis must be strictly positive (:class:ValueError otherwise). The window size is round(span / resolution) per axis, so the realised cell size equals resolution exactly only when span / resolution is integral and is otherwise the nearest whole-pixel fit. None (default) caps the longer side of the window at 1024 px (preserving the bbox aspect ratio). A window larger than 25000 px on either side is rejected with :class:ValueError. When output_crs is set, resolution sizes the native-CRS read; the reprojected output's pixel size is then chosen by the warp.	None
coverage_crs	str | None	The coverage's CRS, used only when the service's advertised CRS does not resolve in PROJ so GDAL opens the coverage with no spatial reference. Any proj4 / WKT / authority string pyproj understands. None (default) relies on the CRS the service advertises. Mirrors :meth:from_wcs.	None
output	str | Path | None	Optional path to also write the result to as a GeoTIFF. The method still returns the :class:Dataset.	None
resample	str	Resampling method for the output_crs reprojection. Defaults to "nearest".	'nearest'
auth	tuple[str, str] | None	Optional (username, password) for Basic-authed services.	None
timeout	float	HTTP timeout in seconds for the metadata / coverage requests (whole seconds; a value below 1 is clamped to 1). Defaults to 60.0.	60.0

Returns:

Name	Type	Description
Dataset	Dataset	The fetched coverage subset.

Raises:

Type	Description
ValueError	bbox is malformed — an inverted latitude range still counts, since there is no seam in latitude — coverage is not advertised, or coverage_crs cannot be interpreted.
OGCAPIError	The service could not be reached or returned an error / a non-raster body.

Examples:

Read a small bbox subset of a public coverage (network call — skipped in doctests):

>>> ds = Dataset.from_ogc_coverages(  # doctest: +SKIP
...     "https://maps.gnosis.earth/ogcapi",
...     coverage="SRTM_ViewFinderPanorama",
...     bbox=(5.0, 51.0, 6.0, 52.0),
... )

See Also

• :meth:from_wcs: the classic WCS sibling.
• :meth:pyramids.feature.FeatureCollection.from_ogc_features: the OGC API – Features (vector) sibling.
• :meth:read_file: open a raster from a path or URL.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_ogc_coverages(
    cls,
    endpoint: str,
    *,
    coverage: str,
    bbox: tuple[float, float, float, float],
    output_crs: str | None = None,
    resolution: float | tuple[float, float] | None = None,
    coverage_crs: str | None = None,
    output: str | Path | None = None,
    resample: str = "nearest",
    auth: tuple[str, str] | None = None,
    timeout: float = 60.0,
) -> Dataset:
    """Read a coverage subset from an **OGC API – Coverages** service.

    Fetches a windowed subset of a coverage from an OGC API – Coverages
    service and returns it as a :class:`Dataset`. OGC API – Coverages is the
    modern REST/JSON successor to WCS: a landing page links to
    ``/collections`` and each coverage exposes ``/collections/{id}/coverage``
    with format negotiation. The transport is GDAL's native ``OGCAPI`` driver,
    so discovery, GeoTIFF negotiation and the windowed read happen inside GDAL;
    the caller supplies a single lon/lat ``bbox`` (plus optional ``resolution``
    and ``output_crs``). The driver exposes the coverage as an unbounded virtual
    raster, so the ``bbox`` is applied at read time as a native-CRS ``projWin``
    window (not passed through as a service-side ``bbox`` subset). This is the
    OGC-API-era sibling of :meth:`from_wcs`.

    A ``bbox`` is **required**. The driver exposes the coverage as an unbounded
    virtual raster, so a windowless read is impossible; pyramids projects the
    lon/lat ``bbox`` into the coverage's native CRS and reads it with an
    explicit output-size cap so the fetch always stays bounded.

    The ``coverage`` is validated against a (cached) ``/collections`` document
    so an unadvertised coverage fails fast with a clear :class:`ValueError`
    rather than an opaque driver error.

    Args:
        endpoint: The OGC API landing-page / base URL (e.g.
            ``"https://maps.gnosis.earth/ogcapi"``). Catalog / coverage-name
            routing belongs in the calling layer, not here.
        coverage: The coverage identifier as advertised by ``/collections``
            (e.g. ``"SRTM_ViewFinderPanorama"``). A value the service does not
            advertise raises :class:`ValueError`.
        bbox: **Required** ``(minx, miny, maxx, maxy)`` spatial subset in
            **lon/lat (CRS84)**. It is projected into the coverage's native CRS
            and read as a bounded, size-capped window; an unbounded full read is
            not supported (the virtual raster spans the whole coverage).
            ``minx > maxx`` reads as a subset crossing the antimeridian, as in
            :meth:`from_wcs`, and is read as two windows either side of the 180
            degree seam. With no ``resolution`` the two are sized *together* —
            the combined span is capped once and the resulting pixel size
            applied to both — because sizing each half against the cap on its
            own gives them different pixel sizes and row counts, which cannot be
            concatenated at all.
        output_crs: Optional CRS to reproject the result into (any form
            :meth:`to_crs` accepts). ``None`` (default) keeps the coverage's
            native CRS.
        resolution: Approximate pixel size of the read window, in the units of
            the coverage's **native CRS** (CRS84 degrees by default). A scalar
            gives square pixels; an ``(x_res, y_res)`` pair gives non-square
            pixels; every axis must be strictly positive (:class:`ValueError`
            otherwise). The window size is ``round(span / resolution)`` per
            axis, so the realised cell size equals ``resolution`` exactly only
            when ``span / resolution`` is integral and is otherwise the nearest
            whole-pixel fit. ``None`` (default) caps the longer side of the
            window at 1024 px (preserving the bbox aspect ratio). A window
            larger than 25000 px on either side is rejected with
            :class:`ValueError`. When ``output_crs`` is set, ``resolution``
            sizes the native-CRS read; the reprojected output's pixel size is
            then chosen by the warp.
        coverage_crs: The coverage's CRS, used only when the service's
            advertised CRS does not resolve in PROJ so GDAL opens the coverage
            with no spatial reference. Any proj4 / WKT / authority string
            ``pyproj`` understands. ``None`` (default) relies on the CRS the
            service advertises. Mirrors :meth:`from_wcs`.
        output: Optional path to also write the result to as a GeoTIFF. The
            method still returns the :class:`Dataset`.
        resample: Resampling method for the ``output_crs`` reprojection.
            Defaults to ``"nearest"``.
        auth: Optional ``(username, password)`` for Basic-authed services.
        timeout: HTTP timeout in seconds for the metadata / coverage requests
            (whole seconds; a value below 1 is clamped to 1). Defaults to
            ``60.0``.

    Returns:
        Dataset: The fetched coverage subset.

    Raises:
        ValueError: ``bbox`` is malformed — an inverted *latitude* range
            still counts, since there is no seam in latitude — ``coverage`` is
            not advertised, or ``coverage_crs`` cannot be interpreted.
        pyramids.errors.OGCAPIError: The service could not be reached or
            returned an error / a non-raster body.

    Examples:
        Read a small bbox subset of a public coverage (network call — skipped
        in doctests):

        ```python
        >>> ds = Dataset.from_ogc_coverages(  # doctest: +SKIP
        ...     "https://maps.gnosis.earth/ogcapi",
        ...     coverage="SRTM_ViewFinderPanorama",
        ...     bbox=(5.0, 51.0, 6.0, 52.0),
        ... )

        ```

    See Also:
        - :meth:`from_wcs`: the classic WCS sibling.
        - :meth:`pyramids.feature.FeatureCollection.from_ogc_features`: the OGC
          API – Features (vector) sibling.
        - :meth:`read_file`: open a raster from a path or URL.
    """
    return _from_ogc_coverages(
        cls,
        endpoint,
        coverage=coverage,
        bbox=bbox,
        output_crs=output_crs,
        resolution=resolution,
        coverage_crs=coverage_crs,
        output=output,
        resample=resample,
        auth=auth,
        timeout=timeout,
    )

copy(path=None)

Deep copy.

Parameters:

Name	Type	Description	Default
path	str	Destination for the copy. None (default) copies into memory with the MEM driver. Otherwise the extension alone selects the output format (.tif -> GTiff, .nc -> netCDF, .png -> PNG, …), so copy doubles as a format conversion and is not GeoTIFF-only. The copy is made with CreateCopy, so a write-by-copy-only format such as PNG or JPEG is accepted here even though the Create-based constructors (from_array, create_empty) refuse it.	None

Returns:

Name	Type	Description
Dataset	Dataset	An independent copy. Access mode of the returned
Dataset	Dataset
	Dataset	path is None (in-memory copy) → "write". The copy is a fresh MEM raster that nothing else references, so refusing writes on it protects nothing: the source file is untouched either way. Propagating the source's mode instead meant a copy() taken specifically to get a mutable working copy of a read-only file could not be written to, and the resulting ReadOnlyError advised reopening the source with read_only=False, which is not what the caller wanted.
	Dataset	path is not None and the format supports Create (GTiff, netCDF, HFA, …) → "write", because the caller has just made a new file they presumably want to populate.
	Dataset	path is not None and the format is write-by-copy only (.png, .jpg / .jpeg, .jp2 / .j2k, .asc) → "read_only". CreateCopy hands back a read-only dataset for those, so claiming otherwise would let a write fail inside GDAL instead of raising :class:~pyramids.errors.ReadOnlyError here.

Raises:

Type	Description
DriverNotExistError	path has no extension, or one the driver catalog does not know.
FileFormatNotSupportedError	path names a format that writes a reference rather than a self-contained raster (.vrt), which would produce a file GDAL cannot reopen.

Examples:

• Copy into memory and edit the copy without touching the source:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> src = Dataset.from_array(
  ...     np.zeros((3, 4), dtype="int16"),
  ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
  ... )
  >>> clone = src.copy()
  >>> clone.write_array(np.full((3, 4), 7, dtype="int16"))
  >>> int(clone.read_array().max()), int(src.read_array().max())
  (7, 0)
  

• The destination extension picks the format, so a copy can convert:

  >>> import os, tempfile
  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> src = Dataset.from_array(
  ...     np.arange(12, dtype="uint8").reshape(3, 4),
  ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
  ...     no_data_value=None,
  ... )
  >>> out = os.path.join(tempfile.mkdtemp(), "converted.png")
  >>> png = src.copy(out)
  >>> png.raster.GetDriver().ShortName
  'PNG'
  >>> png.close()
  

Source code in src/pyramids/dataset/dataset.py

def copy(self, path: str | Path | None = None) -> Dataset:
    """Deep copy.

    Args:
        path (str, optional):
            Destination for the copy. `None` (default) copies into memory
            with the `MEM` driver. Otherwise the extension alone selects
            the output format (`.tif` -> GTiff, `.nc` -> netCDF,
            `.png` -> PNG, …), so `copy` doubles as a format conversion
            and is not GeoTIFF-only. The copy is made with `CreateCopy`,
            so a write-by-copy-only format such as PNG or JPEG is accepted
            here even though the `Create`-based constructors
            (`from_array`, `create_empty`) refuse it.

    Returns:
        Dataset: An independent copy. Access mode of the returned
        Dataset:

        * `path is None` (in-memory copy) → `"write"`. The copy is a
          fresh MEM raster that nothing else references, so refusing
          writes on it protects nothing: the source file is untouched
          either way. Propagating the source's mode instead meant a
          `copy()` taken specifically to get a mutable working copy of
          a read-only file could not be written to, and the resulting
          `ReadOnlyError` advised reopening the *source* with
          `read_only=False`, which is not what the caller wanted.
        * `path is not None` and the format supports `Create`
          (GTiff, netCDF, HFA, …) → `"write"`, because the caller
          has just made a new file they presumably want to
          populate.
        * `path is not None` and the format is write-by-copy only
          (`.png`, `.jpg` / `.jpeg`, `.jp2` / `.j2k`, `.asc`) →
          `"read_only"`. `CreateCopy` hands back a read-only
          dataset for those, so claiming otherwise would let a
          write fail inside GDAL instead of raising
          :class:`~pyramids.errors.ReadOnlyError` here.

    Raises:
        DriverNotExistError: `path` has no extension, or one the driver
            catalog does not know.
        FileFormatNotSupportedError: `path` names a format that writes a
            reference rather than a self-contained raster (`.vrt`), which
            would produce a file GDAL cannot reopen.

    Examples:
        - Copy into memory and edit the copy without touching the source:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> src = Dataset.from_array(
            ...     np.zeros((3, 4), dtype="int16"),
            ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
            ... )
            >>> clone = src.copy()
            >>> clone.write_array(np.full((3, 4), 7, dtype="int16"))
            >>> int(clone.read_array().max()), int(src.read_array().max())
            (7, 0)

            ```
        - The destination extension picks the format, so a copy can convert:
            ```python
            >>> import os, tempfile
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> src = Dataset.from_array(
            ...     np.arange(12, dtype="uint8").reshape(3, 4),
            ...     geo_ref=GeoReference(top_left_corner=(0, 0), cell_size=1.0, epsg=4326),
            ...     no_data_value=None,
            ... )
            >>> out = os.path.join(tempfile.mkdtemp(), "converted.png")
            >>> png = src.copy(out)
            >>> png.raster.GetDriver().ShortName
            'PNG'
            >>> png.close()

            ```
    """
    if path is None:
        path = ""
        driver = MEMORY_DRIVER
        # A MEM copy is a fresh buffer nothing else holds, so it is always
        # writable. Carrying the source's read-only flag over made the copy
        # useless for the case it exists to serve: getting a mutable working
        # copy of a read-only file.
        new_access = "write"
    else:
        # From the extension, not hardcoded: `copy(path="x.nc")` produced a
        # GTiff carrying a netCDF name. `for_copy` because this writes
        # with CreateCopy, which copy-only formats support.
        driver = resolve_output_driver(path, for_copy=True)
        # A copy-only driver returns a read-only handle, so claiming
        # "write" here meant `write_array` leaked a raw GDAL error past
        # the package's own ReadOnlyError guard.
        new_access = "write" if copy_yields_writable(driver) else "read_only"

    src = gdal.GetDriverByName(driver).CreateCopy(str(path), self._raster)
    return Dataset(src, access=new_access)

close()

Close the dataset.

Safe to call multiple times — subsequent calls after the first are no-ops.

Also releases the per-thread file manager created by read_array(threadsafe=True): the calling thread's handle is closed eagerly and the manager reference is dropped, so handles held by other (finished) threads are released with it. Without this, lingering read-only handles would keep the file locked on Windows after close().

Source code in src/pyramids/dataset/dataset.py

def close(self) -> None:
    """Close the dataset.

    Safe to call multiple times — subsequent calls after the first are no-ops.

    Also releases the per-thread file manager created by
    ``read_array(threadsafe=True)``: the calling thread's handle is
    closed eagerly and the manager reference is dropped, so handles
    held by other (finished) threads are released with it. Without
    this, lingering read-only handles would keep the file locked on
    Windows after ``close()``.
    """
    if self._raster is not None:
        self._raster.FlushCache()
        self._raster = None
    manager = getattr(self, "_thread_manager", None)
    if manager is not None:
        manager.close()
        self._thread_manager = None

create(rows, columns, dtype, bands, *, geo_ref, no_data_value=None, path=None) classmethod

Create a new dataset, optionally filled with the no_data_value.

With a no_data_value the sentinel is stamped on every band and the array is filled with it. The parameter defaults to None, which stamps no sentinel and performs no fill -- the bands read back as whatever the driver allocates (0 for GTiff). Pass one explicitly to get a filled raster, as :meth:create_empty documents for the same opt-out.

Parameters:

Name	Type	Description	Default
rows	int	Number of rows.	required
columns	int	Number of columns.	required
dtype	str	Data type.	required
bands	int	Number of bands to create in the output raster. Required.	required
geo_ref	GeoReference	How the array maps to space — an affine geo transform, or a top_left_corner + cell_size, plus the epsg. Required; a raster has to be placed somewhere. Note the CRS is not: epsg defaults to 4326, so a reference that omits it stamps WGS 84 rather than refusing. This method previously took a required epsg and raised TypeError when it was missing — pass epsg explicitly, or epsg=None for a deliberately CRS-less raster.	required
no_data_value	float | None	No data value.	None
path	str	Destination, which alone decides the driver. None (default) builds the raster in memory; otherwise the extension selects the format (.tif -> GTiff, .nc -> netCDF, …).	None

Returns:

Name	Type	Description
Dataset	Dataset	A new dataset

Raises:

Type	Description
ValueError	geo_ref carries neither a geo nor a complete top_left_corner + cell_size pair.
DriverNotExistError	path has no extension, or one the driver catalog does not know.
FileFormatNotSupportedError	path's extension maps to a write-by-copy-only format such as PNG, which cannot be built with Create.

Examples:

• Create a filled in-memory raster and read a cell back:

  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.create(
  ...     3, 4, "float32", 1,
  ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 3.0, 0.0, -1.0)),
  ...     no_data_value=-9999.0,
  ... )
  >>> (ds.rows, ds.columns, ds.band_count)
  (3, 4, 1)
  >>> float(ds.read_array()[0, 0])
  -9999.0
  

• Place it with a corner and a cell size instead of a transform:

  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.create(
  ...     2, 2, "int16", 1,
  ...     geo_ref=GeoReference(
  ...         top_left_corner=(10.0, 50.0), cell_size=0.5, epsg=4326
  ...     ),
  ... )
  >>> tuple(ds.geotransform)
  (10.0, 0.5, 0.0, 50.0, 0.0, -0.5)
  >>> ds.epsg
  4326
  

See Also

• :meth:create_empty: Allocate the header only, without filling every cell — the out-of-core sibling of this method.
• :meth:from_array: Build a raster around an array you already have.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def create(
    cls,
    rows: int,
    columns: int,
    dtype: str,
    bands: int,
    *,
    geo_ref: GeoReference,
    no_data_value: Any | None = None,
    path: str | Path | None = None,
) -> Dataset:
    """Create a new dataset, optionally filled with the no_data_value.

    With a `no_data_value` the sentinel is stamped on every band and the
    array is filled with it. The parameter defaults to `None`, which stamps
    no sentinel and performs no fill -- the bands read back as whatever the
    driver allocates (0 for GTiff). Pass one explicitly to get a filled
    raster, as :meth:`create_empty` documents for the same opt-out.

    Args:
        rows (int):
            Number of rows.
        columns (int):
            Number of columns.
        dtype (str):
            Data type.
        bands (int):
            Number of bands to create in the output raster. Required.
        geo_ref (GeoReference):
            How the array maps to space — an affine ``geo`` transform, or a
            ``top_left_corner`` + ``cell_size``, plus the ``epsg``. Required;
            a raster has to be placed somewhere. Note the CRS is not:
            ``epsg`` defaults to 4326, so a reference that omits it stamps
            WGS 84 rather than refusing. This method previously took a
            **required** ``epsg`` and raised ``TypeError`` when it was
            missing — pass ``epsg`` explicitly, or ``epsg=None`` for a
            deliberately CRS-less raster.
        no_data_value (float|None):
            No data value.
        path (str, optional):
            Destination, which alone decides the driver. `None` (default)
            builds the raster in memory; otherwise the extension selects the
            format (``.tif`` -> GTiff, ``.nc`` -> netCDF, …).

    Returns:
        Dataset: A new dataset

    Raises:
        ValueError: `geo_ref` carries neither a ``geo`` nor a complete
            ``top_left_corner`` + ``cell_size`` pair.
        DriverNotExistError: `path` has no extension, or one the driver
            catalog does not know.
        FileFormatNotSupportedError: `path`'s extension maps to a
            write-by-copy-only format such as PNG, which cannot be built
            with ``Create``.

    Examples:
        - Create a filled in-memory raster and read a cell back:
            ```python
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.create(
            ...     3, 4, "float32", 1,
            ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 3.0, 0.0, -1.0)),
            ...     no_data_value=-9999.0,
            ... )
            >>> (ds.rows, ds.columns, ds.band_count)
            (3, 4, 1)
            >>> float(ds.read_array()[0, 0])
            -9999.0

            ```
        - Place it with a corner and a cell size instead of a transform:
            ```python
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.create(
            ...     2, 2, "int16", 1,
            ...     geo_ref=GeoReference(
            ...         top_left_corner=(10.0, 50.0), cell_size=0.5, epsg=4326
            ...     ),
            ... )
            >>> tuple(ds.geotransform)
            (10.0, 0.5, 0.0, 50.0, 0.0, -0.5)
            >>> ds.epsg
            4326

            ```

    See Also:
        - :meth:`create_empty`: Allocate the header only, without filling
          every cell — the out-of-core sibling of this method.
        - :meth:`from_array`: Build a raster around an array you already
          have.
    """
    gdal_dtype = numpy_to_gdal_dtype(dtype)
    crs_wkt = _crs_wkt_from_epsg(geo_ref.epsg)
    geotransform = geo_ref.resolve_geotransform()
    return cls._build_dataset(
        columns,
        rows,
        bands,
        gdal_dtype,
        geotransform,
        crs_wkt,
        no_data_value,
        path=path,
    )

create_empty(rows, cols, *, bands=1, dtype='float32', geo_ref=None, no_data_value=DEFAULT_NO_DATA_VALUE, path=None, options=None) classmethod

Allocate an empty, header-only raster without materialising a full array.

Out-of-core algorithms allocate the output once and scatter result windows into it with write_array(array, window=Window(col_off, row_off, cols, rows)) (see :class:~pyramids.dataset.window.Window). With a .tif path the file is tiled, sparse, and BigTIFF (see :data:OUT_OF_CORE_CREATION_OPTIONS), so a 50 000 x 50 000 float32 raster is created in O(1) RAM, never-written blocks cost no disk, and writes past the 4 GB classic-TIFF ceiling succeed. A never-written cell reads back as no_data_value (not 0) — on GTiff because SPARSE_OK + the band no-data sentinel returns no-data for unwritten blocks, and on MEM because the band is filled with the no-data value at allocation — so downstream code must treat unwritten tiles as no-data.

Parameters:

Name	Type	Description	Default
rows	int	Number of rows of the output raster.	required
cols	int	Number of columns of the output raster.	required
bands	int	Number of bands. Default 1.	1
dtype	str	NumPy dtype name for the bands (e.g. "float32", "int16"). Default "float32".	'float32'
geo_ref	GeoReference | None	How the raster maps to space — an affine geo transform, or a top_left_corner + cell_size, plus the epsg. Unlike the other constructors this one is optional: a header-only allocation often does not care where it sits, so None (default) — or a reference carrying no transform at all, such as GeoReference(epsg=3857) — keeps the identity transform (0.0, 1.0, 0.0, 0.0, 0.0, -1.0), a unit-pixel grid with the origin at (0, 0). A partially specified reference is not covered by that convenience: a top_left_corner without a cell_size (or the reverse) raises, exactly as it does in :meth:from_array and :meth:create, rather than silently discarding the half that was supplied.	None
no_data_value	Any	No-data sentinel stamped on every band at creation. Default :data:DEFAULT_NO_DATA_VALUE. Keep it set so sparse unwritten blocks read back as no-data rather than 0. Passing None skips the band fill and stamps no sentinel, which opts out of that guarantee — a sparse GTiff's unwritten blocks then read back as 0, not no-data. A path that resolves to GTiff emits a :class:NoDataSentinelWarning; the in-RAM "MEM" driver is dense, and the other disk drivers are not sparse, so neither warns.	DEFAULT_NO_DATA_VALUE
path	str | Path | None	Destination, which alone decides the driver. None (default) builds an in-memory "MEM" raster; otherwise the extension selects the format (.tif -> GTiff). The sparse / tiled / BigTIFF defaults below apply only when the path resolves to GTiff.	None
options	list[str] | None	GDAL creation options. None (default) uses :data:OUT_OF_CORE_CREATION_OPTIONS for GTiff. Override to align BLOCKXSIZE / BLOCKYSIZE to your tile size or to change compression. Forwarded to whichever disk driver the extension selects — only the default set is GTiff-specific; passing options without a path raises rather than silently dropping them.	None

Returns:

Name	Type	Description
Dataset	Dataset	An empty raster whose bands read back as no_data_value
	Dataset	before any write. On GTiff this is sparse — SPARSE_OK keeps
	Dataset	never-written blocks unallocated and GDAL returns the no-data
	Dataset	sentinel for them; on MEM every band is filled with no_data_value
	Dataset	at allocation, so unwritten MEM cells read back as no-data too.

Raises:

Type	Description
ValueError	options is given without a path — creation options apply only to a disk driver, so accepting them for an in-memory raster would silently drop them; or geo_ref is partially specified (one half of the top_left_corner / cell_size pair).
DriverNotExistError	path has an extension the driver catalog does not know.
FileFormatNotSupportedError	path's extension maps to a write-by-copy-only format, which cannot be allocated with Create.

Examples:

• Allocate an in-memory empty raster and read its no-data metadata:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset
  >>> ds = Dataset.create_empty(
  ...     4, 5, dtype="float32", no_data_value=-9999.0
  ... )
  >>> (ds.rows, ds.columns, ds.band_count)
  (4, 5, 1)
  >>> float(ds.no_data_value[0])
  -9999.0
  

• Allocate, then scatter a window into it and read it back:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset
  >>> from pyramids.dataset import Window
  >>> ds = Dataset.create_empty(4, 4, dtype="float32")
  >>> block = np.arange(4, dtype="float32").reshape(2, 2)
  >>> ds.write_array(block, window=Window(1, 1, 2, 2))
  >>> ds.read_array(window=[1, 1, 2, 2]).tolist()
  [[0.0, 1.0], [2.0, 3.0]]
  

See Also

• :meth:empty_like: Allocate an empty raster shaped like an existing template instead of from explicit dimensions.
• :meth:create: Allocate a raster and eagerly fill every cell with the no-data value (no sparse / BigTIFF defaults).
• :meth:write_array: Scatter a window into the allocated raster (window=(row_off, col_off, n_rows, n_cols)).

Source code in src/pyramids/dataset/dataset.py

@classmethod
def create_empty(
    cls,
    rows: int,
    cols: int,
    *,
    bands: int = 1,
    dtype: str = "float32",
    geo_ref: GeoReference | None = None,
    no_data_value: Any = DEFAULT_NO_DATA_VALUE,
    path: str | Path | None = None,
    options: list[str] | None = None,
) -> Dataset:
    """Allocate an empty, header-only raster without materialising a full array.

    Out-of-core algorithms allocate the output once and scatter result
    windows into it with
    ``write_array(array, window=Window(col_off, row_off, cols, rows))``
    (see :class:`~pyramids.dataset.window.Window`).
    With a ``.tif`` path the file is **tiled, sparse,
    and BigTIFF** (see :data:`OUT_OF_CORE_CREATION_OPTIONS`), so a
    50 000 x 50 000 float32 raster is created in O(1) RAM, never-written
    blocks cost no disk, and writes past the 4 GB classic-TIFF ceiling
    succeed. A never-written cell reads back as ``no_data_value`` (not 0) —
    on GTiff because SPARSE_OK + the band no-data sentinel returns no-data
    for unwritten blocks, and on MEM because the band is filled with the
    no-data value at allocation — so downstream code must treat unwritten
    tiles as no-data.

    Args:
        rows: Number of rows of the output raster.
        cols: Number of columns of the output raster.
        bands: Number of bands. Default 1.
        dtype: NumPy dtype name for the bands (e.g. ``"float32"``,
            ``"int16"``). Default ``"float32"``.
        geo_ref: How the raster maps to space — an affine ``geo``
            transform, or a ``top_left_corner`` + ``cell_size``, plus the
            ``epsg``. Unlike the other constructors this one is optional:
            a header-only allocation often does not care where it sits, so
            `None` (default) — or a reference carrying *no* transform at
            all, such as ``GeoReference(epsg=3857)`` — keeps the identity
            transform ``(0.0, 1.0, 0.0, 0.0, 0.0, -1.0)``, a unit-pixel
            grid with the origin at ``(0, 0)``. A **partially** specified
            reference is not covered by that convenience: a
            ``top_left_corner`` without a ``cell_size`` (or the reverse)
            raises, exactly as it does in :meth:`from_array` and
            :meth:`create`, rather than silently discarding the half that
            was supplied.
        no_data_value: No-data sentinel stamped on every band at
            creation. Default :data:`DEFAULT_NO_DATA_VALUE`. Keep it set
            so sparse unwritten blocks read back as no-data rather than 0.
            Passing ``None`` skips the band fill and stamps no sentinel,
            which opts out of that guarantee — a sparse GTiff's unwritten
            blocks then read back as **0**, not no-data. A path that
            resolves to GTiff emits a :class:`NoDataSentinelWarning`;
            the in-RAM ``"MEM"`` driver is dense, and the other disk
            drivers are not sparse, so neither warns.
        path: Destination, which alone decides the driver. `None`
            (default) builds an in-memory ``"MEM"`` raster; otherwise the
            extension selects the format (``.tif`` -> GTiff). The sparse /
            tiled / BigTIFF defaults below apply only when the path
            resolves to GTiff.
        options: GDAL creation options. `None` (default) uses
            :data:`OUT_OF_CORE_CREATION_OPTIONS` for GTiff. Override to
            align ``BLOCKXSIZE`` / ``BLOCKYSIZE`` to your tile size or to
            change compression. Forwarded to whichever disk driver the
            extension selects — only the *default* set is GTiff-specific;
            passing `options` without a `path` raises rather than silently
            dropping them.

    Returns:
        Dataset: An empty raster whose bands read back as `no_data_value`
        before any write. On GTiff this is sparse — SPARSE_OK keeps
        never-written blocks unallocated and GDAL returns the no-data
        sentinel for them; on MEM every band is filled with `no_data_value`
        at allocation, so unwritten MEM cells read back as no-data too.

    Raises:
        ValueError: ``options`` is given without a ``path`` — creation
            options apply only to a disk driver, so accepting them for an
            in-memory raster would silently drop them; or `geo_ref` is
            partially specified (one half of the
            ``top_left_corner`` / ``cell_size`` pair).
        DriverNotExistError: ``path`` has an extension the driver catalog
            does not know.
        FileFormatNotSupportedError: ``path``'s extension maps to a
            write-by-copy-only format, which cannot be allocated with
            ``Create``.

    Examples:
        - Allocate an in-memory empty raster and read its no-data metadata:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset
            >>> ds = Dataset.create_empty(
            ...     4, 5, dtype="float32", no_data_value=-9999.0
            ... )
            >>> (ds.rows, ds.columns, ds.band_count)
            (4, 5, 1)
            >>> float(ds.no_data_value[0])
            -9999.0

            ```
        - Allocate, then scatter a window into it and read it back:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset
            >>> from pyramids.dataset import Window
            >>> ds = Dataset.create_empty(4, 4, dtype="float32")
            >>> block = np.arange(4, dtype="float32").reshape(2, 2)
            >>> ds.write_array(block, window=Window(1, 1, 2, 2))
            >>> ds.read_array(window=[1, 1, 2, 2]).tolist()
            [[0.0, 1.0], [2.0, 3.0]]

            ```

    See Also:
        - :meth:`empty_like`: Allocate an empty raster shaped like an
          existing template instead of from explicit dimensions.
        - :meth:`create`: Allocate a raster and eagerly fill every cell
          with the no-data value (no sparse / BigTIFF defaults).
        - :meth:`write_array`: Scatter a window into the allocated raster
          (``window=(row_off, col_off, n_rows, n_cols)``).
    """
    # The old "GTiff without a path" guard is gone: that combination is now
    # unrepresentable, because the driver comes from the path.
    # Creation options apply only to a disk driver (path given); the MEM
    # driver takes none. Reject explicit options that would be dropped
    # rather than silently ignoring them.
    if options is not None and path is None:
        raise ValueError(
            "create_empty received `options` but no `path`: GDAL creation "
            "options apply only to a disk driver. Pass a `path`, or drop "
            "`options` for the in-memory MEM raster."
        )
    # Only a sparse GTiff can read back 0 instead of no-data for a block
    # that was never written, so the warning is specific to that target.
    # The MEM driver (path is None) is a dense in-RAM buffer, and the other
    # disk drivers are not sparse either — warning about unwritten sparse
    # blocks on a netCDF would state a reason that does not apply to it.
    if no_data_value is None and _resolves_to_gtiff(path):
        warnings.warn(
            "create_empty(no_data_value=None) on a GTiff target stamps no "
            "no-data sentinel, so unwritten sparse blocks read back as 0, not "
            "no-data. Pass a no_data_value to keep the 'unwritten == no-data' "
            "guarantee.",
            NoDataSentinelWarning,
            stacklevel=2,
        )
    gdal_dtype = numpy_to_gdal_dtype(dtype)
    # `create_empty` allocates a header; where it sits in space is often
    # irrelevant to the caller. A geo_ref that carries no transform at all
    # (e.g. `GeoReference(epsg=3857)`) therefore keeps the identity one
    # rather than raising, which is what the flat `epsg=`-only form did.
    geo_ref = geo_ref if geo_ref is not None else GeoReference()
    # Substitute the identity transform only when the reference carries no
    # georeferencing at all. A *half*-filled pair (a corner with no cell
    # size, or the reverse) is a mistake, not a request for the origin:
    # falling back here would silently discard the half the caller did
    # supply, and place the raster at (0, 0) with 1-unit pixels. Leaving it
    # to `resolve_geotransform()` makes it raise, which is what the same
    # value object already does in `from_array` and `create`.
    if (
        geo_ref.geo is None
        and geo_ref.top_left_corner is None
        and geo_ref.cell_size is None
    ):
        geo_ref = replace(geo_ref, geo=_IDENTITY_GEO)
    crs_wkt = _crs_wkt_from_epsg(geo_ref.epsg)
    geo = geo_ref.resolve_geotransform()
    # The tiled / sparse / BigTIFF defaults are GTiff-specific, so apply them
    # only when the path actually resolves to GTiff.
    if options is None and _resolves_to_gtiff(path):
        options = list(OUT_OF_CORE_CREATION_OPTIONS)
    return cls._build_dataset(
        cols,
        rows,
        bands,
        gdal_dtype,
        geo,
        crs_wkt,
        no_data_value,
        path=path,
        options=options,
        array=None,
    )

empty_like(template, *, dtype=None, bands=None, no_data_value=INHERIT_NO_DATA, path=None, options=None) classmethod

Allocate an empty raster aligned to a template's geo / epsg / shape / nodata.

The header-only sibling of :meth:dataset_like — same spatial footprint as template (geotransform, CRS, rows, columns, no-data), but no array is written, so it can allocate an out-of-core output the size of an input DEM without materialising it. The driver comes from path: MEM when it is None, otherwise whatever the extension selects. A .tif destination additionally gets the tiled / sparse / BigTIFF defaults in :data:OUT_OF_CORE_CREATION_OPTIONS.

Parameters:

Name	Type	Description	Default
template	Dataset	Source raster whose geotransform, CRS, shape, and no-data value the output copies.	required
dtype	str | None	NumPy dtype name for the output bands. None (default) reuses the template's dtype.	None
bands	int | None	Number of output bands. None (default) reuses the template's band count.	None
no_data_value	Any	No-data sentinel for the output. Default inherits from the template: when the band count is unchanged and every template band has a sentinel, the per-band no-data values are preserved; otherwise (a bands override, or a template band with no sentinel) the template's first-band value is used. Pass an explicit scalar or per-band list to override. If this resolves to None (passed explicitly, or inherited from a template with no no-data set), no sentinel is stamped and a sparse GTiff's unwritten blocks read back as 0, not no-data; a path that resolves to GTiff emits a :class:NoDataSentinelWarning (the in-RAM MEM result and the other, non-sparse disk drivers do not warn).	INHERIT_NO_DATA
path	str | Path | None	Destination, which alone decides the driver. None (default) keeps the raster in memory (MEM); otherwise the extension selects the format (.tif -> GTiff, .nc -> netCDF, ...).	None
options	list[str] | None	GDAL creation options forwarded to the disk driver. None (default) uses :data:OUT_OF_CORE_CREATION_OPTIONS, but only when the path resolves to GTiff — those options are GTiff-specific, so any other disk driver gets none. Passing options without a path raises rather than silently dropping them.	None

Returns:

Name	Type	Description
Dataset	Dataset	An empty raster matching the template's footprint.

Raises:

Type	Description
ValueError	options is given without a path (creation options apply only to a disk driver).
DriverNotExistError	path has no extension, or one the driver catalog does not know.
FileFormatNotSupportedError	path's extension maps to a write-by-copy-only format, which cannot be allocated with Create.

Examples:

• Allocate an empty raster shaped like an existing one, with a different dtype:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> template = Dataset.from_array(
  ...     np.ones((3, 4, 5), dtype="float32"),
  ...     no_data_value=-9999.0,
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 10.0), cell_size=0.5, epsg=4326),
  ... )
  >>> out = Dataset.empty_like(template, dtype="int16")
  >>> (out.rows, out.columns, out.band_count, out.epsg)
  (4, 5, 3, 4326)
  >>> out.geotransform == template.geotransform
  True
  

• Reduce the band count and inherit the template's no-data value, then confirm the empty output reads back as no-data:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> template = Dataset.from_array(
  ...     np.ones((3, 4, 4), dtype="float32"),
  ...     no_data_value=-9999.0,
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 10.0), cell_size=1.0, epsg=4326),
  ... )
  >>> out = Dataset.empty_like(template, bands=1)
  >>> out.band_count
  1
  >>> float(out.no_data_value[0])
  -9999.0
  

See Also

• :meth:create_empty: Allocate an empty raster from explicit dimensions / CRS instead of copying a template.
• :meth:dataset_like: The array-writing sibling — copies the template footprint and writes a supplied array.
• :meth:write_array: Scatter a window into the allocated raster.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def empty_like(
    cls,
    template: Dataset,
    *,
    dtype: str | None = None,
    bands: int | None = None,
    no_data_value: Any = INHERIT_NO_DATA,
    path: str | Path | None = None,
    options: list[str] | None = None,
) -> Dataset:
    """Allocate an empty raster aligned to a template's geo / epsg / shape / nodata.

    The header-only sibling of :meth:`dataset_like` — same spatial
    footprint as `template` (geotransform, CRS, rows, columns, no-data),
    but **no array is written**, so it can allocate an out-of-core output
    the size of an input DEM without materialising it. The driver comes
    from `path`: MEM when it is `None`, otherwise whatever the extension
    selects. A `.tif` destination additionally gets the tiled / sparse /
    BigTIFF defaults in :data:`OUT_OF_CORE_CREATION_OPTIONS`.

    Args:
        template: Source raster whose geotransform, CRS, shape, and
            no-data value the output copies.
        dtype: NumPy dtype name for the output bands. `None` (default)
            reuses the template's dtype.
        bands: Number of output bands. `None` (default) reuses the
            template's band count.
        no_data_value: No-data sentinel for the output. Default inherits
            from the template: when the band count is unchanged and every
            template band has a sentinel, the **per-band** no-data values
            are preserved; otherwise (a `bands` override, or a template
            band with no sentinel) the template's first-band value is used.
            Pass an explicit scalar or per-band list to override. If this
            resolves to ``None`` (passed explicitly, or inherited from a
            template with no no-data set), no sentinel is stamped and a
            sparse GTiff's unwritten blocks read back as **0**, not no-data;
            a path that resolves to GTiff emits a
            :class:`NoDataSentinelWarning` (the in-RAM MEM result and the
            other, non-sparse disk drivers do not warn).
        path: Destination, which alone decides the driver. `None`
            (default) keeps the raster in memory (MEM); otherwise the
            extension selects the format (`.tif` -> GTiff, `.nc` ->
            netCDF, ...).
        options: GDAL creation options forwarded to the disk driver.
            `None` (default) uses :data:`OUT_OF_CORE_CREATION_OPTIONS`,
            but only when the path resolves to GTiff — those options are
            GTiff-specific, so any other disk driver gets none. Passing
            `options` without a `path` raises rather than silently
            dropping them.

    Returns:
        Dataset: An empty raster matching the template's footprint.

    Raises:
        ValueError: `options` is given without a `path` (creation
            options apply only to a disk driver).
        DriverNotExistError: `path` has no extension, or one the driver
            catalog does not know.
        FileFormatNotSupportedError: `path`'s extension maps to a
            write-by-copy-only format, which cannot be allocated with
            `Create`.

    Examples:
        - Allocate an empty raster shaped like an existing one, with a
          different dtype:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> template = Dataset.from_array(
            ...     np.ones((3, 4, 5), dtype="float32"),
            ...     no_data_value=-9999.0,
            ...     geo_ref=GeoReference(top_left_corner=(0.0, 10.0), cell_size=0.5, epsg=4326),
            ... )
            >>> out = Dataset.empty_like(template, dtype="int16")
            >>> (out.rows, out.columns, out.band_count, out.epsg)
            (4, 5, 3, 4326)
            >>> out.geotransform == template.geotransform
            True

            ```
        - Reduce the band count and inherit the template's no-data value,
          then confirm the empty output reads back as no-data:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> template = Dataset.from_array(
            ...     np.ones((3, 4, 4), dtype="float32"),
            ...     no_data_value=-9999.0,
            ...     geo_ref=GeoReference(top_left_corner=(0.0, 10.0), cell_size=1.0, epsg=4326),
            ... )
            >>> out = Dataset.empty_like(template, bands=1)
            >>> out.band_count
            1
            >>> float(out.no_data_value[0])
            -9999.0

            ```

    See Also:
        - :meth:`create_empty`: Allocate an empty raster from explicit
          dimensions / CRS instead of copying a template.
        - :meth:`dataset_like`: The array-writing sibling — copies the
          template footprint *and* writes a supplied array.
        - :meth:`write_array`: Scatter a window into the allocated raster.
    """
    if options is not None and path is None:
        raise ValueError(
            "empty_like received `options` but no `path`: GDAL creation options "
            "apply only to a disk driver. Pass a `path`, or drop "
            "`options` for the in-memory MEM raster."
        )
    gdal_dtype = (
        template.gdal_dtype[0] if dtype is None else numpy_to_gdal_dtype(dtype)
    )
    n_bands = template.band_count if bands is None else bands
    if no_data_value is not INHERIT_NO_DATA:
        nodata = no_data_value
    else:
        template_nd = template.no_data_value
        # Preserve the template's per-band sentinels when the band count is
        # unchanged and every band actually has one; otherwise (band-count
        # override, or a band with no sentinel) fall back to band 0's value.
        if bands is None and all(v is not None for v in template_nd):
            nodata = list(template_nd)
        else:
            nodata = template_nd[0]
    # Warn only for a GTiff target, the only one whose unwritten sparse
    # blocks read back as 0 when no sentinel is stamped. An in-RAM MEM
    # result (no path) is dense, and the other disk drivers are not sparse,
    # so the stated reason would not apply to them.
    if nodata is None and _resolves_to_gtiff(path):
        warnings.warn(
            "empty_like produced a GTiff raster with no no-data sentinel "
            "(no_data_value resolved to None, explicitly or inherited from a "
            "template with no no-data), so unwritten sparse blocks read back as "
            "0, not no-data. Pass no_data_value to keep the 'unwritten == "
            "no-data' guarantee.",
            NoDataSentinelWarning,
            stacklevel=2,
        )
    # The tiled / sparse / BigTIFF defaults are GTiff-specific, so apply them
    # only when the path actually resolves to GTiff — matching `create_empty`.
    # Hardcoding "GTiff for any path" was harmless while the driver was
    # passed down explicitly; now that it comes from the extension, a `.nc`
    # destination really is netCDF and must not be handed GTiff options.
    if options is None and _resolves_to_gtiff(path):
        options = list(OUT_OF_CORE_CREATION_OPTIONS)
    return cls._build_dataset(
        template.columns,
        template.rows,
        n_bands,
        gdal_dtype,
        template.geotransform,
        template.crs,
        nodata,
        path=path,
        options=options,
        array=None,
    )

from_features(features, *, cell_size=None, template=None, snap_to_template=False, column_name=None) classmethod

Rasterize a :class:FeatureCollection into a new :class:Dataset.

Burns the values from column_name (or every attribute column if None) into a single-band or multi-band raster. When a template Dataset is given, the output adopts its geotransform, cell size, row/column count, and no-data value — the vector is burned onto the template's fixed grid, so features outside it are clipped. With snap_to_template=True the template supplies only the cell size and grid alignment while the extent is cropped to the features (snapped onto the template's grid lines), giving a small raster co-registered with the template. Otherwise cell_size controls the resolution and the extent is derived from :attr:FeatureCollection.total_bounds.

Parameters:

Name	Type	Description	Default
features	FeatureCollection	The vector to rasterize.	required
cell_size	int | float | None	Cell size for the new raster. Required unless template is given.	None
template	Dataset | None	Optional template raster. When supplied, the output inherits its geotransform and no-data value. Features that fall entirely outside the template extent, or an empty FeatureCollection, produce an all-nodata raster and emit a UserWarning (#46); use cell_size instead to size the output to the features.	None
snap_to_template	bool	When True (requires template), keep the template's cell size and grid alignment but size the output to the features' bounds snapped outward onto the template's grid lines — a small raster that still co-registers with the template pixel-for-pixel (#46). Requires a square, axis-aligned template and features with valid (non-NaN) geometry bounds. The output is sized to the features, so a fine-celled template with far-apart features can allocate a large raster.	False
column_name	str | list[str] | None	Attribute column(s) to burn as band values. None burns every non-geometry column as a separate band. Mixed-dtype column lists are promoted to the smallest numpy dtype that holds every selected column without lossy cast (numpy result-type rules).	None

Returns:

Name	Type	Description
Dataset	Dataset	The burned raster.

Raises:

Type	Description
ValueError	cell_size missing or non-positive, column_name empty or referencing missing columns, snap_to_template set without a template, or (in snap mode) a rotated / non-square template or features with no valid (non-NaN) geometry bounds.
TypeError	template is not a Dataset, or column_name is not str / list / None.
CRSError	features.epsg is None, or template.epsg!= features.epsg.

Examples:

• cell_size sizes the output to the feature bounds:

>>> import geopandas as gpd
>>> from shapely.geometry import box
>>> from pyramids.dataset import Dataset, GeoReference
>>> from pyramids.feature import FeatureCollection
>>> gdf = gpd.GeoDataFrame(
...     {"class_id": [7]},
...     geometry=[box(0.0, 0.0, 3.0, 3.0)],
...     crs="EPSG:4326",
... )
>>> raster = Dataset.from_features(
...     FeatureCollection(gdf), cell_size=1.0, column_name="class_id"
... )
>>> (raster.rows, raster.columns)
(3, 3)
>>> int(raster.read_array().max())
7

• A template burns onto its fixed grid, so the output adopts the template's shape (features outside it would warn and yield all-nodata — see #46):

>>> import numpy as np
>>> template = Dataset.from_array(
...     np.zeros((5, 5), dtype="int32"),
...     geo_ref=GeoReference(top_left_corner=(0.0, 5.0), cell_size=1.0, epsg=4326),
... )
>>> inside = FeatureCollection(
...     gpd.GeoDataFrame(
...         {"class_id": [7]},
...         geometry=[box(1.0, 1.0, 4.0, 4.0)],
...         crs="EPSG:4326",
...     )
... )
>>> burned = Dataset.from_features(
...     inside, template=template, column_name="class_id"
... )
>>> (burned.rows, burned.columns)
(5, 5)

• snap_to_template=True keeps the template's grid but crops to the features, so the output is small yet co-registered (its origin is on the template's grid lines):

>>> snapped = Dataset.from_features(
...     inside,
...     template=template,
...     snap_to_template=True,
...     column_name="class_id",
... )
>>> (snapped.rows, snapped.columns)
(3, 3)
>>> snapped.top_left_corner
(1.0, 4.0)

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_features(
    cls,
    features: FeatureCollection,
    *,
    cell_size: Any | None = None,
    template: Dataset | None = None,
    snap_to_template: bool = False,
    column_name: str | list[str] | None = None,
) -> Dataset:
    """Rasterize a :class:`FeatureCollection` into a new :class:`Dataset`.

    Burns the values from `column_name` (or every attribute
    column if `None`) into a single-band or multi-band raster.
    When a `template` Dataset is given, the output adopts its
    geotransform, cell size, row/column count, and no-data value —
    the vector is burned onto the template's fixed grid, so features
    outside it are clipped. With `snap_to_template=True` the template
    supplies only the cell size and grid alignment while the extent is
    cropped to the features (snapped onto the template's grid lines),
    giving a small raster co-registered with the template. Otherwise
    `cell_size` controls the resolution and the extent is derived from
    :attr:`FeatureCollection.total_bounds`.

    Args:
        features (FeatureCollection):
            The vector to rasterize.
        cell_size (int | float | None):
            Cell size for the new raster. Required unless
            `template` is given.
        template (Dataset | None):
            Optional template raster. When supplied, the output
            inherits its geotransform and no-data value. Features
            that fall entirely outside the template extent, or an
            empty FeatureCollection, produce an all-nodata raster
            and emit a `UserWarning` (#46); use `cell_size` instead
            to size the output to the features.
        snap_to_template (bool):
            When `True` (requires `template`), keep the template's
            cell size and grid alignment but size the output to the
            features' bounds snapped outward onto the template's grid
            lines — a small raster that still co-registers with the
            template pixel-for-pixel (#46). Requires a square,
            axis-aligned template and features with valid (non-NaN)
            geometry bounds. The output is sized to the features, so a
            fine-celled template with far-apart features can allocate a
            large raster.
        column_name (str | list[str] | None):
            Attribute column(s) to burn as band values. `None`
            burns every non-geometry column as a separate band.
            Mixed-dtype column lists are promoted to the smallest
            numpy dtype that holds every selected column without
            lossy cast (numpy result-type rules).

    Returns:
        Dataset: The burned raster.

    Raises:
        ValueError: `cell_size` missing or non-positive,
            `column_name` empty or referencing missing columns,
            `snap_to_template` set without a `template`, or (in snap
            mode) a rotated / non-square template or features with no
            valid (non-NaN) geometry bounds.
        TypeError: `template` is not a Dataset, or
            `column_name` is not `str` / `list` / `None`.
        CRSError: `features.epsg` is `None`, or
            `template.epsg!= features.epsg`.

    Examples:
        - `cell_size` sizes the output to the feature bounds:

          ```python
          >>> import geopandas as gpd
          >>> from shapely.geometry import box
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> from pyramids.feature import FeatureCollection
          >>> gdf = gpd.GeoDataFrame(
          ...     {"class_id": [7]},
          ...     geometry=[box(0.0, 0.0, 3.0, 3.0)],
          ...     crs="EPSG:4326",
          ... )
          >>> raster = Dataset.from_features(
          ...     FeatureCollection(gdf), cell_size=1.0, column_name="class_id"
          ... )
          >>> (raster.rows, raster.columns)
          (3, 3)
          >>> int(raster.read_array().max())
          7

          ```

        - A `template` burns onto its fixed grid, so the output adopts the template's
          shape (features outside it would warn and yield all-nodata — see #46):

          ```python
          >>> import numpy as np
          >>> template = Dataset.from_array(
          ...     np.zeros((5, 5), dtype="int32"),
          ...     geo_ref=GeoReference(top_left_corner=(0.0, 5.0), cell_size=1.0, epsg=4326),
          ... )
          >>> inside = FeatureCollection(
          ...     gpd.GeoDataFrame(
          ...         {"class_id": [7]},
          ...         geometry=[box(1.0, 1.0, 4.0, 4.0)],
          ...         crs="EPSG:4326",
          ...     )
          ... )
          >>> burned = Dataset.from_features(
          ...     inside, template=template, column_name="class_id"
          ... )
          >>> (burned.rows, burned.columns)
          (5, 5)

          ```

        - `snap_to_template=True` keeps the template's grid but crops to the features,
          so the output is small yet co-registered (its origin is on the template's
          grid lines):

          ```python
          >>> snapped = Dataset.from_features(
          ...     inside,
          ...     template=template,
          ...     snap_to_template=True,
          ...     column_name="class_id",
          ... )
          >>> (snapped.rows, snapped.columns)
          (3, 3)
          >>> snapped.top_left_corner
          (1.0, 4.0)

          ```
    """
    return rasterize_features(
        features,
        cls,
        cell_size=cell_size,
        template=template,
        snap_to_template=snap_to_template,
        column_name=column_name,
    )

from_points(points, value_column, *, algorithm='invdist:power=2.0:smoothing=0.0', cell_size=None, width=None, height=None, bbox=None, epsg=None) classmethod

Interpolate scattered point samples onto a regular grid (gdal.Grid).

The GDAL-native equivalent of gdal_grid — turns an irregular point layer (gauge readings, soundings, station observations) into a continuous single-band raster. The output extent defaults to the points' bounding box and the resolution is set by cell_size (or an explicit width/height).

Parameters:

Name	Type	Description	Default
points	FeatureCollection	A point :class:FeatureCollection carrying value_column.	required
value_column	str	Numeric attribute column to interpolate (the Z field).	required
algorithm	str	A gdal.Grid algorithm string. Defaults to inverse-distance weighting ("invdist:power=2.0:smoothing=0.0"). Other options include "invdistnn", "nearest", "linear", and "average".	'invdist:power=2.0:smoothing=0.0'
cell_size	float | None	Output pixel size in the points' CRS units. Required unless both width and height are given.	None
width	int | None	Output width in pixels. Overrides cell_size on the x axis.	None
height	int | None	Output height in pixels. Overrides cell_size on the y axis.	None
bbox	tuple[float, float, float, float] | None	(minx, miny, maxx, maxy) output extent. Defaults to the points' total bounds.	None
epsg	int | None	Output EPSG code. Defaults to the points' CRS.	None

Returns:

Name	Type	Description
Dataset	Dataset	A single-band raster of the interpolated surface.

Raises:

Type	Description
ValueError	value_column missing, output bounds degenerate, or neither cell_size nor width+height provided.
FailedToSaveError	gdal.Grid produced no dataset.

Examples:

• Inverse-distance interpolate four corner readings onto a 1-degree grid and read back the surface shape:

  >>> from shapely.geometry import Point
  >>> from geopandas import GeoDataFrame
  >>> from pyramids.feature import FeatureCollection
  >>> from pyramids.dataset import Dataset
  >>> gdf = GeoDataFrame(
  ...     {"rain": [10.0, 20.0, 30.0, 40.0]},
  ...     geometry=[Point(0, 0), Point(10, 0), Point(0, 10), Point(10, 10)],
  ...     crs="EPSG:4326",
  ... )
  >>> ds = Dataset.from_points(FeatureCollection(gdf), "rain", cell_size=1.0)
  >>> (ds.rows, ds.columns, ds.band_count)
  (10, 10, 1)
  

• Use nearest-neighbour with an explicit output size:

  >>> from shapely.geometry import Point
  >>> from geopandas import GeoDataFrame
  >>> from pyramids.feature import FeatureCollection
  >>> from pyramids.dataset import Dataset
  >>> gdf = GeoDataFrame(
  ...     {"z": [1.0, 2.0, 3.0, 4.0]},
  ...     geometry=[Point(0, 0), Point(5, 0), Point(0, 5), Point(5, 5)],
  ...     crs="EPSG:4326",
  ... )
  >>> ds = Dataset.from_points(
  ...     FeatureCollection(gdf), "z", algorithm="nearest", width=5, height=5
  ... )
  >>> ds.columns
  5
  

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_points(
    cls,
    points: FeatureCollection,
    value_column: str,
    *,
    algorithm: str = "invdist:power=2.0:smoothing=0.0",
    cell_size: float | None = None,
    width: int | None = None,
    height: int | None = None,
    bbox: tuple[float, float, float, float] | None = None,
    epsg: Any | None = None,
) -> Dataset:
    """Interpolate scattered point samples onto a regular grid (``gdal.Grid``).

    The GDAL-native equivalent of ``gdal_grid`` — turns an irregular point
    layer (gauge readings, soundings, station observations) into a
    continuous single-band raster. The output extent defaults to the points'
    bounding box and the resolution is set by ``cell_size`` (or an explicit
    ``width``/``height``).

    Args:
        points (FeatureCollection):
            A point :class:`FeatureCollection` carrying ``value_column``.
        value_column (str):
            Numeric attribute column to interpolate (the Z field).
        algorithm (str):
            A ``gdal.Grid`` algorithm string. Defaults to inverse-distance
            weighting (``"invdist:power=2.0:smoothing=0.0"``). Other options
            include ``"invdistnn"``, ``"nearest"``, ``"linear"``, and
            ``"average"``.
        cell_size (float | None):
            Output pixel size in the points' CRS units. Required unless both
            ``width`` and ``height`` are given.
        width (int | None):
            Output width in pixels. Overrides ``cell_size`` on the x axis.
        height (int | None):
            Output height in pixels. Overrides ``cell_size`` on the y axis.
        bbox (tuple[float, float, float, float] | None):
            ``(minx, miny, maxx, maxy)`` output extent. Defaults to the
            points' total bounds.
        epsg (int | None):
            Output EPSG code. Defaults to the points' CRS.

    Returns:
        Dataset: A single-band raster of the interpolated surface.

    Raises:
        ValueError: ``value_column`` missing, output bounds degenerate, or
            neither ``cell_size`` nor ``width``+``height`` provided.
        FailedToSaveError: ``gdal.Grid`` produced no dataset.

    Examples:
        - Inverse-distance interpolate four corner readings onto a 1-degree
          grid and read back the surface shape:
            ```python
            >>> from shapely.geometry import Point
            >>> from geopandas import GeoDataFrame
            >>> from pyramids.feature import FeatureCollection
            >>> from pyramids.dataset import Dataset
            >>> gdf = GeoDataFrame(
            ...     {"rain": [10.0, 20.0, 30.0, 40.0]},
            ...     geometry=[Point(0, 0), Point(10, 0), Point(0, 10), Point(10, 10)],
            ...     crs="EPSG:4326",
            ... )
            >>> ds = Dataset.from_points(FeatureCollection(gdf), "rain", cell_size=1.0)
            >>> (ds.rows, ds.columns, ds.band_count)
            (10, 10, 1)

            ```
        - Use nearest-neighbour with an explicit output size:
            ```python
            >>> from shapely.geometry import Point
            >>> from geopandas import GeoDataFrame
            >>> from pyramids.feature import FeatureCollection
            >>> from pyramids.dataset import Dataset
            >>> gdf = GeoDataFrame(
            ...     {"z": [1.0, 2.0, 3.0, 4.0]},
            ...     geometry=[Point(0, 0), Point(5, 0), Point(0, 5), Point(5, 5)],
            ...     crs="EPSG:4326",
            ... )
            >>> ds = Dataset.from_points(
            ...     FeatureCollection(gdf), "z", algorithm="nearest", width=5, height=5
            ... )
            >>> ds.columns
            5

            ```
    """
    return grid_points(
        points,
        value_column,
        cls,
        algorithm=algorithm,
        cell_size=cell_size,
        width=width,
        height=height,
        bbox=bbox,
        epsg=epsg,
    )

from_point_arrays(x, y, z, *, algorithm='invdist:power=2.0:smoothing=0.0', cell_size=None, width=None, height=None, bbox=None, crs=None, epsg=None) classmethod

Interpolate raw coordinate arrays onto a grid — no geometry built.

The array-native sibling of :meth:from_points. Where from_points takes a point :class:~pyramids.feature.FeatureCollection (a shapely geometry per point), this takes raw x / y / z arrays straight into gdal.Grid through an in-memory CSV, so a large sample table (bathymetric soundings, a dense gauge network, a CSV of readings) never materialises a geometry object. Both share one gridding core, so the two differ only in how the points arrive.

gdal.Grid does not reproject: crs / epsg only label the output. The grid is computed in the coordinates' own space, so cell_size and bbox are in those units.

This is the low-level array entry, and like :meth:from_points it does not enforce the minimum-point-count or column-dtype policy that the higher-level :meth:~pyramids.feature.FeatureCollection.interpolate_to_raster applies -- gridding a single point is allowed. It does reject the inputs gdal.Grid cannot use: non-finite coordinates or bbox raise, non-finite values are dropped as missing readings, and an all-non-finite value array raises.

Parameters:

Name	Type	Description	Default
x	Any	Point x-coordinates (anything :func:numpy.asarray reads as a 1-D float array).	required
y	Any	Point y-coordinates, the same length as x.	required
z	Any	The value to interpolate at each point, the same length as x.	required
algorithm	str	A gdal.Grid algorithm string. Defaults to inverse-distance weighting ("invdist:power=2.0:smoothing=0.0"); other options include "invdistnn", "nearest", "linear" and "average".	'invdist:power=2.0:smoothing=0.0'
cell_size	float | None	Output pixel size in the coordinates' units. Required unless both width and height are given.	None
width	int | None	Output width in pixels. With height, overrides cell_size.	None
height	int | None	Output height in pixels. With width, overrides cell_size.	None
bbox	tuple[float, float, float, float] | None	(minx, miny, maxx, maxy) output extent. Defaults to the arrays' own min/max.	None
crs	Any	CRS the coordinates are in, to stamp on the output (any form :func:~pyramids.base.crs.sr_from_user_input accepts), or None. Mutually informative with epsg; epsg wins if both are given.	None
epsg	int | None	Output EPSG code. Takes precedence over crs.	None

Returns:

Name	Type	Description
Dataset	Dataset	A single-band raster of the interpolated surface.

Raises:

Type	Description
ValueError	x / y / z are not 1-D of equal length, are empty, a coordinate (x or y) or bbox is non-finite, every z value is non-finite (nothing to interpolate), the bounds are degenerate, cell_size is not positive, or neither cell_size nor width + height was given.
FailedToSaveError	gdal.Grid produced no dataset.

Examples:

• Grid four corner readings onto a 1-degree grid straight from arrays:

  >>> from pyramids.dataset import Dataset
  >>> x = [0.0, 10.0, 0.0, 10.0]
  >>> y = [0.0, 0.0, 10.0, 10.0]
  >>> z = [10.0, 20.0, 30.0, 40.0]
  >>> ds = Dataset.from_point_arrays(x, y, z, cell_size=1.0, epsg=4326)
  >>> (ds.rows, ds.columns, ds.band_count)
  (10, 10, 1)
  >>> ds.epsg
  4326
  

• Nearest-neighbour with an explicit output size and a wider extent:

  >>> from pyramids.dataset import Dataset
  >>> ds = Dataset.from_point_arrays(
  ...     [0.0, 5.0, 0.0, 5.0], [0.0, 0.0, 5.0, 5.0],
  ...     [1.0, 2.0, 3.0, 4.0],
  ...     algorithm="nearest", width=8, height=8, bbox=(-2, -2, 7, 7),
  ... )
  >>> (ds.rows, ds.columns)
  (8, 8)
  >>> round(ds.geotransform[0])
  -2
  

See Also

• :meth:from_points: the same gridding from a point :class:~pyramids.feature.FeatureCollection.
• :meth:pyramids.feature.FeatureCollection.from_xyz: build a point layer from arrays when you want the vector model, not a raster.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_point_arrays(
    cls,
    x: Any,
    y: Any,
    z: Any,
    *,
    algorithm: str = "invdist:power=2.0:smoothing=0.0",
    cell_size: float | None = None,
    width: int | None = None,
    height: int | None = None,
    bbox: tuple[float, float, float, float] | None = None,
    crs: Any = None,
    epsg: int | None = None,
) -> Dataset:
    """Interpolate raw coordinate arrays onto a grid — no geometry built.

    The array-native sibling of :meth:`from_points`. Where ``from_points``
    takes a point :class:`~pyramids.feature.FeatureCollection` (a shapely
    geometry per point), this takes raw ``x`` / ``y`` / ``z`` arrays straight
    into ``gdal.Grid`` through an in-memory CSV, so a large sample table
    (bathymetric soundings, a dense gauge network, a CSV of readings) never
    materialises a geometry object. Both share one gridding core, so the two
    differ only in how the points arrive.

    ``gdal.Grid`` does not reproject: ``crs`` / ``epsg`` only label the output.
    The grid is computed in the coordinates' own space, so ``cell_size`` and
    ``bbox`` are in those units.

    This is the low-level array entry, and like :meth:`from_points` it does not
    enforce the minimum-point-count or column-dtype policy that the higher-level
    :meth:`~pyramids.feature.FeatureCollection.interpolate_to_raster` applies --
    gridding a single point is allowed. It does reject the inputs ``gdal.Grid``
    cannot use: non-finite coordinates or ``bbox`` raise, non-finite values are
    dropped as missing readings, and an all-non-finite value array raises.

    Args:
        x (Any):
            Point x-coordinates (anything :func:`numpy.asarray` reads as a 1-D
            float array).
        y (Any):
            Point y-coordinates, the same length as ``x``.
        z (Any):
            The value to interpolate at each point, the same length as ``x``.
        algorithm (str):
            A ``gdal.Grid`` algorithm string. Defaults to inverse-distance
            weighting (``"invdist:power=2.0:smoothing=0.0"``); other options
            include ``"invdistnn"``, ``"nearest"``, ``"linear"`` and
            ``"average"``.
        cell_size (float | None):
            Output pixel size in the coordinates' units. Required unless both
            ``width`` and ``height`` are given.
        width (int | None):
            Output width in pixels. With ``height``, overrides ``cell_size``.
        height (int | None):
            Output height in pixels. With ``width``, overrides ``cell_size``.
        bbox (tuple[float, float, float, float] | None):
            ``(minx, miny, maxx, maxy)`` output extent. Defaults to the arrays'
            own min/max.
        crs (Any):
            CRS the coordinates are in, to stamp on the output (any form
            :func:`~pyramids.base.crs.sr_from_user_input` accepts), or ``None``.
            Mutually informative with ``epsg``; ``epsg`` wins if both are given.
        epsg (int | None):
            Output EPSG code. Takes precedence over ``crs``.

    Returns:
        Dataset: A single-band raster of the interpolated surface.

    Raises:
        ValueError: ``x`` / ``y`` / ``z`` are not 1-D of equal length, are
            empty, a coordinate (``x`` or ``y``) or ``bbox`` is non-finite,
            every ``z`` value is non-finite (nothing to interpolate), the bounds
            are degenerate, ``cell_size`` is not positive, or neither
            ``cell_size`` nor ``width`` + ``height`` was given.
        FailedToSaveError: ``gdal.Grid`` produced no dataset.

    Examples:
        - Grid four corner readings onto a 1-degree grid straight from arrays:
            ```python
            >>> from pyramids.dataset import Dataset
            >>> x = [0.0, 10.0, 0.0, 10.0]
            >>> y = [0.0, 0.0, 10.0, 10.0]
            >>> z = [10.0, 20.0, 30.0, 40.0]
            >>> ds = Dataset.from_point_arrays(x, y, z, cell_size=1.0, epsg=4326)
            >>> (ds.rows, ds.columns, ds.band_count)
            (10, 10, 1)
            >>> ds.epsg
            4326

            ```
        - Nearest-neighbour with an explicit output size and a wider extent:
            ```python
            >>> from pyramids.dataset import Dataset
            >>> ds = Dataset.from_point_arrays(
            ...     [0.0, 5.0, 0.0, 5.0], [0.0, 0.0, 5.0, 5.0],
            ...     [1.0, 2.0, 3.0, 4.0],
            ...     algorithm="nearest", width=8, height=8, bbox=(-2, -2, 7, 7),
            ... )
            >>> (ds.rows, ds.columns)
            (8, 8)
            >>> round(ds.geotransform[0])
            -2

            ```

    See Also:
        - :meth:`from_points`: the same gridding from a point
          :class:`~pyramids.feature.FeatureCollection`.
        - :meth:`pyramids.feature.FeatureCollection.from_xyz`: build a point
          layer from arrays when you want the vector model, not a raster.
    """
    output_srs: str | None = None
    if epsg is not None:
        output_srs = f"EPSG:{int(epsg)}"
    elif crs is not None:
        output_srs = sr_from_user_input(crs).ExportToWkt()
    return grid_arrays(
        x,
        y,
        z,
        cls,
        algorithm=algorithm,
        cell_size=cell_size,
        width=width,
        height=height,
        bbox=bbox,
        output_srs=output_srs,
    )

to_dataframe(*, bands=None, dropna=False)

Hand the raster to pandas, one row per cell on a (band, y, x) MultiIndex.

The inverse of :meth:from_dataframe. Each row is a cell; the single values column holds that cell's value; the MultiIndex names band (0-based, outermost), then the row (y) and column (x) cell-centre coordinates — the order the array is laid out, so df["values"].to_numpy().reshape(bands, rows, cols) is the array back, with nodata as NaN. The frame is coordinate-keyed and carries no geometry or CRS; for a geometry-per-cell GeoDataFrame (points or polygons, optionally with the band values) use :meth:to_geodataframe, and to read values at scattered points use :meth:sample / :meth:extract.

The band level is always present, even for a one-band raster (value [0]); df["values"].unstack("band") gives the wide, one-column-per-band view.

Parameters:

Name	Type	Description	Default
bands	int | Sequence[int] | None	Which band(s) become rows, zero-based. None (default) takes every band; a single int takes that one; a sequence takes them in the given order. The band index level holds these positional indices.	None
dropna	bool	Drop rows whose values is NaN (the no-data / gap cells). False (default) keeps the full grid, which is what makes the round trip with :meth:from_dataframe reproduce the raster; True returns only the cells that carry data.	False

Returns:

Type	Description
DataFrame	pandas.DataFrame: prod(len(bands), rows, cols) rows, one values column,
DataFrame	every value float64 whatever the raster's own dtype, gaps as NaN,
DataFrame	north-up (y descending, x ascending). Integer values above 2**53 are
DataFrame	not exactly representable once coerced to float64.

Raises:

Type	Description
ValueError	A requested band index is out of range for the raster, or bands= is an empty selection (pass bands=None for every band).
TypeError	bands= is a boolean (bool subclasses int, so it is refused rather than silently selecting band 0 / 1).

Examples:

• A one-band 2x2 raster as pandas sees it (the band level is kept):

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> ds = Dataset.from_array(
...     np.array([[1.0, 2.0], [3.0, 4.0]]),
...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=4326),
... )
>>> ds.to_dataframe()["values"].tolist()
[1.0, 2.0, 3.0, 4.0]
>>> list(ds.to_dataframe().index.names)
['band', 'y', 'x']

Source code in src/pyramids/dataset/dataset.py

def to_dataframe(
    self, *, bands: int | Sequence[int] | None = None, dropna: bool = False
) -> pd.DataFrame:
    """Hand the raster to pandas, one row per cell on a ``(band, y, x)`` MultiIndex.

    The inverse of :meth:`from_dataframe`. Each row is a cell; the single ``values``
    column holds that cell's value; the ``MultiIndex`` names ``band`` (0-based,
    outermost), then the row (``y``) and column (``x``) cell-centre coordinates — the
    order the array is laid out, so ``df["values"].to_numpy().reshape(bands, rows, cols)``
    is the array back, with nodata as ``NaN``. The frame is coordinate-keyed and carries
    **no geometry or CRS**; for a geometry-per-cell ``GeoDataFrame`` (points or polygons,
    optionally with the band values) use :meth:`to_geodataframe`, and to read values at
    scattered points use :meth:`sample` / :meth:`extract`.

    The ``band`` level is always present, even for a one-band raster (value ``[0]``);
    ``df["values"].unstack("band")`` gives the wide, one-column-per-band view.

    Args:
        bands: Which band(s) become rows, zero-based. ``None`` (default) takes every band;
            a single ``int`` takes that one; a sequence takes them in the given order. The
            ``band`` index level holds these positional indices.
        dropna: Drop rows whose ``values`` is ``NaN`` (the no-data / gap cells). ``False``
            (default) keeps the full grid, which is what makes the round trip with
            :meth:`from_dataframe` reproduce the raster; ``True`` returns only the cells
            that carry data.

    Returns:
        pandas.DataFrame: ``prod(len(bands), rows, cols)`` rows, one ``values`` column,
        every value ``float64`` whatever the raster's own dtype, gaps as ``NaN``,
        north-up (``y`` descending, ``x`` ascending). Integer values above ``2**53`` are
        not exactly representable once coerced to ``float64``.

    Raises:
        ValueError: A requested band index is out of range for the raster, or ``bands=``
            is an empty selection (pass ``bands=None`` for every band).
        TypeError: ``bands=`` is a boolean (``bool`` subclasses ``int``, so it is refused
            rather than silently selecting band 0 / 1).

    Examples:
        - A one-band 2x2 raster as pandas sees it (the ``band`` level is kept):

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> ds = Dataset.from_array(
          ...     np.array([[1.0, 2.0], [3.0, 4.0]]),
          ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=4326),
          ... )
          >>> ds.to_dataframe()["values"].tolist()
          [1.0, 2.0, 3.0, 4.0]
          >>> list(ds.to_dataframe().index.names)
          ['band', 'y', 'x']

          ```
    """
    count = self.band_count
    if bands is None:
        selected = list(range(count))
    elif isinstance(bands, bool):
        # bool subclasses int, so guard it before the int branch or True/False
        # would silently select band 1/0 — almost certainly a caller mistake.
        raise TypeError(
            f"Dataset.to_dataframe() got a boolean bands={bands!r}; pass a band index, a "
            "sequence of indices, or None for every band."
        )
    elif isinstance(bands, (int, np.integer)):
        selected = [int(bands)]
    else:
        selected = [int(b) for b in bands]
    if not selected:
        raise ValueError(
            "Dataset.to_dataframe() was given an empty bands= selection; pass "
            f"bands=None for every band, or indices in 0..{count - 1}."
        )
    out_of_range = [b for b in selected if not 0 <= b < count]
    if out_of_range:
        raise ValueError(
            f"Dataset.to_dataframe() got band index/indices {out_of_range} out of range "
            f"for a {count}-band raster (valid 0..{count - 1})."
        )
    # `squeeze=True` keeps the classic flattened `(bands, rows, cols)` this band-indexed
    # dataframe build expects, not the dimension-preserving default (#1241).
    array = np.asarray(self.read_array(squeeze=True), dtype="float64")
    if array.ndim == 2:
        array = array[np.newaxis, ...]
    array = array[selected]
    sentinels = self.no_data_value
    for i, band in enumerate(selected):
        sentinel = sentinels[band]
        # A NaN sentinel already reads back as NaN; only a real value needs masking.
        # Guard the isnan by type — it raises on integer sentinels (e.g. uint64).
        is_nan_sentinel = isinstance(sentinel, (float, np.floating)) and np.isnan(
            sentinel
        )
        if sentinel is not None and not is_nan_sentinel:
            array[i] = np.where(array[i] == sentinel, np.nan, array[i])
    index = pd.MultiIndex.from_product(
        [
            selected,
            list(np.asarray(self.y, dtype="float64")),
            list(np.asarray(self.x, dtype="float64")),
        ],
        names=["band", "y", "x"],
    )
    frame = pd.DataFrame({"values": array.reshape(-1)}, index=index)
    if dropna:
        frame = frame.dropna(subset=["values"])
    return frame

from_dataframe(df, *, crs=None, x=None, y=None, no_data_value=np.nan, path=None) classmethod

Rebuild a raster from a (band, y, x) MultiIndex DataFrame — inverse of to_dataframe.

The frame is indexed by its axes: the innermost two index levels are the (y, x) grid and an optional outer level is the positional band axis, so Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg) reproduces ds's values, band count/order, grid and CRS (the geotransform is recovered by differencing cell centres); gaps come back as NaN unless no_data_value= restores a specific sentinel. A frame with no band level (a plain (y, x) MultiIndex) builds a single-band raster. A DataFrame carries no georeferencing, so the geotransform is inferred from the x / y cell centres (a regular grid is required; a single-row or single-column axis is refused) and the CRS is taken from crs. The result is always north-up.

A raster's bands are positional, so — unlike :meth:pyramids.netcdf.NetCDF.from_dataframe — this takes a single value column (the band axis lives in the index); a multi-column frame is refused with a pointer to NetCDF.from_dataframe.

Parameters:

Name	Type	Description	Default
df	DataFrame	A DataFrame on a pandas.MultiIndex of at least two named levels — the innermost two the row (y) and column (x) axes (unless x / y name them), an optional outer level the band axis — and exactly one value column. A tidy frame on a plain index is refused.	required
crs	str | int | None	The CRS for the result, an EPSG code or a CRS string. None (default) leaves it unset — a DataFrame carries none, so a full round trip needs crs=ds.epsg to recover it.	None
x	str | None	The index level holding the column (x) coordinates; defaults to the innermost.	None
y	str | None	The index level holding the row (y) coordinates; defaults to the second-innermost.	None
no_data_value	Any	Sentinel stamped on gaps (NaN cells and cells absent from the frame). Defaults to np.nan, so gaps stay NaN and the rebuilt raster declares NaN as its nodata; pass e.g. no_data_value=ds.no_data_value[0] to restore a specific sentinel and its dtype.	nan
path	str | Path | None	Destination — None (default) builds in memory; otherwise the extension selects the driver, exactly as :meth:from_array.	None

Returns:

Name	Type	Description
Dataset	Dataset	The rebuilt raster on the inferred grid.

Raises:

Type	Description
ValueError	The frame is not a MultiIndex of at least two named levels; a named x / y level is missing or the two coincide; there is not exactly one value column; more than one band index level is present; the index has duplicate rows; or the x / y axis is irregular or single-celled.

Examples:

• Round-trip a two-band raster through pandas and back:

>>> import numpy as np
>>> from pyramids.dataset import Dataset, GeoReference
>>> ds = Dataset.from_array(
...     np.arange(8.0).reshape(2, 2, 2),
...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=4326),
... )
>>> back = Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg)
>>> back.read_array().tolist()
[[[0.0, 1.0], [2.0, 3.0]], [[4.0, 5.0], [6.0, 7.0]]]
>>> back.band_count
2

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_dataframe(
    cls,
    df: pd.DataFrame,
    *,
    crs: str | int | None = None,
    x: str | None = None,
    y: str | None = None,
    no_data_value: Any = np.nan,
    path: str | Path | None = None,
) -> Dataset:
    """Rebuild a raster from a ``(band, y, x)`` MultiIndex DataFrame — inverse of ``to_dataframe``.

    The frame is indexed by its axes: the innermost two index levels are the ``(y, x)``
    grid and an optional outer level is the positional ``band`` axis, so
    ``Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg)`` reproduces ``ds``'s values,
    band count/order, grid and CRS (the geotransform is recovered by differencing cell
    centres); gaps come back as ``NaN`` unless ``no_data_value=`` restores a specific
    sentinel. A frame with no band level (a plain ``(y, x)`` MultiIndex) builds a single-band
    raster. A DataFrame carries no georeferencing, so the geotransform is inferred from
    the ``x`` / ``y`` cell centres (a regular grid is required; a single-row or
    single-column axis is refused) and the CRS is taken from ``crs``. The result is always
    north-up.

    A raster's bands are positional, so — unlike
    :meth:`pyramids.netcdf.NetCDF.from_dataframe` — this takes a **single** value column
    (the band axis lives in the index); a multi-column frame is refused with a pointer to
    ``NetCDF.from_dataframe``.

    Args:
        df: A DataFrame on a ``pandas.MultiIndex`` of at least two named levels — the
            innermost two the row (``y``) and column (``x``) axes (unless ``x`` / ``y``
            name them), an optional outer level the ``band`` axis — and exactly one value
            column. A tidy frame on a plain index is refused.
        crs: The CRS for the result, an EPSG code or a CRS string. ``None`` (default)
            leaves it unset — a DataFrame carries none, so a full round trip needs
            ``crs=ds.epsg`` to recover it.
        x: The index level holding the column (x) coordinates; defaults to the innermost.
        y: The index level holding the row (y) coordinates; defaults to the
            second-innermost.
        no_data_value: Sentinel stamped on gaps (``NaN`` cells and cells absent from the
            frame). Defaults to ``np.nan``, so gaps stay ``NaN`` and the rebuilt raster
            declares ``NaN`` as its nodata; pass e.g. ``no_data_value=ds.no_data_value[0]``
            to restore a specific sentinel and its dtype.
        path: Destination — ``None`` (default) builds in memory; otherwise the extension
            selects the driver, exactly as :meth:`from_array`.

    Returns:
        Dataset: The rebuilt raster on the inferred grid.

    Raises:
        ValueError: The frame is not a MultiIndex of at least two named levels; a named
            ``x`` / ``y`` level is missing or the two coincide; there is not exactly one
            value column; more than one band index level is present; the index has
            duplicate rows; or the ``x`` / ``y`` axis is irregular or single-celled.

    Examples:
        - Round-trip a two-band raster through pandas and back:

          ```python
          >>> import numpy as np
          >>> from pyramids.dataset import Dataset, GeoReference
          >>> ds = Dataset.from_array(
          ...     np.arange(8.0).reshape(2, 2, 2),
          ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=4326),
          ... )
          >>> back = Dataset.from_dataframe(ds.to_dataframe(), crs=ds.epsg)
          >>> back.read_array().tolist()
          [[[0.0, 1.0], [2.0, 3.0]], [[4.0, 5.0], [6.0, 7.0]]]
          >>> back.band_count
          2

          ```
    """
    columns = value_columns(df, None)
    if len(columns) != 1:
        raise ValueError(
            "Dataset.from_dataframe() expects a single value column — a raster's bands "
            f"live in the index, not in columns — but the frame has {columns}. For a "
            "multi-variable table use NetCDF.from_dataframe()."
        )
    band_names, row_name, col_name = frame_axes(df, x, y)
    if len(band_names) > 1:
        raise ValueError(
            "Dataset.from_dataframe() expects at most one band index level (band, y, x), "
            f"but got band levels {band_names}. For several band dimensions use "
            "NetCDF.from_dataframe()."
        )
    check_no_duplicate_index(df)
    _band_coords, _y_coords, _x_coords, geo, ordered, shape = reshape_to_grid(
        df, band_names, row_name, col_name
    )
    arr = column_array(ordered, columns[0], shape)
    arr = np.where(np.isnan(arr), no_data_value, arr)
    return cls.from_array(
        arr,
        geo_ref=GeoReference(geo=geo, epsg=crs),
        no_data_value=no_data_value,
        path=path,
    )

from_array(arr, *, geo_ref, no_data_value=DEFAULT_NO_DATA_VALUE, path=None) classmethod

Create a new dataset from an array.

Parameters:

Name	Type	Description	Default
arr	ndarray	Numpy array.	required
geo_ref	GeoReference	How the array maps to space — an affine geo transform, or a top_left_corner + cell_size, plus the epsg. Required; a raster has to be placed somewhere. An epsg of None (or 0) creates an ungeoreferenced raster that reports no CRS, rather than one silently stamped WGS 84.	required
no_data_value	Any	No data value to mask the cells out of the domain. The default is -9999.	DEFAULT_NO_DATA_VALUE
path	str	Destination. None (default) builds the raster in memory; otherwise the extension selects the driver (.tif -> GTiff, .nc -> netCDF, …). A .nc destination here writes a classic single-variable netCDF through the plain GDAL raster API; for a multi-variable, CF-attributed store use :meth:pyramids.netcdf.NetCDF.from_array, which goes through the multidimensional path.	None

Returns:

Name	Type	Description
Dataset	Dataset	Dataset object will be returned.

Raises:

Type	Description
ValueError	geo_ref carries neither a geo nor a complete top_left_corner + cell_size pair.
DriverNotExistError	path has no extension, or one the driver catalog does not know.
FileFormatNotSupportedError	path's extension maps to a write-by-copy-only format such as PNG, which cannot be built with Create.

Examples:

• Wrap a 2-D array, then read it back:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> arr = np.arange(6, dtype="float32").reshape(2, 3)
  >>> ds = Dataset.from_array(
  ...     arr, geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0))
  ... )
  >>> ds.read_array().tolist()
  [[0.0, 1.0, 2.0], [3.0, 4.0, 5.0]]
  >>> (ds.rows, ds.columns, ds.band_count)
  (2, 3, 1)
  

• A leading axis becomes bands:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> stack = np.ones((3, 2, 2), dtype="int16")
  >>> ds = Dataset.from_array(
  ...     stack,
  ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0),
  ... )
  >>> ds.band_count
  3
  

• epsg=None builds an ungeoreferenced raster rather than silently claiming WGS 84:

  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> ds = Dataset.from_array(
  ...     np.zeros((2, 2), dtype="float32"),
  ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=None),
  ... )
  >>> ds.crs
  ''
  

See Also

• :meth:dataset_like: Reuse another dataset's georeferencing instead of stating it.
• :meth:create: Allocate a raster filled with the no-data value when there is no array yet.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_array(
    cls,
    arr: np.ndarray,
    *,
    geo_ref: GeoReference,
    no_data_value: Any | list = DEFAULT_NO_DATA_VALUE,
    path: str | Path | None = None,
) -> Dataset:
    """Create a new dataset from an array.

    Args:
        arr (np.ndarray):
            Numpy array.
        geo_ref (GeoReference):
            How the array maps to space — an affine ``geo`` transform, or a
            ``top_left_corner`` + ``cell_size``, plus the ``epsg``. Required;
            a raster has to be placed somewhere. An ``epsg`` of `None` (or
            `0`) creates an ungeoreferenced raster that reports no CRS,
            rather than one silently stamped WGS 84.
        no_data_value (Any, optional):
            No data value to mask the cells out of the domain. The default is -9999.
        path (str, optional):
            Destination. `None` (default) builds the raster in memory;
            otherwise the extension selects the driver (``.tif`` -> GTiff,
            ``.nc`` -> netCDF, …). A ``.nc`` destination here writes a
            *classic* single-variable netCDF through the plain GDAL raster
            API; for a multi-variable, CF-attributed store use
            :meth:`pyramids.netcdf.NetCDF.from_array`, which goes through
            the multidimensional path.

    Returns:
        Dataset:
            Dataset object will be returned.

    Raises:
        ValueError: `geo_ref` carries neither a ``geo`` nor a complete
            ``top_left_corner`` + ``cell_size`` pair.
        DriverNotExistError: `path` has no extension, or one the driver
            catalog does not know.
        FileFormatNotSupportedError: `path`'s extension maps to a
            write-by-copy-only format such as PNG, which cannot be built
            with ``Create``.

    Examples:
        - Wrap a 2-D array, then read it back:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> arr = np.arange(6, dtype="float32").reshape(2, 3)
            >>> ds = Dataset.from_array(
            ...     arr, geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0))
            ... )
            >>> ds.read_array().tolist()
            [[0.0, 1.0, 2.0], [3.0, 4.0, 5.0]]
            >>> (ds.rows, ds.columns, ds.band_count)
            (2, 3, 1)

            ```
        - A leading axis becomes bands:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> stack = np.ones((3, 2, 2), dtype="int16")
            >>> ds = Dataset.from_array(
            ...     stack,
            ...     geo_ref=GeoReference(top_left_corner=(0.0, 2.0), cell_size=1.0),
            ... )
            >>> ds.band_count
            3

            ```
        - `epsg=None` builds an ungeoreferenced raster rather than
          silently claiming WGS 84:
            ```python
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> ds = Dataset.from_array(
            ...     np.zeros((2, 2), dtype="float32"),
            ...     geo_ref=GeoReference(geo=(0.0, 1.0, 0.0, 2.0, 0.0, -1.0), epsg=None),
            ... )
            >>> ds.crs
            ''

            ```

    See Also:
        - :meth:`dataset_like`: Reuse another dataset's georeferencing
          instead of stating it.
        - :meth:`create`: Allocate a raster filled with the no-data value
          when there is no array yet.
    """
    geo = geo_ref.resolve_geotransform()
    epsg = geo_ref.epsg

    if arr.ndim == 2:
        bands = 1
        rows = int(arr.shape[0])
        cols = int(arr.shape[1])
    else:
        bands = arr.shape[0]
        rows = int(arr.shape[1])
        cols = int(arr.shape[2])

    # The shared helper owns the CRS rules — the `sr_from_epsg` path for an
    # EPSG int/numeric string, the `sr_from_user_input` fallback that carries
    # a no-EPSG CRS such as geostationary through as WKT (#706), and the
    # empty-string result that leaves a deliberately ungeoreferenced raster
    # unprojected rather than stamping a default (ARC-26).
    crs_wkt = _crs_wkt_from_epsg(epsg)

    return cls._build_dataset(
        cols,
        rows,
        bands,
        numpy_to_gdal_dtype(arr),
        geo,
        crs_wkt,
        no_data_value,
        path=path,
        array=arr,
    )

dataset_like(src, array, path=None) classmethod

Create a new dataset like another dataset.

dataset_like method creates a Dataset from an array like another source dataset. The new dataset will have the same projection, coordinates or the top left corner of the original dataset, cell size, no_data_velue, and number of rows and columns. the array and the source dataset should have the same number of columns and rows

Parameters:

Name	Type	Description	Default
src	Dataset	source raster to get the spatial information	required
array	ndarray	data to store in the new dataset.	required
path	str	path to save the new dataset, if not given, the method will return in-memory dataset.	None

Returns:

Name	Type	Description
Dataset	Dataset	if the path is given, the method will save the new raster to the given path, else the method will return an in-memory dataset.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def dataset_like(
    cls,
    src: Dataset,
    array: np.ndarray,
    path: str | Path | None = None,
) -> Dataset:
    """Create a new dataset like another dataset.

    dataset_like method creates a Dataset from an array like another source dataset. The new dataset
    will have the same `projection`, `coordinates` or the `top left corner` of the original dataset,
    `cell size`, `no_data_velue`, and number of `rows` and `columns`.
    the array and the source dataset should have the same number of columns and rows

    Args:
        src (Dataset):
            source raster to get the spatial information
        array (ndarray):
            data to store in the new dataset.
        path (str, optional):
            path to save the new dataset, if not given, the method will return in-memory dataset.

    Returns:
        Dataset:
            if the `path` is given, the method will save the new raster to the given path, else the
            method will return an in-memory dataset.
    """
    if not isinstance(array, np.ndarray):
        raise TypeError("array should be of type numpy array")

    bands = 1 if array.ndim == 2 else array.shape[0]
    return cls._build_dataset(
        src.columns,
        src.rows,
        bands,
        numpy_to_gdal_dtype(array),
        src.geotransform,
        src.crs,
        src.no_data_value[0],
        path=path,
        array=array,
    )

from_band_files(files, *, band_names=None, align=False, resampling=None, no_data_value=INHERIT_NO_DATA, path=None) classmethod

Stack N single-band rasters into one multi-band :class:Dataset.

Each input file becomes one band, in order, with its name preserved. This is the natural target for an Earth Engine default download (<assetSlug>.<bandName>.tif — one file per band), a Landsat Collection-2 scene (per-band .TIF), or a Sentinel-2 SAFE (per-band JP2s).

By default all inputs must already share the same grid and CRS; pass align=True to resample mismatched rasters onto the first file's grid (nearest-neighbour, via :meth:align) — or resampling= to pick the algorithm, globally or per band. When the inputs have different numpy dtypes the output dtype is the smallest type that holds every input without a lossy cast.

Stacking copies the stores rather than computing anything: each band holds its source's stored values, and each source's CF packing (scale_factor / add_offset) is carried onto its band, so a packed input still reads back in physical units from the stack.

Parameters:

Name	Type	Description	Default
files	Sequence[str | Path]	Paths (or URLs / /vsi* strings) of the single-band rasters to stack. Order is preserved as band order.	required
band_names	list[str] | None	Explicit band names, one per file. When None (default) names are derived from the file names (<slug>.<band>.tif → <band>; dotless stems are kept whole; duplicates get a _<n> suffix).	None
align	bool	When False (default), a grid/CRS mismatch among the inputs raises :class:AlignmentError. When True, every input is resampled onto files[0]'s grid first.	False
resampling	str | dict[str, str] | None	Which algorithm that alignment uses (align=True only). None (default) keeps the historical nearest-neighbour behaviour for every band. A method name ("bilinear", "cubic", "average", … — any key of :data:~pyramids.base._utils.INTERPOLATION_METHODS) applies to every band, and a {band name: method} mapping sets it per band, so a continuous band can be interpolated while a categorical one (a cloud mask, a class map) stays on nearest. Bands a mapping leaves out keep nearest. Names are validated up front, and a band whose grid already matches files[0] skips the warp entirely, so its method is moot. Passing anything but None with align=False raises, rather than being silently ignored.	None
no_data_value	Any	No-data value stamped on the output bands. When omitted, it is inherited from the source rasters (a warning is issued if they disagree, and the first file's value wins; if no source declares one, the output has none). Pass an explicit value (including None for "no no-data sentinel") to override.	INHERIT_NO_DATA
path	str | Path | None	Output path, whose extension selects the driver as it does for every other factory (.tif -> GTiff, .nc -> netCDF, …). When None (default) the result is an in-memory dataset. Write-by-copy-only formats (.png, .jp2) are refused. One of the two internal write paths could produce them -- aligned, same-dtype inputs go through a VRT and CreateCopy -- but which path runs depends on align and on whether the sources share a dtype, neither of which says anything about the destination format. Accepting .png only sometimes would make the destination's legality depend on an unrelated argument, so both paths answer alike.	None

Returns:

Name	Type	Description
Dataset	Dataset	A multi-band dataset with band_count == len(files)
	Dataset	and band_names set.

Raises:

Type	Description
ValueError	files is empty, band_names length does not match files, an input has more than one band, or resampling names an unsupported algorithm / a band that is not being stacked.
TypeError	resampling is neither a string, a mapping nor None.
AlignmentError	align=False and the inputs do not share a grid/CRS.
CRSError	An input raster has no CRS.
DriverNotExistError	path has no extension, or one the driver catalog does not know.
FileFormatNotSupportedError	path's extension maps to a write-by-copy-only format, whichever write path the inputs take.

Examples:

• Stack three per-band GeoTIFFs into one 3-band dataset; band names come from the file names:

  >>> import numpy as np
  >>> import tempfile, os
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> d = tempfile.mkdtemp()
  >>> paths = []
  >>> triples = [("scene.B2.tif", 2), ("scene.B3.tif", 3), ("scene.B4.tif", 4)]
  >>> for name, val in triples:
  ...     p = os.path.join(d, name)
  ...     _ = Dataset.from_array(
  ...         np.full((4, 5), val, dtype="int16"),
  ...         geo_ref=GeoReference(
  ...             top_left_corner=(0, 0), cell_size=1.0, epsg=4326
  ...         ),
  ...         path=p,
  ...     ).close()
  ...     paths.append(p)
  >>> ds = Dataset.from_band_files(paths)
  >>> ds.band_count
  3
  >>> ds.band_names
  ['B2', 'B3', 'B4']
  >>> [int(ds.read_array(band=i).flat[0]) for i in range(3)]
  [2, 3, 4]
  

• Override the band names explicitly:

  >>> ds = Dataset.from_band_files(paths, band_names=["blue", "green", "red"])
  >>> ds.band_names
  ['blue', 'green', 'red']
  

• Mismatched grids are rejected unless align=True:

  >>> odd = os.path.join(d, "odd.tif")
  >>> _ = Dataset.from_array(
  ...     np.zeros((8, 9), dtype="int16"),
  ...     geo_ref=GeoReference(
  ...         top_left_corner=(0, 0), cell_size=0.5, epsg=4326
  ...     ),
  ...     path=odd,
  ... ).close()
  >>> try:
  ...     Dataset.from_band_files([paths[0], odd])
  ... except AlignmentError as exc:
  ...     print("align=True" in str(exc))
  True
  >>> aligned = Dataset.from_band_files([paths[0], odd], align=True)
  >>> aligned.band_count
  2
  >>> (aligned.rows, aligned.columns) == (
  ...     Dataset.read_file(paths[0]).rows,
  ...     Dataset.read_file(paths[0]).columns,
  ... )
  True
  

• Pick the resampling per band — interpolate the mismatched band while everything else stays on nearest:

  >>> mixed = Dataset.from_band_files(
  ...     [paths[0], odd], align=True, resampling={"odd": "bilinear"}
  ... )
  >>> mixed.band_names
  ['B2', 'odd']
  

See Also

• :meth:align: resample one dataset onto another's grid.
• :meth:from_array: build a dataset from a numpy array.
• :meth:pyramids.dataset.DatasetCollection.from_files: stack rasters along time instead of along bands.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_band_files(
    cls,
    files: Sequence[str | Path],
    *,
    band_names: list[str] | None = None,
    align: bool = False,
    resampling: str | dict[str, str] | None = None,
    no_data_value: Any = INHERIT_NO_DATA,
    path: str | Path | None = None,
) -> Dataset:
    """Stack N single-band rasters into one multi-band :class:`Dataset`.

    Each input file becomes one band, in order, with its name preserved.
    This is the natural target for an Earth Engine default download
    (`<assetSlug>.<bandName>.tif` — one file per band), a Landsat
    Collection-2 scene (per-band `.TIF`), or a Sentinel-2 SAFE
    (per-band JP2s).

    By default all inputs must already share the same grid and CRS;
    pass `align=True` to resample mismatched rasters onto the first
    file's grid (nearest-neighbour, via :meth:`align`) — or
    `resampling=` to pick the algorithm, globally or per band. When the
    inputs have different numpy dtypes the output dtype is the smallest
    type that holds every input without a lossy cast.

    Stacking copies the stores rather than computing anything: each band
    holds its source's stored values, and each source's CF packing
    (`scale_factor` / `add_offset`) is carried onto its band, so a packed
    input still reads back in physical units from the stack.

    Args:
        files: Paths (or URLs / `/vsi*` strings) of the single-band
            rasters to stack. Order is preserved as band order.
        band_names: Explicit band names, one per file. When `None`
            (default) names are derived from the file names
            (`<slug>.<band>.tif` → `<band>`; dotless stems are kept
            whole; duplicates get a `_<n>` suffix).
        align: When `False` (default), a grid/CRS mismatch among the
            inputs raises :class:`AlignmentError`. When `True`, every
            input is resampled onto `files[0]`'s grid first.
        resampling: Which algorithm that alignment uses (`align=True`
            only). `None` (default) keeps the historical nearest-neighbour
            behaviour for every band. A method name (`"bilinear"`,
            `"cubic"`, `"average"`, … — any key of
            :data:`~pyramids.base._utils.INTERPOLATION_METHODS`) applies to
            every band, and a `{band name: method}` mapping sets it per
            band, so a continuous band can be interpolated while a
            categorical one (a cloud mask, a class map) stays on nearest.
            Bands a mapping leaves out keep nearest. Names are validated up
            front, and a band whose grid already matches `files[0]` skips
            the warp entirely, so its method is moot. Passing anything but
            `None` with `align=False` raises, rather than being silently
            ignored.
        no_data_value: No-data value stamped on the output bands. When
            omitted, it is inherited from the source rasters (a warning
            is issued if they disagree, and the first file's value
            wins; if no source declares one, the output has none). Pass
            an explicit value (including `None` for "no no-data
            sentinel") to override.
        path: Output path, whose extension selects the driver as it does
            for every other factory (`.tif` -> GTiff, `.nc` ->
            netCDF, …). When `None` (default) the result is an
            in-memory dataset.

            Write-by-copy-only formats (`.png`, `.jp2`) are refused. One
            of the two internal write paths could produce them --
            aligned, same-dtype inputs go through a VRT and
            `CreateCopy` -- but which path runs depends on `align` and
            on whether the sources share a dtype, neither of which says
            anything about the destination format. Accepting `.png` only
            sometimes would make the destination's legality depend on an
            unrelated argument, so both paths answer alike.

    Returns:
        Dataset: A multi-band dataset with `band_count == len(files)`
        and `band_names` set.

    Raises:
        ValueError: `files` is empty, `band_names` length does not
            match `files`, an input has more than one band, or
            `resampling` names an unsupported algorithm / a band that is
            not being stacked.
        TypeError: `resampling` is neither a string, a mapping nor `None`.
        AlignmentError: `align=False` and the inputs do not share a
            grid/CRS.
        CRSError: An input raster has no CRS.
        DriverNotExistError: `path` has no extension, or one the driver
            catalog does not know.
        FileFormatNotSupportedError: `path`'s extension maps to a
            write-by-copy-only format, whichever write path the inputs
            take.

    Examples:
        - Stack three per-band GeoTIFFs into one 3-band dataset; band
          names come from the file names:
            ```python
            >>> import numpy as np
            >>> import tempfile, os
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> d = tempfile.mkdtemp()
            >>> paths = []
            >>> triples = [("scene.B2.tif", 2), ("scene.B3.tif", 3), ("scene.B4.tif", 4)]
            >>> for name, val in triples:
            ...     p = os.path.join(d, name)
            ...     _ = Dataset.from_array(
            ...         np.full((4, 5), val, dtype="int16"),
            ...         geo_ref=GeoReference(
            ...             top_left_corner=(0, 0), cell_size=1.0, epsg=4326
            ...         ),
            ...         path=p,
            ...     ).close()
            ...     paths.append(p)
            >>> ds = Dataset.from_band_files(paths)
            >>> ds.band_count
            3
            >>> ds.band_names
            ['B2', 'B3', 'B4']
            >>> [int(ds.read_array(band=i).flat[0]) for i in range(3)]
            [2, 3, 4]

            ```
        - Override the band names explicitly:
            ```python
            >>> ds = Dataset.from_band_files(paths, band_names=["blue", "green", "red"])
            >>> ds.band_names
            ['blue', 'green', 'red']

            ```
        - Mismatched grids are rejected unless `align=True`:
            ```python
            >>> odd = os.path.join(d, "odd.tif")
            >>> _ = Dataset.from_array(
            ...     np.zeros((8, 9), dtype="int16"),
            ...     geo_ref=GeoReference(
            ...         top_left_corner=(0, 0), cell_size=0.5, epsg=4326
            ...     ),
            ...     path=odd,
            ... ).close()
            >>> try:
            ...     Dataset.from_band_files([paths[0], odd])
            ... except AlignmentError as exc:
            ...     print("align=True" in str(exc))
            True
            >>> aligned = Dataset.from_band_files([paths[0], odd], align=True)
            >>> aligned.band_count
            2
            >>> (aligned.rows, aligned.columns) == (
            ...     Dataset.read_file(paths[0]).rows,
            ...     Dataset.read_file(paths[0]).columns,
            ... )
            True

            ```
        - Pick the resampling per band — interpolate the mismatched band
          while everything else stays on nearest:
            ```python
            >>> mixed = Dataset.from_band_files(
            ...     [paths[0], odd], align=True, resampling={"odd": "bilinear"}
            ... )
            >>> mixed.band_names
            ['B2', 'odd']

            ```

    See Also:
        - :meth:`align`: resample one dataset onto another's grid.
        - :meth:`from_array`: build a dataset from a numpy array.
        - :meth:`pyramids.dataset.DatasetCollection.from_files`: stack
          rasters along *time* instead of along *bands*.
    """
    resolved_paths = [str(_io._parse_path(str(p))) for p in files]
    if not resolved_paths:
        raise ValueError("from_band_files requires at least one file")

    datasets = [cls.read_file(p) for p in resolved_paths]
    for p, ds in zip(resolved_paths, datasets):
        if ds.band_count != 1:
            raise ValueError(
                f"{p!r} has {ds.band_count} bands; from_band_files expects exactly "
                "one band per file"
            )
        if not ds.crs:
            raise CRSError(f"{p!r} has no CRS; cannot stack rasters without a CRS")

    template = datasets[0]

    if band_names is not None:
        out_names = list(band_names)
        if len(out_names) != len(resolved_paths):
            raise ValueError(
                f"band_names has {len(out_names)} entries but {len(resolved_paths)} "
                "files were given"
            )
    else:
        out_names = _derive_band_names(resolved_paths)

    if resampling is not None and not align:
        raise ValueError(
            "resampling only applies to the align=True path, which is what "
            "resamples mismatched inputs onto the first file's grid; with "
            "align=False a mismatch raises instead. Pass align=True, or drop "
            "resampling."
        )
    band_methods = _resolve_band_resampling(resampling, out_names)

    if no_data_value is INHERIT_NO_DATA:
        resolved_nd: Any | None = inherit_no_data(
            [ds.no_data_value[0] for ds in datasets]
        )
    else:
        resolved_nd = no_data_value

    if not align:
        for p, ds in zip(resolved_paths[1:], datasets[1:]):
            if not template.spatial.same_grid(ds):
                raise AlignmentError(
                    f"{p!r} does not share the grid/CRS of {resolved_paths[0]!r}; "
                    "pass align=True to resample mismatched rasters onto the first "
                    "file's grid"
                )

    # gdal.BuildVRT(separate=True) does not promote dtypes (it truncates the
    # wider bands) — take that low-memory band-by-band path only when the
    # grids already match and every input shares one dtype. Otherwise read
    # the (possibly resampled) band arrays and let numpy pick the common dtype.
    uniform_dtype = len({ds.gdal_dtype[0] for ds in datasets}) == 1

    if align or not uniform_dtype:
        # Resolve the common output dtype up front so the output can be
        # allocated once and written band-by-band, instead of reading every
        # band, np.stacking them into a second full-cube copy, and writing the
        # lot — peak drops from ~O(N·grid) to one band + the output (ARC-50).
        target_np_dtype = np.result_type(*(ds.numpy_dtype[0] for ds in datasets))
        grid_template = None
        if align:
            # Resample every input onto the first file's grid in the promoted
            # dtype. Dataset.align adopts the alignment source's dtype, so cast
            # the template first to avoid truncating wider inputs (e.g. a float
            # band onto an int template).
            # `Dataset.from_array`, not `cls.from_array`: same reason as
            # `convert_units`. On a NetCDF subclass the override returns a
            # bandless Container, and this template is then read band-wise.
            grid_template = Dataset.from_array(
                template.read_array(band=0, unpack=False).astype(
                    target_np_dtype, copy=False
                ),
                # epsg is None only for a no-EPSG CRS reported as such (a NetCDF
                # geostationary grid); from_array raises CRSError on None, so
                # fall back to the WKT. No-op for a plain Dataset (#706).
                geo_ref=GeoReference(
                    geo=template.geotransform,
                    epsg=crs_spec(template.epsg, template.crs),
                ),
                no_data_value=resolved_nd,
            )
        obj = cls._build_dataset(
            template.columns,
            template.rows,
            len(resolved_paths),
            numpy_to_gdal_dtype(target_np_dtype),
            template.geotransform,
            template.crs,
            resolved_nd,
            path=path,
            array=None,
        )
        for band_i, ds_i in enumerate(datasets):
            # `unpack=False` throughout: this branch stacks the sources' stored
            # bands into one raster and carries each band's packing over below, which
            # is what the `BuildVRT` branch gets for free from `CreateCopy`. Reading
            # physical values instead would truncate them back into the promoted
            # *stored* dtype -- an int16 stack of packed inputs losing everything
            # after the point -- and leave the two branches disagreeing.
            if align and not template.spatial.same_grid(ds_i):
                arr = ds_i.align(
                    grid_template, method=band_methods[band_i]
                ).read_array(band=0, unpack=False)
            else:
                # Same grid (or the non-align mixed-dtype path): just cast to
                # the promoted dtype, which is lossless.
                arr = ds_i.read_array(band=0, unpack=False).astype(
                    target_np_dtype, copy=False
                )
            if align:
                # Dataset.align fills the warp fringe with the SOURCE's sentinel;
                # when sources disagree on nodata (first-wins resolved_nd + a
                # UserWarning) remap so the array matches the band's declared
                # nodata. A same-grid source skips the warp and is lossless.
                arr = _remap_nodata_to(arr, ds_i.no_data_value[0], resolved_nd)
            obj.raster.GetRasterBand(band_i + 1).WriteArray(arr)
            carry_band_packing(
                ds_i.raster.GetRasterBand(1),
                obj.raster.GetRasterBand(band_i + 1),
            )
            del arr
        obj._raster.FlushCache()
    else:
        vrt = gdal.BuildVRT("", resolved_paths, separate=True)
        if (
            vrt is None
        ):  # pragma: no cover - BuildVRT returns None only on bad input
            raise AlignmentError(
                f"gdal.BuildVRT could not stack {resolved_paths!r}"
            )
        if path is not None:
            # Resolve the driver from the extension like every other
            # factory. Hardcoding GTiff here is what forced the `.tif`-only
            # guard above: without it a `.nc` destination produced a GTiff
            # carrying a netCDF name, a file whose extension lies about its
            # contents. LZW is GTiff-specific, so it is applied only there.
            # Deliberately NOT `for_copy`, though this branch does use
            # `CreateCopy`. Which branch runs depends on `align` and on
            # whether the sources share a dtype -- things the caller cannot
            # easily predict -- so accepting `.png` here and refusing it on
            # the `Create` branch would make the destination's legality
            # depend on an unrelated argument. That is the same defect this
            # branch removed from `merge_rasters`; one gate for both paths.
            driver = resolve_output_driver(path)
            options = ["COMPRESS=LZW"] if driver == "GTiff" else []
            dst = gdal.GetDriverByName(driver).CreateCopy(
                str(path), vrt, strict=1, options=options
            )
        else:
            dst = gdal.GetDriverByName(MEMORY_DRIVER).CreateCopy("", vrt, strict=1)
        vrt = None
        # BuildVRT(separate=True) carries each source band's no-data through;
        # honour an explicit override (including ``None`` = drop it).
        for i in range(dst.RasterCount):
            band = dst.GetRasterBand(i + 1)
            if resolved_nd is None:
                band.DeleteNoDataValue()
            else:
                band.SetNoDataValue(float(resolved_nd))
        obj = cls(dst, access="write")

    obj.band_names = out_names
    obj._raster.FlushCache()
    return obj

from_archive(url_or_path, *, kind='auto', member_glob='*', band_names=None, align=False, no_data_value=INHERIT_NO_DATA, path=None) classmethod

Open every raster in an archive and merge them into one multi-band Dataset.

Lists the archive's members (locally or over the network — a remote ZIP is read via the chained /vsizip//vsicurl/… path) and hands them to :meth:from_band_files. For "one Dataset per member" (a temporal stack) use :meth:pyramids.dataset.DatasetCollection.from_archive instead.

GDAL driver open_options are not threaded through this band-stacking entry point; if a member needs a driver option, open it directly with :meth:read_file (which accepts open_options=).

The archive's file name must carry a recognised extension (.zip / .tar / .tar.gz / .gz) — GDAL's archive handlers key off the extension. An extension-less download URL (e.g. an Earth Engine getDownloadURL ending in :getPixels) must first be fetched and saved with a .zip name (or written to /vsimem/<name>.zip via :func:osgeo.gdal.FileFromMemBuffer) before calling this.

Parameters:

Name	Type	Description	Default
url_or_path	str | Path	Path or URL of the archive (.zip / .tar / .tar.gz / .gz).	required
kind	str	Archive kind — "zip", "tar" (also "tar.gz" / "tgz"), "gzip" (also "gz"), or "auto" (default, infer from the extension).	'auto'
member_glob	str	:mod:fnmatch pattern selecting which members to stack. Default "*" (all top-level members, sorted by name). Pass e.g. "*.tif" for an archive that also ships sidecar files.	'*'
band_names	list[str] | None	Explicit per-band names; None derives them from the member names (see :meth:from_band_files).	None
align	bool	When True, resample mismatched members onto the first member's grid instead of raising :class:AlignmentError.	False
no_data_value	Any	No-data value for the output bands; omitted means "inherit from the members".	INHERIT_NO_DATA
path	str | Path | None	Output .tif path; None keeps the result in memory.	None

Returns:

Name	Type	Description
Dataset	Dataset	A multi-band dataset, one band per matching archive member.

Raises:

Type	Description
FileFormatNotSupportedError	kind="auto" and the extension is not recognised, or the archive could not be listed.
FileNotFoundError	No member matched member_glob.
ValueError / AlignmentError / CRSError	As for :meth:from_band_files.

Examples:

• Stack the raster members of a local ZIP into one multi-band dataset (band names come from the member names):

  >>> import os, tempfile, zipfile
  >>> import numpy as np
  >>> from pyramids.dataset import Dataset, GeoReference
  >>> d = tempfile.mkdtemp()
  >>> members = []
  >>> pairs = [("scene.B2.tif", 2), ("scene.B3.tif", 3)]
  >>> for name, val in pairs:
  ...     p = os.path.join(d, name)
  ...     _ = Dataset.from_array(
  ...         np.full((4, 5), val, dtype="int16"),
  ...         geo_ref=GeoReference(
  ...             top_left_corner=(0, 0), cell_size=1.0, epsg=4326
  ...         ),
  ...         path=p,
  ...     ).close()
  ...     members.append(p)
  >>> zip_path = os.path.join(d, "download.zip")
  >>> with zipfile.ZipFile(zip_path, "w") as zf:
  ...     for m in members:
  ...         zf.write(m, arcname=os.path.basename(m))
  >>> ds = Dataset.from_archive(zip_path, member_glob="*.tif")
  >>> ds.band_count
  2
  >>> ds.band_names
  ['B2', 'B3']
  >>> [int(ds.read_array(band=i).flat[0]) for i in range(2)]
  [2, 3]
  

See Also

• :meth:from_band_files: stack a known list of single-band rasters.
• :meth:pyramids.dataset.DatasetCollection.from_archive: open each member as a separate timestep instead of merging them into bands.

Source code in src/pyramids/dataset/dataset.py

@classmethod
def from_archive(
    cls,
    url_or_path: str | Path,
    *,
    kind: str = "auto",
    member_glob: str = "*",
    band_names: list[str] | None = None,
    align: bool = False,
    no_data_value: Any = INHERIT_NO_DATA,
    path: str | Path | None = None,
) -> Dataset:
    """Open every raster in an archive and merge them into one multi-band Dataset.

    Lists the archive's members (locally or over the network — a remote ZIP
    is read via the chained ``/vsizip//vsicurl/…`` path) and hands them to
    :meth:`from_band_files`. For "one Dataset per member" (a temporal stack)
    use :meth:`pyramids.dataset.DatasetCollection.from_archive` instead.

    GDAL driver ``open_options`` are **not** threaded through this
    band-stacking entry point; if a member needs a driver option, open it
    directly with :meth:`read_file` (which accepts ``open_options=``).

    The archive's file name must carry a recognised extension (``.zip`` /
    ``.tar`` / ``.tar.gz`` / ``.gz``) — GDAL's archive handlers key off the
    extension. An extension-less download URL (e.g. an Earth Engine
    ``getDownloadURL`` ending in ``:getPixels``) must first be fetched and
    saved with a ``.zip`` name (or written to ``/vsimem/<name>.zip`` via
    :func:`osgeo.gdal.FileFromMemBuffer`) before calling this.

    Args:
        url_or_path: Path or URL of the archive (``.zip`` / ``.tar`` /
            ``.tar.gz`` / ``.gz``).
        kind: Archive kind — ``"zip"``, ``"tar"`` (also ``"tar.gz"`` /
            ``"tgz"``), ``"gzip"`` (also ``"gz"``), or ``"auto"`` (default,
            infer from the extension).
        member_glob: :mod:`fnmatch` pattern selecting which members to stack.
            Default ``"*"`` (all top-level members, sorted by name). Pass e.g.
            ``"*.tif"`` for an archive that also ships sidecar files.
        band_names: Explicit per-band names; ``None`` derives them from the
            member names (see :meth:`from_band_files`).
        align: When ``True``, resample mismatched members onto the first
            member's grid instead of raising :class:`AlignmentError`.
        no_data_value: No-data value for the output bands; omitted means
            "inherit from the members".
        path: Output ``.tif`` path; ``None`` keeps the result in memory.

    Returns:
        Dataset: A multi-band dataset, one band per matching archive member.

    Raises:
        FileFormatNotSupportedError: ``kind="auto"`` and the extension is
            not recognised, or the archive could not be listed.
        FileNotFoundError: No member matched ``member_glob``.
        ValueError / AlignmentError / CRSError: As for :meth:`from_band_files`.

    Examples:
        - Stack the raster members of a local ZIP into one multi-band dataset
          (band names come from the member names):
            ```python
            >>> import os, tempfile, zipfile
            >>> import numpy as np
            >>> from pyramids.dataset import Dataset, GeoReference
            >>> d = tempfile.mkdtemp()
            >>> members = []
            >>> pairs = [("scene.B2.tif", 2), ("scene.B3.tif", 3)]
            >>> for name, val in pairs:
            ...     p = os.path.join(d, name)
            ...     _ = Dataset.from_array(
            ...         np.full((4, 5), val, dtype="int16"),
            ...         geo_ref=GeoReference(
            ...             top_left_corner=(0, 0), cell_size=1.0, epsg=4326
            ...         ),
            ...         path=p,
            ...     ).close()
            ...     members.append(p)
            >>> zip_path = os.path.join(d, "download.zip")
            >>> with zipfile.ZipFile(zip_path, "w") as zf:
            ...     for m in members:
            ...         zf.write(m, arcname=os.path.basename(m))
            >>> ds = Dataset.from_archive(zip_path, member_glob="*.tif")
            >>> ds.band_count
            2
            >>> ds.band_names
            ['B2', 'B3']
            >>> [int(ds.read_array(band=i).flat[0]) for i in range(2)]
            [2, 3]

            ```

    See Also:
        - :meth:`from_band_files`: stack a known list of single-band rasters.
        - :meth:`pyramids.dataset.DatasetCollection.from_archive`: open each
          member as a separate timestep instead of merging them into bands.
    """
    dir_vsi = _io._archive_dir_vsi(url_or_path, kind)
    members = _io._archive_members(dir_vsi, member_glob)
    member_paths = [f"{dir_vsi}/{m}" for m in members]
    return cls.from_band_files(
        member_paths,
        band_names=band_names,
        align=align,
        no_data_value=no_data_value,
        path=path,
    )