@woosh/meep-engine 2.168.1 → 2.169.0

package/src/core/geom/2d/polygon/polygon2_is_counter_clockwise.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Exact winding test for a 2D contour: `true` when it is wound counter-clockwise.
+ *
+ * Decided by one exact orientation predicate at the contour's lexicographically
+ * smallest vertex. That vertex is necessarily on the convex hull, so the turn
+ * taken there is the contour's own turn direction -- no summation, no
+ * cancellation, and the answer does not depend on how far the contour sits from
+ * the origin.
+ *
+ * This is what {@link polygon2_signed_area} cannot give you. Its shoelace sum is
+ * a difference of terms of magnitude `O(|p|^2)` where the answer is the area, so
+ * for a small polygon far from the origin -- or a small polygon whose vertices are
+ * close together -- the computed sign is rounding noise. A 1e-9-sided square at
+ * (1, 1) already has a true area of 1e-18 against per-term rounding of ~1e-16: the
+ * sum's sign is then meaningless. Use the signed area when you want the area, and
+ * this when you want the winding.
+ *
+ * Coincident neighbours of the extreme vertex are stepped over, so a contour with
+ * duplicated points still answers correctly. A contour with no area at all (every
+ * vertex collinear, or all coincident) has no winding; it reports `false`.
+ *
+ * @param {ArrayLike<number>} points flat (x, y) pairs, stride 2
+ * @param {number} from first vertex index of the contour
+ * @param {number} count number of vertices in the contour
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon2_is_counter_clockwise(points: ArrayLike<number>, from: number, count: number): boolean;
+//# sourceMappingURL=polygon2_is_counter_clockwise.d.ts.map

package/src/core/geom/2d/polygon/polygon2_is_counter_clockwise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon2_is_counter_clockwise.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/polygon/polygon2_is_counter_clockwise.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,sDARW,UAAU,MAAM,CAAC,QACjB,MAAM,SACN,MAAM,GACJ,OAAO,CAyDnB"}

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

