zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/web/src/core/terrain_analysis.js

@@ -0,0 +1,267 @@
+// @ts-check
+// Terrain derivatives of a DEM grid ({ cols, rows, cell, minX, maxY, values },
+// row-major from the north-west): curvature, topographic position,
+// ruggedness, flow accumulation and wetness, and aspect classes.
+// Edges are handled by repeating the border cell; NaN cells stay NaN.
+
+const clampIndex = (v, n) => (v < 0 ? 0 : v >= n ? n - 1 : v);
+
+/**
+ * The part of a grid inside an area, coarsened by whole cells until it has
+ * at most maxCells (block means, NaN ignored).
+ */
+export function cropGrid(g, area, maxCells = 4_000_000) {
+  const c0 = Math.max(0, Math.floor((area.minX - g.minX) / g.cell + 0.5));
+  const c1 = Math.min(g.cols - 1, Math.ceil((area.maxX - g.minX) / g.cell - 0.5));
+  const r0 = Math.max(0, Math.floor((g.maxY - area.maxY) / g.cell + 0.5));
+  const r1 = Math.min(g.rows - 1, Math.ceil((g.maxY - area.minY) / g.cell - 0.5));
+  if (c1 < c0 || r1 < r0) throw new Error('The area does not overlap the terrain.');
+  const w = c1 - c0 + 1, hgt = r1 - r0 + 1;
+  const k = Math.max(1, Math.ceil(Math.sqrt((w * hgt) / maxCells)));
+  const cols = Math.ceil(w / k), rows = Math.ceil(hgt / k);
+  const values = new Float32Array(cols * rows);
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      let s = 0, n = 0;
+      for (let dr = 0; dr < k; dr++) {
+        const rr = r0 + r * k + dr;
+        if (rr > r1) break;
+        for (let dc = 0; dc < k; dc++) {
+          const cc = c0 + c * k + dc;
+          if (cc > c1) break;
+          const v = g.values[rr * g.cols + cc];
+          if (Number.isFinite(v)) { s += v; n++; }
+        }
+      }
+      values[r * cols + c] = n ? s / n : NaN;
+    }
+  }
+  // Cell centres of the coarse grid: the centre of each k x k block.
+  const cell = g.cell * k;
+  return { cols, rows, cell, minX: g.minX + (c0 + (k - 1) / 2) * g.cell, maxY: g.maxY - (r0 + (k - 1) / 2) * g.cell, values, factor: k };
+}
+
+/**
+ * General curvature (Zevenbergen and Thorne 1987) in 1/100 m, the
+ * convention of most GIS: positive on convex ground (ridges, crests),
+ * negative on concave ground (valleys, hollows).
+ */
+export function curvature(g) {
+  const { cols, rows, cell, values: z } = g;
+  const out = new Float32Array(cols * rows);
+  const L2 = cell * cell;
+  for (let r = 0; r < rows; r++) {
+    const ru = clampIndex(r - 1, rows), rd = clampIndex(r + 1, rows);
+    for (let c = 0; c < cols; c++) {
+      const cl = clampIndex(c - 1, cols), cr = clampIndex(c + 1, cols);
+      const z5 = z[r * cols + c];
+      const D = ((z[r * cols + cl] + z[r * cols + cr]) / 2 - z5) / L2;
+      const E = ((z[ru * cols + c] + z[rd * cols + c]) / 2 - z5) / L2;
+      out[r * cols + c] = -2 * (D + E) * 100;
+    }
+  }
+  return out;
+}
+
+/** Summed-area table (with NaN cells counted as missing) for window means. */
+function integral(g) {
+  const { cols, rows, values: z } = g;
+  const W = cols + 1;
+  const sum = new Float64Array(W * (rows + 1));
+  const cnt = new Float64Array(W * (rows + 1));
+  for (let r = 0; r < rows; r++) {
+    let rs = 0, rc = 0;
+    for (let c = 0; c < cols; c++) {
+      const v = z[r * cols + c];
+      if (Number.isFinite(v)) { rs += v; rc++; }
+      sum[(r + 1) * W + c + 1] = sum[r * W + c + 1] + rs;
+      cnt[(r + 1) * W + c + 1] = cnt[r * W + c + 1] + rc;
+    }
+  }
+  return { sum, cnt, W };
+}
+
+/**
+ * Topographic position index (Weiss 2001): elevation minus the mean
+ * elevation of a square window of radius `radius` cells around it.
+ * Positive on hilltops and ridges, negative in valleys, near 0 on flat
+ * ground and even slopes.
+ */
+export function tpi(g, radius) {
+  const { cols, rows, values: z } = g;
+  const R = Math.max(1, Math.round(radius));
+  const { sum, cnt, W } = integral(g);
+  const out = new Float32Array(cols * rows);
+  for (let r = 0; r < rows; r++) {
+    const a = Math.max(0, r - R), b = Math.min(rows - 1, r + R);
+    for (let c = 0; c < cols; c++) {
+      const v = z[r * cols + c];
+      if (!Number.isFinite(v)) { out[r * cols + c] = NaN; continue; }
+      const l = Math.max(0, c - R), rt = Math.min(cols - 1, c + R);
+      const s = sum[(b + 1) * W + rt + 1] - sum[a * W + rt + 1] - sum[(b + 1) * W + l] + sum[a * W + l];
+      const n = cnt[(b + 1) * W + rt + 1] - cnt[a * W + rt + 1] - cnt[(b + 1) * W + l] + cnt[a * W + l];
+      // Mean of the neighbours, the cell itself left out.
+      out[r * cols + c] = n > 1 ? v - (s - v) / (n - 1) : 0;
+    }
+  }
+  return out;
+}
+
+/** Terrain ruggedness index (Riley et al. 1999): root of the summed squared differences to the 8 neighbours, in metres. */
+export function ruggedness(g) {
+  const { cols, rows, values: z } = g;
+  const out = new Float32Array(cols * rows);
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const v = z[r * cols + c];
+      if (!Number.isFinite(v)) { out[r * cols + c] = NaN; continue; }
+      let s = 0;
+      for (let dr = -1; dr <= 1; dr++) {
+        for (let dc = -1; dc <= 1; dc++) {
+          if (!dr && !dc) continue;
+          const n = z[clampIndex(r + dr, rows) * cols + clampIndex(c + dc, cols)];
+          if (Number.isFinite(n)) s += (n - v) * (n - v);
+        }
+      }
+      out[r * cols + c] = Math.sqrt(s);
+    }
+  }
+  return out;
+}
+
+/** Aspect classes: 0 flat (slope under flatDeg), 1 N, 2 NE, ... 8 NW. */
+export function aspectClasses(slope, aspect, flatDeg = 1) {
+  const out = new Float32Array(slope.length);
+  for (let i = 0; i < slope.length; i++) {
+    if (!Number.isFinite(slope[i])) { out[i] = NaN; continue; }
+    if (slope[i] < flatDeg || aspect[i] < 0) { out[i] = 0; continue; }
+    out[i] = 1 + (Math.floor((aspect[i] + 22.5) / 45) % 8);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- flow
+/** Binary min-heap of cell indices keyed by a Float64 priority. */
+class Heap {
+  constructor(capacity) {
+    this.idx = new Int32Array(capacity);
+    this.key = new Float64Array(capacity);
+    this.n = 0;
+  }
+
+  push(i, k) {
+    let p = this.n++;
+    while (p > 0) {
+      const q = (p - 1) >> 1;
+      if (this.key[q] <= k) break;
+      this.idx[p] = this.idx[q]; this.key[p] = this.key[q];
+      p = q;
+    }
+    this.idx[p] = i; this.key[p] = k;
+  }
+
+  pop() {
+    const top = this.idx[0];
+    const li = this.idx[--this.n], lk = this.key[this.n];
+    let p = 0;
+    for (;;) {
+      let q = 2 * p + 1;
+      if (q >= this.n) break;
+      if (q + 1 < this.n && this.key[q + 1] < this.key[q]) q++;
+      if (this.key[q] >= lk) break;
+      this.idx[p] = this.idx[q]; this.key[p] = this.key[q];
+      p = q;
+    }
+    this.idx[p] = li; this.key[p] = lk;
+    return top;
+  }
+}
+
+const DC = [-1, 0, 1, -1, 1, -1, 0, 1], DR = [-1, -1, -1, 0, 0, 1, 1, 1];
+
+/**
+ * Flow accumulation in cells (each cell counts itself) by D8 steepest
+ * descent on a depression-filled surface: priority flood from the edges
+ * (Barnes et al. 2014) with a small rise across flats so every cell drains
+ * to the edge. NaN cells are outlets, like the edge; water that reaches an
+ * edge cell leaves the DEM there instead of running along the edge (the
+ * ground beyond it is unknown).
+ * @returns {{ acc: Float32Array, filled: Float32Array, order: Int32Array }}
+ */
+export function flowAccumulation(g) {
+  const { cols, rows, cell, values: z } = g;
+  const N = cols * rows;
+  const filled = new Float64Array(N);
+  const done = new Uint8Array(N);
+  const isEdge = new Uint8Array(N);
+  const order = new Int32Array(N); // cells in pop order: every cell after the cell it drains to
+  let popped = 0;
+  const heap = new Heap(N);
+  const eps = 1e-5 * Math.max(1, cell);
+  for (let i = 0; i < N; i++) {
+    const r = (i / cols) | 0, c = i - r * cols;
+    if (!Number.isFinite(z[i])) { done[i] = 1; filled[i] = -Infinity; continue; }
+    let edge = r === 0 || c === 0 || r === rows - 1 || c === cols - 1;
+    for (let k = 0; k < 8 && !edge; k++) if (!Number.isFinite(z[(r + DR[k]) * cols + c + DC[k]])) edge = true;
+    if (edge) { filled[i] = z[i]; done[i] = 1; isEdge[i] = 1; heap.push(i, z[i]); }
+  }
+  while (heap.n) {
+    const i = heap.pop();
+    order[popped++] = i;
+    const r = (i / cols) | 0, c = i - r * cols;
+    for (let k = 0; k < 8; k++) {
+      const rr = r + DR[k], cc = c + DC[k];
+      if (rr < 0 || cc < 0 || rr >= rows || cc >= cols) continue;
+      const j = rr * cols + cc;
+      if (done[j]) continue;
+      done[j] = 1;
+      filled[j] = Math.max(z[j], filled[i] + eps);
+      heap.push(j, filled[j]);
+    }
+  }
+  // Receiver: steepest descent on the filled surface (diagonals over √2 cells).
+  const acc = new Float32Array(N);
+  for (let n = 0; n < popped; n++) acc[order[n]] = 1;
+  for (let n = popped - 1; n >= 0; n--) {
+    const i = order[n];
+    const r = (i / cols) | 0, c = i - r * cols;
+    let best = -1, drop = 0;
+    for (let k = 0; k < 8; k++) {
+      const rr = r + DR[k], cc = c + DC[k];
+      if (rr < 0 || cc < 0 || rr >= rows || cc >= cols) continue;
+      const j = rr * cols + cc;
+      if (!Number.isFinite(z[j]) || (isEdge[i] && isEdge[j])) continue;
+      const d = (filled[i] - filled[j]) / (DC[k] && DR[k] ? Math.SQRT2 : 1);
+      if (d > drop) { drop = d; best = j; }
+    }
+    if (best >= 0) acc[best] += acc[i];
+  }
+  for (let i = 0; i < N; i++) if (!Number.isFinite(z[i])) acc[i] = NaN;
+  return { acc, filled: Float32Array.from(filled, (v) => (Number.isFinite(v) ? v : NaN)), order: order.subarray(0, popped) };
+}
+
+/**
+ * Topographic wetness index ln(a / tan β) (Beven and Kirkby 1979): a is the
+ * upslope area per unit contour width (accumulated cells x cell size), β the
+ * local slope. High on flat ground that collects water.
+ */
+export function wetness(g, slopeDeg, acc = flowAccumulation(g).acc) {
+  const out = new Float32Array(acc.length);
+  const minTan = Math.tan((0.1 * Math.PI) / 180);
+  for (let i = 0; i < acc.length; i++) {
+    if (!Number.isFinite(acc[i]) || !Number.isFinite(slopeDeg[i])) { out[i] = NaN; continue; }
+    const tanB = Math.max(minTan, Math.tan((slopeDeg[i] * Math.PI) / 180));
+    out[i] = Math.log((acc[i] * g.cell) / tanB);
+  }
+  return out;
+}
+
+/** Value at the p-th percentile (0..1) of the finite values, from a sample. */
+export function percentile(values, p, sample = 200000) {
+  const step = Math.max(1, Math.floor(values.length / sample));
+  const s = [];
+  for (let i = 0; i < values.length; i += step) if (Number.isFinite(values[i])) s.push(values[i]);
+  if (!s.length) return NaN;
+  s.sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.max(0, Math.round(p * (s.length - 1))))];
+}

