rastr 0.6.0__tar.gz → 0.7.0__tar.gz

{rastr-0.6.0 → rastr-0.7.0}/.github/copilot-instructions.md

@@ -69,7 +69,9 @@
 
 - Use `uv run pytest` for testing, and ensure all tests are passing before committing changes.
 - Do not perform equality checks with floating point values; instead, use `pytest.approx`.
-- Use only one assert statement per test function to ensure clarity and simplicity.
+- Follow an arrange-act-assert structure in test functions with explicit comments separating each section where possible (context managers can force the assert and act sections to be unified).
+- In the assert block of each test, use only one contiguous block of assert statements to ensure clarity and simplicity.
+
 
 ## Documentation & Workflow Management
 

{rastr-0.6.0 → rastr-0.7.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: rastr
-Version: 0.6.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/a1b755ea9cde7f81b2963dcb12917090019f2b47.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

rastr-0.7.0/src/rastr/__init__.py

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

{rastr-0.6.0 → rastr-0.7.0}/src/rastr/_version.py

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

{rastr-0.6.0 → rastr-0.7.0}/src/rastr/create.py

@@ -11,7 +11,9 @@ 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
 
@@ -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 = []
@@ -312,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."
@@ -343,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-0.7.0/src/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-0.7.0/src/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-0.6.0 → rastr-0.7.0}/src/rastr/gis/smooth.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 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
 
@@ -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-0.7.0/src/rastr/meta.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+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
+
+
+class RasterMeta(BaseModel, extra="forbid"):
+    """Raster metadata.
+
+    Attributes:
+        cell_size: Cell size in meters.
+        crs: Coordinate reference system.
+        transform: The affine transformation associated with the raster. This is based
+                   on the CRS, the cell size, as well as the offset/origin.
+    """
+
+    cell_size: float
+    crs: InstanceOf[CRS]
+    transform: InstanceOf[Affine]
+
+    @classmethod
+    def example(cls) -> Self:
+        """Create an example RasterMeta object."""
+        return cls(
+            cell_size=2.0,
+            crs=CRS.from_epsg(2193),
+            transform=Affine.scale(2.0, 2.0),
+        )
+
+    def get_cell_centre_coords(self, shape: tuple[int, int]) -> NDArray:
+        """Return an array of (x, y) coordinates for the center of each cell.
+
+        The coordinates will be in the coordinate system defined by the
+        raster's transform.
+
+        Args:
+            shape: (rows, cols) of the raster array.
+
+        Returns:
+            (x, y) coordinates for each cell center, with shape (rows, cols, 2)
+        """
+        x_coords = self.get_cell_x_coords(shape[1])  # cols for x-coordinates
+        y_coords = self.get_cell_y_coords(shape[0])  # rows for y-coordinates
+        coords = np.stack(np.meshgrid(x_coords, y_coords), axis=-1)
+        return coords
+
+    def get_cell_x_coords(self, n_columns: int) -> NDArray:
+        """Return an array of x coordinates for the center of each cell.
+
+        The coordinates will be in the coordinate system defined by the
+        raster's transform.
+
+        Args:
+            n_columns: Number of columns in the raster array.
+
+        Returns:
+            x_coordinates at cell centers, with shape (n_columns,)
+        """
+        x_idx = np.arange(n_columns) + 0.5
+        y_idx = np.zeros_like(x_idx)  # Use y=0 for a single row
+        x_coords, _ = self.transform * (x_idx, y_idx)  # type: ignore[reportAssignmentType] overloaded tuple size in affine
+        return x_coords
+
+    def get_cell_y_coords(self, n_rows: int) -> NDArray:
+        """Return an array of y coordinates for the center of each cell.
+
+        The coordinates will be in the coordinate system defined by the
+        raster's transform.
+
+        Args:
+            n_rows: Number of rows in the raster array.
+
+        Returns:
+            y_coordinates at cell centers, with shape (n_rows,)
+        """
+        x_idx = np.zeros(n_rows)  # Use x=0 for a single column
+        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