@@ -0,0 +1,84 @@
+import { orient2d_indexed } from "../convex-hull/orient2d_indexed.js";
+
+/**
+ * Exact winding test for a 2D contour: `true` when it is wound counter-clockwise.
+ *
+ * Decided by one exact orientation predicate at the contour's lexicographically
+ * smallest vertex. That vertex is necessarily on the convex hull, so the turn
+ * taken there is the contour's own turn direction -- no summation, no
+ * cancellation, and the answer does not depend on how far the contour sits from
+ * the origin.
+ *
+ * This is what {@link polygon2_signed_area} cannot give you. Its shoelace sum is
+ * a difference of terms of magnitude `O(|p|^2)` where the answer is the area, so
+ * for a small polygon far from the origin -- or a small polygon whose vertices are
+ * close together -- the computed sign is rounding noise. A 1e-9-sided square at
+ * (1, 1) already has a true area of 1e-18 against per-term rounding of ~1e-16: the
+ * sum's sign is then meaningless. Use the signed area when you want the area, and
+ * this when you want the winding.
+ *
+ * Coincident neighbours of the extreme vertex are stepped over, so a contour with
+ * duplicated points still answers correctly. A contour with no area at all (every
+ * vertex collinear, or all coincident) has no winding; it reports `false`.
+ *
+ * @param {ArrayLike<number>} points flat (x, y) pairs, stride 2
+ * @param {number} from first vertex index of the contour
+ * @param {number} count number of vertices in the contour
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function polygon2_is_counter_clockwise(points, from, count) {
+    if (count < 3) {
+        return false;
+    }
+
+    const to = from + count;
+
+    // Lexicographically smallest vertex -- guaranteed to be a hull vertex.
+    let extreme = from;
+    let ex = points[from * 2];
+    let ey = points[from * 2 + 1];
+
+    for (let i = from + 1; i < to; i++) {
+        const x = points[i * 2];
+        const y = points[i * 2 + 1];
+
+        if (x < ex || (x === ex && y < ey)) {
+            extreme = i;
+            ex = x;
+            ey = y;
+        }
+    }
+
+    // Step over neighbours that sit exactly on the extreme vertex; a zero-length
+    // edge carries no direction.
+    let prev = extreme;
+    for (let steps = 1; steps < count; steps++) {
+        const candidate = from + ((extreme - from - steps + count) % count);
+
+        if (points[candidate * 2] !== ex || points[candidate * 2 + 1] !== ey) {
+            prev = candidate;
+            break;
+        }
+    }
+
+    let next = extreme;
+    for (let steps = 1; steps < count; steps++) {
+        const candidate = from + ((extreme - from + steps) % count);
+
+        if (points[candidate * 2] !== ex || points[candidate * 2 + 1] !== ey) {
+            next = candidate;
+            break;
+        }
+    }
+
+    if (prev === extreme || next === extreme) {
+        // every vertex is coincident with the extreme one
+        return false;
+    }
+
+    // orient2d is negative for a counter-clockwise triple (see polygon2_triangulate)
+    return orient2d_indexed(points, prev, extreme, next) < 0;
+}

package/src/core/geom/2d/polygon/polygon2_signed_area.d.ts

@@ -1,6 +1,28 @@
 /**
- * Uses Green's Theorem to compute area of a 2d polygon
- * @param {number[]|Float32Array|Float64Array} points
+ * Signed area of a 2D polygon by the shoelace formula. Positive for
+ * counter-clockwise winding, negative for clockwise.
+ *
+ * The contour is implicitly closed: a repeated first-as-last point is handled,
+ * and so is an open list.
+ *
+ * Every vertex is taken RELATIVE TO THE FIRST before it is crossed. The
+ * absolute-coordinate form -- `sum += x0*y1 - y0*x1` over the raw points, which
+ * this used to compute -- accumulates terms of magnitude `O(|p|^2)` to reach an
+ * answer that is only the area, so the significant digits cancel away for any
+ * polygon that is small relative to its distance from the origin. A unit square
+ * at (1e6, 1e6) already loses most of its precision that way, and a
+ * 1e-9-sided square at (1, 1) comes back as exactly 0.
+ *
+ * Translating to the first vertex costs one subtraction per term and makes the
+ * result translation-invariant, which is what the formula claims to be
+ * mathematically. Both edges incident to that first vertex then contribute
+ * nothing, which is why the loop starts at 1 and no separate closing term is
+ * needed.
+ *
+ * This is still floating point. When only the *winding* matters, prefer
+ * {@link polygon2_is_counter_clockwise}, which is exact at any scale.
+ *
+ * @param {number[]|Float32Array|Float64Array} points flat (x, y) pairs, stride 2
  * @param {number} point_count
  * @returns {number}
  */

package/src/core/geom/2d/polygon/polygon2_signed_area.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"polygon2_signed_area.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/polygon/polygon2_signed_area.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,6CAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,eAClC,MAAM,GACJ,MAAM,CA6BlB"}
+{"version":3,"file":"polygon2_signed_area.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/polygon/polygon2_signed_area.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,6CAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,eAClC,MAAM,GACJ,MAAM,CAyBlB"}

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

