@woosh/meep-engine 2.168.1 → 2.169.1

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"}