zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/terrain.py

@@ -0,0 +1,610 @@
+"""Terrain analysis on a DEM :class:`~zero2geospatial3d.grid.Grid`.
+
+Slope and aspect (Horn 1981), hillshade, contours (marching squares),
+profiles / terrain sections, bathtub and seeded flooding, cut and fill,
+curvature, topographic position (TPI), ruggedness (TRI), flow accumulation
+(priority flood + D8) and the topographic wetness index (TWI).
+
+NaN cells are "no data": they never flood, contour, cut or fill, and they
+stay NaN in every derived map (edges are handled by repeating the border
+cell, as in the plugin's viewer).
+"""
+
+from __future__ import annotations
+
+import heapq
+import math
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+import numpy as np
+
+from .grid import Grid
+
+__all__ = [
+    "ContourSet",
+    "CutFillResult",
+    "FloodResult",
+    "GridStats",
+    "Profile",
+    "aspect_classes",
+    "balanced_level",
+    "contours",
+    "crop_grid",
+    "curvature",
+    "cut_fill",
+    "flood",
+    "flow_accumulation",
+    "grid_stats",
+    "hillshade",
+    "percentile",
+    "point_in_ring",
+    "points_in_ring",
+    "profile",
+    "ruggedness",
+    "slope_aspect",
+    "slope_aspect_at",
+    "tpi",
+    "wetness",
+]
+
+Ring = Sequence[Sequence[float]]
+
+
+def _padded(z: np.ndarray) -> np.ndarray:
+    return np.pad(z, 1, mode="edge")
+
+
+def _horn(g: Grid) -> tuple[np.ndarray, np.ndarray]:
+    """Horn gradients (dz/dx towards east, dz/dy towards north), edges repeated."""
+    p = _padded(g.values)
+    a, b, cc = p[:-2, :-2], p[:-2, 1:-1], p[:-2, 2:]
+    d, f = p[1:-1, :-2], p[1:-1, 2:]
+    gg, h, i = p[2:, :-2], p[2:, 1:-1], p[2:, 2:]
+    dzdx = ((cc + 2 * f + i) - (a + 2 * d + gg)) / (8 * g.cell)
+    dzdy = ((a + 2 * b + cc) - (gg + 2 * h + i)) / (8 * g.cell)
+    return dzdx, dzdy
+
+
+def slope_aspect(g: Grid) -> tuple[np.ndarray, np.ndarray]:
+    """Horn (1981) slope and aspect in degrees.
+
+    Returns:
+        ``(slope, aspect)`` arrays of shape ``(rows, cols)``. Aspect is the
+        downslope bearing clockwise from north, ``-1`` on flat cells.
+    """
+    dzdx, dzdy = _horn(g)
+    slope = np.degrees(np.arctan(np.hypot(dzdx, dzdy)))
+    with np.errstate(invalid="ignore"):
+        aspect = np.degrees(np.arctan2(-dzdx, -dzdy))
+    aspect = np.where(aspect < 0, aspect + 360, aspect)
+    aspect = np.where((dzdx == 0) & (dzdy == 0), -1.0, aspect)
+    return slope, aspect
+
+
+def slope_aspect_at(g: Grid, c: int, r: int) -> tuple[float, float]:
+    """Horn slope and aspect (degrees, ``-1`` flat) of a single cell."""
+    z = g.values
+    rows, cols = z.shape
+
+    def at(cc: int, rr: int) -> float:
+        return float(z[min(max(rr, 0), rows - 1), min(max(cc, 0), cols - 1)])
+
+    dzdx = (
+        (at(c + 1, r - 1) + 2 * at(c + 1, r) + at(c + 1, r + 1))
+        - (at(c - 1, r - 1) + 2 * at(c - 1, r) + at(c - 1, r + 1))
+    ) / (8 * g.cell)
+    dzdy = (
+        (at(c - 1, r - 1) + 2 * at(c, r - 1) + at(c + 1, r - 1))
+        - (at(c - 1, r + 1) + 2 * at(c, r + 1) + at(c + 1, r + 1))
+    ) / (8 * g.cell)
+    slope = math.degrees(math.atan(math.hypot(dzdx, dzdy)))
+    if dzdx == 0 and dzdy == 0:
+        return slope, -1.0
+    aspect = math.degrees(math.atan2(-dzdx, -dzdy))
+    if aspect < 0:
+        aspect += 360
+    return slope, aspect
+
+
+def hillshade(
+    g: Grid, azimuth_deg: float = 315.0, altitude_deg: float = 45.0, z_factor: float = 1.0
+) -> np.ndarray:
+    """Hillshade in ``0..1`` for a light from ``azimuth_deg`` / ``altitude_deg``."""
+    zen = math.radians(90 - altitude_deg)
+    az = math.radians(azimuth_deg)
+    lx = math.sin(zen) * math.sin(az)
+    ly = math.sin(zen) * math.cos(az)
+    lz = math.cos(zen)
+    dzdx, dzdy = _horn(g)
+    dzdx = dzdx * z_factor
+    dzdy = dzdy * z_factor
+    shade = (-dzdx * lx - dzdy * ly + lz) / np.sqrt(dzdx * dzdx + dzdy * dzdy + 1)
+    return np.maximum(0.0, shade)
+
+
+@dataclass
+class ContourSet:
+    """Contour segments at one level; ``segments`` is ``(n, 4)``: x1, y1, x2, y2."""
+
+    level: float
+    segments: np.ndarray
+
+
+def contours(
+    g: Grid, interval: float, base: float = 0.0, max_levels: int = 400
+) -> list[ContourSet]:
+    """Contour line segments by marching squares, sorted by level.
+
+    Cells with a NaN corner produce no segments; a saddle cell yields two.
+    """
+    z = g.values
+    if not (interval > 0) or not np.isfinite(z).any():
+        return []
+    lo = float(np.nanmin(z))
+    hi = float(np.nanmax(z))
+    k_first = math.ceil((lo - base) / interval)
+    k_last = min(math.floor((hi - base) / interval), k_first + max_levels - 1)
+    if g.rows < 2 or g.cols < 2:
+        return []
+    v0 = z[:-1, :-1]
+    v1 = z[:-1, 1:]
+    v2 = z[1:, 1:]
+    v3 = z[1:, :-1]
+    valid = np.isfinite(v0) & np.isfinite(v1) & np.isfinite(v2) & np.isfinite(v3)
+    nr, nc = v0.shape
+    xa = g.min_x + np.arange(nc) * g.cell
+    ya = g.max_y - np.arange(nr) * g.cell
+    xa, ya = np.meshgrid(xa, ya)
+    xb = xa + g.cell
+    yb = ya - g.cell
+    cell = g.cell
+    out: list[ContourSet] = []
+    with np.errstate(invalid="ignore", divide="ignore"):
+        for k in range(k_first, k_last + 1):
+            level = base + k * interval
+            b0, b1, b2, b3 = v0 < level, v1 < level, v2 < level, v3 < level
+            e = [b0 != b1, b1 != b2, b2 != b3, b3 != b0]
+            n = e[0].astype(int) + e[1] + e[2] + e[3]
+            ok = valid & ((n == 2) | (n == 4))
+            if not ok.any():
+                continue
+            pts = [
+                (xa + cell * (level - v0) / (v1 - v0), ya),
+                (xb, ya - cell * (level - v1) / (v2 - v1)),
+                (xb - cell * (level - v2) / (v3 - v2), yb),
+                (xa, yb + cell * (level - v3) / (v0 - v3)),
+            ]
+            rr, cc = np.nonzero(ok)
+            segs: list[list[float]] = []
+            for r, c in zip(rr.tolist(), cc.tolist()):
+                p: list[float] = []
+                for j in range(4):
+                    if e[j][r, c]:
+                        p.append(float(pts[j][0][r, c]))
+                        p.append(float(pts[j][1][r, c]))
+                segs.append(p[:4])
+                if len(p) == 8:
+                    segs.append(p[4:])
+            out.append(ContourSet(level, np.asarray(segs, dtype=float).reshape(-1, 4)))
+    return out
+
+
+@dataclass
+class Profile:
+    """Heights sampled along a polyline: distance ``d``, position ``x, y``, height ``z``."""
+
+    d: np.ndarray
+    x: np.ndarray
+    y: np.ndarray
+    z: np.ndarray
+
+    def __len__(self) -> int:
+        return int(self.d.size)
+
+
+def profile(g: Grid, points: Sequence[Sequence[float]], step: Optional[float] = None) -> Profile:
+    """Terrain section: sample heights along a polyline every ``step`` metres.
+
+    ``step`` defaults to half a cell. Gaps in the DEM (NaN) come back as NaN.
+    """
+    s = step or g.cell / 2
+    ds: list[np.ndarray] = []
+    xs: list[np.ndarray] = []
+    ys: list[np.ndarray] = []
+    dist = 0.0
+    for i in range(len(points) - 1):
+        x0, y0 = float(points[i][0]), float(points[i][1])
+        x1, y1 = float(points[i + 1][0]), float(points[i + 1][1])
+        length = math.hypot(x1 - x0, y1 - y0)
+        n = max(1, math.ceil(length / s))
+        t = np.arange(0 if i == 0 else 1, n + 1) / n
+        xs.append(x0 + (x1 - x0) * t)
+        ys.append(y0 + (y1 - y0) * t)
+        ds.append(dist + length * t)
+        dist += length
+    if not ds:
+        empty = np.zeros(0)
+        return Profile(empty, empty.copy(), empty.copy(), empty.copy())
+    x = np.concatenate(xs)
+    y = np.concatenate(ys)
+    return Profile(np.concatenate(ds), x, y, g.sample_many(x, y))
+
+
+@dataclass
+class FloodResult:
+    """Water depth per cell (NaN where dry) and totals."""
+
+    depth: np.ndarray
+    flooded_cells: int
+    area: float
+    volume: float
+    max_depth: float
+
+
+def flood(g: Grid, level: float, seed: Optional[Sequence[float]] = None) -> FloodResult:
+    """Cells under a water ``level``.
+
+    Without a ``seed`` every cell below the level floods (a plain bathtub).
+    With a seed ``(x, y)`` only cells 4-connected to it flood, like water
+    rising from that point. NaN cells never flood.
+    """
+    z = g.values
+    rows, cols = z.shape
+    depth = np.full(z.shape, np.nan)
+    with np.errstate(invalid="ignore"):
+        below = z < level
+    if seed is not None:
+        c0 = int(round((seed[0] - g.min_x) / g.cell))
+        r0 = int(round((g.max_y - seed[1]) / g.cell))
+        if c0 < 0 or r0 < 0 or c0 >= cols or r0 >= rows or not below[r0, c0]:
+            return FloodResult(depth, 0, 0.0, 0.0, 0.0)
+        mask = np.zeros(z.shape, dtype=bool)
+        mask[r0, c0] = True
+        stack = [(r0, c0)]
+        while stack:
+            r, c = stack.pop()
+            for rr, cc in ((r, c - 1), (r, c + 1), (r - 1, c), (r + 1, c)):
+                if 0 <= rr < rows and 0 <= cc < cols and not mask[rr, cc] and below[rr, cc]:
+                    mask[rr, cc] = True
+                    stack.append((rr, cc))
+    else:
+        mask = below
+    d = level - z[mask]
+    depth[mask] = d
+    count = int(mask.sum())
+    return FloodResult(
+        depth=depth,
+        flooded_cells=count,
+        area=count * g.cell * g.cell,
+        volume=float(d.sum()) * g.cell * g.cell,
+        max_depth=float(max(0.0, d.max())) if count else 0.0,
+    )
+
+
+def points_in_ring(x: np.ndarray, y: np.ndarray, ring: Ring) -> np.ndarray:
+    """Vectorised even-odd point-in-polygon test."""
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    inside = np.zeros(np.broadcast(x, y).shape, dtype=bool)
+    n = len(ring)
+    j = n - 1
+    for i in range(n):
+        xi, yi = float(ring[i][0]), float(ring[i][1])
+        xj, yj = float(ring[j][0]), float(ring[j][1])
+        dy = (yj - yi) or 1e-12
+        cross = ((yi > y) != (yj > y)) & (x < (xj - xi) * (y - yi) / dy + xi)
+        inside ^= cross
+        j = i
+    return inside
+
+
+def point_in_ring(x: float, y: float, ring: Ring) -> bool:
+    """Even-odd test of one point against a polygon ring ``[(x, y), ...]``."""
+    return bool(points_in_ring(np.array(x), np.array(y), ring))
+
+
+@dataclass
+class CutFillResult:
+    """Earthwork volumes (m3) and per-cell ``delta = design - ground`` (NaN outside)."""
+
+    cut: float
+    fill: float
+    net: float
+    area: float
+    delta: np.ndarray
+
+
+def cut_fill(g: Grid, ring: Ring, design_level: float) -> CutFillResult:
+    """Cut and fill to bring the ground inside ``ring`` to a flat ``design_level``."""
+    z = g.values
+    rows, cols = z.shape
+    delta = np.full(z.shape, np.nan)
+    ring_arr = np.asarray(ring, dtype=float)
+    min_x, min_y = ring_arr[:, 0].min(), ring_arr[:, 1].min()
+    max_x, max_y = ring_arr[:, 0].max(), ring_arr[:, 1].max()
+    c0 = max(0, math.floor((min_x - g.min_x) / g.cell))
+    c1 = min(cols - 1, math.ceil((max_x - g.min_x) / g.cell))
+    r0 = max(0, math.floor((g.max_y - max_y) / g.cell))
+    r1 = min(rows - 1, math.ceil((g.max_y - min_y) / g.cell))
+    if c1 < c0 or r1 < r0:
+        return CutFillResult(0.0, 0.0, 0.0, 0.0, delta)
+    xs = g.min_x + np.arange(c0, c1 + 1) * g.cell
+    ys = g.max_y - np.arange(r0, r1 + 1) * g.cell
+    xx, yy = np.meshgrid(xs, ys)
+    sub = z[r0 : r1 + 1, c0 : c1 + 1]
+    inside = points_in_ring(xx, yy, ring) & np.isfinite(sub)
+    d = design_level - sub[inside]
+    window = delta[r0 : r1 + 1, c0 : c1 + 1]
+    window[inside] = d
+    a = g.cell * g.cell
+    fill = float(d[d > 0].sum()) * a
+    cut = float(-d[d <= 0].sum()) * a
+    return CutFillResult(cut, fill, fill - cut, int(inside.sum()) * a, delta)
+
+
+def balanced_level(g: Grid, ring: Ring) -> float:
+    """Design level that balances cut and fill inside ``ring`` (bisection).
+
+    A polygon smaller than a cell holds no cell centre: the ground at its
+    centre is returned.
+    """
+    ground = -cut_fill(g, ring, 0.0).delta
+    finite = ground[np.isfinite(ground)]
+    if finite.size == 0:
+        pts = np.asarray(ring, dtype=float)
+        cx, cy = pts[:, 0].mean(), pts[:, 1].mean()
+        c = max(0, min(g.cols - 1, int(round((cx - g.min_x) / g.cell))))
+        r = max(0, min(g.rows - 1, int(round((g.max_y - cy) / g.cell))))
+        return float(g.values[r, c])
+    lo, hi = float(finite.min()), float(finite.max())
+    for _ in range(40):
+        mid = (lo + hi) / 2
+        if cut_fill(g, ring, mid).net > 0:
+            hi = mid
+        else:
+            lo = mid
+    return (lo + hi) / 2
+
+
+@dataclass
+class GridStats:
+    """Minimum, maximum and mean of the finite values, and how many there are."""
+
+    min: float
+    max: float
+    mean: float
+    count: int
+
+
+def grid_stats(values: np.ndarray) -> GridStats:
+    """Statistics of the finite values (NaN / inf ignored)."""
+    v = np.asarray(values, dtype=float).ravel()
+    v = v[np.isfinite(v)]
+    if v.size == 0:
+        return GridStats(math.inf, -math.inf, math.nan, 0)
+    return GridStats(float(v.min()), float(v.max()), float(v.mean()), int(v.size))
+
+
+# ------------------------------------------------------------------ derivatives
+
+
+def crop_grid(g: Grid, area: dict, max_cells: int = 4_000_000) -> tuple[Grid, int]:
+    """The part of ``g`` inside ``area`` (``min_x, max_x, min_y, max_y``).
+
+    The crop is coarsened by whole cells (block means, NaN ignored) until it
+    has at most ``max_cells`` cells.
+
+    Returns:
+        ``(grid, factor)`` where ``factor`` is the coarsening factor.
+    """
+    c0 = max(0, math.floor((area["min_x"] - g.min_x) / g.cell + 0.5))
+    c1 = min(g.cols - 1, math.ceil((area["max_x"] - g.min_x) / g.cell - 0.5))
+    r0 = max(0, math.floor((g.max_y - area["max_y"]) / g.cell + 0.5))
+    r1 = min(g.rows - 1, math.ceil((g.max_y - area["min_y"]) / g.cell - 0.5))
+    if c1 < c0 or r1 < r0:
+        raise ValueError("The area does not overlap the terrain.")
+    w = c1 - c0 + 1
+    h = r1 - r0 + 1
+    k = max(1, math.ceil(math.sqrt((w * h) / max_cells)))
+    cols = math.ceil(w / k)
+    rows = math.ceil(h / k)
+    sub = g.values[r0 : r1 + 1, c0 : c1 + 1]
+    padded = np.full((rows * k, cols * k), np.nan)
+    padded[:h, :w] = sub
+    blocks = padded.reshape(rows, k, cols, k)
+    finite = np.isfinite(blocks)
+    s = np.where(finite, blocks, 0.0).sum(axis=(1, 3))
+    n = finite.sum(axis=(1, 3))
+    with np.errstate(invalid="ignore", divide="ignore"):
+        values = np.where(n > 0, s / np.maximum(n, 1), np.nan)
+    out = Grid(
+        values,
+        g.cell * k,
+        g.min_x + (c0 + (k - 1) / 2) * g.cell,
+        g.max_y - (r0 + (k - 1) / 2) * g.cell,
+        g.nodata,
+    )
+    return out, k
+
+
+def curvature(g: Grid) -> np.ndarray:
+    """General curvature (Zevenbergen and Thorne 1987) in 1/100 m.
+
+    Positive on convex ground (ridges), negative on concave ground (valleys).
+    """
+    p = _padded(g.values)
+    z5 = g.values
+    l2 = g.cell * g.cell
+    d = ((p[1:-1, :-2] + p[1:-1, 2:]) / 2 - z5) / l2
+    e = ((p[:-2, 1:-1] + p[2:, 1:-1]) / 2 - z5) / l2
+    return -2 * (d + e) * 100
+
+
+def tpi(g: Grid, radius: float) -> np.ndarray:
+    """Topographic position index (Weiss 2001).
+
+    Elevation minus the mean of a square window of ``radius`` cells around it
+    (the cell itself left out, NaN neighbours ignored).
+    """
+    z = g.values
+    rows, cols = z.shape
+    rad = max(1, int(math.floor(radius + 0.5)))
+    finite = np.isfinite(z)
+    s = np.zeros((rows + 1, cols + 1))
+    n = np.zeros((rows + 1, cols + 1))
+    s[1:, 1:] = np.where(finite, z, 0.0).cumsum(0).cumsum(1)
+    n[1:, 1:] = finite.cumsum(0).cumsum(1)
+    r = np.arange(rows)[:, None]
+    c = np.arange(cols)[None, :]
+    a = np.maximum(0, r - rad)
+    b = np.minimum(rows - 1, r + rad)
+    lft = np.maximum(0, c - rad)
+    rt = np.minimum(cols - 1, c + rad)
+
+    def box(t: np.ndarray) -> np.ndarray:
+        return t[b + 1, rt + 1] - t[a, rt + 1] - t[b + 1, lft] + t[a, lft]
+
+    ssum = box(s)
+    cnt = box(n)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        out = np.where(cnt > 1, z - (ssum - z) / (cnt - 1), 0.0)
+    return np.where(finite, out, np.nan)
+
+
+def ruggedness(g: Grid) -> np.ndarray:
+    """Terrain ruggedness index (Riley et al. 1999), in metres."""
+    z = g.values
+    p = _padded(z)
+    rows, cols = z.shape
+    total = np.zeros(z.shape)
+    for dr in (-1, 0, 1):
+        for dc in (-1, 0, 1):
+            if dr == 0 and dc == 0:
+                continue
+            nb = p[1 + dr : 1 + dr + rows, 1 + dc : 1 + dc + cols]
+            diff = nb - z
+            total += np.where(np.isfinite(nb), diff * diff, 0.0)
+    return np.where(np.isfinite(z), np.sqrt(total), np.nan)
+
+
+def aspect_classes(slope: np.ndarray, aspect: np.ndarray, flat_deg: float = 1.0) -> np.ndarray:
+    """Aspect classes: 0 flat (slope under ``flat_deg``), 1 N, 2 NE, ... 8 NW."""
+    slope = np.asarray(slope, dtype=float)
+    aspect = np.asarray(aspect, dtype=float)
+    with np.errstate(invalid="ignore"):
+        cls = 1 + np.mod(np.floor((aspect + 22.5) / 45), 8)
+        out = np.where((slope < flat_deg) | (aspect < 0), 0.0, cls)
+    return np.where(np.isfinite(slope), out, np.nan)
+
+
+_DC = (-1, 0, 1, -1, 1, -1, 0, 1)
+_DR = (-1, -1, -1, 0, 0, 1, 1, 1)
+
+
+def flow_accumulation(g: Grid) -> tuple[np.ndarray, np.ndarray]:
+    """D8 flow accumulation (cells, each counting itself) on a filled surface.
+
+    Depressions are filled by priority flood from the edges (Barnes et al.
+    2014) with a tiny rise across flats so every cell drains. NaN cells act as
+    outlets like the edge; water reaching an edge cell leaves the DEM there.
+
+    Returns:
+        ``(acc, filled)``, both ``(rows, cols)``; NaN on no-data cells.
+    """
+    z = g.values
+    rows, cols = z.shape
+    n_cells = rows * cols
+    zf = z.ravel()
+    finite = np.isfinite(zf)
+    filled = np.where(finite, zf, -np.inf).astype(float)
+    done = ~finite
+    # Edge: border cells and cells with a no-data 8-neighbour.
+    nanpad = np.pad(~np.isfinite(z), 1, constant_values=True)
+    near_nan = np.zeros(z.shape, dtype=bool)
+    for dr, dc in zip(_DR, _DC):
+        near_nan |= nanpad[1 + dr : 1 + dr + rows, 1 + dc : 1 + dc + cols]
+    is_edge = (near_nan.ravel()) & finite
+    eps = 1e-5 * max(1.0, g.cell)
+    heap: list[tuple[float, int, int]] = []
+    seq = 0
+    for i in np.flatnonzero(is_edge).tolist():
+        done[i] = True
+        heap.append((float(filled[i]), seq, i))
+        seq += 1
+    heapq.heapify(heap)
+    order: list[int] = []
+    while heap:
+        _, _, i = heapq.heappop(heap)
+        order.append(i)
+        r, c = divmod(i, cols)
+        fi = filled[i]
+        for k in range(8):
+            rr = r + _DR[k]
+            cc = c + _DC[k]
+            if rr < 0 or cc < 0 or rr >= rows or cc >= cols:
+                continue
+            j = rr * cols + cc
+            if done[j]:
+                continue
+            done[j] = True
+            v = max(zf[j], fi + eps)
+            filled[j] = v
+            heapq.heappush(heap, (v, seq, j))
+            seq += 1
+    # Receivers: steepest descent on the filled surface (diagonals over sqrt 2).
+    f2 = filled.reshape(rows, cols)
+    fpad = np.pad(f2, 1, constant_values=np.nan)
+    finpad = np.pad(np.isfinite(z), 1, constant_values=False)
+    edgepad = np.pad(is_edge.reshape(rows, cols), 1, constant_values=False)
+    edge2 = is_edge.reshape(rows, cols)
+    drops = np.full((8, rows, cols), -np.inf)
+    for k in range(8):
+        dr, dc = _DR[k], _DC[k]
+        nb = fpad[1 + dr : 1 + dr + rows, 1 + dc : 1 + dc + cols]
+        ok = finpad[1 + dr : 1 + dr + rows, 1 + dc : 1 + dc + cols]
+        ok = ok & ~(edge2 & edgepad[1 + dr : 1 + dr + rows, 1 + dc : 1 + dc + cols])
+        dist = math.sqrt(2) if (dr and dc) else 1.0
+        with np.errstate(invalid="ignore"):
+            drops[k] = np.where(ok, (f2 - nb) / dist, -np.inf)
+    best_k = np.argmax(drops, axis=0)
+    best_d = np.take_along_axis(drops, best_k[None], 0)[0]
+    rr_idx = np.arange(rows)[:, None] + np.asarray(_DR)[best_k]
+    cc_idx = np.arange(cols)[None, :] + np.asarray(_DC)[best_k]
+    receiver = np.where(best_d > 0, rr_idx * cols + cc_idx, -1).ravel().tolist()
+    acc = np.zeros(n_cells)
+    acc[order] = 1.0
+    acc_l = acc.tolist()
+    for i in reversed(order):
+        j = receiver[i]
+        if j >= 0:
+            acc_l[j] += acc_l[i]
+    acc = np.asarray(acc_l, dtype=float)
+    acc[~finite] = np.nan
+    filled_out = np.where(np.isfinite(filled), filled, np.nan)
+    return acc.reshape(rows, cols), filled_out.reshape(rows, cols)
+
+
+def wetness(g: Grid, slope_deg: np.ndarray, acc: Optional[np.ndarray] = None) -> np.ndarray:
+    """Topographic wetness index ``ln(a / tan(beta))`` (Beven and Kirkby 1979)."""
+    if acc is None:
+        acc = flow_accumulation(g)[0]
+    acc = np.asarray(acc, dtype=float)
+    slope_deg = np.asarray(slope_deg, dtype=float)
+    min_tan = math.tan(math.radians(0.1))
+    with np.errstate(invalid="ignore", divide="ignore"):
+        tan_b = np.maximum(min_tan, np.tan(np.radians(slope_deg)))
+        out = np.log((acc * g.cell) / tan_b)
+    return np.where(np.isfinite(acc) & np.isfinite(slope_deg), out, np.nan)
+
+
+def percentile(values: np.ndarray, p: float, sample: int = 200_000) -> float:
+    """Value at the ``p``-th percentile (0..1) of the finite values, from a sample."""
+    v = np.asarray(values, dtype=float).ravel()
+    step = max(1, v.size // sample)
+    s = v[::step]
+    s = np.sort(s[np.isfinite(s)])
+    if s.size == 0:
+        return math.nan
+    idx = min(s.size - 1, max(0, int(math.floor(p * (s.size - 1) + 0.5))))
+    return float(s[idx])