@@ -1,34 +1,52 @@
-/**
- * Uses Green's Theorem to compute area of a 2d polygon
- * @param {number[]|Float32Array|Float64Array} points
- * @param {number} point_count
- * @returns {number}
- */
-export function polygon2_signed_area(points, point_count) {
-    let sum = 0;
-
-    for (let i = 0; i < point_count - 1; i++) {
-        const i2 = i * 2;
-
-        const x0 = points[i2];
-        const y0 = points[i2 + 1];
-
-        const x1 = points[i2 + 2];
-        const y1 = points[i2 + 3];
-
-        sum += x0 * y1 - y0 * x1;
-    }
-
-    const first_x = points[0];
-    const first_y = points[1];
-
-    const last_x = points[point_count * 2 - 2];
-    const last_y = points[point_count * 2 - 1];
-
-    if (first_x !== last_x || first_y !== last_y) {
-        // doesn't wrap around, let's close the loop ourselves
-        sum += last_x * first_y - last_y * first_x;
-    }
-
-    return sum * 0.5;
-}
+/**
+ * Signed area of a 2D polygon by the shoelace formula. Positive for
+ * counter-clockwise winding, negative for clockwise.
+ *
+ * The contour is implicitly closed: a repeated first-as-last point is handled,
+ * and so is an open list.
+ *
+ * Every vertex is taken RELATIVE TO THE FIRST before it is crossed. The
+ * absolute-coordinate form -- `sum += x0*y1 - y0*x1` over the raw points, which
+ * this used to compute -- accumulates terms of magnitude `O(|p|^2)` to reach an
+ * answer that is only the area, so the significant digits cancel away for any
+ * polygon that is small relative to its distance from the origin. A unit square
+ * at (1e6, 1e6) already loses most of its precision that way, and a
+ * 1e-9-sided square at (1, 1) comes back as exactly 0.
+ *
+ * Translating to the first vertex costs one subtraction per term and makes the
+ * result translation-invariant, which is what the formula claims to be
+ * mathematically. Both edges incident to that first vertex then contribute
+ * nothing, which is why the loop starts at 1 and no separate closing term is
+ * needed.
+ *
+ * This is still floating point. When only the *winding* matters, prefer
+ * {@link polygon2_is_counter_clockwise}, which is exact at any scale.
+ *
+ * @param {number[]|Float32Array|Float64Array} points flat (x, y) pairs, stride 2
+ * @param {number} point_count
+ * @returns {number}
+ */
+export function polygon2_signed_area(points, point_count) {
+    if (point_count < 3) {
+        return 0;
+    }
+
+    const origin_x = points[0];
+    const origin_y = points[1];
+
+    let sum = 0;
+
+    for (let i = 1; i < point_count - 1; i++) {
+        const i2 = i * 2;
+
+        const x0 = points[i2] - origin_x;
+        const y0 = points[i2 + 1] - origin_y;
+
+        const x1 = points[i2 + 2] - origin_x;
+        const y1 = points[i2 + 3] - origin_y;
+
+        sum += x0 * y1 - y0 * x1;
+    }
+
+    return sum * 0.5;
+}

package/src/core/geom/2d/polygon/polygon2_triangulate.corpus.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Inputs that have actually broken {@link polygon2_triangulate}, kept so they can
+ * never break it again.
+ *
+ * This file only ever grows, and only from real failures -- a case someone
+ * *imagines* might be hard belongs in the ordinary spec, not here. Every entry
+ * records what went wrong when it was added, because that is the part that stops
+ * a future change from quietly reintroducing the same class of bug. The practice
+ * is borrowed from manifold, whose triangulator carries ~3 MB of recorded failing
+ * polygons replayed as tests.
+ *
+ * `expect_full` says whether the polygon is well-formed enough that the whole of
+ * its area must be covered. `false` means the input is genuinely invalid
+ * (self-intersecting) and the only requirements are the universal ones: no throw,
+ * no hang, no out-of-range index.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const POLYGON2_TRIANGULATE_CORPUS: {
+    name: string;
+    why: string;
+    points: number[];
+    contour_ends: number[];
+    contour_count: number;
+    expect_full: boolean;
+}[];
+//# sourceMappingURL=polygon2_triangulate.corpus.d.ts.map

package/src/core/geom/2d/polygon/polygon2_triangulate.corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon2_triangulate.corpus.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/polygon/polygon2_triangulate.corpus.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;IAkEE"}

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

