@woosh/meep-engine 2.168.1 → 2.169.1

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js

@@ -0,0 +1,599 @@
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+/**
+ * Which kind of element a defect was found on. Typed constant (no stringly-typed
+ * states), mirroring the four pools of {@link BinaryTopology}.
+ * @readonly
+ */
+export const BT_ELEMENT_TYPE = Object.freeze({
+    VERTEX: 0,
+    EDGE: 1,
+    LOOP: 2,
+    FACE: 3,
+});
+
+/**
+ * Structural defects {@link bt_mesh_validate} can report. Each value names a
+ * broken invariant of {@link BinaryTopology}, not a symptom.
+ * @readonly
+ */
+export const BT_DEFECT = Object.freeze({
+    /** A handle points at a pool slot that is not allocated (dangling reference). */
+    DANGLING_REFERENCE: 0,
+    /** A cycle (disk / radial / face-loop) does not return to its start within the pool's size. */
+    CYCLE_NOT_CLOSED: 1,
+    /** `prev` is not the inverse of `next` somewhere on a cycle. */
+    CYCLE_LINK_ASYMMETRIC: 2,
+    /** An edge is missing from the disk cycle of one of its vertices. */
+    EDGE_NOT_IN_DISK: 3,
+    /** An edge sits on the disk cycle of a vertex that is not one of its endpoints. */
+    DISK_EDGE_VERTEX_MISMATCH: 4,
+    /** A loop is missing from the radial cycle of the edge it claims. */
+    LOOP_NOT_IN_RADIAL: 5,
+    /** A loop on an edge's radial cycle does not claim that edge. */
+    RADIAL_LOOP_EDGE_MISMATCH: 6,
+    /** A loop on a face's loop cycle does not claim that face. */
+    FACE_LOOP_FACE_MISMATCH: 7,
+    /** A face's loop cycle is shorter than three corners. */
+    FACE_TOO_FEW_CORNERS: 8,
+    /** The same vertex appears twice on one face's loop cycle. */
+    FACE_VERTEX_REPEATED: 9,
+    /** A loop's edge does not connect that loop's vertex to the next loop's vertex. */
+    LOOP_EDGE_ENDPOINT_MISMATCH: 10,
+    /** An allocated loop is not reachable from any allocated face. */
+    LOOP_ORPHANED: 11,
+    /** A vertex with incident edges has a NULL edge pointer, or vice versa. */
+    VERTEX_EDGE_POINTER_INCONSISTENT: 12,
+    /** A coordinate or normal component is not finite. */
+    NON_FINITE_VALUE: 13,
+});
+
+/**
+ * Bit set in `edge_seen` once an edge has been reached through its v1 disk slot.
+ * @type {number}
+ */
+const SEEN_V1 = 1;
+/**
+ * Bit set in `edge_seen` once an edge has been reached through its v2 disk slot.
+ * @type {number}
+ */
+const SEEN_V2 = 2;
+
+/**
+ * @param {object[]} out
+ * @param {number} code one of {@link BT_DEFECT}
+ * @param {number} element_type one of {@link BT_ELEMENT_TYPE}
+ * @param {number} element
+ * @param {string} detail
+ */
+function record(out, code, element_type, element, detail) {
+    out.push({ code, element_type, element, detail });
+}
+
+/**
+ * True when `id` is a live slot of `pool`, i.e. safe to dereference.
+ * @param {BinaryElementPool} pool
+ * @param {number} id
+ * @returns {boolean}
+ */
+function is_live(pool, id) {
+    return id !== NULL_POINTER && id < pool.size && pool.is_allocated(id);
+}
+
+/**
+ * Check every handle an element stores actually points at a live slot of the
+ * right pool. Runs first so the cycle walks below can dereference freely.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_references(mesh, out) {
+    const vertices = mesh.vertices;
+    const edges = mesh.edges;
+    const loops = mesh.loops;
+    const faces = mesh.faces;
+
+    for (let v = 0; v < vertices.size; v++) {
+        if (!vertices.is_allocated(v)) {
+            continue;
+        }
+
+        const e = mesh.vertex_read_edge(v);
+
+        if (e !== NULL_POINTER && !is_live(edges, e)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.VERTEX, v,
+                `vertex ${v} points at edge ${e}, which is not allocated`);
+        }
+    }
+
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+
+        const v1 = mesh.edge_read_vertex1(e);
+        const v2 = mesh.edge_read_vertex2(e);
+
+        if (!is_live(vertices, v1)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} vertex1 = ${v1}, which is not allocated`);
+        }
+
+        if (!is_live(vertices, v2)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} vertex2 = ${v2}, which is not allocated`);
+        }
+
+        const l = mesh.edge_read_loop(e);
+
+        if (l !== NULL_POINTER && !is_live(loops, l)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} points at loop ${l}, which is not allocated`);
+        }
+    }
+
+    for (let l = 0; l < loops.size; l++) {
+        if (!loops.is_allocated(l)) {
+            continue;
+        }
+
+        const v = mesh.loop_read_vertex(l);
+        const e = mesh.loop_read_edge(l);
+        const f = mesh.loop_read_face(l);
+
+        if (!is_live(vertices, v)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} vertex = ${v}, which is not allocated`);
+        }
+
+        if (!is_live(edges, e)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} edge = ${e}, which is not allocated`);
+        }
+
+        if (f !== NULL_POINTER && !is_live(faces, f)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} face = ${f}, which is not allocated`);
+        }
+
+        const links = [
+            ['radial_next', mesh.loop_read_radial_next(l)],
+            ['radial_prev', mesh.loop_read_radial_prev(l)],
+            ['next', mesh.loop_read_next(l)],
+            ['prev', mesh.loop_read_prev(l)],
+        ];
+
+        for (let i = 0; i < links.length; i++) {
+            const name = links[i][0];
+            const target = links[i][1];
+
+            if (!is_live(loops, target)) {
+                record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                    `loop ${l} ${name} = ${target}, which is not allocated`);
+            }
+        }
+    }
+
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+
+        const l = mesh.face_read_loop(f);
+
+        if (!is_live(loops, l)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} points at loop ${l}, which is not allocated`);
+        }
+    }
+}
+
+/**
+ * Walk every vertex's disk cycle and check it is a closed doubly-linked ring
+ * whose members all touch that vertex, then check that every allocated edge was
+ * reached through both of its endpoints.
+ *
+ * Self-loops (`vertex1 === vertex2`) occupy the v1 slot only and their
+ * v2_disk_link is unspecified, so they are expected on exactly one side. See the
+ * disk cycle convention documented on {@link BinaryTopology}.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_disk_cycles(mesh, out) {
+    const vertices = mesh.vertices;
+    const edges = mesh.edges;
+
+    const edge_seen = new Uint8Array(edges.size);
+
+    for (let v = 0; v < vertices.size; v++) {
+        if (!vertices.is_allocated(v)) {
+            continue;
+        }
+
+        const start = mesh.vertex_read_edge(v);
+
+        if (start === NULL_POINTER || !is_live(edges, start)) {
+            continue;
+        }
+
+        let e = start;
+        // The cycle cannot legally be longer than the pool, so this bounds a walk over
+        // corrupt links without hiding the corruption -- it is reported below.
+        let steps = 0;
+        let closed = false;
+
+        do {
+            const v1 = mesh.edge_read_vertex1(e);
+            const v2 = mesh.edge_read_vertex2(e);
+
+            const is_v1 = v1 === v;
+
+            if (!is_v1 && v2 !== v) {
+                record(out, BT_DEFECT.DISK_EDGE_VERTEX_MISMATCH, BT_ELEMENT_TYPE.EDGE, e,
+                    `edge ${e} is on vertex ${v}'s disk cycle but connects ${v1} and ${v2}`);
+                break;
+            }
+
+            edge_seen[e] |= is_v1 ? SEEN_V1 : SEEN_V2;
+
+            const next = is_v1 ? mesh.edge_read_v1_disk_next(e) : mesh.edge_read_v2_disk_next(e);
+
+            if (!is_live(edges, next)) {
+                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.VERTEX, v,
+                    `vertex ${v} disk cycle leaves the pool at edge ${e} (next = ${next})`);
+                break;
+            }
+
+            // prev of next, taken on next's slot for v, must come back to e
+            const next_is_v1 = mesh.edge_read_vertex1(next) === v;
+            const back = next_is_v1 ? mesh.edge_read_v1_disk_prev(next) : mesh.edge_read_v2_disk_prev(next);
+
+            if (back !== e) {
+                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.VERTEX, v,
+                    `vertex ${v} disk cycle: next(${e}) = ${next} but prev(${next}) = ${back}`);
+                break;
+            }
+
+            e = next;
+            steps++;
+
+            if (e === start) {
+                closed = true;
+                break;
+            }
+        } while (steps <= edges.size);
+
+        if (!closed && steps > edges.size) {
+            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.VERTEX, v,
+                `vertex ${v} disk cycle did not return to edge ${start} within ${edges.size} steps`);
+        }
+    }
+
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+
+        const v1 = mesh.edge_read_vertex1(e);
+        const v2 = mesh.edge_read_vertex2(e);
+
+        if (!is_live(vertices, v1) || !is_live(vertices, v2)) {
+            // already reported by check_references
+            continue;
+        }
+
+        if ((edge_seen[e] & SEEN_V1) === 0) {
+            record(out, BT_DEFECT.EDGE_NOT_IN_DISK, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} is not on the disk cycle of its vertex1 (${v1})`);
+        }
+
+        if (v1 !== v2 && (edge_seen[e] & SEEN_V2) === 0) {
+            record(out, BT_DEFECT.EDGE_NOT_IN_DISK, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} is not on the disk cycle of its vertex2 (${v2})`);
+        }
+    }
+}
+
+/**
+ * Walk every edge's radial cycle and check it is a closed doubly-linked ring of
+ * loops that all claim that edge, then check every allocated loop was reached
+ * through the edge it claims.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_radial_cycles(mesh, out) {
+    const edges = mesh.edges;
+    const loops = mesh.loops;
+
+    const loop_seen = new Uint8Array(loops.size);
+
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+
+        const start = mesh.edge_read_loop(e);
+
+        if (start === NULL_POINTER || !is_live(loops, start)) {
+            continue;
+        }
+
+        let l = start;
+        let steps = 0;
+        let closed = false;
+
+        do {
+            if (mesh.loop_read_edge(l) !== e) {
+                record(out, BT_DEFECT.RADIAL_LOOP_EDGE_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
+                    `loop ${l} is on edge ${e}'s radial cycle but claims edge ${mesh.loop_read_edge(l)}`);
+                break;
+            }
+
+            loop_seen[l] = 1;
+
+            const next = mesh.loop_read_radial_next(l);
+
+            if (!is_live(loops, next)) {
+                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.EDGE, e,
+                    `edge ${e} radial cycle leaves the pool at loop ${l} (radial_next = ${next})`);
+                break;
+            }
+
+            const back = mesh.loop_read_radial_prev(next);
+
+            if (back !== l) {
+                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.EDGE, e,
+                    `edge ${e} radial cycle: radial_next(${l}) = ${next} but radial_prev(${next}) = ${back}`);
+                break;
+            }
+
+            l = next;
+            steps++;
+
+            if (l === start) {
+                closed = true;
+                break;
+            }
+        } while (steps <= loops.size);
+
+        if (!closed && steps > loops.size) {
+            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} radial cycle did not return to loop ${start} within ${loops.size} steps`);
+        }
+    }
+
+    for (let l = 0; l < loops.size; l++) {
+        if (!loops.is_allocated(l)) {
+            continue;
+        }
+
+        const e = mesh.loop_read_edge(l);
+
+        if (!is_live(edges, e)) {
+            // already reported by check_references
+            continue;
+        }
+
+        if (loop_seen[l] === 0) {
+            record(out, BT_DEFECT.LOOP_NOT_IN_RADIAL, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} claims edge ${e} but is not on that edge's radial cycle`);
+        }
+    }
+}
+
+/**
+ * Walk every face's loop cycle. Checks closure, `prev`/`next` symmetry, that
+ * every corner claims the face, that the face has at least three corners with no
+ * repeated vertex, and that each corner's edge spans that corner's vertex and the
+ * next corner's vertex. Finally reports allocated loops no face can reach.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_face_cycles(mesh, out) {
+    const loops = mesh.loops;
+    const faces = mesh.faces;
+
+    const loop_seen = new Uint8Array(loops.size);
+
+    // Reused across faces so a fan of small faces does not allocate per face.
+    const cycle_vertices = [];
+
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+
+        const start = mesh.face_read_loop(f);
+
+        if (!is_live(loops, start)) {
+            continue;
+        }
+
+        cycle_vertices.length = 0;
+
+        let l = start;
+        let steps = 0;
+        let closed = false;
+        let broken = false;
+
+        do {
+            if (mesh.loop_read_face(l) !== f) {
+                record(out, BT_DEFECT.FACE_LOOP_FACE_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
+                    `loop ${l} is on face ${f}'s loop cycle but claims face ${mesh.loop_read_face(l)}`);
+                broken = true;
+                break;
+            }
+
+            loop_seen[l] = 1;
+            cycle_vertices.push(mesh.loop_read_vertex(l));
+
+            const next = mesh.loop_read_next(l);
+
+            if (!is_live(loops, next)) {
+                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.FACE, f,
+                    `face ${f} loop cycle leaves the pool at loop ${l} (next = ${next})`);
+                broken = true;
+                break;
+            }
+
+            const back = mesh.loop_read_prev(next);
+
+            if (back !== l) {
+                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.FACE, f,
+                    `face ${f} loop cycle: next(${l}) = ${next} but prev(${next}) = ${back}`);
+                broken = true;
+                break;
+            }
+
+            // the corner's edge must span this corner and the next one
+            const e = mesh.loop_read_edge(l);
+            const v_here = mesh.loop_read_vertex(l);
+            const v_next = mesh.loop_read_vertex(next);
+
+            if (is_live(mesh.edges, e)) {
+                const e1 = mesh.edge_read_vertex1(e);
+                const e2 = mesh.edge_read_vertex2(e);
+
+                const spans = (e1 === v_here && e2 === v_next) || (e1 === v_next && e2 === v_here);
+
+                if (!spans) {
+                    record(out, BT_DEFECT.LOOP_EDGE_ENDPOINT_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
+                        `loop ${l} spans vertices ${v_here}->${v_next} but its edge ${e} connects ${e1} and ${e2}`);
+                }
+            }
+
+            l = next;
+            steps++;
+
+            if (l === start) {
+                closed = true;
+                break;
+            }
+        } while (steps <= loops.size);
+
+        if (!closed && !broken) {
+            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} loop cycle did not return to loop ${start} within ${loops.size} steps`);
+            continue;
+        }
+
+        if (broken) {
+            continue;
+        }
+
+        if (cycle_vertices.length < 3) {
+            record(out, BT_DEFECT.FACE_TOO_FEW_CORNERS, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} has ${cycle_vertices.length} corner(s)`);
+        }
+
+        for (let i = 0; i < cycle_vertices.length; i++) {
+            for (let j = i + 1; j < cycle_vertices.length; j++) {
+                if (cycle_vertices[i] === cycle_vertices[j]) {
+                    record(out, BT_DEFECT.FACE_VERTEX_REPEATED, BT_ELEMENT_TYPE.FACE, f,
+                        `face ${f} visits vertex ${cycle_vertices[i]} at corners ${i} and ${j}`);
+                }
+            }
+        }
+    }
+
+    for (let l = 0; l < loops.size; l++) {
+        if (!loops.is_allocated(l)) {
+            continue;
+        }
+
+        if (loop_seen[l] === 0) {
+            record(out, BT_DEFECT.LOOP_ORPHANED, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} is allocated but no face's loop cycle reaches it`);
+        }
+    }
+}
+
+/**
+ * Vertex coordinates and normals, and face normals, must be finite. A NaN here
+ * survives every topological check and only surfaces much later as an empty
+ * bounding box or a black triangle.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_finite_values(mesh, out) {
+    const vertices = mesh.vertices;
+    const faces = mesh.faces;
+
+    const scratch = new Float32Array(3);
+
+    for (let v = 0; v < vertices.size; v++) {
+        if (!vertices.is_allocated(v)) {
+            continue;
+        }
+
+        mesh.vertex_read_coordinate(scratch, 0, v);
+
+        if (!Number.isFinite(scratch[0]) || !Number.isFinite(scratch[1]) || !Number.isFinite(scratch[2])) {
+            record(out, BT_DEFECT.NON_FINITE_VALUE, BT_ELEMENT_TYPE.VERTEX, v,
+                `vertex ${v} coordinate is (${scratch[0]}, ${scratch[1]}, ${scratch[2]})`);
+        }
+    }
+
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+
+        mesh.face_read_normal(scratch, 0, f);
+
+        if (!Number.isFinite(scratch[0]) || !Number.isFinite(scratch[1]) || !Number.isFinite(scratch[2])) {
+            record(out, BT_DEFECT.NON_FINITE_VALUE, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} normal is (${scratch[0]}, ${scratch[1]}, ${scratch[2]})`);
+        }
+    }
+}
+
+/**
+ * Check every structural invariant of a {@link BinaryTopology} and return the
+ * defects found. An empty result means the mesh is internally consistent: every
+ * handle resolves, every disk / radial / face-loop cycle is a closed
+ * doubly-linked ring, every element agrees with the elements that reference it,
+ * and every stored coordinate is finite.
+ *
+ * This is the counterpart to manifold's `IsManifold()` -- the invariant checker
+ * that makes a pile of topology-surgery primitives trustworthy. `BinaryTopology`
+ * has ~40 mutators (`bt_edge_collapse`, `bt_vert_splice`, `bt_radial_loop_remove`,
+ * `bt_face_poke`, ...), each of which can scribble a cycle; without this, nothing
+ * notices until a much later operation reads garbage. Run it in specs after any
+ * mutation, and in prototypes after any pipeline stage.
+ *
+ * What it deliberately does NOT check, because `BinaryTopology` permits all of
+ * them by design: wire edges (no incident face), boundary edges (one face),
+ * non-manifold edges (three or more faces), n-gon faces, disconnected islands.
+ * For those, see {@link bt_mesh_is_manifold} and {@link bt_mesh_is_closed}.
+ *
+ * O(V + E + L + F) except for the repeated-vertex check, which is quadratic in a
+ * single face's corner count (faces are small; a 1000-gon would be the anomaly,
+ * not the cost).
+ *
+ * Cycle walks are bounded by the corresponding pool's size. That bound is the
+ * theoretical maximum of a legal cycle, so hitting it is itself a defect and is
+ * reported as {@link BT_DEFECT.CYCLE_NOT_CLOSED} rather than swallowed.
+ *
+ * @param {BinaryTopology} mesh
+ * @returns {{code:number, element_type:number, element:number, detail:string}[]}
+ *     defects found, in discovery order; empty when the mesh is consistent
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_mesh_validate(mesh) {
+    const out = [];
+
+    check_references(mesh, out);
+    check_disk_cycles(mesh, out);
+    check_radial_cycles(mesh, out);
+    check_face_cycles(mesh, out);
+    check_finite_values(mesh, out);
+
+    return out;
+}

package/src/core/geom/3d/topology/util/mesh_flood_fill.d.ts

@@ -1,7 +1,7 @@
 /**
  *
  * @param {TopoTriangle[]} initial_set indices of triangles that make up initial set, these are triangles that we start from, they will also be included in the resulting set
- * @param {function(tri:TopoTriangle, prev:TopoTriangle):boolean} filter decides whether a triangle should be included or not
+ * @param {(tri: TopoTriangle, prev: TopoTriangle) => boolean} filter decides whether a triangle should be included or not
  * @returns {TopoTriangle[]} set of selected triangles, will include initial set as well
  */
 export function mesh_flood_fill({ initial_set, filter }: TopoTriangle[]): TopoTriangle[];

