pointclouds 0.0.0__py3-none-any.whl

pointclouds/io/las.py

@@ -0,0 +1,119 @@
+"""laspy-backed LAS/LAZ engine: header-first read, chunked record read, write. (Phase 1 - T-8).
+
+Two entry points, deliberately separate, because the split is the point of the design:
+
+- :func:`read_header` opens the file and returns metadata only. No point record is decompressed, so the cost is
+  constant whatever the file's size - a 40 GB tile answers as fast as a 40 KB one.
+- :func:`read_points` decompresses the record arrays, optionally only the dimensions asked for.
+
+Everything here imports with the core dependency set (numpy, laspy, pyproj). Spatially-indexed windowed reads
+live in :mod:`pointclouds.io.copc` (T-16) and writing lands with T-13; neither belongs in this module. The
+record-array contract the two readers share is in :mod:`pointclouds.io._records`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import laspy
+import numpy as np
+from pyproj import CRS
+
+from pointclouds.io import _records
+
+__all__ = ["LasHeaderInfo", "read_header", "read_points"]
+
+_SUFFIXES = {".las", ".laz"}
+
+
+@dataclass(frozen=True)
+class LasHeaderInfo:
+    """Everything the LAS/LAZ header can answer without touching a point record.
+
+    Attributes:
+        count: the header's point count. On a lazy cloud this is known before any record is read, which is why it
+            is not simply ``len(cloud)``.
+        bounds: ``(xmin, ymin, xmax, ymax)`` as recorded in the header.
+        crs: the file's CRS as a :class:`pyproj.CRS`, or ``None`` when the header carries no SRS. Never a GDAL or
+            pyramids object - that is the dependency boundary this package exists to keep.
+        dimensions: every dimension name the point format declares, in file order.
+        version: the LAS version string, e.g. ``"1.4"``.
+        point_format: the point format id, e.g. ``3``.
+    """
+
+    count: int
+    bounds: tuple[float, float, float, float]
+    crs: CRS | None
+    dimensions: tuple[str, ...]
+    version: str
+    point_format: int
+
+
+def _resolve(path: str | Path) -> Path:
+    """Return ``path`` as a :class:`~pathlib.Path`, rejecting what this engine cannot read.
+
+    Args:
+        path: the LAS/LAZ file to open.
+
+    Returns:
+        The resolved path.
+
+    Raises:
+        FileNotFoundError: when the path does not exist, naming the path rather than surfacing laspy's error.
+        ValueError: when the suffix is neither ``.las`` nor ``.laz``.
+    """
+    resolved = Path(path)
+    if resolved.suffix.lower() not in _SUFFIXES:
+        raise ValueError(f"{resolved.name!r} is not a LAS/LAZ file; expected one of {sorted(_SUFFIXES)}")
+    if not resolved.is_file():
+        raise FileNotFoundError(f"no such point cloud file: {resolved}")
+    return resolved
+
+
+def read_header(path: str | Path) -> LasHeaderInfo:
+    """Read the header of a LAS/LAZ file, touching no point records.
+
+    Args:
+        path: the file to open.
+
+    Returns:
+        A :class:`LasHeaderInfo` with count, bounds, CRS, dimensions and format metadata.
+
+    Raises:
+        FileNotFoundError: when the path does not exist.
+        ValueError: when the suffix is neither ``.las`` nor ``.laz``.
+    """
+    resolved = _resolve(path)
+    with laspy.open(resolved) as reader:
+        header = reader.header
+        return LasHeaderInfo(
+            count=int(header.point_count),
+            bounds=(float(header.x_min), float(header.y_min), float(header.x_max), float(header.y_max)),
+            crs=header.parse_crs(),
+            dimensions=tuple(str(name) for name in header.point_format.dimension_names),
+            version=str(header.version),
+            point_format=int(header.point_format.id),
+        )
+
+
+def read_points(path: str | Path, dimensions: tuple[str, ...] | None = None) -> dict[str, np.ndarray]:
+    """Read the point records of a LAS/LAZ file.
+
+    Args:
+        path: the file to open.
+        dimensions: dimension names to read, case-insensitive. ``None`` reads every dimension this engine maps
+            onto a :class:`~pointclouds.points.PointCloud` field.
+
+    Returns:
+        A mapping of lower-case dimension name to array. A dimension the file's point format does not declare
+        comes back as a zero-length array of the right dtype, never as a missing key.
+
+    Raises:
+        FileNotFoundError: when the path does not exist.
+        ValueError: when the suffix is neither ``.las`` nor ``.laz``.
+        KeyError: when a requested dimension is not one this engine knows.
+    """
+    resolved = _resolve(path)
+    requested = _records.resolve(dimensions)
+    return _records.extract(laspy.read(resolved), requested)

pointclouds/ops/__init__.py

@@ -0,0 +1 @@
+"""Operations on a point cloud: filter, decimate, clip, merge, grid."""

pointclouds/ops/clip.py

@@ -0,0 +1,99 @@
+"""Clip a cloud to an extent or a polygon. (Phase 2 - T-9).
+
+ADR - clip stays in the pure-numpy core (the §9 open question, settled here).
+    The core's selling point is a pure-PyPI wheel that installs anywhere numpy runs, so adding shapely to
+    ``[project.dependencies]`` was rejected. Both clip forms are therefore pure numpy:
+
+    - ``bbox`` is a vectorised coordinate comparison (:func:`pointclouds.ops.filter.bbox_mask`).
+    - ``polygon`` is a vectorised even-odd ray-casting point-in-polygon test over a single ring.
+
+    So the core dependency set is unchanged. Out of scope for the core, and left to the ``[gis]`` vector path
+    (pyramids ``FeatureCollection``): polygons with holes, multipart polygons, and shapely/OGR geometry objects.
+
+:func:`clip_mask` returns a boolean mask; :meth:`PointCloud._take` does the subsetting.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pointclouds.ops.filter import bbox_mask
+
+if TYPE_CHECKING:
+    from pointclouds.points import PointCloud
+
+__all__ = ["clip_mask"]
+
+
+def clip_mask(
+    cloud: PointCloud,
+    *,
+    bbox: tuple[float, float, float, float] | None = None,
+    polygon: np.ndarray | None = None,
+) -> np.ndarray:
+    """Return the mask of points kept by a bbox or polygon clip.
+
+    Args:
+        cloud: the cloud to clip; its records are loaded if they are not in memory yet.
+        bbox: ``(xmin, ymin, xmax, ymax)`` extent, edges included.
+        polygon: an ``(M, 2)`` array of ``(x, y)`` vertices forming a single ring (closed or open).
+
+    Returns:
+        ``(N,)`` boolean mask over the cloud's points.
+
+    Raises:
+        ValueError: when neither or both of ``bbox`` and ``polygon`` are given, or when ``polygon`` is not an
+            ``(M, 2)`` array of at least three vertices.
+
+    Examples:
+        >>> import numpy as np
+        >>> from pointclouds import PointCloud
+        >>> cloud = PointCloud(x=np.array([0.0, 2.0]), y=np.array([0.0, 2.0]), z=np.zeros(2))
+        >>> clip_mask(cloud, bbox=(1.0, 1.0, 3.0, 3.0)).tolist()
+        [False, True]
+        >>> ring = np.array([[1.0, 1.0], [1.0, 3.0], [3.0, 3.0], [3.0, 1.0]])
+        >>> clip_mask(cloud, polygon=ring).tolist()
+        [False, True]
+    """
+    if (bbox is None) == (polygon is None):
+        raise ValueError("clip needs exactly one of bbox or polygon")
+    if bbox is not None:
+        return bbox_mask(cloud.x, cloud.y, bbox)
+    return _points_in_polygon(cloud.x, cloud.y, np.asarray(polygon, dtype=np.float64))
+
+
+def _points_in_polygon(x: np.ndarray, y: np.ndarray, ring: np.ndarray) -> np.ndarray:
+    """Return the mask of points inside a single polygon ring by even-odd ray casting.
+
+    The test is vectorised over all points and loops only over the ring's edges, so its cost is
+    ``O(points * edges)``. A point on the boundary is reported inconsistently, as the even-odd rule always does;
+    that is acceptable for clipping a dense cloud.
+
+    Args:
+        x: ``(N,)`` x-coordinates.
+        y: ``(N,)`` y-coordinates.
+        ring: ``(M, 2)`` vertices; the ring is treated as closed, so the first vertex need not be repeated.
+
+    Returns:
+        ``(N,)`` boolean mask, ``True`` for points inside the ring.
+
+    Raises:
+        ValueError: when ``ring`` is not an ``(M, 2)`` array of at least three vertices.
+    """
+    if ring.ndim != 2 or ring.shape[1] != 2 or ring.shape[0] < 3:
+        raise ValueError(f"polygon must be an (M, 2) array of at least 3 vertices; got shape {ring.shape}")
+
+    px, py = ring[:, 0], ring[:, 1]
+    inside = np.zeros(x.shape[0], dtype=bool)
+    # Walk each edge (j -> i); a horizontal edge never flips the ray parity, and the (yi > y) != (yj > y)
+    # guard makes it harmless, so the divide/invalid warnings it would raise are suppressed rather than hit.
+    with np.errstate(divide="ignore", invalid="ignore"):
+        j = len(px) - 1
+        for i in range(len(px)):
+            crosses = (py[i] > y) != (py[j] > y)
+            x_at_edge = (px[j] - px[i]) * (y - py[i]) / (py[j] - py[i]) + px[i]
+            inside ^= crosses & (x < x_at_edge)
+            j = i
+    return inside

