rastr 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

rastr/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

rastr/create.py

@@ -13,7 +13,7 @@ from shapely.geometry import Point
 
 from rastr.gis.fishnet import create_point_grid, get_point_grid_shape
 from rastr.meta import RasterMeta
-from rastr.raster import RasterModel
+from rastr.raster import Raster
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -49,9 +49,9 @@ def raster_distance_from_polygon(
     *,
     raster_meta: RasterMeta,
     extent_polygon: Polygon | None = None,
-    snap_raster: RasterModel | None = None,
+    snap_raster: Raster | None = None,
     show_pbar: bool = False,
-) -> RasterModel:
+) -> Raster:
     """Make a raster where each cell's value is its centre's distance to a polygon.
 
     The raster should use a projected coordinate system.
@@ -116,7 +116,7 @@ def raster_distance_from_polygon(
     distances = np.where(mask, np.array([polygon.distance(pt) for pt in _pts]), np.nan)
     distance_raster = distances.reshape(x.shape)
 
-    return RasterModel(arr=distance_raster, raster_meta=raster_meta)
+    return Raster(arr=distance_raster, raster_meta=raster_meta)
 
 
 def _pbar(iterable: Iterable[_T], *, desc: str | None = None) -> Iterable[_T]:
@@ -130,11 +130,11 @@ def full_raster(
     *,
     bounds: tuple[float, float, float, float],
     fill_value: float = np.nan,
-) -> RasterModel:
+) -> Raster:
     """Create a raster with a specified fill value for all cells."""
     shape = get_point_grid_shape(bounds=bounds, cell_size=raster_meta.cell_size)
     arr = np.full(shape, fill_value, dtype=np.float32)
-    return RasterModel(arr=arr, raster_meta=raster_meta)
+    return Raster(arr=arr, raster_meta=raster_meta)
 
 
 def rasterize_gdf(
@@ -142,7 +142,7 @@ def rasterize_gdf(
     *,
     raster_meta: RasterMeta,
     target_cols: list[str],
-) -> list[RasterModel]:
+) -> list[Raster]:
     """Rasterize geometries from a GeoDataFrame.
 
     Supports polygons, points, linestrings, and other geometry types.
@@ -205,8 +205,8 @@ def rasterize_gdf(
             dtype=np.float32,
         )
 
-        # Create RasterModel
-        raster = RasterModel(arr=raster_array, raster_meta=raster_meta)
+        # Create Raster
+        raster = Raster(arr=raster_array, raster_meta=raster_meta)
         rasters.append(raster)
 
     return rasters
@@ -286,7 +286,7 @@ def raster_from_point_cloud(
     *,
     crs: CRS | str,
     cell_size: float | None = None,
-) -> RasterModel:
+) -> Raster:
     """Create a raster from a point cloud via interpolation.
 
     Interpolation is only possible within the convex hull of the points. Outside of
@@ -320,8 +320,18 @@ def raster_from_point_cloud(
     if len(x) != len(y) or len(x) != len(z):
         msg = "Length of x, y, and z must be equal."
         raise ValueError(msg)
+    xy_finite_mask = np.isfinite(x) & np.isfinite(y)
+    if np.any(~xy_finite_mask):
+        msg = "Some (x,y) points are NaN-valued or non-finite. These will be ignored."
+        warnings.warn(msg, stacklevel=2)
+        x = x[xy_finite_mask]
+        y = y[xy_finite_mask]
+        z = z[xy_finite_mask]
     if len(x) < 3:
-        msg = "At least three (x, y, z) points are required to triangulate a surface."
+        msg = (
+            "At least three valid (x, y, z) points are required to triangulate a "
+            "surface."
+        )
         raise ValueError(msg)
     # Check for duplicate (x, y) points
     xy_points = np.column_stack((x, y))
@@ -332,8 +342,8 @@ def raster_from_point_cloud(
     # Heuristic for cell size if not provided
     if cell_size is None:
         # Half the 5th percentile of nearest neighbor distances between the (x,y) points
-        tree = KDTree(np.column_stack((x, y)))
-        distances, _ = tree.query(np.column_stack((x, y)), k=2)
+        tree = KDTree(xy_points)
+        distances, _ = tree.query(xy_points, k=2)
         distances: np.ndarray
         cell_size = float(np.percentile(distances[distances > 0], 5)) / 2
 
@@ -378,4 +388,4 @@ def raster_from_point_cloud(
         crs=crs,
         transform=transform,
     )
-    return RasterModel(arr=arr, raster_meta=raster_meta)
+    return Raster(arr=arr, raster_meta=raster_meta)

rastr/io.py

@@ -9,7 +9,7 @@ import rasterio.merge
 from pyproj.crs.crs import CRS
 
 from rastr.meta import RasterMeta
-from rastr.raster import RasterModel
+from rastr.raster import Raster
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
@@ -17,7 +17,7 @@ if TYPE_CHECKING:
 
 def read_raster_inmem(
     raster_path: Path | str, *, crs: CRS | str | None = None
-) -> RasterModel:
+) -> Raster:
     """Read raster data from a file and return an in-memory Raster object."""
     crs = CRS.from_user_input(crs) if crs is not None else None
 
@@ -35,13 +35,13 @@ def read_raster_inmem(
             arr[arr == nodata] = np.nan
 
     raster_meta = RasterMeta(cell_size=cell_size, crs=crs, transform=transform)
-    raster_obj = RasterModel(arr=arr, raster_meta=raster_meta)
+    raster_obj = Raster(arr=arr, raster_meta=raster_meta)
     return raster_obj
 
 
 def read_raster_mosaic_inmem(
     mosaic_dir: Path | str, *, glob: str = "*.tif", crs: CRS | None = None
-) -> RasterModel:
+) -> Raster:
     """Read a raster mosaic from a directory and return an in-memory Raster object.
 
     This assumes that all rasters have the same metadata, e.g. coordinate system,
