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

rastr/__init__.py

@@ -0,0 +1,7 @@
+from rastr.meta import RasterMeta
+from rastr.raster import Raster
+
+__all__ = [
+    "Raster",
+    "RasterMeta",
+]

rastr/_version.py

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

rastr/arr/fill.py

@@ -8,7 +8,7 @@ if TYPE_CHECKING:
     from numpy.typing import NDArray
 
 
-def fillna_nearest_neighbours(arr: NDArray[np.float64]) -> NDArray[np.float64]:
+def fillna_nearest_neighbours(arr: NDArray) -> NDArray:
     """Fill NaN values in an N-dimensional array with their nearest neighbours' values.
 
     The nearest neighbour is determined using the Euclidean distance between array
@@ -28,4 +28,5 @@ def fillna_nearest_neighbours(arr: NDArray[np.float64]) -> NDArray[np.float64]:
     # Interpolate at the array indices
     interp = NearestNDInterpolator(nonnan_idxs, arr[nonnan_mask])
     filled_arr = interp(*np.indices(arr.shape))
-    return filled_arr
+    # Preserve the original dtype
+    return filled_arr.astype(arr.dtype)

rastr/create.py

@@ -11,12 +11,14 @@ from affine import Affine
 from pyproj import CRS
 from shapely.geometry import Point
 
+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.meta import RasterMeta
 from rastr.raster import Raster
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Collection, Iterable
 
     import geopandas as gpd
     from numpy.typing import ArrayLike
@@ -141,7 +143,7 @@ def rasterize_gdf(
     gdf: gpd.GeoDataFrame,
     *,
     raster_meta: RasterMeta,
-    target_cols: list[str],
+    target_cols: Collection[str],
 ) -> list[Raster]:
     """Rasterize geometries from a GeoDataFrame.
 
@@ -183,9 +185,10 @@ def rasterize_gdf(
     shape = get_point_grid_shape(bounds=expanded_bounds, cell_size=cell_size)
 
     # Create the affine transform for rasterization
+    xs, ys = get_affine_sign(raster_meta.crs)
     transform = Affine.translation(
         expanded_bounds[0], expanded_bounds[3]
-    ) * Affine.scale(cell_size, -cell_size)
+    ) * Affine.scale(xs * cell_size, ys * cell_size)
 
     # Create rasters for each target column using rasterio.features.rasterize
     rasters = []