pointclouds/ops/decimate.py

@@ -0,0 +1,107 @@
+"""Choose which points survive a decimation: random thinning and voxel thinning. (Phase 2 - T-9).
+
+Both entry points return an integer index array into the cloud's points; :meth:`PointCloud._take` does the
+actual subsetting, so neither function constructs a cloud. Random thinning is reproducible under a seed; voxel
+thinning keeps one point per cube and is deterministic. Pure numpy - no GDAL, no pyramids.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from pointclouds.points import PointCloud
+
+__all__ = ["select_indices"]
+
+
+def select_indices(
+    cloud: PointCloud,
+    *,
+    target: int | None = None,
+    fraction: float | None = None,
+    method: str = "random",
+    voxel_size: float | None = None,
+    seed: int | None = None,
+) -> np.ndarray:
+    """Return the indices of the points to keep under the requested decimation.
+
+    Args:
+        cloud: the cloud to thin; its records are loaded if they are not in memory yet.
+        target: for ``method="random"``, the number of points to keep. Never more than the cloud holds.
+        fraction: for ``method="random"``, the share of points to keep, in ``(0, 1]``. A positive fraction over a
+            non-empty cloud keeps at least one point (it never rounds down to zero).
+        method: ``"random"`` for a uniform sample without replacement, ``"voxel"`` for one point per cube.
+        voxel_size: for ``method="voxel"``, the cube edge length in CRS units.
+        seed: seeds the random sample so a run is reproducible; ignored by ``"voxel"``.
+
+    Returns:
+        A sorted ``(k,)`` int array of indices into the cloud's points, so ``_take`` preserves point order.
+
+    Raises:
+        ValueError: when the arguments for the chosen method are missing, ambiguous, or out of range, or when
+            ``method`` is neither ``"random"`` nor ``"voxel"``.
+
+    Examples:
+        >>> import numpy as np
+        >>> from pointclouds import PointCloud
+        >>> cloud = PointCloud(x=np.arange(10.0), y=np.zeros(10), z=np.zeros(10))
+        >>> len(select_indices(cloud, target=3, seed=0))
+        3
+        >>> line = PointCloud(x=np.array([0.0, 0.5, 1.0, 1.5]), y=np.zeros(4), z=np.zeros(4))
+        >>> select_indices(line, method="voxel", voxel_size=1.0).tolist()
+        [0, 2]
+    """
+    n = cloud.x.shape[0]  # forces a lazy cloud to load
+
+    if method == "random":
+        return _random_indices(n, target=target, fraction=fraction, seed=seed)
+    if method == "voxel":
+        return _voxel_indices(cloud, voxel_size=voxel_size)
+    raise ValueError(f"unknown decimation method {method!r}; expected 'random' or 'voxel'")
+
+
+def _random_indices(n: int, *, target: int | None, fraction: float | None, seed: int | None) -> np.ndarray:
+    """Return a sorted uniform sample of ``n`` indices, sized by ``target`` or ``fraction``."""
+    if (target is None) == (fraction is None):
+        raise ValueError("random decimation needs exactly one of target or fraction")
+    if target is not None:
+        if target < 0:
+            raise ValueError(f"target must be non-negative; got {target}")
+        keep = min(int(target), n)
+    else:
+        assert fraction is not None  # noqa: S101 - guaranteed by the exactly-one check above
+        if not 0.0 < fraction <= 1.0:
+            raise ValueError(f"fraction must be in (0, 1]; got {fraction}")
+        # A positive fraction over a non-empty cloud keeps at least one point: rounding a small share down to
+        # zero would turn "keep some" into "keep none", which no caller asking for a fraction means.
+        keep = min(n, max(1, int(round(fraction * n)))) if n else 0
+
+    rng = np.random.default_rng(seed)
+    chosen = rng.choice(n, size=keep, replace=False)
+    chosen.sort()
+    return chosen
+
+
+def _voxel_indices(cloud: PointCloud, *, voxel_size: float | None) -> np.ndarray:
+    """Return the index of the first point in each occupied ``voxel_size`` cube, in point order."""
+    if voxel_size is None or voxel_size <= 0:
+        raise ValueError(f"voxel decimation needs a positive voxel_size; got {voxel_size}")
+
+    x, y, z = cloud.x, cloud.y, cloud.z
+    if x.size == 0:
+        return np.empty(0, dtype=np.intp)
+
+    keys = np.stack(
+        [
+            np.floor((x - x.min()) / voxel_size).astype(np.int64),
+            np.floor((y - y.min()) / voxel_size).astype(np.int64),
+            np.floor((z - z.min()) / voxel_size).astype(np.int64),
+        ],
+        axis=1,
+    )
+    _, first = np.unique(keys, axis=0, return_index=True)
+    first.sort()
+    return first

pointclouds/ops/filter.py

@@ -0,0 +1,109 @@
+"""Build the boolean masks that subset a cloud by attribute or extent. (Phase 2 - T-9).
+
+This is the one mask-building helper the four public operations share. :func:`build_mask` turns the
+``filter`` criteria into a boolean mask over the points; :func:`bbox_mask` is the extent test that both
+:meth:`~pointclouds.points.PointCloud.filter` and :mod:`pointclouds.ops.clip` reuse. Nothing here constructs a
+cloud or indexes its arrays - that is :meth:`PointCloud._take`'s job, so the alignment invariant lives in one
+place. Everything imports with the core dependency set alone (numpy); no GDAL, no pyramids, no shapely.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from pointclouds.points import PointCloud
+
+__all__ = ["bbox_mask", "build_mask"]
+
+#: The attribute dimensions :func:`build_mask` can filter on, each a membership test against the given value(s).
+#: Ordered as everywhere else in the package (:data:`pointclouds.points._ATTRIBUTE_DTYPES`, ``ops.merge``).
+_ATTRIBUTE_CRITERIA = ("intensity", "classification", "return_number")
+
+
+def bbox_mask(x: np.ndarray, y: np.ndarray, bbox: tuple[float, float, float, float]) -> np.ndarray:
+    """Return the mask of points inside an axis-aligned bounding box, edges included.
+
+    Args:
+        x: ``(N,)`` x-coordinates.
+        y: ``(N,)`` y-coordinates.
+        bbox: ``(xmin, ymin, xmax, ymax)``; a point on an edge counts as inside.
+
+    Returns:
+        ``(N,)`` boolean mask, ``True`` where the point falls within ``bbox``.
+
+    Raises:
+        ValueError: when ``bbox`` is not four numbers with ``xmin <= xmax`` and ``ymin <= ymax``.
+
+    Examples:
+        >>> import numpy as np
+        >>> x = np.array([0.0, 5.0, 9.0])
+        >>> y = np.array([0.0, 0.0, 0.0])
+        >>> bbox_mask(x, y, (4.0, -1.0, 10.0, 1.0)).tolist()
+        [False, True, True]
+    """
+    xmin, ymin, xmax, ymax = bbox
+    if xmin > xmax or ymin > ymax:
+        raise ValueError(f"bbox must be (xmin, ymin, xmax, ymax) with min <= max; got {bbox}")
+    return (x >= xmin) & (x <= xmax) & (y >= ymin) & (y <= ymax)
+
+
+def build_mask(
+    cloud: PointCloud,
+    *,
+    classification: int | Iterable[int] | None = None,
+    return_number: int | Iterable[int] | None = None,
+    intensity: int | Iterable[int] | None = None,
+    bbox: tuple[float, float, float, float] | None = None,
+) -> np.ndarray:
+    """Combine the given criteria into one boolean mask, ANDing every criterion together.
+
+    Each attribute criterion is a membership test: a scalar keeps points equal to it, an iterable keeps points
+    whose value is in the set. ``bbox`` keeps points inside the extent. A criterion left ``None`` is ignored; with
+    no criteria at all the mask keeps everything.
+
+    Args:
+        cloud: the cloud to test; its record arrays are loaded if they are not in memory yet.
+        classification: an ASPRS class code, or an iterable of them, to keep.
+        return_number: a return number, or an iterable of them, to keep.
+        intensity: an intensity value, or an iterable of them, to keep.
+        bbox: ``(xmin, ymin, xmax, ymax)`` extent to keep, edges included.
+
+    Returns:
+        ``(N,)`` boolean mask over the cloud's points.
+
+    Raises:
+        ValueError: when a criterion names an attribute the cloud does not carry (an empty array), or when
+            ``bbox`` is malformed.
+
+    Examples:
+        >>> import numpy as np
+        >>> from pointclouds import PointCloud
+        >>> cloud = PointCloud(
+        ...     x=np.arange(4.0), y=np.zeros(4), z=np.zeros(4),
+        ...     classification=np.array([2, 5, 2, 6], dtype=np.uint8),
+        ... )
+        >>> build_mask(cloud, classification=2).tolist()
+        [True, False, True, False]
+        >>> build_mask(cloud, classification=[2, 6], bbox=(1.0, -1.0, 3.0, 1.0)).tolist()
+        [False, False, True, True]
+    """
+    n = cloud.x.shape[0]  # also forces a lazy cloud to load, so every array below is populated
+    mask = np.ones(n, dtype=bool)
+
+    for name, criterion in zip(_ATTRIBUTE_CRITERIA, (intensity, classification, return_number), strict=True):
+        if criterion is None:
+            continue
+        values = getattr(cloud, name)
+        if values.size == 0:
+            raise ValueError(f"cannot filter on {name!r}: this cloud carries no {name} data")
+        wanted = np.atleast_1d(np.asarray(criterion))
+        mask &= np.isin(values, wanted)
+
+    if bbox is not None:
+        mask &= bbox_mask(cloud.x, cloud.y, bbox)
+
+    return mask