@@ -87,7 +87,7 @@ def read_raster_mosaic_inmem(
         arr = arr.squeeze().astype(np.float64)
 
         raster_meta = RasterMeta(cell_size=cell_size, crs=crs, transform=transform)
-        raster_obj = RasterModel(arr=arr, raster_meta=raster_meta)
+        raster_obj = Raster(arr=arr, raster_meta=raster_meta)
         return raster_obj
     finally:
         for src in sources:

rastr/raster.py

@@ -4,17 +4,20 @@ from __future__ import annotations
 
 import importlib.util
 import warnings
+from collections.abc import Collection
 from contextlib import contextmanager
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, overload
 
 import numpy as np
 import numpy.ma
+import rasterio.features
 import rasterio.plot
 import rasterio.sample
 import rasterio.transform
 import skimage.measure
 from pydantic import BaseModel, InstanceOf, field_validator
+from pyproj import Transformer
 from pyproj.crs.crs import CRS
 from rasterio.enums import Resampling
 from rasterio.io import MemoryFile
@@ -29,10 +32,14 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Generator
 
     import geopandas as gpd
+    from affine import Affine
+    from branca.colormap import LinearColormap as BrancaLinearColormap
     from folium import Map
     from matplotlib.axes import Axes
+    from matplotlib.image import AxesImage
     from numpy.typing import ArrayLike, NDArray
     from rasterio.io import BufferedDatasetWriter, DatasetReader, DatasetWriter
+    from shapely import MultiPolygon
     from typing_extensions import Self
 
 try:
@@ -45,17 +52,28 @@ FOLIUM_INSTALLED = importlib.util.find_spec("folium") is not None
 BRANCA_INSTALLED = importlib.util.find_spec("branca") is not None
 MATPLOTLIB_INSTALLED = importlib.util.find_spec("matplotlib") is not None
 
+CONTOUR_PERTURB_EPS = 1e-10
+
 
 class RasterCellArrayShapeError(ValueError):
     """Custom error for invalid raster cell array shapes."""
 
 
-class RasterModel(BaseModel):
+class Raster(BaseModel):
     """2-dimensional raster and metadata."""
 
     arr: InstanceOf[np.ndarray]
     raster_meta: RasterMeta
 
+    @field_validator("arr")
+    @classmethod
+    def check_2d_array(cls, v: NDArray) -> NDArray:
+        """Validator to ensure the cell array is 2D."""
+        if v.ndim != 2:
+            msg = "Cell array must be 2D"
+            raise RasterCellArrayShapeError(msg)
+        return v
+
     @property
     def meta(self) -> RasterMeta:
         """Alias for raster_meta."""
@@ -80,6 +98,16 @@ class RasterModel(BaseModel):
         """Set the CRS via meta."""
         self.meta.crs = value
 
+    @property
+    def transform(self) -> Affine:
+        """Convenience property to access the transform via meta."""
+        return self.meta.transform
+
+    @transform.setter
+    def transform(self, value: Affine) -> None:
+        """Set the transform via meta."""
+        self.meta.transform = value
+
     def __init__(
         self,
         *,
@@ -108,14 +136,25 @@ class RasterModel(BaseModel):
         super().__init__(arr=arr, raster_meta=raster_meta)
 
     def __eq__(self, other: object) -> bool:
-        """Check equality of two RasterModel objects."""
-        if not isinstance(other, RasterModel):
+        """Check equality of two Raster objects."""
+        if not isinstance(other, Raster):
             return NotImplemented
         return (
             np.array_equal(self.arr, other.arr)
             and self.raster_meta == other.raster_meta
         )
 
+    def is_like(self, other: Raster) -> bool:
+        """Check if two Raster objects have the same metadata and shape.
+
+        Args:
+            other: Another Raster to compare with.
+
+        Returns:
+            True if both rasters have the same meta and shape attributes.
+        """
+        return self.meta == other.meta and self.shape == other.shape
+
     __hash__ = BaseModel.__hash__
 
     def __add__(self, other: float | Self) -> Self:
@@ -123,7 +162,7 @@ class RasterModel(BaseModel):
         if isinstance(other, float | int):
             new_arr = self.arr + other
             return cls(arr=new_arr, raster_meta=self.raster_meta)
-        elif isinstance(other, RasterModel):
+        elif isinstance(other, Raster):
             if self.raster_meta != other.raster_meta:
                 msg = (
                     "Rasters must have the same metadata (e.g. CRS, cell size, etc.) "
@@ -149,7 +188,7 @@ class RasterModel(BaseModel):
         if isinstance(other, float | int):
             new_arr = self.arr * other
             return cls(arr=new_arr, raster_meta=self.raster_meta)
-        elif isinstance(other, RasterModel):
+        elif isinstance(other, Raster):
             if self.raster_meta != other.raster_meta:
                 msg = (
                     "Rasters must have the same metadata (e.g. CRS, cell size, etc.) "
@@ -172,7 +211,7 @@ class RasterModel(BaseModel):
         if isinstance(other, float | int):
             new_arr = self.arr / other
             return cls(arr=new_arr, raster_meta=self.raster_meta)
-        elif isinstance(other, RasterModel):
+        elif isinstance(other, Raster):
             if self.raster_meta != other.raster_meta:
                 msg = (
                     "Rasters must have the same metadata (e.g. CRS, cell size, etc.) "
@@ -222,7 +261,7 @@ class RasterModel(BaseModel):
         """Create a rasterio in-memory dataset from the Raster object.
 
         Example:
-            >>> raster = RasterModel.example()
+            >>> raster = Raster.example()
             >>> with raster.to_rasterio_dataset() as dataset:
             >>>     ...
         """
@@ -248,12 +287,30 @@ class RasterModel(BaseModel):
         finally:
             memfile.close()
 
+    @overload
+    def sample(
+        self,
+        xy: Collection[tuple[float, float]] | Collection[Point] | ArrayLike,
+        *,
+        na_action: Literal["raise", "ignore"] = "raise",
+    ) -> NDArray: ...
+    @overload
     def sample(
         self,
-        xy: list[tuple[float, float]] | list[Point] | ArrayLike,
+        xy: tuple[float, float] | Point,
         *,
         na_action: Literal["raise", "ignore"] = "raise",
-    ) -> NDArray[np.float64]:
+    ) -> float: ...
+    def sample(
+        self,
+        xy: Collection[tuple[float, float]]
+        | Collection[Point]
+        | ArrayLike
+        | tuple[float, float]
+        | Point,
+        *,
+        na_action: Literal["raise", "ignore"] = "raise",
+    ) -> NDArray | float:
         """Sample raster values at GeoSeries locations and return sampled values.
 
         Args:
@@ -270,13 +327,30 @@ class RasterModel(BaseModel):
         # https://rdrn.me/optimising-sampling/
 
         # Convert shapely Points to coordinate tuples if needed
-        if isinstance(xy, (list, tuple)):
-            xy = [_get_xy_tuple(point) for point in xy]
+        if isinstance(xy, Point):
+            xy = [(xy.x, xy.y)]
+            singleton = True
+        elif (
+            isinstance(xy, Collection)
+            and len(xy) > 0
+            and isinstance(next(iter(xy)), Point)
+        ):
+            xy = [(point.x, point.y) for point in xy]  # pyright: ignore[reportAttributeAccessIssue]
+            singleton = False
+        elif (
+            isinstance(xy, tuple)
+            and len(xy) == 2
+            and isinstance(next(iter(xy)), (float, int))
+        ):
+            xy = [xy]  # pyright: ignore[reportAssignmentType]
+            singleton = True
+        else:
+            singleton = False
 
         xy = np.asarray(xy, dtype=float)
 
-        # Short-circuit
         if len(xy) == 0:
+            # Short-circuit
             return np.array([], dtype=float)
 
         # Create in-memory rasterio dataset from the incumbent Raster object
@@ -326,6 +400,10 @@ class RasterModel(BaseModel):
                     axis=0,
                 )
 
+        if singleton:
+            (raster_value,) = raster_values
+            return raster_value
+
         return raster_values
 
     @property
@@ -354,13 +432,16 @@ class RasterModel(BaseModel):
             ]
         )
 
-    def explore(
+    def explore(  # noqa: PLR0913 c.f. geopandas.explore which also has many input args
         self,
         *,
         m: Map | None = None,
         opacity: float = 1.0,
-        colormap: str = "viridis",
+        colormap: str
+        | Callable[[float], tuple[float, float, float, float]] = "viridis",
         cbar_label: str | None = None,
+        vmin: float | None = None,
+        vmax: float | None = None,
     ) -> Map:
         """Display the raster on a folium map."""
         if not FOLIUM_INSTALLED or not MATPLOTLIB_INSTALLED:
@@ -368,39 +449,44 @@ class RasterModel(BaseModel):
             raise ImportError(msg)
 
         import folium.raster_layers
-        import geopandas as gpd
         import matplotlib as mpl
 
         if m is None:
             m = folium.Map()
 
-        rgba_map: Callable[[float], tuple[float, float, float, float]] = mpl.colormaps[
-            colormap
-        ]
+        if vmin is not None and vmax is not None and vmax <= vmin:
+            msg = "'vmin' must be less than 'vmax'."
+            raise ValueError(msg)
+
+        if isinstance(colormap, str):
+            colormap = mpl.colormaps[colormap]
 
-        # Cast to GDF to facilitate converting bounds to WGS84
+        # Transform bounds to WGS84 using pyproj directly
         wgs84_crs = CRS.from_epsg(4326)
-        gdf = gpd.GeoDataFrame(geometry=[self.bbox], crs=self.raster_meta.crs).to_crs(
-            wgs84_crs
+        transformer = Transformer.from_crs(
+            self.raster_meta.crs, wgs84_crs, always_xy=True
         )
-        xmin, ymin, xmax, ymax = gdf.total_bounds
 
-        arr = np.array(self.arr)
+        # Get the corner points of the bounding box
+        raster_xmin, raster_ymin, raster_xmax, raster_ymax = self.bounds
+        corner_points = [
+            (raster_xmin, raster_ymin),
+            (raster_xmin, raster_ymax),
+            (raster_xmax, raster_ymax),
+            (raster_xmax, raster_ymin),
+        ]
+
+        # Transform all corner points to WGS84
+        transformed_points = [transformer.transform(x, y) for x, y in corner_points]
 
-        # Normalize the data to the range [0, 1] as this is the cmap range
-        with warnings.catch_warnings():
-            warnings.filterwarnings(
-                "ignore",
-                message="All-NaN slice encountered",
-                category=RuntimeWarning,
-            )
-            min_val = np.nanmin(arr)
-            max_val = np.nanmax(arr)
+        # Find the bounding box of the transformed points
+        transformed_xs, transformed_ys = zip(*transformed_points, strict=True)
+        xmin, xmax = min(transformed_xs), max(transformed_xs)
+        ymin, ymax = min(transformed_ys), max(transformed_ys)
 
-        if max_val > min_val:  # Prevent division by zero
-            arr = (arr - min_val) / (max_val - min_val)
-        else:
-            arr = np.zeros_like(arr)  # In case all values are the same
+        # Normalize the array to [0, 1] for colormap mapping
+        _vmin, _vmax = _get_vmin_vmax(self, vmin=vmin, vmax=vmax)
+        arr = self.normalize(vmin=_vmin, vmax=_vmax).arr
 
         # Finally, need to determine whether to flip the image based on negative Affine
         # coefficients
@@ -411,11 +497,12 @@ class RasterModel(BaseModel):
         if flip_y:
             arr = np.flip(arr, axis=0)
 
+        bounds = [[ymin, xmin], [ymax, xmax]]
         img = folium.raster_layers.ImageOverlay(
             image=arr,
-            bounds=[[ymin, xmin], [ymax, xmax]],
+            bounds=bounds,
             opacity=opacity,
-            colormap=rgba_map,
+            colormap=colormap,
             mercator_project=True,
         )
 
@@ -423,26 +510,39 @@ class RasterModel(BaseModel):
 
         # Add a colorbar legend
         if BRANCA_INSTALLED:
-            from branca.colormap import LinearColormap as BrancaLinearColormap
-            from matplotlib.colors import to_hex
-
-            # Determine legend data range in original units
-            vmin = float(min_val) if np.isfinite(min_val) else 0.0
-            vmax = float(max_val) if np.isfinite(max_val) else 1.0
-            if vmax <= vmin:
-                vmax = vmin + 1.0
-
-            sample_points = np.linspace(0, 1, rgba_map.N)
-            colors = [to_hex(rgba_map(x)) for x in sample_points]
-            legend = BrancaLinearColormap(colors=colors, vmin=vmin, vmax=vmax)
+            cbar = _map_colorbar(colormap=colormap, vmin=_vmin, vmax=_vmax)
             if cbar_label:
-                legend.caption = cbar_label
-            legend.add_to(m)
+                cbar.caption = cbar_label
+            cbar.add_to(m)
 
-        m.fit_bounds([[ymin, xmin], [ymax, xmax]])
+        m.fit_bounds(bounds)
 
         return m
 
+    def normalize(
+        self, *, vmin: float | None = None, vmax: float | None = None
+    ) -> Self:
+        """Normalize the raster values to the range [0, 1].
+
+        If custom vmin and vmax values are provided, values below vmin will be set to 0,
+        and values above vmax will be set to 1.
+
+        Args:
+            vmin: Minimum value for normalization. Values below this will be set to 0.
+                  If None, the minimum value in the array is used.
+            vmax: Maximum value for normalization. Values above this will be set to 1.
+                  If None, the maximum value in the array is used.
+        """
+        _vmin, _vmax = _get_vmin_vmax(self, vmin=vmin, vmax=vmax)
+
+        arr = self.arr.copy()
+        if _vmax > _vmin:
+            arr = (arr - _vmin) / (_vmax - _vmin)
+            arr = np.clip(arr, 0, 1)
+        else:
+            arr = np.zeros_like(arr)
+        return self.__class__(arr=arr, raster_meta=self.raster_meta)
+
     def to_clipboard(self) -> None:
         """Copy the raster cell array to the clipboard."""
         import pandas as pd
@@ -456,8 +556,22 @@ class RasterModel(BaseModel):
         cbar_label: str | None = None,
         basemap: bool = False,
         cmap: str = "viridis",
+        suppressed: Collection[float] | float = tuple(),
+        **kwargs: Any,
     ) -> Axes:
-        """Plot the raster on a matplotlib axis."""
+        """Plot the raster on a matplotlib axis.
+
+        Args:
+            ax: A matplotlib axes object to plot on. If None, a new figure will be
+                created.
+            cbar_label: Label for the colorbar. If None, no label is added.
+            basemap: Whether to add a basemap. Currently not implemented.
+            cmap: Colormap to use for the plot.
+            suppressed: Values to suppress from the plot (i.e. not display). This can be
+                        useful for zeroes especially.
+            **kwargs: Additional keyword arguments to pass to `rasterio.plot.show()`.
+                      This includes parameters like `alpha` for transparency.
+        """
         if not MATPLOTLIB_INSTALLED:
             msg = "The 'matplotlib' package is required for 'plot()'."
             raise ImportError(msg)
@@ -465,6 +579,8 @@ class RasterModel(BaseModel):
         from matplotlib import pyplot as plt
         from mpl_toolkits.axes_grid1 import make_axes_locatable
 
+        suppressed = np.array(suppressed)
+
         if ax is None:
             _, _ax = plt.subplots()
             _ax: Axes
@@ -474,33 +590,34 @@ class RasterModel(BaseModel):
             msg = "Basemap plotting is not yet implemented."
             raise NotImplementedError(msg)
 
-        arr = self.arr.copy()
+        model = self.model_copy()
+        model.arr = model.arr.copy()
 
-        # Get extent of the non-zero values in array index coordinates
-        (x_nonzero,) = np.nonzero(arr.any(axis=0))
-        (y_nonzero,) = np.nonzero(arr.any(axis=1))
+        # Get extent of the unsuppressed values in array index coordinates
+        suppressed_mask = np.isin(model.arr, suppressed)
+        (x_unsuppressed,) = np.nonzero((~suppressed_mask).any(axis=0))
+        (y_unsuppressed,) = np.nonzero((~suppressed_mask).any(axis=1))
 
-        if len(x_nonzero) == 0 or len(y_nonzero) == 0:
-            msg = "Raster contains no non-zero values; cannot plot."
+        if len(x_unsuppressed) == 0 or len(y_unsuppressed) == 0:
+            msg = "Raster contains no unsuppressed values; cannot plot."
             raise ValueError(msg)
 
-        min_x_nonzero = np.min(x_nonzero)
-        max_x_nonzero = np.max(x_nonzero)
-        min_y_nonzero = np.min(y_nonzero)
-        max_y_nonzero = np.max(y_nonzero)
+        # N.B. these are array index coordinates, so np.min and np.max are safe since
+        # they cannot encounter NaN values.
+        min_x_unsuppressed = np.min(x_unsuppressed)
+        max_x_unsuppressed = np.max(x_unsuppressed)
+        min_y_unsuppressed = np.min(y_unsuppressed)
+        max_y_unsuppressed = np.max(y_unsuppressed)
 
         # Transform to raster CRS
-        x1, y1 = self.raster_meta.transform * (min_x_nonzero, min_y_nonzero)  # type: ignore[reportAssignmentType] overloaded tuple size in affine
-        x2, y2 = self.raster_meta.transform * (max_x_nonzero, max_y_nonzero)  # type: ignore[reportAssignmentType]
+        x1, y1 = self.raster_meta.transform * (min_x_unsuppressed, min_y_unsuppressed)  # type: ignore[reportAssignmentType] overloaded tuple size in affine
+        x2, y2 = self.raster_meta.transform * (max_x_unsuppressed, max_y_unsuppressed)  # type: ignore[reportAssignmentType]
         xmin, xmax = sorted([x1, x2])
         ymin, ymax = sorted([y1, y2])
 
-        arr[arr == 0] = np.nan
+        model.arr[suppressed_mask] = np.nan
 
-        with self.to_rasterio_dataset() as dataset:
-            img, *_ = rasterio.plot.show(
-                dataset, with_bounds=True, ax=ax, cmap=cmap
-            ).get_images()
+        img, *_ = model.rio_show(ax=ax, cmap=cmap, with_bounds=True, **kwargs)
 
         ax.set_xlim(xmin, xmax)
         ax.set_ylim(ymin, ymax)
@@ -516,6 +633,20 @@ class RasterModel(BaseModel):
             fig.colorbar(img, label=cbar_label, cax=cax)
         return ax
 
+    def rio_show(self, **kwargs: Any) -> list[AxesImage]:
+        """Plot the raster using rasterio's built-in plotting function.
+
+        This is useful for lower-level access to rasterio's plotting capabilities.
+        Generally, the `plot()` method is preferred for most use cases.
+
+        Args:
+            **kwargs: Keyword arguments to pass to `rasterio.plot.show()`. This includes
+            parameters like `alpha` for transparency, and `with_bounds` to control
+            whether to plot in spatial coordinates or array index coordinates.
+        """
+        with self.to_rasterio_dataset() as dataset:
+            return rasterio.plot.show(dataset, **kwargs).get_images()
+
     def as_geodataframe(self, name: str = "value") -> gpd.GeoDataFrame:
         """Create a GeoDataFrame representation of the raster."""
         import geopandas as gpd
@@ -576,7 +707,7 @@ class RasterModel(BaseModel):
 
     @classmethod
     def example(cls) -> Self:
-        """Create an example RasterModel."""
+        """Create an example Raster."""
         # Peaks dataset style example
         n = 256
         x = np.linspace(-3, 3, n)
@@ -625,6 +756,59 @@ class RasterModel(BaseModel):
         new_raster.arr = np.asarray(new_arr)
         return new_raster
 
+    def max(self) -> float:
+        """Get the maximum value in the raster, ignoring NaN values.
+
+        Returns:
+            The maximum value in the raster. Returns NaN if all values are NaN.
+        """
+        return float(np.nanmax(self.arr))
+
+    def min(self) -> float:
+        """Get the minimum value in the raster, ignoring NaN values.
+
+        Returns:
+            The minimum value in the raster. Returns NaN if all values are NaN.
+        """
+        return float(np.nanmin(self.arr))
+
+    def mean(self) -> float:
+        """Get the mean value in the raster, ignoring NaN values.
+
+        Returns:
+            The mean value in the raster. Returns NaN if all values are NaN.
+        """
+        return float(np.nanmean(self.arr))
+
+    def std(self) -> float:
+        """Get the standard deviation of values in the raster, ignoring NaN values.
+
+        Returns:
+            The standard deviation of the raster. Returns NaN if all values are NaN.
+        """
+        return float(np.nanstd(self.arr))
+
+    def quantile(self, q: float) -> float:
+        """Get the specified quantile value in the raster, ignoring NaN values.
+
+        Args:
+            q: Quantile to compute, must be between 0 and 1 inclusive.
+
+        Returns:
+            The quantile value. Returns NaN if all values are NaN.
+        """
+        return float(np.nanquantile(self.arr, q))
+
+    def median(self) -> float:
+        """Get the median value in the raster, ignoring NaN values.
+
+        This is equivalent to quantile(0.5).
+
+        Returns:
+            The median value in the raster. Returns NaN if all values are NaN.
+        """
+        return float(np.nanmedian(self.arr))
+
     def fillna(self, value: float) -> Self:
         """Fill NaN values in the raster with a specified value.
 
@@ -676,9 +860,17 @@ class RasterModel(BaseModel):
         all_levels = []
         all_geoms = []
         for level in levels:
+            # If this is the maximum or minimum level, perturb it ever-so-slightly to
+            # ensure we get contours at the edges of the raster
+            perturbed_level = level
+            if level == self.max():
+                perturbed_level -= CONTOUR_PERTURB_EPS
+            elif level == self.min():
+                perturbed_level += CONTOUR_PERTURB_EPS
+
             contours = skimage.measure.find_contours(
                 self.arr,
-                level=level,
+                level=perturbed_level,
             )
 
             # Construct shapely LineString objects
@@ -751,9 +943,75 @@ class RasterModel(BaseModel):
 
         return raster
 
+    def pad(self, width: float, *, value: float = np.nan) -> Self:
+        """Extend the raster by adding a constant fill value around the edges.
+
+        By default, the padding value is NaN, but this can be changed via the
+        `value` parameter.
+
+        This grows the raster by adding padding around all edges. New cells are
+        filled with the constant `value`.
+
+        If the width is not an exact multiple of the cell size, the padding may be
+        slightly larger than the specified width, i.e. the value is rounded up to
+        the nearest whole number of cells.
+
+        Args:
+            width: The width of the padding, in the same units as the raster CRS
+                   (e.g. meters). This defines how far from the edge the padding
+                   extends.
+            value: The constant value to use for padding. Default is NaN.
+        """
+        cell_size = self.raster_meta.cell_size
+
+        # Calculate number of cells to pad in each direction
+        pad_cells = int(np.ceil(width / cell_size))
+
+        # Get current bounds
+        xmin, ymin, xmax, ymax = self.bounds
+
+        # Calculate new bounds with padding
+        new_xmin = xmin - (pad_cells * cell_size)
+        new_ymin = ymin - (pad_cells * cell_size)
+        new_xmax = xmax + (pad_cells * cell_size)
+        new_ymax = ymax + (pad_cells * cell_size)
+
+        # Create padded array
+        new_height = self.arr.shape[0] + 2 * pad_cells
+        new_width = self.arr.shape[1] + 2 * pad_cells
+
+        # Create new array filled with the padding value
+        padded_arr = np.full((new_height, new_width), value, dtype=self.arr.dtype)
+
+        # Copy original array into the center of the padded array
+        padded_arr[
+            pad_cells : pad_cells + self.arr.shape[0],
+            pad_cells : pad_cells + self.arr.shape[1],
+        ] = self.arr
+
+        # Create new transform for the padded raster
+        new_transform = rasterio.transform.from_bounds(
+            west=new_xmin,
+            south=new_ymin,
+            east=new_xmax,
+            north=new_ymax,
+            width=new_width,
+            height=new_height,
+        )
+
+        # Create new raster metadata
+        new_meta = RasterMeta(
+            cell_size=cell_size,
+            crs=self.raster_meta.crs,
+            transform=new_transform,
+        )
+
+        return self.__class__(arr=padded_arr, raster_meta=new_meta)
+
     def crop(
         self,
         bounds: tuple[float, float, float, float],
+        *,
         strategy: Literal["underflow", "overflow"] = "underflow",
     ) -> Self:
         """Crop the raster to the specified bounds as (minx, miny, maxx, maxy).
@@ -767,7 +1025,7 @@ class RasterModel(BaseModel):
                         remains covered with cells.
 
         Returns:
-            A new RasterModel instance cropped to the specified bounds.
+            A new Raster instance cropped to the specified bounds.
         """
 
         minx, miny, maxx, maxy = bounds
@@ -827,6 +1085,141 @@ class RasterModel(BaseModel):
         )
         return cls(arr=cropped_arr, raster_meta=new_meta)
 
+    def taper_border(self, width: float, *, limit: float = 0.0) -> Self:
+        """Taper values to a limiting value around the border of the raster.
+
+        By default, the borders are tapered to zero, but this can be changed via the
+        `limit` parameter.
+
+        This keeps the raster size the same, overwriting values in the border area.
+        To instead grow the raster, consider using `pad()` followed by `taper_border()`.
+
+        The tapering is linear from the cell centres around the border of the raster,
+        so the value at the edge of the raster will be equal to `limit`.
+
+        Args:
+            width: The width of the taper, in the same units as the raster CRS
+                   (e.g. meters). This defines how far from the edge the tapering
+                   starts.
+            limit: The limiting value to taper to at the edges. Default is zero.
+        """
+
+        # Determine the width in cell units (possibly fractional)
+        cell_size = self.raster_meta.cell_size
+        width_in_cells = width / cell_size
+
+        # Calculate the distance from the edge in cell units
+        arr_height, arr_width = self.arr.shape
+        y_indices, x_indices = np.indices((int(arr_height), int(arr_width)))
+        dist_from_left = x_indices
+        dist_from_right = arr_width - 1 - x_indices
+        dist_from_top = y_indices
+        dist_from_bottom = arr_height - 1 - y_indices
+        dist_from_edge = np.minimum.reduce(
+            [dist_from_left, dist_from_right, dist_from_top, dist_from_bottom]
+        )
+
+        # Mask the arrays to only the area within the width from the edge, rounding up
+        mask = dist_from_edge < np.ceil(width_in_cells)
+        masked_dist_arr = np.where(mask, dist_from_edge, np.nan)
+        masked_arr = np.where(mask, self.arr, np.nan)
+
+        # Calculate the tapering factor based on the distance from the edge
+        taper_factor = np.clip(masked_dist_arr / width_in_cells, 0.0, 1.0)
+        tapered_values = limit + (masked_arr - limit) * taper_factor
+
+        # Create the new raster array
+        new_arr = self.arr.copy()
+        new_arr[mask] = tapered_values[mask]
+        new_raster = self.model_copy()
+        new_raster.arr = new_arr
+
+        return new_raster
+
+    def clip(
+        self,
+        polygon: Polygon | MultiPolygon,
+        *,
+        strategy: Literal["centres"] = "centres",
+    ) -> Self:
+        """Clip the raster to the specified polygon, replacing cells outside with NaN.
+
+        The clipping strategy determines how to handle cells that are partially
+        within the polygon. Currently, only the 'centres' strategy is supported, which
+        retains cells whose centres fall within the polygon.
+
+        Args:
+            polygon: A shapely Polygon or MultiPolygon defining the area to clip to.
+            strategy: The clipping strategy to use. Currently only 'centres' is
+                      supported, which retains cells whose centres fall within the
+                      polygon.
+
+        Returns:
+            A new Raster with cells outside the polygon set to NaN.
+        """
+        if strategy != "centres":
+            msg = f"Unsupported clipping strategy: {strategy}"
+            raise NotImplementedError(msg)
+
+        raster = self.model_copy()
+
+        mask = rasterio.features.rasterize(
+            [(polygon, 1)],
+            fill=0,
+            out_shape=self.shape,
+            transform=self.meta.transform,
+            dtype=np.uint8,
+        )
+
+        raster.arr = np.where(mask, raster.arr, np.nan)
+
+        return raster
+
+    def trim_nan(self) -> Self:
+        """Crop the raster by trimming away all-NaN slices at the edges.
+
+        This effectively trims the raster to the smallest bounding box that contains all
+        of the non-NaN values. Note that this does not guarantee no NaN values at all
+        around the edges, only that there won't be entire edges which are all-NaN.
+
+        Consider using `.extrapolate()` for further cleanup of NaN values.
+        """
+        arr = self.arr
+
+        # Check if the entire array is NaN
+        if np.all(np.isnan(arr)):
+            msg = "Cannot crop raster: all values are NaN"
+            raise ValueError(msg)
+
+        # Find rows and columns that are not all NaN
+        nan_row_mask = np.all(np.isnan(arr), axis=1)
+        nan_col_mask = np.all(np.isnan(arr), axis=0)
+
+        # Find the bounding indices
+        (row_indices,) = np.where(~nan_row_mask)
+        (col_indices,) = np.where(~nan_col_mask)
+
+        min_row, max_row = row_indices[0], row_indices[-1]
+        min_col, max_col = col_indices[0], col_indices[-1]
+
+        # Crop the array
+        cropped_arr = arr[min_row : max_row + 1, min_col : max_col + 1]
+
+        # Shift the transform by the number of pixels cropped (min_col, min_row)
+        new_transform = (
+            self.raster_meta.transform
+            * rasterio.transform.Affine.translation(min_col, min_row)
+        )
+
+        # Create new metadata
+        new_meta = RasterMeta(
+            cell_size=self.raster_meta.cell_size,
+            crs=self.raster_meta.crs,
+            transform=new_transform,
+        )
+
+        return self.__class__(arr=cropped_arr, raster_meta=new_meta)
+
     def resample(
         self, new_cell_size: float, *, method: Literal["bilinear"] = "bilinear"
     ) -> Self:
@@ -874,26 +1267,55 @@ class RasterModel(BaseModel):
 
             return cls(arr=new_arr, raster_meta=new_raster_meta)
 
-    @field_validator("arr")
-    @classmethod
-    def check_2d_array(cls, v: NDArray) -> NDArray:
-        """Validator to ensure the cell array is 2D."""
-        if v.ndim != 2:
-            msg = "Cell array must be 2D"
-            raise RasterCellArrayShapeError(msg)
-        return v
 
+def _map_colorbar(
+    *,
+    colormap: Callable[[float], tuple[float, float, float, float]],
+    vmin: float,
+    vmax: float,
+) -> BrancaLinearColormap:
+    from branca.colormap import LinearColormap as BrancaLinearColormap
+    from matplotlib.colors import ListedColormap, to_hex
+
+    # Determine legend data range in original units
+    vmin = float(vmin) if np.isfinite(vmin) else 0.0
+    vmax = float(vmax) if np.isfinite(vmax) else 1.0
+    if vmax <= vmin:
+        vmax = vmin + 1.0
+
+    if isinstance(colormap, ListedColormap):
+        n = colormap.N
+    else:
+        n = 256
+
+    sample_points = np.linspace(0, 1, n)
+    colors = [to_hex(colormap(x)) for x in sample_points]
+    return BrancaLinearColormap(colors=colors, vmin=vmin, vmax=vmax)
 
-def _get_xy_tuple(xy: Any) -> tuple[float, float]:
-    """Convert Point or coordinate tuple to coordinate tuple.
 
-    Args:
-        xy: Either a coordinate tuple or a shapely Point object.
+def _get_vmin_vmax(
+    raster: Raster, *, vmin: float | None = None, vmax: float | None = None
+) -> tuple[float, float]:
+    """Get maximum and minimum values from a raster array, ignoring NaNs.
 
-    Returns:
-        A coordinate tuple (x, y).
+    Allows for custom over-ride vmin and vmax values to be provided.
     """
-    if isinstance(xy, Point):
-        return (xy.x, xy.y)
-    x, y = xy
-    return (float(x), float(y))
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message="All-NaN slice encountered",
+            category=RuntimeWarning,
+        )
+        if vmin is None:
+            _vmin = raster.min()
+        else:
+            _vmin = vmin
+        if vmax is None:
+            _vmax = raster.max()
+        else:
+            _vmax = vmax
+
+    return _vmin, _vmax
+
+
+RasterModel = Raster

{rastr-0.4.0.dist-info → rastr-0.5.0.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: rastr
-Version: 0.4.0
+Version: 0.5.0
 Summary: Geospatial Raster datatype library for Python.
 Project-URL: Source Code, https://github.com/tonkintaylor/rastr
 Project-URL: Bug Tracker, https://github.com/tonkintaylor/rastr/issues
 Project-URL: Releases, https://github.com/tonkintaylor/rastr/releases
-Project-URL: Source Archive, https://github.com/tonkintaylor/rastr/archive/336916af169603534dd0728c10401667f263d98a.zip
+Project-URL: Source Archive, https://github.com/tonkintaylor/rastr/archive/fde05e3c098da7ff9e77a37332d55fb7dbacd873.zip
 Author-email: Tonkin & Taylor Limited <Sub-DisciplineData+AnalyticsStaff@tonkintaylor.co.nz>, Nathan McDougall <nmcdougall@tonkintaylor.co.nz>, Ben Karl <bkarl@tonkintaylor.co.nz>
 License-Expression: MIT
 License-File: LICENSE
@@ -75,10 +75,10 @@ from pyproj.crs.crs import CRS
 from rasterio.transform import from_origin
 from rastr.create import full_raster
 from rastr.meta import RasterMeta
-from rastr.raster import RasterModel
+from rastr.raster import Raster
 
 # Create an example raster
-raster = RasterModel.example()
+raster = Raster.example()
 
 # Basic arithmetic operations
 doubled = raster * 2
@@ -131,6 +131,12 @@ Current version limitations:
 - Square cells only (rectangular cell support planned).
 - Only float dtypes (integer support planned).
 
+## Similar Projects
+
+- [rasters](https://github.com/python-rasters/rasters) is a project with similar goals of providing a dedicated raster datatype in Python with higher-level interfaces for GIS operations. Unlike `rastr`, it has support for multi-band rasters, and has some more advanced functionality for Earth Science applications. Both projects are relatively new and under active development.
+- [rasterio](https://rasterio.readthedocs.io/) is a core dependency of `rastr` and provides low-level raster I/O and processing capabilities.
+- [rioxarray](https://corteva.github.io/rioxarray/stable/getting_started/getting_started.html) extends [`xarray`](https://docs.xarray.dev/en/stable/index.html) for raster data with geospatial support via `rasterio`.
+
 ### Contributing
 
 See the

{rastr-0.4.0.dist-info → rastr-0.5.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 rastr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rastr/_version.py,sha256=2_0GUP7yBCXRus-qiJKxQD62z172WSs1sQ6DVpPsbmM,704
-rastr/create.py,sha256=6aHpRFRXmpXzuzTt-SxY_BfVc7dXKCBLCArb7DjUrsM,13494
-rastr/io.py,sha256=RgkiV_emOPjTFeI2a1aCBtfWwrSLH0XmP8rx9tu6PAI,2952
+rastr/_version.py,sha256=fvHpBU3KZKRinkriKdtAt3crenOyysELF-M9y3ozg3U,704
+rastr/create.py,sha256=7fmg4GKeTXdM5w8oqrCD9eDrc7PU87oHYGPNA-IZ8Cc,13759
+rastr/io.py,sha256=llR2wFyrJVjEG6HN82UAJLVPs_H8nvDxmbEZLjJYjno,2927
 rastr/meta.py,sha256=5iDvGkYe8iMMkPV6gSL04jNcLRhuRNFqe9AppUpp55E,2928
-rastr/raster.py,sha256=I9CQB2NYUOFvvpdzNsQcDBdgLXDCjB7ONFxDAq_6_SU,31995
+rastr/raster.py,sha256=_1Wr78B0_V9r4oh7X-h5lT1QXlnBsSBW6ZkICGSjUFw,47514
 rastr/arr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rastr/arr/fill.py,sha256=80ucb36el9s042fDSwK1SZJhp_GNJNMM0fpQTWmJvgE,1001
 rastr/gis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rastr/gis/fishnet.py,sha256=Ic-0HV61ST8OxwhyoMyV_ybihs2xuhgAY-3n4CknAt8,2670
 rastr/gis/smooth.py,sha256=3HQDQHQM5_LeNk21R8Eb8VpF727JcXq21HO9JMvcpW4,4810
-rastr-0.4.0.dist-info/METADATA,sha256=GjZF16Tmxjz3WUbEFhAB1jW19AecpNkJpk__YNSamQQ,4953
-rastr-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-rastr-0.4.0.dist-info/licenses/LICENSE,sha256=7qUsx93G2ATTRLZiSYuQofwAX_uWvrqnAiMK8PzxvNc,1080
-rastr-0.4.0.dist-info/RECORD,,
+rastr-0.5.0.dist-info/METADATA,sha256=1-sja-_hUE6ukT7KqsDH-nzPZNWVHVeXCABmM9rzTg8,5701
+rastr-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rastr-0.5.0.dist-info/licenses/LICENSE,sha256=7qUsx93G2ATTRLZiSYuQofwAX_uWvrqnAiMK8PzxvNc,1080
+rastr-0.5.0.dist-info/RECORD,,