zero2geospatial3d/web/src/core/terrain_math.js

@@ -0,0 +1,279 @@
+// @ts-check
+// Terrain grid operations. A grid is { cols, rows, cell, minX, maxY, values }
+// with values row-major from the north-west cell; (minX, maxY) is the centre
+// of that cell in local metres (x east, y north).
+
+export function makeGrid(cols, rows, cell, minX, maxY, values = new Float32Array(cols * rows)) {
+  return { cols, rows, cell, minX, maxY, values };
+}
+
+export function cellCentre(g, c, r) {
+  return [g.minX + c * g.cell, g.maxY - r * g.cell];
+}
+
+/** Bilinear height at local (x, y); clamped at the edges. */
+export function sample(g, x, y) {
+  const fc = Math.max(0, Math.min(g.cols - 1, (x - g.minX) / g.cell));
+  const fr = Math.max(0, Math.min(g.rows - 1, (g.maxY - y) / g.cell));
+  const c0 = Math.min(g.cols - 2, Math.floor(fc));
+  const r0 = Math.min(g.rows - 2, Math.floor(fr));
+  if (g.cols < 2 || g.rows < 2) return g.values[0] || 0;
+  const tx = fc - c0;
+  const ty = fr - r0;
+  const v = g.values;
+  const i = r0 * g.cols + c0;
+  const a = v[i] * (1 - tx) + v[i + 1] * tx;
+  const b = v[i + g.cols] * (1 - tx) + v[i + g.cols + 1] * tx;
+  return a * (1 - ty) + b * ty;
+}
+
+/** Horn (1981) slope (degrees) and aspect (degrees clockwise from north, facing downslope; -1 for flat). */
+export function slopeAspect(g) {
+  const { cols, rows, cell, values: z } = g;
+  const slope = new Float32Array(cols * rows);
+  const aspect = new Float32Array(cols * rows);
+  const at = (c, r) => z[Math.max(0, Math.min(rows - 1, r)) * cols + Math.max(0, Math.min(cols - 1, c))];
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const a = at(c - 1, r - 1), b = at(c, r - 1), cc = at(c + 1, r - 1);
+      const d = at(c - 1, r), f = at(c + 1, r);
+      const gg = at(c - 1, r + 1), h = at(c, r + 1), i = at(c + 1, r + 1);
+      const dzdx = ((cc + 2 * f + i) - (a + 2 * d + gg)) / (8 * cell); // towards east
+      const dzdy = ((a + 2 * b + cc) - (gg + 2 * h + i)) / (8 * cell); // towards north
+      const k = r * cols + c;
+      slope[k] = Math.atan(Math.hypot(dzdx, dzdy)) * 180 / Math.PI;
+      if (dzdx === 0 && dzdy === 0) { aspect[k] = -1; continue; }
+      // Downslope direction is -gradient; bearing clockwise from north.
+      let az = Math.atan2(-dzdx, -dzdy) * 180 / Math.PI;
+      if (az < 0) az += 360;
+      aspect[k] = az;
+    }
+  }
+  return { slope, aspect };
+}
+
+/** Horn slope (degrees) and aspect (degrees, -1 flat) of one cell. */
+export function slopeAspectAt(g, c, r) {
+  const { cols, rows, cell, values: z } = g;
+  const at = (cc, rr) => z[Math.max(0, Math.min(rows - 1, rr)) * cols + Math.max(0, Math.min(cols - 1, cc))];
+  const 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 * cell);
+  const 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 * cell);
+  const slope = Math.atan(Math.hypot(dzdx, dzdy)) * 180 / Math.PI;
+  if (dzdx === 0 && dzdy === 0) return { slope, aspect: -1 };
+  let aspect = Math.atan2(-dzdx, -dzdy) * 180 / Math.PI;
+  if (aspect < 0) aspect += 360;
+  return { slope, aspect };
+}
+
+/**
+ * Hillshade 0..1 for a light from azimuth/altitude (degrees), in one pass
+ * without slope/aspect arrays (a 16 M-cell DEM would need 128 MB for them).
+ */
+export function hillshade(g, azimuthDeg = 315, altitudeDeg = 45, zFactor = 1) {
+  const { cols, rows, cell, values: z } = g;
+  const out = new Float32Array(cols * rows);
+  const zen = (90 - altitudeDeg) * Math.PI / 180;
+  const az = azimuthDeg * Math.PI / 180;
+  // Unit vector towards the light in (east, north, up).
+  const lx = Math.sin(zen) * Math.sin(az), ly = Math.sin(zen) * Math.cos(az), lz = Math.cos(zen);
+  const k = zFactor / (8 * cell);
+  for (let r = 0; r < rows; r++) {
+    const ru = r > 0 ? r - 1 : 0, rd = r < rows - 1 ? r + 1 : rows - 1;
+    for (let c = 0; c < cols; c++) {
+      const cl = c > 0 ? c - 1 : 0, cr = c < cols - 1 ? c + 1 : cols - 1;
+      const a = z[ru * cols + cl], b = z[ru * cols + c], cc = z[ru * cols + cr];
+      const d = z[r * cols + cl], f = z[r * cols + cr];
+      const gg = z[rd * cols + cl], hh = z[rd * cols + c], i = z[rd * cols + cr];
+      const dzdx = ((cc + 2 * f + i) - (a + 2 * d + gg)) * k;  // towards east
+      const dzdy = ((a + 2 * b + cc) - (gg + 2 * hh + i)) * k;  // towards north
+      // Surface normal (-dz/dx, -dz/dy, 1), normalised, dotted with the light.
+      out[r * cols + c] = Math.max(0, (-dzdx * lx - dzdy * ly + lz) / Math.sqrt(dzdx * dzdx + dzdy * dzdy + 1));
+    }
+  }
+  return out;
+}
+
+/**
+ * Contour line segments by marching squares.
+ * @returns {{ level: number, segments: number[] }[]} segments as flat [x1, y1, x2, y2, ...]
+ */
+export function contours(g, interval, { base = 0, maxLevels = 400 } = {}) {
+  const { cols, rows, values: z } = g;
+  let lo = Infinity, hi = -Infinity;
+  for (const v of z) { if (v < lo) lo = v; if (v > hi) hi = v; }
+  if (!(interval > 0) || !Number.isFinite(lo)) return [];
+  // One pass over the cells: each cell emits segments only for the levels
+  // between its lowest and highest corner, so the cost does not grow with
+  // the number of levels (a 4096 x 4096 DEM stays interactive).
+  const kFirst = Math.ceil((lo - base) / interval);
+  const kLast = Math.min(Math.floor((hi - base) / interval), kFirst + maxLevels - 1);
+  const segs = new Map();
+  const { cell, minX, maxY } = g;
+  const pts = [];
+  for (let r = 0; r < rows - 1; r++) {
+    const ya = maxY - r * cell;
+    const yb = ya - cell;
+    for (let c = 0; c < cols - 1; c++) {
+      const v0 = z[r * cols + c], v1 = z[r * cols + c + 1];
+      const v2 = z[(r + 1) * cols + c + 1], v3 = z[(r + 1) * cols + c];
+      const cmin = Math.min(v0, v1, v2, v3);
+      const cmax = Math.max(v0, v1, v2, v3);
+      const k0 = Math.max(kFirst, Math.ceil((cmin - base) / interval));
+      const k1 = Math.min(kLast, Math.floor((cmax - base) / interval));
+      if (k1 < k0) continue;
+      const xa = minX + c * cell;
+      const xb = xa + cell;
+      for (let k = k0; k <= k1; k++) {
+        const level = base + k * interval;
+        pts.length = 0;
+        if ((v0 < level) !== (v1 < level)) { const t = (level - v0) / (v1 - v0); pts.push(xa + cell * t, ya); }
+        if ((v1 < level) !== (v2 < level)) { const t = (level - v1) / (v2 - v1); pts.push(xb, ya - cell * t); }
+        if ((v2 < level) !== (v3 < level)) { const t = (level - v2) / (v3 - v2); pts.push(xb - cell * t, yb); }
+        if ((v3 < level) !== (v0 < level)) { const t = (level - v3) / (v0 - v3); pts.push(xa, yb + cell * t); }
+        if (pts.length !== 4 && pts.length !== 8) continue; // 8: a saddle, two segments
+        let arr = segs.get(k);
+        if (!arr) { arr = []; segs.set(k, arr); }
+        for (const p of pts) arr.push(p);
+      }
+    }
+  }
+  return [...segs.keys()].sort((a, b) => a - b).map((k) => ({ level: base + k * interval, segments: segs.get(k) }));
+}
+
+/** Sample heights along a polyline every `step` metres: [{ d, x, y, z }]. */
+export function profile(g, points, step = null) {
+  const s = step || g.cell / 2;
+  const out = [];
+  let dist = 0;
+  for (let i = 0; i < points.length - 1; i++) {
+    const [x0, y0] = points[i];
+    const [x1, y1] = points[i + 1];
+    const len = Math.hypot(x1 - x0, y1 - y0);
+    const n = Math.max(1, Math.ceil(len / s));
+    for (let k = i === 0 ? 0 : 1; k <= n; k++) {
+      const t = k / n;
+      const x = x0 + (x1 - x0) * t;
+      const y = y0 + (y1 - y0) * t;
+      out.push({ d: dist + len * t, x, y, z: sample(g, x, y) });
+    }
+    dist += len;
+  }
+  return out;
+}
+
+/**
+ * Cells under a water level. With a seed (local x, y) only cells connected to
+ * it (4-neighbours) flood, like water rising from that point; without one,
+ * every cell below the level floods (a plain "bathtub").
+ * @returns {{ depth: Float32Array, floodedCells: number, area: number, volume: number, maxDepth: number }}
+ */
+export function flood(g, level, seed = null) {
+  const { cols, rows, cell, values: z } = g;
+  const depth = new Float32Array(cols * rows).fill(NaN);
+  let count = 0, volume = 0, maxDepth = 0;
+  const mark = (i) => {
+    const d = level - z[i];
+    depth[i] = d;
+    count++;
+    volume += d * cell * cell;
+    if (d > maxDepth) maxDepth = d;
+  };
+  if (seed) {
+    const c0 = Math.round((seed[0] - g.minX) / cell);
+    const r0 = Math.round((g.maxY - seed[1]) / cell);
+    if (c0 < 0 || r0 < 0 || c0 >= cols || r0 >= rows || z[r0 * cols + c0] >= level) {
+      return { depth, floodedCells: 0, area: 0, volume: 0, maxDepth: 0 };
+    }
+    const seen = new Uint8Array(cols * rows);
+    const stack = [r0 * cols + c0];
+    seen[stack[0]] = 1;
+    while (stack.length) {
+      const i = /** @type {number} */ (stack.pop());
+      mark(i);
+      const c = i % cols, r = (i - c) / cols;
+      const next = [c > 0 ? i - 1 : -1, c < cols - 1 ? i + 1 : -1, r > 0 ? i - cols : -1, r < rows - 1 ? i + cols : -1];
+      for (const j of next) {
+        if (j >= 0 && !seen[j] && z[j] < level) { seen[j] = 1; stack.push(j); }
+      }
+    }
+  } else {
+    for (let i = 0; i < z.length; i++) if (z[i] < level) mark(i);
+  }
+  return { depth, floodedCells: count, area: count * cell * cell, volume, maxDepth };
+}
+
+export function pointInRing(x, y, ring) {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const [xi, yi] = ring[i];
+    const [xj, yj] = ring[j];
+    if ((yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi || 1e-12) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+/**
+ * Cut and fill to bring the ground inside a polygon to a flat design level.
+ * @returns {{ cut: number, fill: number, net: number, area: number, delta: Float32Array }}
+ *   cut/fill in m3; delta = design - ground per cell (NaN outside)
+ */
+export function cutFill(g, ring, designLevel) {
+  const { cols, rows, cell, values: z } = g;
+  const delta = new Float32Array(cols * rows).fill(NaN);
+  let cut = 0, fill = 0, n = 0;
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  for (const [x, y] of ring) { minX = Math.min(minX, x); maxX = Math.max(maxX, x); minY = Math.min(minY, y); maxY = Math.max(maxY, y); }
+  const c0 = Math.max(0, Math.floor((minX - g.minX) / cell));
+  const c1 = Math.min(cols - 1, Math.ceil((maxX - g.minX) / cell));
+  const r0 = Math.max(0, Math.floor((g.maxY - maxY) / cell));
+  const r1 = Math.min(rows - 1, Math.ceil((g.maxY - minY) / cell));
+  for (let r = r0; r <= r1; r++) {
+    for (let c = c0; c <= c1; c++) {
+      const [x, y] = cellCentre(g, c, r);
+      if (!pointInRing(x, y, ring)) continue;
+      const i = r * cols + c;
+      if (!Number.isFinite(z[i])) continue; // no DEM data: nothing to cut or fill
+      const d = designLevel - z[i];
+      delta[i] = d;
+      n++;
+      if (d > 0) fill += d * cell * cell; else cut -= d * cell * cell;
+    }
+  }
+  return { cut, fill, net: fill - cut, area: n * cell * cell, delta };
+}
+
+/**
+ * Design level that balances cut and fill inside the polygon (bisection
+ * between the lowest and highest ground inside it). A polygon smaller than
+ * a cell holds no cell centre: the ground at its centre is the balance.
+ */
+export function balancedLevel(g, ring) {
+  let lo = Infinity, hi = -Infinity;
+  const { delta } = cutFill(g, ring, 0); // -ground inside, NaN outside
+  for (const d of delta) { if (Number.isFinite(d)) { if (-d < lo) lo = -d; if (-d > hi) hi = -d; } }
+  if (!(lo <= hi)) {
+    let x = 0, y = 0;
+    for (const p of ring) { x += p[0]; y += p[1]; }
+    const c = Math.max(0, Math.min(g.cols - 1, Math.round((x / ring.length - g.minX) / g.cell)));
+    const r = Math.max(0, Math.min(g.rows - 1, Math.round((g.maxY - y / ring.length) / g.cell)));
+    return g.values[r * g.cols + c];
+  }
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    const { net } = cutFill(g, ring, mid);
+    if (net > 0) hi = mid; else lo = mid;
+  }
+  return (lo + hi) / 2;
+}
+
+export function gridStats(values) {
+  let min = Infinity, max = -Infinity, sum = 0, n = 0;
+  for (const v of values) {
+    if (!Number.isFinite(v)) continue;
+    if (v < min) min = v;
+    if (v > max) max = v;
+    sum += v;
+    n++;
+  }
+  return { min, max, mean: n ? sum / n : NaN, count: n };
+}