@woosh/meep-engine 2.168.0 → 2.169.0

package/src/core/geom/2d/polygon/polygon2_triangulate.js

@@ -0,0 +1,1280 @@
+import { assert } from "../../../assert.js";
+import { UINT32_MAX } from "../../../binary/UINT32_MAX.js";
+import { orient2d_indexed } from "../convex-hull/orient2d_indexed.js";
+import { v2_morton_encode } from "../v2_morton_encode.js";
+import { polygon2_is_counter_clockwise } from "./polygon2_is_counter_clockwise.js";
+
+/**
+ * Sentinel for "no node", matching the codebase-wide typed-array pointer
+ * convention (`NULL_POINTER` in {@link BinaryTopology} is the same value).
+ * @type {number}
+ */
+const NULL_NODE = UINT32_MAX;
+
+/**
+ * Vertex count above which the point-in-ear test switches from a full ring walk
+ * to a Morton-code range walk. Below it the ring is short enough that the walk is
+ * cheaper than maintaining the Z-order list; above it the walk is the entire cost
+ * of the algorithm.
+ *
+ * Not a public option: both paths compute the same triangulation, so exposing the
+ * choice would be a knob with no semantics. Tests assert the two agree.
+ * @type {number}
+ */
+const HASH_THRESHOLD = 80;
+
+/**
+ * Largest quantised coordinate fed to {@link v2_morton_encode}. 15 bits per axis,
+ * matching the resolution the Z-order range test can usefully distinguish.
+ * @type {number}
+ */
+const MORTON_SCALE = 32767;
+
+// --------------------------------------------------------------------------
+// Ring storage.
+//
+// A vertex ring is a doubly-linked list held in flat typed arrays with integer
+// handles -- the same shape as every other meep structure of this kind
+// (`BinaryElementPool`, `BinaryTopology`, `bvh8`), and unlike the object-node
+// lists the reference implementations of this algorithm use. Nodes are never
+// compacted: removal unlinks, so handles stay stable for the whole call.
+//
+// Coordinates are copied in rather than read back through `points`, for three
+// reasons: the bridge nodes created by hole elimination have no entry in
+// `points`; `orient2d_indexed` wants exactly this interleaved layout; and it
+// keeps no reference to caller memory alive.
+//
+// Module-static and grown on demand, so a call allocates nothing in the steady
+// state. The consequence -- documented on the public function -- is that
+// `polygon2_triangulate` is NOT re-entrant, same as `bt_mesh_simplify_by_error`.
+// --------------------------------------------------------------------------
+
+/** Interleaved (x, y) per node. The array `orient2d_indexed` is applied to. */
+let _node_xy = new Float64Array(0);
+/** Index into the caller's `points` that this node reports on output. */
+let _node_point = new Uint32Array(0);
+let _node_next = new Uint32Array(0);
+let _node_prev = new Uint32Array(0);
+/** Morton code, only meaningful while the Z-order list is live. */
+let _node_z = new Uint32Array(0);
+let _node_znext = new Uint32Array(0);
+let _node_zprev = new Uint32Array(0);
+/**
+ * 1 for a node introduced by hole elimination rather than by the caller. Steiner
+ * nodes are exempt from the degenerate-point filter: they are deliberately
+ * coincident with another node and removing them would undo the bridge.
+ */
+let _node_steiner = new Uint8Array(0);
+
+/** Allocation cursor into the node arrays. */
+let _node_count = 0;
+
+/** Output buffer and write cursor for the current call. */
+let _out = null;
+let _out_cursor = 0;
+
+/** Morton quantisation state for the current call. */
+let _min_x = 0;
+let _min_y = 0;
+let _inv_size = 0;
+/** True while the Z-order accelerated ear test is in use. */
+let _hashed = false;
+
+/**
+ * @param {number} capacity
+ */
+function ensure_node_capacity(capacity) {
+    if (_node_point.length >= capacity) {
+        return;
+    }
+
+    _node_xy = new Float64Array(capacity * 2);
+    _node_point = new Uint32Array(capacity);
+    _node_next = new Uint32Array(capacity);
+    _node_prev = new Uint32Array(capacity);
+    _node_z = new Uint32Array(capacity);
+    _node_znext = new Uint32Array(capacity);
+    _node_zprev = new Uint32Array(capacity);
+    _node_steiner = new Uint8Array(capacity);
+}
+
+/**
+ * @param {number} point_index
+ * @param {number} x
+ * @param {number} y
+ * @returns {number} node
+ */
+function create_node(point_index, x, y) {
+    const node = _node_count++;
+
+    _node_xy[node * 2] = x;
+    _node_xy[node * 2 + 1] = y;
+    _node_point[node] = point_index;
+    _node_next[node] = NULL_NODE;
+    _node_prev[node] = NULL_NODE;
+    _node_z[node] = 0;
+    _node_znext[node] = NULL_NODE;
+    _node_zprev[node] = NULL_NODE;
+    _node_steiner[node] = 0;
+
+    return node;
+}
+
+/**
+ * Append a node after `last` in the ring, or start a new ring when `last` is
+ * {@link NULL_NODE}.
+ *
+ * @param {number} point_index
+ * @param {number} x
+ * @param {number} y
+ * @param {number} last
+ * @returns {number} the new node
+ */
+function insert_node(point_index, x, y, last) {
+    const node = create_node(point_index, x, y);
+
+    if (last === NULL_NODE) {
+        _node_next[node] = node;
+        _node_prev[node] = node;
+
+        return node;
+    }
+
+    const after = _node_next[last];
+
+    _node_next[node] = after;
+    _node_prev[node] = last;
+    _node_prev[after] = node;
+    _node_next[last] = node;
+
+    return node;
+}
+
+/**
+ * Unlink `node` from the ring and from the Z-order list.
+ * @param {number} node
+ */
+function remove_node(node) {
+    const next = _node_next[node];
+    const prev = _node_prev[node];
+
+    _node_prev[next] = prev;
+    _node_next[prev] = next;
+
+    const zprev = _node_zprev[node];
+    const znext = _node_znext[node];
+
+    if (zprev !== NULL_NODE) {
+        _node_znext[zprev] = znext;
+    }
+
+    if (znext !== NULL_NODE) {
+        _node_zprev[znext] = zprev;
+    }
+}
+
+function x_of(node) {
+    return _node_xy[node * 2];
+}
+
+function y_of(node) {
+    return _node_xy[node * 2 + 1];
+}
+
+/**
+ * Exact orientation of the node triple: **positive = counter-clockwise**, zero =
+ * collinear. Every combinatorial decision in this file routes through here, so
+ * the triangulation is decided exactly regardless of coordinate magnitude.
+ *
+ * Note the negation. Shewchuk's `orient2d` -- and therefore `robust-predicates`
+ * and {@link orient2d_indexed} -- returns a *negative* value for a
+ * counter-clockwise triple with y up (`orient2d(0,0, 1,0, 0,1) === -1`), and
+ * `-0` for collinear. Negating a double flips the sign exactly, so this keeps the
+ * predicate exact while giving this file the conventional sign. Reading the
+ * inverted convention into every comparison below would be a standing invitation
+ * to get one of them backwards.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number}
+ */
+function orient(a, b, c) {
+    return -orient2d_indexed(_node_xy, a, b, c);
+}
+
+/**
+ * @param {number} a
+ * @param {number} b
+ * @returns {boolean} true when the two nodes sit at exactly the same point
+ */
+function nodes_equal(a, b) {
+    return _node_xy[a * 2] === _node_xy[b * 2] && _node_xy[a * 2 + 1] === _node_xy[b * 2 + 1];
+}
+
+/**
+ * Build a ring from `points[from .. to)` (vertex indices), oriented so that its
+ * signed area has the sign `want_positive` asks for -- counter-clockwise for the
+ * outer contour, clockwise for holes.
+ *
+ * Normalising here rather than demanding it of the caller is deliberate: winding
+ * is derivable from the data, so requiring it would be redundant state the caller
+ * could contradict.
+ *
+ * @param {ArrayLike<number>} points
+ * @param {number} from first vertex index, inclusive
+ * @param {number} to last vertex index, exclusive
+ * @param {boolean} want_positive
+ * @returns {number} the last node of the ring, or {@link NULL_NODE} when empty
+ */
+function link_contour(points, from, to, want_positive) {
+    let last = NULL_NODE;
+
+    const count = to - from;
+
+    if (count <= 0) {
+        return NULL_NODE;
+    }
+
+    // Exactly, via one orientation predicate at a hull vertex. The shoelace sum
+    // cannot be used here: for a small contour, or one far from the origin, its
+    // sign is rounding noise, and getting the winding backwards makes every corner
+    // look reflex and the whole contour untriangulatable.
+    const is_ccw = polygon2_is_counter_clockwise(points, from, count);
+
+    if (is_ccw === want_positive) {
+        for (let i = from; i < to; i++) {
+            last = insert_node(i, points[i * 2], points[i * 2 + 1], last);
+        }
+    } else {
+        for (let i = to - 1; i >= from; i--) {
+            last = insert_node(i, points[i * 2], points[i * 2 + 1], last);
+        }
+    }
+
+    if (last !== NULL_NODE && nodes_equal(last, _node_next[last])) {
+        // the contour repeats its first point as its last
+        remove_node(last);
+        last = _node_next[last];
+    }
+
+    return last;
+}
+
+/**
+ * Drop nodes that are coincident with their successor or collinear with both
+ * neighbours -- neither can contribute a triangle, and both stall the ear search.
+ * Steiner nodes are kept.
+ *
+ * @param {number} start
+ * @param {number} end node to finish at; pass {@link NULL_NODE} for `start`
+ * @returns {number} a surviving node, or {@link NULL_NODE} if the ring collapsed
+ */
+function filter_points(start, end) {
+    if (start === NULL_NODE) {
+        return NULL_NODE;
+    }
+
+    let stop = end === NULL_NODE ? start : end;
+
+    let p = start;
+    let again;
+
+    do {
+        again = false;
+
+        const next = _node_next[p];
+        const prev = _node_prev[p];
+
+        if (_node_steiner[p] === 0 && (nodes_equal(p, next) || orient(prev, p, next) === 0)) {
+            remove_node(p);
+
+            p = prev;
+            stop = prev;
+
+            if (p === _node_next[p]) {
+                return NULL_NODE;
+            }
+
+            again = true;
+        } else {
+            p = next;
+        }
+    } while (again || p !== stop);
+
+    return p;
+}
+
+/**
+ * Inclusive point-in-triangle for a counter-clockwise triangle (a, b, c).
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} p
+ * @returns {boolean}
+ */
+function point_in_triangle(a, b, c, p) {
+    return orient(a, b, p) >= 0 && orient(b, c, p) >= 0 && orient(c, a, p) >= 0;
+}
+
+/**
+ * As {@link point_in_triangle}, but a point coincident with `a` does not count.
+ *
+ * Hole elimination bridges a hole into the outer ring by duplicating a vertex, so
+ * a point sitting exactly on `a` is an expected, legitimate configuration. Letting
+ * it block would make every bridged hole untriangulatable.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} p
+ * @returns {boolean}
+ */
+function point_in_triangle_except_first(a, b, c, p) {
+    return !nodes_equal(a, p) && point_in_triangle(a, b, c, p);
+}
+
+/**
+ * Is the segment `a -> b` inside the polygon in the immediate neighbourhood of
+ * `a`? Splits on whether `a` is a convex or a reflex corner.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {boolean}
+ */
+function locally_inside(a, b) {
+    const prev = _node_prev[a];
+    const next = _node_next[a];
+
+    if (orient(prev, a, next) > 0) {
+        // convex corner: b must be inside the wedge
+        return orient(a, b, next) <= 0 && orient(a, prev, b) <= 0;
+    }
+
+    // reflex corner: b must be outside the (smaller) reflex wedge
+    return orient(a, b, prev) > 0 || orient(a, next, b) > 0;
+}
+
+/**
+ * Is the midpoint of `a -> b` inside the ring? Even-odd ray cast along +x.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {boolean}
+ */
+function middle_inside(a, b) {
+    const px = (x_of(a) + x_of(b)) / 2;
+    const py = (y_of(a) + y_of(b)) / 2;
+
+    let p = a;
+    let inside = false;
+
+    do {
+        const next = _node_next[p];
+
+        const py0 = y_of(p);
+        const py1 = y_of(next);
+
+        if (((py0 > py) !== (py1 > py))
+            && py1 !== py0
+            && (px < (x_of(next) - x_of(p)) * (py - py0) / (py1 - py0) + x_of(p))) {
+            inside = !inside;
+        }
+
+        p = next;
+    } while (p !== a);
+
+    return inside;
+}
+
+/**
+ * Does `q` lie on the segment `p -> r`, given the three are already known to be
+ * collinear?
+ *
+ * @param {number} p
+ * @param {number} q
+ * @param {number} r
+ * @returns {boolean}
+ */
+function on_segment(p, q, r) {
+    return x_of(q) <= Math.max(x_of(p), x_of(r))
+        && x_of(q) >= Math.min(x_of(p), x_of(r))
+        && y_of(q) <= Math.max(y_of(p), y_of(r))
+        && y_of(q) >= Math.min(y_of(p), y_of(r));
+}
+
+/**
+ * @param {number} value
+ * @returns {number} -1, 0 or 1
+ */
+function sign_of(value) {
+    return value > 0 ? 1 : value < 0 ? -1 : 0;
+}
+
+/**
+ * Do the segments `p1 -> q1` and `p2 -> q2` intersect, including collinear
+ * touching?
+ *
+ * @param {number} p1
+ * @param {number} q1
+ * @param {number} p2
+ * @param {number} q2
+ * @returns {boolean}
+ */
+function segments_intersect(p1, q1, p2, q2) {
+    const o1 = sign_of(orient(p1, q1, p2));
+    const o2 = sign_of(orient(p1, q1, q2));
+    const o3 = sign_of(orient(p2, q2, p1));
+    const o4 = sign_of(orient(p2, q2, q1));
+
+    if (o1 !== o2 && o3 !== o4) {
+        return true;
+    }
+
+    if (o1 === 0 && on_segment(p1, p2, q1)) {
+        return true;
+    }
+
+    if (o2 === 0 && on_segment(p1, q2, q1)) {
+        return true;
+    }
+
+    if (o3 === 0 && on_segment(p2, p1, q2)) {
+        return true;
+    }
+
+    if (o4 === 0 && on_segment(p2, q1, q2)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Does the candidate diagonal `a -> b` cross any edge of the ring?
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {boolean}
+ */
+function intersects_polygon(a, b) {
+    let p = a;
+
+    do {
+        const next = _node_next[p];
+
+        if (_node_point[p] !== _node_point[a]
+            && _node_point[next] !== _node_point[a]
+            && _node_point[p] !== _node_point[b]
+            && _node_point[next] !== _node_point[b]
+            && segments_intersect(p, next, a, b)) {
+            return true;
+        }
+
+        p = next;
+    } while (p !== a);
+
+    return false;
+}
+
+/**
+ * Is `a -> b` a diagonal that splits the ring into two simple sub-rings?
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {boolean}
+ */
+function is_valid_diagonal(a, b) {
+    if (_node_point[_node_next[a]] === _node_point[b] || _node_point[_node_prev[a]] === _node_point[b]) {
+        return false;
+    }
+
+    if (intersects_polygon(a, b)) {
+        return false;
+    }
+
+    const locally_visible = locally_inside(a, b)
+        && locally_inside(b, a)
+        && middle_inside(a, b)
+        // and does not produce two opposite-facing sectors
+        && (orient(_node_prev[a], a, _node_prev[b]) !== 0 || orient(a, _node_prev[b], b) !== 0);
+
+    if (locally_visible) {
+        return true;
+    }
+
+    // zero-length diagonal between two coincident reflex corners still separates
+    return nodes_equal(a, b)
+        && orient(_node_prev[a], a, _node_next[a]) < 0
+        && orient(_node_prev[b], b, _node_next[b]) < 0;
+}
+
+/**
+ * Cut the ring in two along the diagonal `a -> b`, duplicating both endpoints.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} a node of the second ring
+ */
+function split_ring(a, b) {
+    const a2 = create_node(_node_point[a], x_of(a), y_of(a));
+    const b2 = create_node(_node_point[b], x_of(b), y_of(b));
+
+    const an = _node_next[a];
+    const bp = _node_prev[b];
+
+    _node_next[a] = b;
+    _node_prev[b] = a;
+
+    _node_next[a2] = an;
+    _node_prev[an] = a2;
+
+    _node_next[b2] = a2;
+    _node_prev[a2] = b2;
+
+    _node_next[bp] = b2;
+    _node_prev[b2] = bp;
+
+    return b2;
+}
+
+/**
+ * Quantise a coordinate pair into the Morton grid for the current call.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @returns {number}
+ */
+function morton_of(x, y) {
+    return v2_morton_encode(
+        ((x - _min_x) * _inv_size) | 0,
+        ((y - _min_y) * _inv_size) | 0
+    );
+}
+
+/**
+ * (Re)build the Z-order doubly-linked list over the ring starting at `start`.
+ *
+ * @param {number} start
+ */
+function index_curve(start) {
+    let p = start;
+
+    do {
+        _node_z[p] = morton_of(x_of(p), y_of(p));
+        _node_zprev[p] = _node_prev[p];
+        _node_znext[p] = _node_next[p];
+
+        p = _node_next[p];
+    } while (p !== start);
+
+    const last = _node_zprev[p];
+
+    _node_znext[last] = NULL_NODE;
+    _node_zprev[p] = NULL_NODE;
+
+    sort_z_linked(p);
+}
+
+/**
+ * Bottom-up merge sort of the Z-order list by Morton code. Operates on links, so
+ * it moves no data and needs no scratch array.
+ *
+ * @param {number} list head node
+ * @returns {number} the new head
+ */
+function sort_z_linked(list) {
+    let in_size = 1;
+    let num_merges;
+
+    do {
+        let p = list;
+        let tail = NULL_NODE;
+
+        list = NULL_NODE;
+        num_merges = 0;
+
+        while (p !== NULL_NODE) {
+            num_merges++;
+
+            let q = p;
+            let p_size = 0;
+
+            for (let i = 0; i < in_size; i++) {
+                p_size++;
+                q = _node_znext[q];
+
+                if (q === NULL_NODE) {
+                    break;
+                }
+            }
+
+            let q_size = in_size;
+
+            while (p_size > 0 || (q_size > 0 && q !== NULL_NODE)) {
+                let e;
+
+                if (p_size !== 0 && (q_size === 0 || q === NULL_NODE || _node_z[p] <= _node_z[q])) {
+                    e = p;
+                    p = _node_znext[p];
+                    p_size--;
+                } else {
+                    e = q;
+                    q = _node_znext[q];
+                    q_size--;
+                }
+
+                if (tail !== NULL_NODE) {
+                    _node_znext[tail] = e;
+                } else {
+                    list = e;
+                }
+
+                _node_zprev[e] = tail;
+                tail = e;
+            }
+
+            p = q;
+        }
+
+        _node_znext[tail] = NULL_NODE;
+        in_size *= 2;
+    } while (num_merges > 1);
+
+    return list;
+}
+
+/**
+ * Is `ear` an ear -- a convex corner whose triangle contains no other reflex
+ * corner of the ring? Linear scan; used below {@link HASH_THRESHOLD}.
+ *
+ * @param {number} ear
+ * @returns {boolean}
+ */
+function is_ear(ear) {
+    const a = _node_prev[ear];
+    const c = _node_next[ear];
+
+    if (orient(a, ear, c) <= 0) {
+        // reflex or straight -- cannot be an ear
+        return false;
+    }
+
+    const x0 = Math.min(x_of(a), x_of(ear), x_of(c));
+    const y0 = Math.min(y_of(a), y_of(ear), y_of(c));
+    const x1 = Math.max(x_of(a), x_of(ear), x_of(c));
+    const y1 = Math.max(y_of(a), y_of(ear), y_of(c));
+
+    let p = _node_next[c];
+
+    while (p !== a) {
+        const px = x_of(p);
+        const py = y_of(p);
+
+        if (px >= x0 && px <= x1 && py >= y0 && py <= y1
+            && point_in_triangle_except_first(a, ear, c, p)
+            && orient(_node_prev[p], p, _node_next[p]) <= 0) {
+            return false;
+        }
+
+        p = _node_next[p];
+    }
+
+    return true;
+}
+
+/**
+ * Does node `p` block the ear (a, ear, c)? Shared by the two Z-order walks.
+ *
+ * @param {number} p
+ * @param {number} a
+ * @param {number} ear
+ * @param {number} c
+ * @param {number} x0
+ * @param {number} y0
+ * @param {number} x1
+ * @param {number} y1
+ * @returns {boolean}
+ */
+function blocks_ear(p, a, ear, c, x0, y0, x1, y1) {
+    if (p === a || p === c) {
+        return false;
+    }
+
+    const px = x_of(p);
+    const py = y_of(p);
+
+    if (px < x0 || px > x1 || py < y0 || py > y1) {
+        return false;
+    }
+
+    if (!point_in_triangle(a, ear, c, p)) {
+        return false;
+    }
+
+    return orient(_node_prev[p], p, _node_next[p]) <= 0;
+}
+
+/**
+ * {@link is_ear} restricted to nodes whose Morton code falls in the ear's
+ * bounding-box code range -- the walk that keeps large rings out of O(n^2).
+ *
+ * @param {number} ear
+ * @returns {boolean}
+ */
+function is_ear_hashed(ear) {
+    const a = _node_prev[ear];
+    const c = _node_next[ear];
+
+    if (orient(a, ear, c) <= 0) {
+        return false;
+    }
+
+    const x0 = Math.min(x_of(a), x_of(ear), x_of(c));
+    const y0 = Math.min(y_of(a), y_of(ear), y_of(c));
+    const x1 = Math.max(x_of(a), x_of(ear), x_of(c));
+    const y1 = Math.max(y_of(a), y_of(ear), y_of(c));
+
+    const min_z = morton_of(x0, y0);
+    const max_z = morton_of(x1, y1);
+
+    let p = _node_zprev[ear];
+    let n = _node_znext[ear];
+
+    while (p !== NULL_NODE && _node_z[p] >= min_z && n !== NULL_NODE && _node_z[n] <= max_z) {
+        if (blocks_ear(p, a, ear, c, x0, y0, x1, y1)) {
+            return false;
+        }
+
+        p = _node_zprev[p];
+
+        if (blocks_ear(n, a, ear, c, x0, y0, x1, y1)) {
+            return false;
+        }
+
+        n = _node_znext[n];
+    }
+
+    while (p !== NULL_NODE && _node_z[p] >= min_z) {
+        if (blocks_ear(p, a, ear, c, x0, y0, x1, y1)) {
+            return false;
+        }
+
+        p = _node_zprev[p];
+    }
+
+    while (n !== NULL_NODE && _node_z[n] <= max_z) {
+        if (blocks_ear(n, a, ear, c, x0, y0, x1, y1)) {
+            return false;
+        }
+
+        n = _node_znext[n];
+    }
+
+    return true;
+}
+
+/**
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ */
+function emit_triangle(a, b, c) {
+    _out[_out_cursor] = _node_point[a];
+    _out[_out_cursor + 1] = _node_point[b];
+    _out[_out_cursor + 2] = _node_point[c];
+    _out_cursor += 3;
+}
+
+/**
+ * Is the ring through `node` down to fewer than three nodes -- i.e. is there no
+ * triangle left in it at all?
+ *
+ * @param {number} node
+ * @returns {boolean}
+ */
+function ring_is_spent(node) {
+    return _node_next[node] === node || _node_next[_node_next[node]] === node;
+}
+
+/**
+ * Second-chance pass: when the ring has no ear left, look for a pair of adjacent
+ * edges that cross and cut the offending vertex pair out as one triangle.
+ *
+ * Takes the output of {@link filter_points} directly, so it accepts and
+ * propagates that function's collapsed-ring sentinel.
+ *
+ * @param {number} start a node, or {@link NULL_NODE}
+ * @returns {number} a node of the repaired ring, or {@link NULL_NODE}
+ */
+function cure_local_intersections(start) {
+    if (start === NULL_NODE) {
+        return NULL_NODE;
+    }
+
+    let p = start;
+
+    do {
+        const a = _node_prev[p];
+        const next = _node_next[p];
+        const b = _node_next[next];
+
+        if (!nodes_equal(a, b)
+            && segments_intersect(a, p, next, b)
+            && locally_inside(a, b)
+            && locally_inside(b, a)) {
+            emit_triangle(a, p, b);
+
+            remove_node(p);
+            remove_node(next);
+
+            // Two nodes just left the ring. Once fewer than three remain there is
+            // no triangle to cure and the walk has nothing left to walk: `p` and
+            // `start` would both be chasing unlinked nodes.
+            if (ring_is_spent(b)) {
+                return NULL_NODE;
+            }
+
+            p = b;
+            start = b;
+        }
+
+        p = _node_next[p];
+    } while (p !== start);
+
+    return filter_points(p, NULL_NODE);
+}
+
+/**
+ * Last-chance pass: split the ring along any valid diagonal and triangulate the
+ * two halves independently.
+ *
+ * @param {number} start
+ */
+function split_ear_clip(start) {
+    let a = start;
+
+    do {
+        let b = _node_next[_node_next[a]];
+
+        while (b !== _node_prev[a]) {
+            if (_node_point[a] !== _node_point[b] && is_valid_diagonal(a, b)) {
+                let c = split_ring(a, b);
+
+                a = filter_points(a, _node_next[a]);
+                c = filter_points(c, _node_next[c]);
+
+                ear_clip(a, 0);
+                ear_clip(c, 0);
+
+                return;
+            }
+
+            b = _node_next[b];
+        }
+
+        a = _node_next[a];
+    } while (a !== start);
+}
+
+/**
+ * Slice ears off the ring until it is a single triangle.
+ *
+ * `pass` records how many recovery tiers have been tried on this ring: 0 = plain,
+ * 1 = after removing degenerate points, 2 = after curing local self-intersections.
+ * Reaching the end of tier 2 without an ear means the ring is not triangulatable
+ * and its remaining area is dropped -- reported to the caller as a short triangle
+ * count.
+ *
+ * @param {number} ear
+ * @param {number} pass
+ */
+function ear_clip(ear, pass) {
+    if (ear === NULL_NODE) {
+        return;
+    }
+
+    if (pass === 0 && _hashed) {
+        index_curve(ear);
+    }
+
+    let stop = ear;
+
+    while (_node_prev[ear] !== _node_next[ear]) {
+        const prev = _node_prev[ear];
+        const next = _node_next[ear];
+
+        if (_hashed ? is_ear_hashed(ear) : is_ear(ear)) {
+            emit_triangle(prev, ear, next);
+
+            remove_node(ear);
+
+            // skipping the next vertex leads to fewer sliver triangles
+            ear = _node_next[next];
+            stop = _node_next[next];
+
+            continue;
+        }
+
+        ear = next;
+
+        if (ear !== stop) {
+            continue;
+        }
+
+        if (pass === 0) {
+            ear_clip(filter_points(ear, NULL_NODE), 1);
+        } else if (pass === 1) {
+            const cured = cure_local_intersections(filter_points(ear, NULL_NODE));
+
+            ear_clip(cured, 2);
+        } else if (pass === 2) {
+            split_ear_clip(ear);
+        }
+
+        return;
+    }
+}
+
+/**
+ * Leftmost (then lowest) node of a ring.
+ *
+ * @param {number} start
+ * @returns {number}
+ */
+function get_leftmost(start) {
+    let p = start;
+    let leftmost = start;
+
+    do {
+        if (x_of(p) < x_of(leftmost) || (x_of(p) === x_of(leftmost) && y_of(p) < y_of(leftmost))) {
+            leftmost = p;
+        }
+
+        p = _node_next[p];
+    } while (p !== start);
+
+    return leftmost;
+}
+
+/**
+ * Find the outer-ring node that the hole's leftmost node can see, so a bridge
+ * between them stays inside the polygon.
+ *
+ * Casts a ray in -x from the hole vertex, takes the closest outer edge it hits,
+ * then -- if any reflex outer vertex lies in the triangle formed by the hit -- picks
+ * the one at the smallest angle to the ray instead.
+ *
+ * @param {number} hole
+ * @param {number} outer
+ * @returns {number} the bridge node, or {@link NULL_NODE} when none is visible
+ */
+function find_hole_bridge(hole, outer) {
+    const hx = x_of(hole);
+    const hy = y_of(hole);
+
+    let qx = -Infinity;
+    let m = NULL_NODE;
+
+    let p = outer;
+
+    if (nodes_equal(hole, p)) {
+        return p;
+    }
+
+    do {
+        const next = _node_next[p];
+
+        if (nodes_equal(hole, next)) {
+            return next;
+        }
+
+        const py = y_of(p);
+        const ny = y_of(next);
+
+        if (hy <= py && hy >= ny && ny !== py) {
+            const x = x_of(p) + (hy - py) * (x_of(next) - x_of(p)) / (ny - py);
+
+            if (x <= hx && x > qx) {
+                qx = x;
+                m = x_of(p) < x_of(next) ? p : next;
+
+                if (x === hx) {
+                    // the hole touches the outer contour exactly here
+                    return m;
+                }
+            }
+        }
+
+        p = next;
+    } while (p !== outer);
+
+    if (m === NULL_NODE) {
+        return NULL_NODE;
+    }
+
+    // Search the sector between the ray hit and the chosen endpoint for a reflex
+    // vertex that would be occluded by the naive bridge.
+    const stop = m;
+    const mx = x_of(m);
+    const my = y_of(m);
+
+    let tan_min = Infinity;
+
+    p = m;
+
+    do {
+        const px = x_of(p);
+        const py = y_of(p);
+
+        if (hx >= px && px >= mx && hx !== px
+            && point_in_triangle_xy(hy < my ? hx : qx, hy, mx, my, hy < my ? qx : hx, hy, px, py)) {
+            const tan = Math.abs(hy - py) / (hx - px);
+
+            if (locally_inside(p, hole)
+                && (tan < tan_min
+                    || (tan === tan_min
+                        && (px > x_of(m) || (px === x_of(m) && sector_contains_sector(m, p)))))) {
+                m = p;
+                tan_min = tan;
+            }
+        }
+
+        p = _node_next[p];
+    } while (p !== stop);
+
+    return m;
+}
+
+/**
+ * Point-in-triangle on raw coordinates. The bridge search builds a triangle from
+ * the ray hit, which is not a ring node, so it cannot use the node-indexed test.
+ *
+ * Inexact by necessity (`qx` is an intersection, computed with a division) -- but
+ * this only selects *which* legal bridge to use, never whether the result is
+ * valid, so an unlucky rounding costs triangle quality and nothing else.
+ *
+ * @returns {boolean}
+ */
+function point_in_triangle_xy(ax, ay, bx, by, cx, cy, px, py) {
+    return (cx - px) * (ay - py) >= (ax - px) * (cy - py)
+        && (ax - px) * (by - py) >= (bx - px) * (ay - py)
+        && (bx - px) * (cy - py) >= (cx - px) * (by - py);
+}
+
+/**
+ * Whether m's interior sector contains p's -- the tie-break when two candidate
+ * bridges sit at the same angle.
+ *
+ * @param {number} m
+ * @param {number} p
+ * @returns {boolean}
+ */
+function sector_contains_sector(m, p) {
+    return orient(_node_prev[m], m, _node_prev[p]) > 0 && orient(_node_next[p], m, _node_next[m]) > 0;
+}
+
+/**
+ * Splice one hole into the outer ring through a doubled bridge edge.
+ *
+ * @param {number} hole leftmost node of the hole ring
+ * @param {number} outer
+ * @returns {number} the outer ring node to continue from
+ */
+function eliminate_hole(hole, outer) {
+    if (outer === NULL_NODE) {
+        return NULL_NODE;
+    }
+
+    const bridge = find_hole_bridge(hole, outer);
+
+    if (bridge === NULL_NODE) {
+        return outer;
+    }
+
+    const bridge_reverse = split_ring(bridge, hole);
+
+    filter_points(bridge_reverse, _node_next[bridge_reverse]);
+
+    return filter_points(bridge, _node_next[bridge]);
+}
+
+/**
+ * Compare two hole rings by their leftmost node, so bridges are cut left to right
+ * and therefore never cross one another.
+ *
+ * @param {number} a leftmost node of one hole
+ * @param {number} b leftmost node of another
+ * @returns {number}
+ */
+function compare_hole_leftmost(a, b) {
+    let result = x_of(a) - x_of(b);
+
+    if (result !== 0) {
+        return result;
+    }
+
+    result = y_of(a) - y_of(b);
+
+    if (result !== 0) {
+        return result;
+    }
+
+    // Two holes meeting at one point: order them by outgoing slope so the bridge
+    // is always cut at the vertex where they meet.
+    const a_slope = (y_of(_node_next[a]) - y_of(a)) / (x_of(_node_next[a]) - x_of(a));
+    const b_slope = (y_of(_node_next[b]) - y_of(b)) / (x_of(_node_next[b]) - x_of(b));
+
+    return a_slope - b_slope;
+}
+
+/**
+ * Splice every hole contour into the outer ring.
+ *
+ * @param {ArrayLike<number>} points
+ * @param {ArrayLike<number>} contour_ends
+ * @param {number} contour_count
+ * @param {number} outer
+ * @returns {number} the merged ring
+ */
+function eliminate_holes(points, contour_ends, contour_count, outer) {
+    const queue = [];
+
+    for (let c = 1; c < contour_count; c++) {
+        const from = contour_ends[c - 1];
+        const to = contour_ends[c];
+
+        const last = link_contour(points, from, to, false);
+
+        if (last === NULL_NODE) {
+            continue;
+        }
+
+        if (last === _node_next[last]) {
+            // the hole collapsed to a single point; keep it as a Steiner vertex
+            _node_steiner[last] = 1;
+        }
+
+        queue.push(get_leftmost(last));
+    }
+
+    queue.sort(compare_hole_leftmost);
+
+    for (let i = 0; i < queue.length; i++) {
+        outer = eliminate_hole(queue[i], outer);
+    }
+
+    return outer;
+}
+
+/**
+ * Triangulate a 2D polygon with holes.
+ *
+ * Ear clipping over a doubly-linked vertex ring, with every combinatorial
+ * decision made by the exact `orient2d` predicate already used elsewhere in
+ * `core/geom` -- so the result does not depend on coordinate magnitude, and
+ * collinear or coincident input is decided rather than guessed. Above
+ * {@link HASH_THRESHOLD} vertices the point-in-ear test is restricted to a
+ * Morton-code range, which is what keeps large rings off the quadratic path.
+ *
+ * Contour `i` spans `points[(i === 0 ? 0 : contour_ends[i - 1]) .. contour_ends[i])`
+ * in vertex units. Contour 0 is the outer boundary and the rest are holes.
+ * Winding is normalised internally, so callers cannot get it subtly wrong.
+ *
+ * Output is triples of indices into `points`, in ear-cut order, each triangle
+ * counter-clockwise.
+ *
+ * A well-formed polygon yields exactly `V + 2H - 2` triangles, where `V` is the
+ * total vertex count and `H` the hole count. **A smaller return value is how this
+ * function reports that the input could not be fully triangulated** -- it is
+ * self-intersecting, or partly degenerate. It never throws for that: a partial
+ * triangulation is still the best available answer, and the caller is told how
+ * much of one it got. {@link polygon2_triangulation_deviation} measures the
+ * shortfall in area terms.
+ *
+ * Not re-entrant: the vertex ring lives in module-static buffers so a call
+ * allocates nothing in the steady state.
+ *
+ * @param {Uint32Array} result receives 3 point indices per triangle
+ * @param {number} result_offset first index written in `result`
+ * @param {ArrayLike<number>} points flat (x, y) pairs, stride 2
+ * @param {ArrayLike<number>} contour_ends exclusive end vertex index per contour, non-decreasing
+ * @param {number} contour_count number of contours, at least 1
+ * @returns {number} number of triangles written
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon2_triangulate(result, result_offset, points, contour_ends, contour_count) {
+    assert.defined(result, "result");
+    assert.isNonNegativeInteger(result_offset, "result_offset");
+    assert.isArrayLike(points, "points");
+    assert.isArrayLike(contour_ends, "contour_ends");
+    assert.isPositiveInteger(contour_count, "contour_count");
+
+    const vertex_count = contour_ends[contour_count - 1];
+
+    assert.isNonNegativeInteger(vertex_count, "contour_ends[contour_count - 1]");
+    assert.greaterThanOrEqual(points.length, vertex_count * 2, "points.length");
+
+    if (vertex_count < 3) {
+        return 0;
+    }
+
+    // Hole elimination duplicates two vertices per bridge, and each recovery split
+    // duplicates two more. Splits only ever happen on a ring that already failed to
+    // clip, and each consumes at least one vertex, so 2 per vertex bounds both.
+    ensure_node_capacity(vertex_count * 3 + contour_count * 2);
+
+    _node_count = 0;
+    _out = result;
+    _out_cursor = result_offset;
+
+    let outer = link_contour(points, 0, contour_ends[0], true);
+
+    if (outer === NULL_NODE || _node_next[outer] === _node_prev[outer]) {
+        _out = null;
+
+        return 0;
+    }
+
+    if (contour_count > 1) {
+        outer = eliminate_holes(points, contour_ends, contour_count, outer);
+    }
+
+    _hashed = vertex_count > HASH_THRESHOLD;
+
+    if (_hashed) {
+        let min_x = Infinity;
+        let min_y = Infinity;
+        let max_x = -Infinity;
+        let max_y = -Infinity;
+
+        for (let i = 0; i < vertex_count; i++) {
+            const x = points[i * 2];
+            const y = points[i * 2 + 1];
+
+            if (x < min_x) min_x = x;
+            if (y < min_y) min_y = y;
+            if (x > max_x) max_x = x;
+            if (y > max_y) max_y = y;
+        }
+
+        _min_x = min_x;
+        _min_y = min_y;
+
+        const extent = Math.max(max_x - min_x, max_y - min_y);
+
+        // A zero-extent polygon has no area to triangulate; any finite scale works.
+        _inv_size = extent > 0 ? MORTON_SCALE / extent : 0;
+    }
+
+    ear_clip(outer, 0);
+
+    const triangles = (_out_cursor - result_offset) / 3;
+
+    _out = null;
+
+    return triangles;
+}