@@ -0,0 +1,86 @@
+/**
+ * Inputs that have actually broken {@link polygon2_triangulate}, kept so they can
+ * never break it again.
+ *
+ * This file only ever grows, and only from real failures -- a case someone
+ * *imagines* might be hard belongs in the ordinary spec, not here. Every entry
+ * records what went wrong when it was added, because that is the part that stops
+ * a future change from quietly reintroducing the same class of bug. The practice
+ * is borrowed from manifold, whose triangulator carries ~3 MB of recorded failing
+ * polygons replayed as tests.
+ *
+ * `expect_full` says whether the polygon is well-formed enough that the whole of
+ * its area must be covered. `false` means the input is genuinely invalid
+ * (self-intersecting) and the only requirements are the universal ones: no throw,
+ * no hang, no out-of-range index.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const POLYGON2_TRIANGULATE_CORPUS = [
+    {
+        name: "unit-offset micro square",
+        why: "Winding was decided by the shoelace sum, whose sign here is pure "
+            + "rounding noise: the true area is 1e-18 against ~1e-16 per-term error. "
+            + "The ring came out backwards, every corner looked reflex, and the "
+            + "result was zero triangles. Fixed by deciding winding with one exact "
+            + "orientation predicate at a hull vertex (polygon2_is_counter_clockwise).",
+        points: [
+            1, 1,
+            1 + 1e-9, 1,
+            1 + 1e-9, 1 + 1e-9,
+            1, 1 + 1e-9,
+        ],
+        contour_ends: [4],
+        contour_count: 1,
+        expect_full: true,
+    },
+    {
+        name: "coarse-grid point soup (fuzz seed 24)",
+        why: "Twenty points on a 7x7 integer grid, with duplicates and collinear "
+            + "runs. The ear search exhausted itself, fell through to the "
+            + "cure-local-intersections pass, and that pass walked the "
+            + "collapsed-ring sentinel as if it were a node -- an infinite loop. "
+            + "Fixed by making the recovery pass accept and propagate the sentinel, "
+            + "and by stopping it once the ring holds fewer than three nodes.",
+        points: [
+            2, 3, 3, 6, 1, 5, 0, 4, 5, 0,
+            4, 2, 3, 3, 3, 6, 2, 3, 6, 1,
+            4, 4, 2, 6, 3, 2, 6, 4, 1, 1,
+            3, 0, 5, 0, 3, 2, 6, 4, 3, 3,
+        ],
+        contour_ends: [20],
+        contour_count: 1,
+        expect_full: false,
+    },
+    {
+        name: "two rectangular holes bridged through a shared edge",
+        why: "Produced 12 triangles where the Euler bound allows 14, which looked "
+            + "like dropped geometry. It was not: the bridges left collinear corners "
+            + "that were correctly absorbed rather than emitted as zero-area "
+            + "triangles. Kept as the standing reminder that V + 2H - 2 is an upper "
+            + "bound, not an equality -- area conservation is the real invariant.",
+        points: [
+            0, 0, 20, 0, 20, 10, 0, 10,
+            2, 8, 6, 8, 6, 2, 2, 2,
+            12, 8, 18, 8, 18, 2, 12, 2,
+        ],
+        contour_ends: [4, 8, 12],
+        contour_count: 3,
+        expect_full: true,
+    },
+    {
+        name: "hole touching the outer boundary at a vertex",
+        why: "Same class as above -- 6 triangles against a bound of 7. The hole's "
+            + "corner lands exactly on the outer edge, so the bridge is degenerate "
+            + "and one corner becomes collinear. Area is still exact and every input "
+            + "vertex is still used.",
+        points: [
+            0, 0, 10, 0, 10, 10, 0, 10,
+            4, 7, 4, 3, 0, 5,
+        ],
+        contour_ends: [4, 7],
+        contour_count: 2,
+        expect_full: true,
+    },
+];

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

@@ -0,0 +1,40 @@
+/**
+ * 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: Uint32Array, result_offset: number, points: ArrayLike<number>, contour_ends: ArrayLike<number>, contour_count: number): number;
+//# sourceMappingURL=polygon2_triangulate.d.ts.map

package/src/core/geom/2d/polygon/polygon2_triangulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon2_triangulate.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/polygon/polygon2_triangulate.js"],"names":[],"mappings":"AAkpCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,6CAVW,WAAW,iBACX,MAAM,UACN,UAAU,MAAM,CAAC,gBACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,CA4ElB"}