package/src/core/geom/3d/topology/util/mesh_flood_fill.js

@@ -9,7 +9,7 @@ const neighbours = [];
 /**
  *
  * @param {TopoTriangle[]} initial_set indices of triangles that make up initial set, these are triangles that we start from, they will also be included in the resulting set
- * @param {function(tri:TopoTriangle, prev:TopoTriangle):boolean} filter decides whether a triangle should be included or not
+ * @param {(tri: TopoTriangle, prev: TopoTriangle) => boolean} filter decides whether a triangle should be included or not
  * @returns {TopoTriangle[]} set of selected triangles, will include initial set as well
  */
 export function mesh_flood_fill({

package/src/core/geom/3d/triangle/tri3_compute_signed_volume.d.ts

@@ -1,6 +1,38 @@
 /**
  * Compute signed volume of a tetrahedron with the last point at the origin
  * Triangle is defined by points A,B,C
+ *
+ * Evaluated as `p · ((q - p) × (r - p))` where `(p, q, r)` is the cyclic
+ * rotation of `(a, b, c)` that puts the vertex nearest the origin first. Both
+ * steps are exact rewrites of `a · (b × c)`: a cyclic rotation leaves a 3×3
+ * determinant unchanged, and the two extra terms the edge form introduces,
+ * `p · (q × p)` and `p · (p × r)`, are identically zero.
+ *
+ * The rotation is not cosmetic — the two forms fail in opposite regimes, and
+ * picking the apex is what makes the result well conditioned in both. The
+ * error behaves like `eps · |p| · |q - p| · |r - p|`:
+ *
+ *   - the expanded determinant of absolute coordinates loses everything for a
+ *     SMALL triangle FAR from the origin. Summed over a unit cube translated to
+ *     (1e6, 1e6, 1e6) it returned 256, and −262144 at 1e7;
+ *   - anchoring unconditionally on `a` instead loses everything for a LARGE
+ *     triangle reaching IN toward the origin, where `|b - a|` and `|c - a|` are
+ *     both as large as `|a|`. `(1e8, 1e8, 1e8), (1, 0, 0), (0, 1, 0)` returned
+ *     0 for a true volume of 16666666.67, and flipped the sign of a needle
+ *     tetrahedron often enough to break callers using this as an orientation
+ *     predicate.
+ *
+ * Anchoring on the vertex nearest the origin is exact in both, and measured at
+ * a worst relative error of 8e-13 over 400k triangles with each vertex drawn
+ * from an independent magnitude decade up to 1e9.
+ *
+ * Distance is compared by largest absolute component rather than by squared
+ * length, which is cheaper and cannot overflow for coordinates above ~1e154.
+ *
+ * A caller summing over a whole mesh should still subtract a reference point,
+ * as {@link tri3_mesh_compute_signed_volume} does: this conditions each term,
+ * but only the caller can stop the terms themselves from being enormous.
+ *
  * @see "EFFICIENT FEATURE EXTRACTION FOR 2D/3D OBJECTS IN MESH REPRESENTATION" by Cha Zhang and Tsuhan Chen
  * @param {number} ax
  * @param {number} ay

package/src/core/geom/3d/triangle/tri3_compute_signed_volume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tri3_compute_signed_volume.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/triangle/tri3_compute_signed_volume.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,+CAXW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAiBjB"}
+{"version":3,"file":"tri3_compute_signed_volume.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/triangle/tri3_compute_signed_volume.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,+CAXW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CA4CjB"}