pointclouds/ops/grid.py

@@ -0,0 +1,241 @@
+"""Grid a cloud to a raster surface (``to_grid``). (Phase 2 - T-11).
+
+NumPy binning plus a SciPy KD-tree for the radius window, no GDAL. The aggregation names follow PDAL's
+``writers.gdal`` vocabulary exactly - ``min``, ``max``, ``mean``, ``count``, ``stdev``, ``idw`` and ``p<n>`` -
+so a reader arriving from PDAL meets the same words.
+
+Decision - the default window is ``mode="bin"`` (the §6/§9 open question, settled here).
+    PDAL defaults to a radius window with a ``binmode`` opt-in; this package does the opposite, because a DSM/DTM
+    caller almost always means "the points that fall in this pixel", and digital-rivers' bare-earth path only
+    ever uses bin mode. The choice is made explicit in the signature rather than implied: pass ``mode="radius"``
+    for PDAL's behaviour, where every point within ``radius`` of a cell centre contributes.
+
+Cost: bin mode is a single vectorised pass over the points. Radius mode issues one KD-tree ball query per cell,
+so its cost grows with the number of cells - prefer bin mode for a large grid unless the radius window is needed.
+
+The result is ``(array, transform, crs)``: a plain NumPy array, a GDAL-style affine 6-tuple
+``(x_origin, cell_size, 0, y_origin, 0, -cell_size)``, and the cloud's :class:`pyproj.CRS` (or ``None``) - never a
+GDAL object. Turning that into a pyramids ``Dataset`` is the separate ``[gis]`` step in
+:mod:`pointclouds.convert` (T-12).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+if TYPE_CHECKING:
+    from pyproj import CRS
+
+    from pointclouds.points import PointCloud
+
+__all__ = ["to_grid"]
+
+#: Matches a percentile aggregate such as ``p95`` or ``p99.5`` and captures the percentile.
+_PERCENTILE = re.compile(r"^p(\d{1,3}(?:\.\d+)?)$")
+
+#: Aggregates that need no per-point distance, so the plain reducers serve them.
+_SIMPLE = frozenset({"min", "max", "mean", "count", "stdev"})
+
+#: Floor on the point-to-centre distance used by ``idw``, so a point sitting on a cell centre does not blow up.
+_IDW_EPS = 1e-12
+
+
+def to_grid(
+    cloud: PointCloud,
+    *,
+    cell_size: float,
+    aggregate: str = "mean",
+    mode: str = "bin",
+    radius: float | None = None,
+    bounds: tuple[float, float, float, float] | None = None,
+    nodata: float = np.nan,
+) -> tuple[np.ndarray, tuple[float, float, float, float, float, float], CRS | None]:
+    """Bin or interpolate the cloud onto a regular grid.
+
+    Args:
+        cloud: the cloud to grid; its records are loaded if they are not in memory yet.
+        cell_size: the pixel edge length in CRS units; must be positive.
+        aggregate: how the z-values in (or near) a cell are reduced - one of ``min``, ``max``, ``mean``,
+            ``count``, ``stdev``, ``idw``, or a percentile ``p<n>`` such as ``p95`` (PDAL ``writers.gdal`` names).
+        mode: ``"bin"`` (the default) counts only points inside the pixel; ``"radius"`` counts every point within
+            ``radius`` of the pixel centre.
+        radius: the search radius for ``mode="radius"``; defaults to ``cell_size * sqrt(2)`` (PDAL's default)
+            when ``None``. Ignored in bin mode.
+        bounds: ``(xmin, ymin, xmax, ymax)`` extent to grid; defaults to the cloud's own bounds. When its width
+            or height is not a whole multiple of ``cell_size``, the grid is rounded up to whole cells and so
+            extends past ``bounds``; points within that physical extent are kept, not dropped.
+        nodata: the value written to empty cells. The default ``NaN`` forces a float grid. ``count`` is the one
+            exception - an empty cell counts ``0``, not ``nodata``.
+
+    Returns:
+        ``(array, transform, crs)``: an ``(nrows, ncols)`` float64 array (row 0 is the northernmost), a GDAL-style
+        affine 6-tuple ``(xmin, cell_size, 0, ymax, 0, -cell_size)``, and the cloud's CRS.
+
+    Raises:
+        ValueError: when ``cell_size`` is not positive; when the extent has a non-positive area - either a
+            ``bounds`` with ``xmax <= xmin`` or ``ymax <= ymin``, or the default extent of a flat cloud whose
+            points share a single x or a single y; when ``mode`` is neither ``"bin"`` nor ``"radius"``; or when
+            ``aggregate`` is not a recognised name.
+
+    Examples:
+        >>> import numpy as np
+        >>> from pointclouds import PointCloud
+        >>> cloud = PointCloud(x=np.array([0.5, 1.5]), y=np.array([0.5, 0.5]), z=np.array([10.0, 20.0]))
+        >>> array, transform, _ = cloud.to_grid(cell_size=1.0, aggregate="min", bounds=(0, 0, 2, 1))
+        >>> array.tolist()
+        [[10.0, 20.0]]
+        >>> transform
+        (0.0, 1.0, 0.0, 1.0, 0.0, -1.0)
+    """
+    if cell_size <= 0:
+        raise ValueError(f"cell_size must be positive; got {cell_size}")
+    if mode not in ("bin", "radius"):
+        raise ValueError(f"unknown mode {mode!r}; expected 'bin' or 'radius'")
+    reducer = _reducer(aggregate)  # validate the aggregate before any heavy work
+
+    xmin, ymin, xmax, ymax = cloud.bounds if bounds is None else bounds
+    if xmax <= xmin or ymax <= ymin:
+        raise ValueError(f"to_grid needs a positive-area bounds; got {(xmin, ymin, xmax, ymax)}")
+    ncols = math.ceil((xmax - xmin) / cell_size)
+    nrows = math.ceil((ymax - ymin) / cell_size)
+
+    x, y, z = cloud.x, cloud.y, cloud.z
+    if mode == "bin":
+        cell, values, distance = _bin_contributions(x, y, z, xmin, ymax, cell_size, ncols, nrows)
+    else:
+        cell, values, distance = _radius_contributions(
+            x, y, z, xmin, ymax, cell_size, ncols, nrows, radius if radius is not None else cell_size * math.sqrt(2)
+        )
+
+    flat = reducer(cell, values, distance, ncols * nrows, nodata)
+    transform = (float(xmin), float(cell_size), 0.0, float(ymax), 0.0, -float(cell_size))
+    return flat.reshape(nrows, ncols), transform, cloud.crs
+
+
+def _bin_contributions(x, y, z, xmin, ymax, cell_size, ncols, nrows):
+    """Assign each point to the one cell it falls in, dropping points outside the grid.
+
+    The grid is anchored at the top-left ``(xmin, ymax)`` and spans whole cells, so its physical extent reaches
+    ``xmin + ncols*cell_size`` / ``ymax - nrows*cell_size`` - past a ``bounds`` that is not a whole multiple of
+    ``cell_size``. Membership is that physical box, and the cell index is then clamped into the grid, so a point
+    on any edge - the ceil-rounded overhang as well as the max-x / min-y edge of the default extent (where
+    ``bounds`` is the data's own min/max) - folds into the cell that visually covers it (the closed-last-edge rule
+    ``np.histogram2d`` uses) instead of being discarded.
+
+    Returns the flat cell index, the z-value and the distance to that cell's centre, one entry per kept point.
+    """
+    x_max = xmin + ncols * cell_size
+    y_min = ymax - nrows * cell_size
+    inside = (x >= xmin) & (x <= x_max) & (y >= y_min) & (y <= ymax)
+    xi, yi, zi = x[inside], y[inside], z[inside]
+    col = np.clip(np.floor((xi - xmin) / cell_size).astype(np.int64), 0, ncols - 1)
+    row = np.clip(np.floor((ymax - yi) / cell_size).astype(np.int64), 0, nrows - 1)
+
+    centre_x = xmin + (col + 0.5) * cell_size
+    centre_y = ymax - (row + 0.5) * cell_size
+    distance = np.hypot(xi - centre_x, yi - centre_y)
+    return row * ncols + col, zi, distance
+
+
+def _radius_contributions(x, y, z, xmin, ymax, cell_size, ncols, nrows, radius):
+    """Let every point within ``radius`` of a cell centre contribute to that cell.
+
+    A point can land in several cells. Returns the flat cell index, the z-value and the point-to-centre distance,
+    one entry per (cell, point) pair.
+    """
+    ncells = ncols * nrows
+    rows, cols = np.divmod(np.arange(ncells), ncols)
+    centre_x = xmin + (cols + 0.5) * cell_size
+    centre_y = ymax - (rows + 0.5) * cell_size
+
+    tree = cKDTree(np.column_stack([x, y]))
+    neighbours = tree.query_ball_point(np.column_stack([centre_x, centre_y]), r=radius)
+
+    counts = np.fromiter((len(n) for n in neighbours), dtype=np.int64, count=ncells)
+    cell = np.repeat(np.arange(ncells), counts)
+    points = np.fromiter((p for n in neighbours for p in n), dtype=np.int64, count=int(counts.sum()))
+    distance = np.hypot(x[points] - centre_x[cell], y[points] - centre_y[cell])
+    return cell, z[points], distance
+
+
+def _reducer(aggregate: str):
+    """Return the reducer for an aggregate name, or raise when the name is not recognised."""
+    if aggregate in _SIMPLE:
+        return lambda cell, values, distance, ncells, nodata: _reduce_simple(aggregate, cell, values, ncells, nodata)
+    if aggregate == "idw":
+        return _reduce_idw
+    match = _PERCENTILE.match(aggregate)
+    if match:
+        percentile = float(match.group(1))
+        if not 0.0 <= percentile <= 100.0:
+            raise ValueError(f"percentile out of range in {aggregate!r}; expected p0..p100")
+        return lambda cell, values, distance, ncells, nodata: _reduce_percentile(
+            percentile, cell, values, ncells, nodata
+        )
+    raise ValueError(
+        f"unknown aggregate {aggregate!r}; expected one of min, max, mean, count, stdev, idw, or a percentile like p95"
+    )
+
+
+def _reduce_simple(aggregate: str, cell: np.ndarray, values: np.ndarray, ncells: int, nodata: float) -> np.ndarray:
+    """Reduce with one of the count-based aggregates (``count``/``mean``/``min``/``max``/``stdev``)."""
+    count = np.bincount(cell, minlength=ncells)
+    if aggregate == "count":
+        return count.astype(np.float64)  # an empty cell honestly holds zero points, not nodata
+
+    grid = np.full(ncells, float(nodata), dtype=np.float64)
+    occupied = count > 0
+    if aggregate in ("mean", "stdev"):
+        total = np.bincount(cell, weights=values, minlength=ncells)
+        mean = np.zeros(ncells)
+        mean[occupied] = total[occupied] / count[occupied]
+        if aggregate == "mean":
+            grid[occupied] = mean[occupied]
+        else:
+            # Two-pass variance about the per-cell mean. Stable where the one-pass sum-of-squares minus
+            # mean-squared catastrophically cancels for large-magnitude z (e.g. projected elevations near 1e9),
+            # and non-negative by construction, so no clip-to-zero is needed.
+            deviation = values - mean[cell]
+            sum_sq = np.bincount(cell, weights=deviation * deviation, minlength=ncells)
+            grid[occupied] = np.sqrt(sum_sq[occupied] / count[occupied])
+    elif aggregate == "min":
+        reduced = np.full(ncells, np.inf)
+        np.minimum.at(reduced, cell, values)
+        grid[occupied] = reduced[occupied]
+    else:  # max
+        reduced = np.full(ncells, -np.inf)
+        np.maximum.at(reduced, cell, values)
+        grid[occupied] = reduced[occupied]
+    return grid
+
+
+def _reduce_idw(cell: np.ndarray, values: np.ndarray, distance: np.ndarray, ncells: int, nodata: float) -> np.ndarray:
+    """Reduce by inverse-distance weighting, each contribution weighted by ``1 / distance`` to the cell centre."""
+    grid = np.full(ncells, float(nodata), dtype=np.float64)
+    weight = 1.0 / np.maximum(distance, _IDW_EPS)
+    weight_sum = np.bincount(cell, weights=weight, minlength=ncells)
+    weighted = np.bincount(cell, weights=weight * values, minlength=ncells)
+    occupied = weight_sum > 0
+    grid[occupied] = weighted[occupied] / weight_sum[occupied]
+    return grid
+
+
+def _reduce_percentile(
+    percentile: float, cell: np.ndarray, values: np.ndarray, ncells: int, nodata: float
+) -> np.ndarray:
+    """Reduce to a per-cell percentile, looping over occupied cells only."""
+    grid = np.full(ncells, float(nodata), dtype=np.float64)
+    if cell.size == 0:
+        return grid
+    order = np.argsort(cell, kind="stable")
+    sorted_cells, sorted_values = cell[order], values[order]
+    occupied, starts = np.unique(sorted_cells, return_index=True)
+    bounds = np.append(starts, sorted_cells.size)
+    for k, index in enumerate(occupied):
+        grid[index] = np.percentile(sorted_values[bounds[k] : bounds[k + 1]], percentile)
+    return grid