@@ -212,7 +215,9 @@ def rasterize_gdf(
     return rasters
 
 
-def _validate_columns_exist(gdf: gpd.GeoDataFrame, target_cols: list[str]) -> None:
+def _validate_columns_exist(
+    gdf: gpd.GeoDataFrame, target_cols: Collection[str]
+) -> None:
     """Validate that all target columns exist in the GeoDataFrame.
 
     Args:
@@ -228,7 +233,9 @@ def _validate_columns_exist(gdf: gpd.GeoDataFrame, target_cols: list[str]) -> No
         raise MissingColumnsError(msg)
 
 
-def _validate_columns_numeric(gdf: gpd.GeoDataFrame, target_cols: list[str]) -> None:
+def _validate_columns_numeric(
+    gdf: gpd.GeoDataFrame, target_cols: Collection[str]
+) -> None:
     """Validate that all target columns contain numeric data.
 
     Args:
@@ -308,14 +315,31 @@ def raster_from_point_cloud(
     Raises:
         ValueError: If any (x, y) points are duplicated, or if they are all collinear.
     """
-    from scipy.interpolate import LinearNDInterpolator
-    from scipy.spatial import KDTree, QhullError
-
-    x = np.asarray(x).ravel()
-    y = np.asarray(y).ravel()
-    z = np.asarray(z).ravel()
     crs = CRS.from_user_input(crs)
+    x, y, z = _validate_xyz(
+        np.asarray(x).ravel(), np.asarray(y).ravel(), np.asarray(z).ravel()
+    )
 
+    raster_meta, shape = RasterMeta.infer(x, y, cell_size=cell_size, crs=crs)
+    arr = interpn_kernel(
+        points=np.column_stack((x, y)),
+        values=z,
+        xi=np.column_stack(_get_grid(raster_meta, shape=shape)),
+    ).reshape(shape)
+
+    # We only support float rasters for now; we should preserve the input dtype if
+    # possible
+    if z.dtype in (np.float16, np.float32, np.float64):
+        arr = arr.astype(z.dtype)
+    else:
+        arr = arr.astype(np.float64)
+
+    return Raster(arr=arr, raster_meta=raster_meta)
+
+
+def _validate_xyz(
+    x: np.ndarray, y: np.ndarray, z: np.ndarray
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     # Validate input arrays
     if len(x) != len(y) or len(x) != len(z):
         msg = "Length of x, y, and z must be equal."
@@ -339,53 +363,18 @@ def raster_from_point_cloud(
         msg = "Duplicate (x, y) points found. Each (x, y) point must be unique."
         raise ValueError(msg)
 
-    # 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(xy_points)
-        distances, _ = tree.query(xy_points, k=2)
-        distances: np.ndarray
-        cell_size = float(np.percentile(distances[distances > 0], 5)) / 2
-
-    # Compute bounds from data
-    minx, miny, maxx, maxy = np.min(x), np.min(y), np.max(x), np.max(y)
-
-    # Compute grid shape
-    width = int(np.ceil((maxx - minx) / cell_size))
-    height = int(np.ceil((maxy - miny) / cell_size))
-    shape = (height, width)
+    return x, y, z
 
-    # Compute transform: upper left corner is (minx, maxy)
-    transform = Affine.translation(minx, maxy) * Affine.scale(cell_size, -cell_size)
 
-    # Create grid coordinates for raster cells
+def _get_grid(
+    raster_meta: RasterMeta, *, shape: tuple[int, int]
+) -> tuple[np.ndarray, np.ndarray]:
+    """Get coordinates for raster cell centres based on raster metadata and shape."""
     rows, cols = np.indices(shape)
     xs, ys = rasterio.transform.xy(
-        transform=transform, rows=rows, cols=cols, offset="center"
+        transform=raster_meta.transform, rows=rows, cols=cols, offset="center"
     )
     grid_x = np.array(xs).ravel()
     grid_y = np.array(ys).ravel()
 
-    # Perform interpolation
-    try:
-        interpolator = LinearNDInterpolator(
-            points=xy_points, values=z, fill_value=np.nan
-        )
-    except QhullError as err:
-        msg = (
-            "Failed to interpolate. This may be due to insufficient or "
-            "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
-
-    grid_values = np.array(interpolator(np.column_stack((grid_x, grid_y))))
-
-    arr = grid_values.reshape(shape).astype(np.float32)
-
-    raster_meta = RasterMeta(
-        cell_size=cell_size,
-        crs=crs,
-        transform=transform,
-    )
-    return Raster(arr=arr, raster_meta=raster_meta)
+    return grid_x, grid_y

rastr/gis/crs.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import warnings
+from typing import Literal
+
+from pyproj import CRS
+
+
+def get_affine_sign(crs: CRS | str) -> tuple[Literal[+1, -1], Literal[+1, -1]]:
+    """Return (x_sign, y_sign) for an Affine scale, given a CRS.
+
+    Some coordinate systems may use unconventional axis directions, in which case
+    the correct direction may not be possible to infer correctly. In these cases,
+    the assumption is that x increases to the right, and y increases upwards.
+    """
+    crs = CRS.from_user_input(crs)
+
+    # Try to detect horizontal axis directions from CRS metadata
+    dir_x, dir_y, *_ = [(a.direction or "").lower() for a in crs.axis_info]
+
+    try:
+        if _is_conventional_direction(dir_x):
+            x_sign = +1
+        else:
+            x_sign = -1
+    except NotImplementedError:
+        msg = (
+            f"Could not determine x-axis direction from CRS axis info '{dir_x}'. "
+            "Falling back to +1 (increasing to the right)."
+        )
+        warnings.warn(msg, stacklevel=2)
+        x_sign = +1
+
+    try:
+        if _is_conventional_direction(dir_y):
+            y_sign = -1
+        else:
+            y_sign = +1
+    except NotImplementedError:
+        msg = (
+            f"Could not determine y-axis direction from CRS axis info '{dir_y}'. "
+            "Falling back to -1 (increasing upwards)."
+        )
+        warnings.warn(msg, stacklevel=2)
+        y_sign = -1
+
+    return x_sign, y_sign
+
+
+def _is_conventional_direction(direction: str) -> bool:
+    """Return True if the axis direction indicates positive increase."""
+    if (
+        "north" in direction
+        or "up" in direction
+        or "east" in direction
+        or "right" in direction
+    ):
+        return True
+    elif (
+        "south" in direction
+        or "down" in direction
+        or "west" in direction
+        or "left" in direction
+    ):
+        return False
+    else:
+        raise NotImplementedError

rastr/gis/fishnet.py

@@ -41,8 +41,20 @@ def get_point_grid_shape(
     """Calculate the shape of the point grid based on bounds and cell size."""
 
     xmin, ymin, xmax, ymax = bounds
-    ncols = int(np.ceil((xmax - xmin) / cell_size))
-    nrows = int(np.ceil((ymax - ymin) / cell_size))
+    ncols_exact = (xmax - xmin) / cell_size
+    nrows_exact = (ymax - ymin) / cell_size
+
+    # Use round for values very close to integers to avoid floating-point
+    # sensitivity while maintaining ceil behavior for truly fractional values
+    if np.isclose(ncols_exact, np.round(ncols_exact)):
+        ncols = int(np.round(ncols_exact))
+    else:
+        ncols = int(np.ceil(ncols_exact))
+
+    if np.isclose(nrows_exact, np.round(nrows_exact)):
+        nrows = int(np.round(nrows_exact))
+    else:
+        nrows = int(np.ceil(nrows_exact))
 
     return nrows, ncols
 

rastr/gis/interpolate.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def interpn_kernel(
+    points: np.ndarray,
+    values: np.ndarray,
+    *,
+    xi: np.ndarray,
+    kernel: Callable[[np.ndarray], np.ndarray] | None = None,
+) -> np.ndarray:
+    """Interpolate scattered data to new points, with optional kernel transformation.
+
+    For example, you could provide a kernel to transform cartesian coordinate points
+    to polar coordinates before interpolation, giving interpolation which follows the
+    circular pattern of the data.
+
+    Args:
+        points: Array of shape (n_points, n_dimensions) representing the input points.
+        values: Array of shape (n_points,) representing the values at each input point.
+        xi: Array of shape (m_points, n_dimensions) representing the points to
+            interpolate to.
+        kernel: Optional function to transform points (and xi) before interpolation.
+    """
+    from scipy.interpolate import LinearNDInterpolator
+    from scipy.spatial import QhullError
+
+    if kernel is not None:
+        xi = kernel(xi)
+        points = kernel(points)
+    try:
+        interpolator = LinearNDInterpolator(
+            points=points, values=values, fill_value=np.nan
+        )
+    except QhullError as err:
+        msg = (
+            "Failed to interpolate. This may be due to insufficient or "
+            "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
+
+    grid_values = np.array(interpolator(xi))
+    return grid_values

rastr/gis/smooth.py

@@ -5,16 +5,17 @@ Fork + Port of <https://github.com/philipschall/shapelysmooth> (Public domain)
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, TypeAlias
+from typing import TYPE_CHECKING, TypeVar
 
 import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
 from shapely.geometry import LineString, Polygon
 from typing_extensions import assert_never
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
-T: TypeAlias = LineString | Polygon
+T = TypeVar("T", bound=LineString | Polygon)
 
 
 class InputeTypeError(TypeError):
@@ -38,12 +39,12 @@ def catmull_rom_smooth(geometry: T, alpha: float = 0.5, subdivs: int = 10) -> T:
     coords, interior_coords = _get_coords(geometry)
     coords_smoothed = _catmull_rom(coords, alpha=alpha, subdivs=subdivs)
     if isinstance(geometry, LineString):
-        return type(geometry)(coords_smoothed)
+        return geometry.__class__(coords_smoothed)
     elif isinstance(geometry, Polygon):
         interior_coords_smoothed = [
             _catmull_rom(c, alpha=alpha, subdivs=subdivs) for c in interior_coords
         ]
-        return type(geometry)(coords_smoothed, holes=interior_coords_smoothed)
+        return geometry.__class__(coords_smoothed, holes=interior_coords_smoothed)
     else:
         assert_never(geometry)
 
@@ -55,7 +56,8 @@ def _catmull_rom(
     subdivs: int = 8,
 ) -> list[tuple[float, float]]:
     arr = np.asarray(coords, dtype=float)
-    if arr.shape[0] < 2:
+    n = arr.shape[0]
+    if n < 2:
         return arr.tolist()
 
     is_closed = np.allclose(arr[0], arr[-1])
@@ -70,63 +72,80 @@ def _catmull_rom(
             ]
         )
 
-    new_ls = [tuple(arr[1])]
-    for k in range(len(arr) - 3):
-        slice4 = arr[k : k + 4]
-        tangents = [0.0]
-        for j in range(3):
-            dist = float(np.linalg.norm(slice4[j + 1] - slice4[j]))
-            tangents.append(float(tangents[-1] + dist**alpha))
-
-        # Resample: subdivs-1 samples strictly between t1 and t2
-        seg_len = (tangents[2] - tangents[1]) / float(subdivs)
-        if subdivs > 1:
-            ts = np.linspace(tangents[1] + seg_len, tangents[2] - seg_len, subdivs - 1)
-        else:
-            ts = np.array([])
-
-        interpolants = _recursive_eval(slice4, tangents, ts)
-        new_ls.extend(interpolants)
-        new_ls.append(tuple(slice4[2]))
-    return new_ls
-
-
-def _recursive_eval(
-    slice4: NDArray, tangents: list[float], ts: NDArray
-) -> list[tuple[float, float]]:
+    # Shape of (segments, 4, D)
+    segments = sliding_window_view(arr, (4, arr.shape[1]))[:, 0, :]
+
+    # Distances and tangent values
+    diffs = np.diff(segments, axis=1)
+    dists = np.linalg.norm(diffs, axis=2)
+    tangents = np.concatenate(
+        [np.zeros((len(dists), 1)), np.cumsum(dists**alpha, axis=1)], axis=1
+    )
+
+    # Build ts per segment
+    if subdivs > 1:
+        seg_lens = (tangents[:, 2] - tangents[:, 1]) / subdivs
+        u = np.linspace(1, subdivs - 1, subdivs - 1)
+        ts = tangents[:, [1]] + seg_lens[:, None] * u  # (N-3, subdivs-1)
+    else:
+        ts = np.empty((len(segments), 0))
+
+    # Vectorize over segments
+    out_segments = []
+    for seg, tang, tvals in zip(segments, tangents, ts, strict=True):
+        if tvals.size:
+            out_segments.append(
+                _recursive_eval(seg, np.asarray(tang), np.asarray(tvals))
+            )
+    if out_segments:
+        all_midpoints = np.vstack(out_segments)
+    else:
+        all_midpoints = np.empty((0, arr.shape[1]))
+
+    # Gather final output in order
+    result = [tuple(arr[1])]
+    idx = 0
+    for k in range(len(segments)):
+        block = all_midpoints[idx : idx + max(subdivs - 1, 0)]
+        result.extend(map(tuple, block))
+        result.append(tuple(segments[k, 2]))
+        idx += max(subdivs - 1, 0)
+
+    return result
+
+
+def _recursive_eval(slice4: NDArray, tangents: NDArray, ts: NDArray) -> NDArray:
     """De Boor/De Casteljau-style recursive linear interpolation over 4 control points.
 
     Parameterized by the non-uniform 'tangents' values.
     """
-    # N.B. comments are LLM-generated
-
-    out = []
-    for tp in ts:
-        # Start with the 4 control points for this segment
-        points = slice4.copy()
-        # Perform 3 levels of linear interpolation (De Casteljau's algorithm)
-        for r in range(1, 4):
-            idx = max(r - 2, 0)
-            new_points = []
-            # Interpolate between points at this level
-            for i in range(4 - r):
-                # Compute denominator for parameterization
-                denom = tangents[i + r - idx] - tangents[i + idx]
-                if denom == 0:
-                    # If degenerate (coincident tangents), use midpoint
-                    left_w = right_w = 0.5
-                else:
-                    # Otherwise, compute weights for linear interpolation
-                    left_w = (tangents[i + r - idx] - tp) / denom
-                    right_w = (tp - tangents[i + idx]) / denom
-                # Weighted average of the two points
-                pt = left_w * points[i] + right_w * points[i + 1]
-                new_points.append(pt)
-            # Move to the next level with the new set of points
-            points = np.array(new_points)
-        # The final point is the interpolated value for this parameter tp
-        out.append(tuple(points[0]))
-    return out
+    slice4 = np.asarray(slice4, dtype=float)
+    tangents = np.asarray(tangents, dtype=float)
+    ts = np.asarray(ts, dtype=float)
+    bigm = ts.shape[0]
+    bigd = slice4.shape[1]
+
+    # Initialize points for all ts, shape (M, 4, D)
+    points = np.broadcast_to(slice4, (bigm, 4, bigd)).copy()
+
+    # Recursive interpolation, but vectorized across all ts
+    for r in range(1, 4):
+        idx = max(r - 2, 0)
+        denom = tangents[r - idx : 4 - idx] - tangents[idx : 4 - r + idx]
+        denom = np.where(denom == 0, np.finfo(float).eps, denom)  # avoid div 0
+
+        # Compute weights for all parameter values at once
+        left_w = (tangents[r - idx : 4 - idx][None, :] - ts[:, None]) / denom
+        right_w = 1 - left_w
+
+        # Weighted sums between consecutive points
+        points = (
+            left_w[..., None] * points[:, 0 : 4 - r, :]
+            + right_w[..., None] * points[:, 1 : 5 - r, :]
+        )
+
+    # Result is first (and only) point at this level
+    return points[:, 0, :]
 
 
 def _get_coords(

rastr/io.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypeVar
 
 import numpy as np
 import rasterio
@@ -14,28 +14,48 @@ from rastr.raster import Raster
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
+R = TypeVar("R", bound=Raster)
+
 
 def read_raster_inmem(
-    raster_path: Path | str, *, crs: CRS | str | None = None
-) -> Raster:
-    """Read raster data from a file and return an in-memory Raster object."""
+    raster_path: Path | str,
+    *,
+    crs: CRS | str | None = None,
+    cls: type[R] = Raster,
+) -> R:
+    """Read raster data from a file and return an in-memory Raster object.
+
+    Args:
+        raster_path: Path to the raster file.
+        crs: Optional CRS to override the raster's native CRS.
+        cls: The Raster subclass to instantiate. This is mostly for internal use,
+             but can be useful if you have a custom `Raster` subclass.
+    """
     crs = CRS.from_user_input(crs) if crs is not None else None
 
     with rasterio.open(raster_path, mode="r") as dst:
         # Read the entire array
-        arr: NDArray[np.float64] = dst.read()
-        arr = arr.squeeze().astype(np.float64)
+        raw_arr: NDArray = dst.read()
+        raw_arr = raw_arr.squeeze()
+
         # Extract metadata
         cell_size = dst.res[0]
         if crs is None:
             crs = CRS.from_user_input(dst.crs)
         transform = dst.transform
         nodata = dst.nodata
+
+        # Cast integers to float16 to handle NaN values
+        if np.issubdtype(raw_arr.dtype, np.integer):
+            arr = raw_arr.astype(np.float16)
+        else:
+            arr = raw_arr
+
         if nodata is not None:
-            arr[arr == nodata] = np.nan
+            arr[raw_arr == nodata] = np.nan
 
     raster_meta = RasterMeta(cell_size=cell_size, crs=crs, transform=transform)
-    raster_obj = Raster(arr=arr, raster_meta=raster_meta)
+    raster_obj = cls(arr=arr, raster_meta=raster_meta)
     return raster_obj
 
 
@@ -81,10 +101,16 @@ def read_raster_mosaic_inmem(
             crs = CRS.from_user_input(sources[0].crs)
 
         nodata = sources[0].nodata
-        if nodata is not None:
-            arr[arr == nodata] = np.nan
+        raw_arr = arr.squeeze()
 
-        arr = arr.squeeze().astype(np.float64)
+        # Cast integers to float16 to handle NaN values
+        if np.issubdtype(raw_arr.dtype, np.integer):
+            arr = raw_arr.astype(np.float16)
+        else:
+            arr = raw_arr
+
+        if nodata is not None:
+            arr[raw_arr == nodata] = np.nan
 
         raster_meta = RasterMeta(cell_size=cell_size, crs=crs, transform=transform)
         raster_obj = Raster(arr=arr, raster_meta=raster_meta)

rastr/meta.py

@@ -7,6 +7,8 @@ from affine import Affine
 from pydantic import BaseModel, InstanceOf
 from pyproj import CRS
 
+from rastr.gis.crs import get_affine_sign
+
 if TYPE_CHECKING:
     from numpy.typing import NDArray
     from typing_extensions import Self
@@ -85,3 +87,99 @@ class RasterMeta(BaseModel, extra="forbid"):
         y_idx = np.arange(n_rows) + 0.5
         _, y_coords = self.transform * (x_idx, y_idx)  # type: ignore[reportAssignmentType] overloaded tuple size in affine
         return y_coords
+
+    @classmethod
+    def infer(
+        cls,
+        x: np.ndarray,
+        y: np.ndarray,
+        *,
+        cell_size: float | None = None,
+        crs: CRS,
+    ) -> tuple[Self, tuple[int, int]]:
+        """Automatically get recommended raster metadata (and shape) using data bounds.
+
+        The cell size can be provided, or a heuristic will be used based on the spacing
+        of the (x, y) points.
+        """
+        # Heuristic for cell size if not provided
+        if cell_size is None:
+            cell_size = infer_cell_size(x, y)
+
+        shape = infer_shape(x, y, cell_size=cell_size)
+        transform = infer_transform(x, y, cell_size=cell_size, crs=crs)
+
+        raster_meta = cls(
+            cell_size=cell_size,
+            crs=crs,
+            transform=transform,
+        )
+        return raster_meta, shape
+
+
+def infer_transform(
+    x: np.ndarray,
+    y: np.ndarray,
+    *,
+    cell_size: float | None = None,
+    crs: CRS,
+) -> Affine:
+    """Infer a suitable raster transform based on the bounds of (x, y) data points."""
+    if cell_size is None:
+        cell_size = infer_cell_size(x, y)
+
+    (xs, ys) = get_affine_sign(crs)
+    return Affine.translation(*infer_origin(x, y)) * Affine.scale(
+        xs * cell_size, ys * cell_size
+    )
+
+
+def infer_origin(x: np.ndarray, y: np.ndarray) -> tuple[float, float]:
+    """Infer a suitable raster origin based on the bounds of (x, y) data points."""
+    # Compute bounds from data
+    minx, _miny, _maxx, maxy = np.min(x), np.min(y), np.max(x), np.max(y)
+
+    origin = (minx, maxy)
+    return origin
+
+
+def infer_shape(
+    x: np.ndarray, y: np.ndarray, *, cell_size: float | None = None
+) -> tuple[int, int]:
+    """Infer a suitable raster shape based on the bounds of (x, y) data points."""
+    if cell_size is None:
+        cell_size = infer_cell_size(x, y)
+
+    # Compute bounds from data
+    minx, miny, maxx, maxy = np.min(x), np.min(y), np.max(x), np.max(y)
+
+    # Compute grid shape
+    width = int(np.ceil((maxx - minx) / cell_size))
+    height = int(np.ceil((maxy - miny) / cell_size))
+    shape = (height, width)
+
+    return shape
+
+
+def infer_cell_size(x: np.ndarray, y: np.ndarray) -> float:
+    """Infer a suitable cell size based on the spacing of (x, y) data points.
+
+    When points are distributed regularly, this corresponds to roughly half the distance
+    between neighboring points.
+
+    When distributed irregularly, the size is more influenced by the densest clusters of
+    points, i.e. the cell size will be small enough to capture the detail in these
+    clusters.
+
+    This is based on a heuristic which has been found to work well in practice.
+    """
+    from scipy.spatial import KDTree
+
+    # Half the 5th percentile of nearest neighbor distances between the (x,y) points
+    xy_points = np.column_stack((x, y))
+    tree = KDTree(xy_points)
+    distances, _ = tree.query(xy_points, k=2)
+    distances: np.ndarray
+    cell_size = float(np.percentile(distances[distances > 0], 5)) / 2
+
+    return cell_size

rastr/raster.py

@@ -108,6 +108,16 @@ class Raster(BaseModel):
         """Set the transform via meta."""
         self.meta.transform = value
 
+    @property
+    def cell_size(self) -> float:
+        """Convenience property to access the cell size via meta."""
+        return self.meta.cell_size
+
+    @cell_size.setter
+    def cell_size(self, value: float) -> None:
+        """Set the cell size via meta."""
+        self.meta.cell_size = value
+
     def __init__(
         self,
         *,
@@ -663,8 +673,15 @@ class Raster(BaseModel):
 
         return raster_gdf
 
-    def to_file(self, path: Path | str) -> None:
-        """Write the raster to a GeoTIFF file."""
+    def to_file(self, path: Path | str, **kwargs: Any) -> None:
+        """Write the raster to a GeoTIFF file.
+
+        Args:
+            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)
 
@@ -679,6 +696,15 @@ class Raster(BaseModel):
             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",
@@ -689,17 +715,18 @@ class Raster(BaseModel):
             dtype=self.arr.dtype,
             crs=self.raster_meta.crs,
             transform=self.raster_meta.transform,
-            nodata=np.nan,
+            nodata=nodata_value,
+            **kwargs,
         ) as dst:
             try:
-                dst.write(self.arr, 1)
+                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 __str__(self) -> str:
         cls = self.__class__
-        mean = np.nanmean(self.arr)
+        mean = self.mean()
         return f"{cls.__name__}(shape={self.arr.shape}, {mean=})"
 
     def __repr__(self) -> str:
@@ -719,6 +746,34 @@ class Raster(BaseModel):
         raster_meta = RasterMeta.example()
         return cls(arr=arr, raster_meta=raster_meta)
 
+    @classmethod
+    def full_like(cls, other: Raster, *, fill_value: float) -> Self:
+        """Create a raster with the same metadata as another but filled with a constant.
+
+        Args:
+            other: The raster to copy metadata from.
+            fill_value: The constant value to fill all cells with.
+
+        Returns:
+            A new raster with the same shape and metadata as `other`, but with all cells
+            set to `fill_value`.
+        """
+        arr = np.full(other.shape, fill_value, dtype=np.float32)
+        return cls(arr=arr, raster_meta=other.raster_meta)
+
+    @classmethod
+    def read_file(cls, filename: Path | str, crs: CRS | str | None = None) -> Self:
+        """Read raster data from a file and return an in-memory Raster object.
+
+        Args:
+            filename: Path to the raster file.
+            crs: Optional coordinate reference system to override the file's CRS.
+        """
+        # Import here to avoid circular import (rastr.io imports Raster)
+        from rastr.io import read_raster_inmem  # noqa: PLC0415
+
+        return read_raster_inmem(filename, crs=crs, cls=cls)
+
     @overload
     def apply(
         self,
@@ -819,6 +874,78 @@ class Raster(BaseModel):
         new_raster.arr = filled_arr
         return new_raster
 
+    def replace(
+        self, to_replace: float | dict[float, float], value: float | None = None
+    ) -> Self:
+        """Replace values in the raster with other values.
+
+        Creates a new raster with the specified values replaced. This is useful for
+        operations like replacing zeros with NaNs, or vice versa.
+
+        The method supports two interfaces:
+        1. Single replacement: `raster.replace(to_replace=0, value=np.nan)`
+        2. Multiple replacements using a dictionary:
+           `raster.replace({0: np.nan, -999: np.nan})`
+
+        Args:
+            to_replace: Value to be replaced, or a dictionary mapping values to
+                        their replacements.
+            value: Replacement value. Required when to_replace is a float, must be
+                   None when to_replace is a dict.
+
+        Examples:
+            >>> # Replace a single value
+            >>> raster.replace(to_replace=0, value=np.nan)
+            >>> # Replace multiple values
+            >>> raster.replace({0: np.nan, -999: np.nan})
+        """
+        # Determine the replacement map
+        if isinstance(to_replace, dict):
+            if value is not None:
+                msg = "value must be None when to_replace is a dict"
+                raise ValueError(msg)
+            map_ = to_replace
+        else:
+            if value is None:
+                msg = "value must be specified when to_replace is a float"
+                raise ValueError(msg)
+            map_ = {to_replace: value}
+
+        # Start with a copy of the array
+        replaced_arr = self.arr.copy()
+
+        # Check if we need to convert to float (if assigning NaN to non-float array)
+        needs_float = any(
+            np.isnan(new_val) for new_val in map_.values()
+        ) and not np.issubdtype(replaced_arr.dtype, np.floating)
+        if needs_float:
+            replaced_arr = replaced_arr.astype(float)
+
+        # Apply each replacement based on the original array values
+        # to prevent chained replacements
+        for old_val, new_val in map_.items():
+            # Handle NaN specially since NaN != NaN
+            if np.isnan(old_val):
+                mask = np.isnan(self.arr)
+            else:
+                mask = self.arr == old_val
+
+            replaced_arr[mask] = new_val
+
+        new_raster = self.model_copy()
+        new_raster.arr = replaced_arr
+        return new_raster
+
+    def copy(self) -> Self:  # type: ignore[override]
+        """Create a copy of the raster.
+
+        This method wraps `model_copy()` for convenience.
+
+        Returns:
+            A new Raster instance.
+        """
+        return self.model_copy(deep=True)
+
     def get_xy(self) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
         """Get the x and y coordinates of the raster cell centres in meshgrid format.
 
@@ -835,7 +962,7 @@ class Raster(BaseModel):
         return coords[:, :, 0], coords[:, :, 1]
 
     def contour(
-        self, levels: list[float] | NDArray, *, smoothing: bool = True
+        self, levels: Collection[float] | NDArray, *, smoothing: bool = True
     ) -> gpd.GeoDataFrame:
         """Create contour lines from the raster data, optionally with smoothing.
 
@@ -848,8 +975,8 @@ class Raster(BaseModel):
         contouring, to denoise the contours.
 
         Args:
-            levels: A list or array of contour levels to generate. The contour lines
-                    will be generated for each level in this sequence.
+            levels: A collection or array of contour levels to generate. The contour
+                    lines will be generated for each level in this sequence.
             smoothing: Defaults to true, which corresponds to applying a smoothing
                        algorithm to the contour lines. At the moment, this is the
                        Catmull-Rom spline algorithm. If set to False, the raw
@@ -905,19 +1032,40 @@ 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 blur(self, sigma: float) -> Self:
+    def blur(self, sigma: float, *, preserve_nan: bool = True) -> Self:
         """Apply a Gaussian blur to the raster data.
 
         Args:
             sigma: Standard deviation for Gaussian kernel, in units of geographic
                    coordinate distance (e.g. meters). A larger sigma results in a more
                    blurred image.
+            preserve_nan: If True, applies NaN-safe blurring by extrapolating NaN values
+                          before blurring and restoring them afterwards. This prevents
+                          NaNs from spreading into valid data during the blur operation.
         """
         from scipy.ndimage import gaussian_filter
 
         cell_sigma = sigma / self.raster_meta.cell_size
 
-        blurred_array = gaussian_filter(self.arr, sigma=cell_sigma)
+        if preserve_nan:
+            # Save the original NaN mask
+            nan_mask = np.isnan(self.arr)
+
+            # If there are no NaNs, just apply regular blur
+            if not np.any(nan_mask):
+                blurred_array = gaussian_filter(self.arr, sigma=cell_sigma)
+            else:
+                # Extrapolate to fill NaN values temporarily
+                extrapolated_arr = fillna_nearest_neighbours(arr=self.arr)
+
+                # Apply blur to the extrapolated array
+                blurred_array = gaussian_filter(extrapolated_arr, sigma=cell_sigma)
+
+                # Restore original NaN values
+                blurred_array = np.where(nan_mask, np.nan, blurred_array)
+        else:
+            blurred_array = gaussian_filter(self.arr, sigma=cell_sigma)
+
         new_raster = self.model_copy()
         new_raster.arr = blurred_array
         return new_raster
@@ -1175,29 +1323,27 @@ class Raster(BaseModel):
 
         return raster
 
-    def trim_nan(self) -> Self:
-        """Crop the raster by trimming away all-NaN slices at the edges.
+    def _trim_value(self, *, value_mask: NDArray[np.bool_], value_name: str) -> Self:
+        """Crop the raster by trimming away slices matching the mask 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.
+        Args:
+            value_mask: Boolean mask where True indicates values to trim
+            value_name: Name of the value type for error messages (e.g., 'NaN', 'zero')
         """
         arr = self.arr
 
-        # Check if the entire array is NaN
-        if np.all(np.isnan(arr)):
-            msg = "Cannot crop raster: all values are NaN"
+        # Check if the entire array matches the mask
+        if np.all(value_mask):
+            msg = f"Cannot crop raster: all values are {value_name}"
             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 rows and columns that are not all matching the mask
+        row_mask = np.all(value_mask, axis=1)
+        col_mask = np.all(value_mask, axis=0)
 
         # Find the bounding indices
-        (row_indices,) = np.where(~nan_row_mask)
-        (col_indices,) = np.where(~nan_col_mask)
+        (row_indices,) = np.where(~row_mask)
+        (col_indices,) = np.where(~col_mask)
 
         min_row, max_row = row_indices[0], row_indices[-1]
         min_col, max_col = col_indices[0], col_indices[-1]
@@ -1220,6 +1366,26 @@ class Raster(BaseModel):
 
         return self.__class__(arr=cropped_arr, raster_meta=new_meta)
 
+    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.
+        """
+        return self._trim_value(value_mask=np.isnan(self.arr), value_name="NaN")
+
+    def trim_zeros(self) -> Self:
+        """Crop the raster by trimming away all-zero slices at the edges.
+
+        This effectively trims the raster to the smallest bounding box that contains all
+        of the non-zero values. Note that this does not guarantee no zero values at all
+        around the edges, only that there won't be entire edges which are all-zero.
+        """
+        return self._trim_value(value_mask=(self.arr == 0), value_name="zero")
+
     def resample(
         self, new_cell_size: float, *, method: Literal["bilinear"] = "bilinear"
     ) -> Self:
@@ -1307,11 +1473,11 @@ def _get_vmin_vmax(
             category=RuntimeWarning,
         )
         if vmin is None:
-            _vmin = raster.min()
+            _vmin = float(raster.min())
         else:
             _vmin = vmin
         if vmax is None:
-            _vmax = raster.max()
+            _vmax = float(raster.max())
         else:
             _vmax = vmax
 

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: rastr
-Version: 0.5.0
+Version: 0.7.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/fde05e3c098da7ff9e77a37332d55fb7dbacd873.zip
+Project-URL: Source Archive, https://github.com/tonkintaylor/rastr/archive/2b485cc676121c82f468dca7733e444c3033abbe.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
@@ -77,8 +77,8 @@ from rastr.create import full_raster
 from rastr.meta import RasterMeta
 from rastr.raster import Raster
 
-# Create an example raster
-raster = Raster.example()
+# Read a raster from a file
+raster = Raster.read_file("path/to/raster.tif")
 
 # Basic arithmetic operations
 doubled = raster * 2

rastr-0.7.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+rastr/__init__.py,sha256=z26KywZdRKwO-N5Qc34SuuGGwH8Y812csKORc3S4SYU,113
+rastr/_version.py,sha256=uLbRjFSUZAgfl7V7O8zKV5Db36k7tz87ZIVq3l2SWs0,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=FeEiO9RNyX9bP_yM2bvgQPLGyF0lHjll20ur52ehp1c,5182
+rastr-0.7.0.dist-info/METADATA,sha256=yc3gYgbIgMLAoUeubfE0rXiJtN1b9YPbz4Yjewrr0QE,5724
+rastr-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rastr-0.7.0.dist-info/licenses/LICENSE,sha256=7qUsx93G2ATTRLZiSYuQofwAX_uWvrqnAiMK8PzxvNc,1080
+rastr-0.7.0.dist-info/RECORD,,

rastr-0.5.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-rastr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-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=_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.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,,