rastr 0.7.1__py3-none-any.whl → 0.8.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.7.1'
-__version_tuple__ = version_tuple = (0, 7, 1)
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)
 
 __commit_id__ = commit_id = None

rastr/create.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import importlib.util
 import warnings
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING, Literal, TypeVar
 
 import numpy as np
 import rasterio.features
@@ -10,19 +10,21 @@ import rasterio.transform
 from affine import Affine
 from pyproj import CRS
 from shapely.geometry import Point
+from typing_extensions import assert_never
 
 from rastr.gis.crs import get_affine_sign
 from rastr.gis.fishnet import create_point_grid, get_point_grid_shape
-from rastr.gis.interpolate import interpn_kernel
+from rastr.gis.interpolate import InterpolationError, interpn_kernel
 from rastr.meta import RasterMeta
-from rastr.raster import Raster
+from rastr.raster import Raster, RasterModel
 
 if TYPE_CHECKING:
     from collections.abc import Collection, Iterable
 
     import geopandas as gpd
-    from numpy.typing import ArrayLike
+    from numpy.typing import ArrayLike, NDArray
     from shapely.geometry import Polygon
+    from shapely.geometry.base import BaseGeometry
 
 
 TQDM_INSTALLED = importlib.util.find_spec("tqdm") is not None
@@ -215,6 +217,137 @@ def rasterize_gdf(
     return rasters
 
 
+def rasterize_z_gdf(
+    gdf: gpd.GeoDataFrame,
+    *,
+    cell_size: float,
+    crs: CRS | str,
+    agg: Literal["mean", "min", "max"] = "mean",
+) -> RasterModel:
+    """Rasterize interpolated Z-values from geometries in a GeoDataFrame.
+
+    Handles overlapping geometries by aggregating values using a specified method.
+    All geometries must be 3D (have Z coordinates) for interpolation to work.
+
+    The Z-value for each cell is interpolated at the cell center.
+
+    Args:
+        gdf: GeoDataFrame containing 3D geometries with Z coordinates.
+        cell_size: Desired cell size for the output raster.
+        crs: Coordinate reference system for the output raster.
+        agg: Aggregation function to use for overlapping values ("mean", "min", "max").
+
+    Returns:
+        A raster of interpolated Z values.
+
+    Raises:
+        ValueError: If any geometries are not 3D.
+    """
+    crs = CRS.from_user_input(crs)
+
+    if len(gdf) == 0:
+        msg = "Cannot rasterize an empty GeoDataFrame."
+        raise ValueError(msg)
+
+    _validate_geometries_are_3d(gdf)
+
+    # Determine the bounds that would encompass the geometry while respecting the grid
+    gdf_bounds = gdf.total_bounds
+    meta, shape = RasterMeta.infer(
+        x=np.array([gdf_bounds[0], gdf_bounds[2]]),
+        y=np.array([gdf_bounds[1], gdf_bounds[3]]),
+        cell_size=cell_size,
+        crs=crs,
+    )
+
+    # Generate grid coordinates for interpolation
+    x_coords, y_coords = _get_grid(meta, shape=shape)
+
+    # Create 2D accumulation arrays
+    z_stack = []
+    for geom in gdf.geometry:
+        z_vals = _interpolate_z_in_geometry(geom, x_coords, y_coords)
+        z_stack.append(z_vals)
+
+    if not z_stack:
+        msg = (
+            "No valid Z values could be interpolated from the geometries. Raster "
+            "will be entirely NaN-valued."
+        )
+        warnings.warn(msg, stacklevel=2)
+        arr = np.full(shape, np.nan, dtype=np.float64)
+        return RasterModel(arr=arr, raster_meta=meta)
+
+    z_stack = np.array(z_stack)  # Shape: (N, height * width)
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore", category=RuntimeWarning, message="All-NaN slice encountered"
+        )
+        warnings.filterwarnings(
+            "ignore", category=RuntimeWarning, message="Mean of empty slice"
+        )
+
+        if agg == "mean":
+            z_agg = np.nanmean(z_stack, axis=0)
+        elif agg == "min":
+            z_agg = np.nanmin(z_stack, axis=0)
+        elif agg == "max":
+            z_agg = np.nanmax(z_stack, axis=0)
+        else:
+            assert_never(agg)
+
+    arr = np.asarray(z_agg, dtype=np.float64).reshape(shape)
+
+    return RasterModel(arr=arr, raster_meta=meta)
+
+
+def _validate_geometries_are_3d(gdf: gpd.GeoDataFrame) -> None:
+    """Validate that all geometries have 3D coordinates (Z values).
+
+    Args:
+        gdf: The GeoDataFrame to check for 3D geometries.
+
+    Raises:
+        ValueError: If any geometries are not 3D.
+    """
+    for idx, geom in enumerate(gdf.geometry):
+        if geom is None or geom.is_empty:
+            continue
+
+        # Check if geometry has Z coordinates
+        if not geom.has_z:
+            msg = (
+                f"Geometry at index {idx} is not 3D. Z-coordinates are required since "
+                "they give the cell values during rasterization."
+            )
+            raise ValueError(msg)
+
+
+def _interpolate_z_in_geometry(
+    geometry: BaseGeometry, x: NDArray, y: NDArray
+) -> NDArray[np.float64]:
+    """Vectorized interpolation of Z values in a geometry at multiple (x, y) points.
+
+    Only the boundary is considered (e.g. holes in polygons are ignored).
+
+    Parameters:
+        geometry: Shapely geometry with Z coordinates (Polygon, LineString, etc.).
+        x: Array of X coordinates, shape (N,).
+        y: Array of Y coordinates, shape (N,).
+
+    Returns:
+        Array of interpolated Z values (NaN if outside convex hull or no boundary).
+    """
+    # Extract coordinates from geometry boundary only
+    coords = np.array(geometry.boundary.coords)
+
+    try:
+        return interpn_kernel(coords[:, :2], coords[:, 2], xi=np.column_stack((x, y)))
+    except InterpolationError:
+        return np.full_like(x, np.nan, dtype=np.float64)
+
+
 def _validate_columns_exist(
     gdf: gpd.GeoDataFrame, target_cols: Collection[str]
 ) -> None:
@@ -299,7 +432,8 @@ def raster_from_point_cloud(
     Interpolation is only possible within the convex hull of the points. Outside of
     this, cells will be NaN-valued.
 
-    All (x,y) points must be unique.
+    Duplicate (x, y, z) triples are silently deduplicated. However, duplicate (x, y)
+    points with different z values will raise an error.
 
     Args:
         x: X coordinates of points.
@@ -313,7 +447,8 @@ def raster_from_point_cloud(
         Raster containing the interpolated values.
 
     Raises:
-        ValueError: If any (x, y) points are duplicated, or if they are all collinear.
+        ValueError: If any (x, y) points have different z values, or if they are all
+                    collinear.
     """
     crs = CRS.from_user_input(crs)
     x, y, z = _validate_xyz(
@@ -357,7 +492,21 @@ def _validate_xyz(
             "surface."
         )
         raise ValueError(msg)
-    # Check for duplicate (x, y) points
+    # Check for duplicate (x, y, z) triples and deduplicate them
+    xyz_points = np.column_stack((x, y, z))
+    unique_xyz, first_occurrence_indices = np.unique(
+        xyz_points, axis=0, return_index=True
+    )
+
+    # If we have duplicate (x, y, z) triples, deduplicate them
+    if len(unique_xyz) < len(xyz_points):
+        x = x[first_occurrence_indices]
+        y = y[first_occurrence_indices]
+        z = z[first_occurrence_indices]
+
+    # Check for duplicate (x, y) points with different z values
+    # After deduplication, if there are still duplicate (x,y) points, they must have
+    # different z values
     xy_points = np.column_stack((x, y))
     if len(xy_points) != len(np.unique(xy_points, axis=0)):
         msg = "Duplicate (x, y) points found. Each (x, y) point must be unique."

rastr/gis/fishnet.py

@@ -7,7 +7,7 @@ from shapely import BufferCapStyle, BufferJoinStyle
 
 if TYPE_CHECKING:
     from geopandas.array import GeometryArray
-    from numpy.typing import NDArray
+    from numpy.typing import ArrayLike, NDArray
 
 
 def create_point_grid(
@@ -36,11 +36,11 @@ def create_point_grid(
 
 
 def get_point_grid_shape(
-    *, bounds: tuple[float, float, float, float], cell_size: float
+    *, bounds: tuple[float, float, float, float] | ArrayLike, cell_size: float
 ) -> tuple[int, int]:
     """Calculate the shape of the point grid based on bounds and cell size."""
 
-    xmin, ymin, xmax, ymax = bounds
+    xmin, ymin, xmax, ymax = np.asarray(bounds)
     ncols_exact = (xmax - xmin) / cell_size
     nrows_exact = (ymax - ymin) / cell_size
 

rastr/gis/interpolate.py

@@ -8,6 +8,10 @@ if TYPE_CHECKING:
     from collections.abc import Callable
 
 
+class InterpolationError(ValueError):
+    """Exception for interpolation-related errors."""
+
+
 def interpn_kernel(
     points: np.ndarray,
     values: np.ndarray,
@@ -44,7 +48,7 @@ def interpn_kernel(
             "degenerate input points. Ensure that the (x, y) points are not all "
             "collinear (i.e. that the convex hull is non-degenerate)."
         )
-        raise ValueError(msg) from err
+        raise InterpolationError(msg) from err
 
     grid_values = np.array(interpolator(xi))
     return grid_values

rastr/io.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+import warnings
 from pathlib import Path
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
 import numpy as np
 import rasterio
@@ -12,8 +13,14 @@ from rastr.meta import RasterMeta
 from rastr.raster import Raster
 
 if TYPE_CHECKING:
+    import geopandas as gpd
     from numpy.typing import NDArray
 
+try:
+    from rasterio._err import CPLE_BaseError
+except ImportError:
+    CPLE_BaseError = Exception  # Fallback if private module import fails
+
 R = TypeVar("R", bound=Raster)
 
 
@@ -118,3 +125,115 @@ def read_raster_mosaic_inmem(
     finally:
         for src in sources:
             src.close()
+
+
+def write_raster(raster: Raster, *, path: Path | str, **kwargs: Any) -> None:
+    """Write the raster to a file.
+
+    Args:
+        raster: The Raster object to write.
+        path: Path to output file.
+        **kwargs: Additional keyword arguments to pass to `rasterio.open()`. If
+                    `nodata` is provided, NaN values in the raster will be replaced
+                    with the nodata value.
+    """
+    path = Path(path)
+
+    suffix = path.suffix.lower()
+    if suffix in (".tif", ".tiff"):
+        driver = "GTiff"
+    elif suffix in (".grd"):
+        # https://grapherhelp.goldensoftware.com/subsys/ascii_grid_file_format.htm
+        # e.g. Used by AnAqSim
+        driver = "GSAG"
+    else:
+        msg = f"Unsupported file extension: {suffix}"
+        raise ValueError(msg)
+
+    # Handle nodata: use provided value or default to np.nan
+    if "nodata" in kwargs:
+        # Replace NaN values with the nodata value
+        nodata_value = kwargs.pop("nodata")
+        arr_to_write = np.where(np.isnan(raster.arr), nodata_value, raster.arr)
+    else:
+        nodata_value = np.nan
+        arr_to_write = raster.arr
+
+    with rasterio.open(
+        path,
+        "w",
+        driver=driver,
+        height=raster.arr.shape[0],
+        width=raster.arr.shape[1],
+        count=1,
+        dtype=raster.arr.dtype,
+        crs=raster.raster_meta.crs,
+        transform=raster.raster_meta.transform,
+        nodata=nodata_value,
+        **kwargs,
+    ) as dst:
+        try:
+            dst.write(arr_to_write, 1)
+        except CPLE_BaseError as err:
+            msg = f"Failed to write raster to file: {err}"
+            raise OSError(msg) from err
+
+
+def read_cad_gdf(path: Path | str, crs: CRS | str | None = None) -> gpd.GeoDataFrame:
+    """Read a GeoDataFrame from a DXF/CAD file with warning suppression.
+
+    This is useful in tandem with `Raster.clip` and `rastr.create.rasterize_z_gdf` to
+    create rasters from CAD files. Often CAD files represent surfaces which for GIS
+    contexts are better represented as rasters. In other cases, CAD files represent
+    geometries but their difficult representation means that it is often easier to first
+    rasterize them, and then spatially join with a clean vector representation
+    developed separately.
+
+    DXF files often have large geometries that can trigger warnings during reading.
+    This function suppresses those warnings and ensures proper CRS handling.
+
+    Supports any format supported by `geopandas.read_file` which provides 3D geometries.
+
+    Args:
+        path: Path to the CAD file.
+        crs: Optional CRS for the output GeoDataFrame. If None, uses the CRS from the
+             CAD file.
+
+    Returns:
+        GeoDataFrame: The CAD data as a GeoDataFrame.
+
+    Raises:
+        ValueError: If CRS is missing from CAD file and not provided, or if CRS is
+                    inconsistent between CAD file and provided CRS.
+    """
+    import geopandas as gpd
+
+    path = Path(path)
+
+    with warnings.catch_warnings():
+        # The CAD-derived geometries are really messy, so we can get warnings
+        # about large polygons, but we're going to handle those.
+        warnings.filterwarnings(
+            "ignore",
+            message=".*Non closed ring detected.*",
+            category=RuntimeWarning,
+        )
+
+        # Read the CAD file using geopandas
+        gdf = gpd.read_file(path)
+
+    # Handle CRS logic
+    crs = CRS.from_user_input(crs) if crs is not None else None
+    if crs is None:
+        if gdf.crs is None:
+            msg = (
+                f"No CRS found in CAD file {path} and no CRS provided. "
+                "Please provide a CRS parameter."
+            )
+            raise ValueError(msg)
+    # Check if CRS are consistent
+    elif gdf.crs is not None and not gdf.crs.equals(crs):
+        # Reproject if inconsistent
+        gdf = gdf.to_crs(crs)
+
+    return gdf

rastr/meta.py

@@ -97,7 +97,7 @@ class RasterMeta(BaseModel, extra="forbid"):
         cell_size: float | None = None,
         crs: CRS,
     ) -> tuple[Self, tuple[int, int]]:
-        """Automatically get recommended raster metadata (and shape) using data bounds.
+        """Automatically get recommended raster metadata (and shape) using data points.
 
         The cell size can be provided, or a heuristic will be used based on the spacing
         of the (x, y) points.

rastr/raster.py

@@ -6,8 +6,7 @@ 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
+from typing import TYPE_CHECKING, Any, Literal, NamedTuple, overload
 
 import numpy as np
 import numpy.ma
@@ -15,13 +14,12 @@ 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
-from shapely.geometry import LineString, Point, Polygon
+from shapely.geometry import LineString, MultiPolygon, Point, Polygon
 
 from rastr.arr.fill import fillna_nearest_neighbours
 from rastr.gis.fishnet import create_fishnet
@@ -30,6 +28,7 @@ from rastr.meta import RasterMeta
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Generator
+    from pathlib import Path
 
     import geopandas as gpd
     from affine import Affine
@@ -39,14 +38,9 @@ if TYPE_CHECKING:
     from matplotlib.image import AxesImage
     from numpy.typing import ArrayLike, NDArray
     from rasterio.io import BufferedDatasetWriter, DatasetReader, DatasetWriter
-    from shapely import MultiPolygon
+    from shapely.geometry.base import BaseGeometry
     from typing_extensions import Self
 
-try:
-    from rasterio._err import CPLE_BaseError
-except ImportError:
-    CPLE_BaseError = Exception  # Fallback if private module import fails
-
 
 FOLIUM_INSTALLED = importlib.util.find_spec("folium") is not None
 BRANCA_INSTALLED = importlib.util.find_spec("branca") is not None
@@ -55,6 +49,27 @@ MATPLOTLIB_INSTALLED = importlib.util.find_spec("matplotlib") is not None
 CONTOUR_PERTURB_EPS = 1e-10
 
 
+@contextmanager
+def suppress_slice_warning() -> Generator[None, None, None]:
+    """Context manager to suppress all-NaN slice warnings from NumPy operations.
+
+    An all-NaN slice is a row or a column of an array where every value is NaN.
+    This is common for rasters around the edges, and is almost always a false
+    positive.
+
+    Note that even .trim_nan() won't even guarantee there aren't NaN slices,
+    since that method only applies around the edges of a raster, whereas there
+    might be NaN slices in between non-NaN data in the middle.
+    """
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message="All-NaN slice encountered",
+            category=RuntimeWarning,
+        )
+        yield
+
+
 class RasterCellArrayShapeError(ValueError):
     """Custom error for invalid raster cell array shapes."""
 
@@ -249,6 +264,18 @@ class Raster(BaseModel):
         cls = self.__class__
         return cls(arr=-self.arr, raster_meta=self.raster_meta)
 
+    def abs(self) -> Self:
+        """Compute the absolute value of the raster.
+
+        Returns a new raster with the absolute value of each cell. The original raster
+        is not modified.
+
+        Returns:
+            A new Raster instance with the absolute values.
+        """
+        cls = self.__class__
+        return cls(arr=np.abs(self.arr), raster_meta=self.raster_meta)
+
     @property
     def cell_centre_coords(self) -> NDArray[np.float64]:
         """Get the coordinates of the cell centres in the raster."""
@@ -417,8 +444,8 @@ class Raster(BaseModel):
         return raster_values
 
     @property
-    def bounds(self) -> tuple[float, float, float, float]:
-        """Bounding box of the raster as (xmin, ymin, xmax, ymax)"""
+    def bounds(self) -> Bounds:
+        """Bounding box of the raster as a named tuple with xmin, ymin, xmax, ymax."""
         x1, y1, x2, y2 = rasterio.transform.array_bounds(
             height=self.arr.shape[0],
             width=self.arr.shape[1],
@@ -426,7 +453,7 @@ class Raster(BaseModel):
         )
         xmin, xmax = sorted([x1, x2])
         ymin, ymax = sorted([y1, y2])
-        return (xmin, ymin, xmax, ymax)
+        return Bounds(xmin=xmin, ymin=ymin, xmax=xmax, ymax=ymax)
 
     @property
     def bbox(self) -> Polygon:
@@ -580,7 +607,8 @@ class Raster(BaseModel):
             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.
+                      This includes parameters like `alpha` for transparency, and `vmin`
+                      and `vmax` for controlling the color scale limits.
         """
         if not MATPLOTLIB_INSTALLED:
             msg = "The 'matplotlib' package is required for 'plot()'."
@@ -673,8 +701,15 @@ class Raster(BaseModel):
 
         return raster_gdf
 
+    def gdf(self, name: str = "value") -> gpd.GeoDataFrame:
+        """Create a GeoDataFrame representation of the raster.
+
+        Alias for `as_geodataframe()`.
+        """
+        return self.as_geodataframe(name=name)
+
     def to_file(self, path: Path | str, **kwargs: Any) -> None:
-        """Write the raster to a GeoTIFF file.
+        """Write the raster to a file.
 
         Args:
             path: Path to output file.
@@ -682,47 +717,9 @@ class Raster(BaseModel):
                       `nodata` is provided, NaN values in the raster will be replaced
                       with the nodata value.
         """
+        from rastr.io import write_raster  # noqa: PLC0415
 
-        path = Path(path)
-
-        suffix = path.suffix.lower()
-        if suffix in (".tif", ".tiff"):
-            driver = "GTiff"
-        elif suffix in (".grd"):
-            # https://grapherhelp.goldensoftware.com/subsys/ascii_grid_file_format.htm
-            # e.g. Used by AnAqSim
-            driver = "GSAG"
-        else:
-            msg = f"Unsupported file extension: {suffix}"
-            raise ValueError(msg)
-
-        # Handle nodata: use provided value or default to np.nan
-        if "nodata" in kwargs:
-            # Replace NaN values with the nodata value
-            nodata_value = kwargs.pop("nodata")
-            arr_to_write = np.where(np.isnan(self.arr), nodata_value, self.arr)
-        else:
-            nodata_value = np.nan
-            arr_to_write = self.arr
-
-        with rasterio.open(
-            path,
-            "w",
-            driver=driver,
-            height=self.arr.shape[0],
-            width=self.arr.shape[1],
-            count=1,
-            dtype=self.arr.dtype,
-            crs=self.raster_meta.crs,
-            transform=self.raster_meta.transform,
-            nodata=nodata_value,
-            **kwargs,
-        ) as dst:
-            try:
-                dst.write(arr_to_write, 1)
-            except CPLE_BaseError as err:
-                msg = f"Failed to write raster to file: {err}"
-                raise OSError(msg) from err
+        return write_raster(self, path=path, **kwargs)
 
     def __str__(self) -> str:
         cls = self.__class__
@@ -817,7 +814,8 @@ class Raster(BaseModel):
         Returns:
             The maximum value in the raster. Returns NaN if all values are NaN.
         """
-        return float(np.nanmax(self.arr))
+        with suppress_slice_warning():
+            return float(np.nanmax(self.arr))
 
     def min(self) -> float:
         """Get the minimum value in the raster, ignoring NaN values.
@@ -825,7 +823,8 @@ class Raster(BaseModel):
         Returns:
             The minimum value in the raster. Returns NaN if all values are NaN.
         """
-        return float(np.nanmin(self.arr))
+        with suppress_slice_warning():
+            return float(np.nanmin(self.arr))
 
     def mean(self) -> float:
         """Get the mean value in the raster, ignoring NaN values.
@@ -833,7 +832,8 @@ class Raster(BaseModel):
         Returns:
             The mean value in the raster. Returns NaN if all values are NaN.
         """
-        return float(np.nanmean(self.arr))
+        with suppress_slice_warning():
+            return float(np.nanmean(self.arr))
 
     def std(self) -> float:
         """Get the standard deviation of values in the raster, ignoring NaN values.
@@ -841,7 +841,8 @@ class Raster(BaseModel):
         Returns:
             The standard deviation of the raster. Returns NaN if all values are NaN.
         """
-        return float(np.nanstd(self.arr))
+        with suppress_slice_warning():
+            return float(np.nanstd(self.arr))
 
     def quantile(self, q: float) -> float:
         """Get the specified quantile value in the raster, ignoring NaN values.
@@ -852,7 +853,8 @@ class Raster(BaseModel):
         Returns:
             The quantile value. Returns NaN if all values are NaN.
         """
-        return float(np.nanquantile(self.arr, q))
+        with suppress_slice_warning():
+            return float(np.nanquantile(self.arr, q))
 
     def median(self) -> float:
         """Get the median value in the raster, ignoring NaN values.
@@ -862,7 +864,8 @@ class Raster(BaseModel):
         Returns:
             The median value in the raster. Returns NaN if all values are NaN.
         """
-        return float(np.nanmedian(self.arr))
+        with suppress_slice_warning():
+            return float(np.nanmedian(self.arr))
 
     def fillna(self, value: float) -> Self:
         """Fill NaN values in the raster with a specified value.
@@ -983,6 +986,7 @@ class Raster(BaseModel):
                        contours will be returned without any smoothing.
         """
         import geopandas as gpd
+        import skimage.measure
 
         all_levels = []
         all_geoms = []
@@ -1032,6 +1036,27 @@ class Raster(BaseModel):
         # Dissolve contours by level to merge all contour lines of the same level
         return contour_gdf.dissolve(by="level", as_index=False)
 
+    def sobel(self) -> Self:
+        """Compute the Sobel gradient magnitude of the raster.
+
+        This is effectively a discrete differentiation operator, computing an
+        approximation of the magnitude of the gradient of the image intensity function.
+
+        Borders are treated using half-sample symmetric sampling, i.e. repeating the
+        border values. Be aware that this can lead to edge artifacts and under-estimate
+        the gradient along the border pixels.
+
+        Returns:
+            New raster containing the gradient magnitude in units of raster cell units
+            per unit distance (e.g. per meter).
+        """
+        from skimage import filters
+
+        new_raster = self.model_copy()
+        # Scale by cell size to convert to per unit distance
+        new_raster.arr = filters.sobel(self.arr) / self.cell_size
+        return new_raster
+
     def blur(self, sigma: float, *, preserve_nan: bool = True) -> Self:
         """Apply a Gaussian blur to the raster data.
 
@@ -1286,7 +1311,7 @@ class Raster(BaseModel):
 
     def clip(
         self,
-        polygon: Polygon | MultiPolygon,
+        polygon: BaseGeometry,
         *,
         strategy: Literal["centres"] = "centres",
     ) -> Self:
@@ -1304,22 +1329,25 @@ class Raster(BaseModel):
 
         Returns:
             A new Raster with cells outside the polygon set to NaN.
+
+        Raises:
+            TypeError: If the provided geometry is not a Polygon or MultiPolygon.
         """
+        if not isinstance(polygon, Polygon | MultiPolygon):
+            msg = (
+                f"Only Polygon and MultiPolygon geometries are supported for clipping, "
+                f"got {type(polygon).__name__}"
+            )
+            raise TypeError(msg)
+
         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,
-        )
+        mask_raster = self._polygon_indicator(polygon)
 
-        raster.arr = np.where(mask, raster.arr, np.nan)
+        raster = self.model_copy()
+        raster.arr = np.where(mask_raster.arr, raster.arr, np.nan)
 
         return raster
 
@@ -1433,6 +1461,99 @@ class Raster(BaseModel):
 
             return cls(arr=new_arr, raster_meta=new_raster_meta)
 
+    def replace_polygon(
+        self,
+        polygon: BaseGeometry | dict[BaseGeometry, float],
+        value: float | None = None,
+    ) -> Self:
+        """Replace values within the specified polygon(s) with other values.
+
+        Creates a new raster with the specified values replaced. This is useful for
+        operations like masking or setting regions to NaN.
+
+        The method supports two interfaces:
+        1. Single replacement: `raster.replace_polygon(polygon1, value=np.nan)`
+        2. Multiple replacements using a dictionary:
+           `raster.replace_polygon({polygon1: 0, polygon2: 1})`
+
+        Args:
+            polygon: Geometry to replace, or dict mapping geometries to values.
+            value: Replacement value. Required if polygon is a geometry, None if polygon
+                   is a dict.
+
+        Examples:
+            >>> # Replace a single polygon
+            >>> raster.replace_polygon(polygon1, value=np.nan)
+            >>> # Replace multiple polygons
+            >>> raster.replace_polygon({polygon1: 0, polygon2: 1})
+        """
+        # Normalize input to dict format
+        if isinstance(polygon, dict):
+            if value is not None:
+                msg = "value must be None when polygon is a dict"
+                raise ValueError(msg)
+            replacements = polygon
+        else:
+            if value is None:
+                msg = "value must be specified when polygon is a geometry"
+                raise ValueError(msg)
+            replacements = {polygon: value}
+
+        # Validate all geometries upfront
+        for geom in replacements.keys():
+            if not isinstance(geom, Polygon | MultiPolygon):
+                msg = (
+                    f"Only Polygon and MultiPolygon geometries are supported, "
+                    f"got {type(geom).__name__}"
+                )
+                raise TypeError(msg)
+
+        # Create copy and convert to float if needed
+        raster = self.model_copy()
+        needs_float = any(
+            isinstance(v, float) or (v is not None and np.isnan(v))
+            for v in replacements.values()
+        )
+        if needs_float and not np.issubdtype(raster.arr.dtype, np.floating):
+            raster.arr = raster.arr.astype(float)
+
+        # Apply all replacements
+        for geom, val in replacements.items():
+            mask_raster = self._polygon_indicator(geom)
+            raster.arr = np.where(mask_raster.arr, val, raster.arr)
+
+        return raster
+
+    def _polygon_indicator(self, geom: BaseGeometry) -> Self:
+        """Create a binary mask with 1 inside the polygon, 0 outside.
+
+        The mask has the same shape and transform as the raster.
+
+        Args:
+            geom:
+                A shapely geometry (typically Polygon or MultiPolygon)
+                to rasterize.
+
+        Returns:
+            Raster:
+                A new Raster where cells inside the geometry are 1,
+                and outside are 0.
+        """
+
+        arr = rasterio.features.rasterize(
+            [(geom, 1)],
+            fill=0,
+            out_shape=self.shape,
+            transform=self.meta.transform,
+            dtype=np.uint8,
+        )
+
+        # Create a new raster with the binary mask array
+        raster = self.model_copy()
+        raster.arr = arr
+
+        return raster
+
 
 def _map_colorbar(
     *,
@@ -1466,22 +1587,32 @@ def _get_vmin_vmax(
 
     Allows for custom over-ride vmin and vmax values to be provided.
     """
-    with warnings.catch_warnings():
-        warnings.filterwarnings(
-            "ignore",
-            message="All-NaN slice encountered",
-            category=RuntimeWarning,
-        )
-        if vmin is None:
-            _vmin = float(raster.min())
-        else:
-            _vmin = vmin
-        if vmax is None:
-            _vmax = float(raster.max())
-        else:
-            _vmax = vmax
+    if vmin is None:
+        _vmin = float(raster.min())
+    else:
+        _vmin = vmin
+    if vmax is None:
+        _vmax = float(raster.max())
+    else:
+        _vmax = vmax
 
     return _vmin, _vmax
 
 
 RasterModel = Raster
+
+
+class Bounds(NamedTuple):
+    """Bounding box coordinates for a raster.
+
+    Attributes:
+        xmin: The minimum x-coordinate.
+        ymin: The minimum y-coordinate.
+        xmax: The maximum x-coordinate.
+        ymax: The maximum y-coordinate.
+    """
+
+    xmin: float
+    ymin: float
+    xmax: float
+    ymax: float

{rastr-0.7.1.dist-info → rastr-0.8.0.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: rastr
-Version: 0.7.1
+Version: 0.8.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/f84ab299005d87e37339d53759e005e85c9e5ad2.zip
+Project-URL: Source Archive, https://github.com/tonkintaylor/rastr/archive/68715eeb3fa4dca80a0999df65ebf2f9c7daca6d.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
@@ -39,9 +39,8 @@ Description-Content-Type: text/markdown
 # rastr
 
 [![PyPI Version](https://img.shields.io/pypi/v/rastr.svg)](<https://pypi.python.org/pypi/rastr>)
-[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![usethis](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/usethis-python/usethis-python/main/assets/badge/v1.json)](https://github.com/usethis-python/usethis-python)
+[![PyPI Supported Versions](https://img.shields.io/pypi/pyversions/rastr.svg)](https://pypi.python.org/pypi/rastr)
+![PyPI License](https://img.shields.io/pypi/l/rastr.svg)
 
 A lightweight geospatial raster datatype library for Python focused on simplicity.
 
@@ -73,9 +72,8 @@ pip install rastr
 ```python
 from pyproj.crs.crs import CRS
 from rasterio.transform import from_origin
+from rastr import Raster, RasterMeta
 from rastr.create import full_raster
-from rastr.meta import RasterMeta
-from rastr.raster import Raster
 
 # Read a raster from a file
 raster = Raster.read_file("path/to/raster.tif")

rastr-0.8.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+rastr/__init__.py,sha256=z26KywZdRKwO-N5Qc34SuuGGwH8Y812csKORc3S4SYU,113
+rastr/_version.py,sha256=Rttl-BDadtcW1QzGnNffCWA_Wc9mUKDMOBPZp--Mnsc,704
+rastr/create.py,sha256=a2T-kv6Zi0Pnx65kCq9oHBPOeIhS1mtioqTm_XoRRU0,18312
+rastr/io.py,sha256=Tui_1AzmGEkvyDrNEHVK6S-I5OEjh36lZqNRwA9effQ,7722
+rastr/meta.py,sha256=ex4GVIwkJza8qZGJiEvMMstx4HOum0kHPCnl9PzrFkw,5980
+rastr/raster.py,sha256=zTwyUPGZAgEBjawg0i6dTR6knrFYrzvH7sUaF_DuMuU,59078
+rastr/arr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rastr/arr/fill.py,sha256=ZSd9mcfzYafkAes2G2q8hJGlxhW47kI2brPf--jds3o,1029
+rastr/gis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rastr/gis/crs.py,sha256=9K57Ys6P32v0uzap-l7L_HbjolJMX-ETuRB_rN30Qz0,1953
+rastr/gis/fishnet.py,sha256=J6hQEBFSWaSTg6dC9f6ppDxTk-cV2UVmX-O35T9Yj7w,3143
+rastr/gis/interpolate.py,sha256=osRobeMx1QntggbNv-K3HDrWLUS7WO_XPp8nrMiPqVE,1799
+rastr/gis/smooth.py,sha256=bGNBFs7PYW_J_vzcX0h2VL2R0o4dX3Da_nEm7Pjivlw,5295
+rastr-0.8.0.dist-info/METADATA,sha256=EiigwvI6q_QFgJHMWmJ1iMHXE9Zm25SH9GTCbbyjsz8,5369
+rastr-0.8.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rastr-0.8.0.dist-info/licenses/LICENSE,sha256=7qUsx93G2ATTRLZiSYuQofwAX_uWvrqnAiMK8PzxvNc,1080
+rastr-0.8.0.dist-info/RECORD,,

rastr-0.7.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-rastr/__init__.py,sha256=z26KywZdRKwO-N5Qc34SuuGGwH8Y812csKORc3S4SYU,113
-rastr/_version.py,sha256=az9tfX88VBVbBBILFx2zOlpMh1RBTXIwP6baQTMKtHc,704
-rastr/create.py,sha256=jT2X7mgJoMapnRz-M11dJoKFidaf0k_qleR5zxnRAnw,13195
-rastr/io.py,sha256=RPhypnSNhLaWYdGRzctM9aTXbw9_TuMjvhMvDyUZavk,3640
-rastr/meta.py,sha256=lUZVodFzhnzLI1sr7SgiM9XN9D-n7nXvs0voWTJYlMg,5980
-rastr/raster.py,sha256=9yib1g0HOzPepaLCu_ApEbfUynb0IjQzCD__FEOco1c,54219
-rastr/arr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rastr/arr/fill.py,sha256=ZSd9mcfzYafkAes2G2q8hJGlxhW47kI2brPf--jds3o,1029
-rastr/gis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rastr/gis/crs.py,sha256=9K57Ys6P32v0uzap-l7L_HbjolJMX-ETuRB_rN30Qz0,1953
-rastr/gis/fishnet.py,sha256=nAiJ_DuSQP326pLM9JmI8A4QwWWgVu7Mae1K1dWjDc4,3108
-rastr/gis/interpolate.py,sha256=DzjtD5ynnwKP7TrwPiK3P0dOy5ZRzME9bV8-7tn5TFk,1697
-rastr/gis/smooth.py,sha256=bGNBFs7PYW_J_vzcX0h2VL2R0o4dX3Da_nEm7Pjivlw,5295
-rastr-0.7.1.dist-info/METADATA,sha256=-MvdAkql2szGVK4jAI2Kw3evRhIYq3daQBmvPAfpJ0o,5724
-rastr-0.7.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-rastr-0.7.1.dist-info/licenses/LICENSE,sha256=7qUsx93G2ATTRLZiSYuQofwAX_uWvrqnAiMK8PzxvNc,1080
-rastr-0.7.1.dist-info/RECORD,,