@woosh/meep-engine 3.29.0 → 3.30.0

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js

@@ -9,6 +9,7 @@ import { quadric_attribute_reduce } from "../../../../quadric/quadric_attribute_
 import { quadric_attribute_size } from "../../../../quadric/quadric_attribute_size.js";
 import { quadric_attribute_solve } from "../../../../quadric/quadric_attribute_solve.js";
 import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_edge_collapse_fold_limit } from "../query/bt_edge_collapse_fold_limit.js";
 import { bt_edge_collapse_would_fold } from "../query/bt_edge_collapse_would_fold.js";
 import { bt_loop_kill } from "./bt_loop_kill.js";
 import { bt_mesh_compute_vertex_quadrics } from "./bt_mesh_compute_vertex_quadrics.js";
@@ -24,6 +25,28 @@ const scratch_coord_a = new Float32Array(3);
 const scratch_coord_b = new Float32Array(3);
 const scratch_target = new Float32Array(3);
 const scratch_combined_q = new Quadric3();
+const scratch_anchor = new Float32Array(3);
+const scratch_candidate = new Float32Array(3);
+const scratch_placement = new Float32Array(3);
+
+/**
+ * How much of the way to the fold limit a constrained placement is allowed to travel.
+ *
+ * The limit itself is where a surviving triangle reaches *zero* area, which is refused along with an
+ * outright flip and for the same reason: a zero-area triangle has no normal, so the quadrics built
+ * from it afterwards are meaningless and every later collapse around it is priced off nothing. So
+ * stopping short of the limit is a statement about the mesh rather than about arithmetic.
+ *
+ * Half, because the feasible interval along the segment is `[0, limit)` and its midpoint is the
+ * placement furthest from both ends of it — from the anchor, which is the placement this was trying
+ * to improve on, and from the degeneracy. Nothing is given up by stopping there: swept against 0.9
+ * and 0.99 over Zorah's 479k-triangle `mesh0[0]`, all three build the *same* 34 levels to the *same*
+ * root error of `1.0445e+3`, and differ only in cluster count, by 0.3% and in no particular
+ * direction (11,511 / 11,498 / 11,532). The choice is free on everything that was measured, so it
+ * goes to the end that cannot produce a sliver.
+ * @type {number}
+ */
+const FOLD_LIMIT_TRAVEL = 0.5;
 
 /**
  * The pair's summed attribute quadric, and its reduction. Grown to whatever channel count the
@@ -104,6 +127,143 @@ function count_edge_faces(mesh, edge_id) {
     return count;
 }
 
+/**
+ * What a collapse of this pair costs with its surviving vertex at `(x, y, z)`.
+ *
+ * The two geometric quadrics say how far the placement is from the surface the pair was cut out of;
+ * the reduced attribute quadric, when there is one, says what the channels still cost once each has
+ * been given its best value there — in units of length, because the weights put them there.
+ *
+ * It is exactly the function the placement minimizes — quadric evaluation is linear in the quadric,
+ * so the sum `optimize` was handed evaluates to the sum of the two terms below — which is why
+ * constraining the placement can only ever raise this, never lower it. Read at the placement
+ * actually chosen, so the queue's order is a statement about the collapses that will happen rather
+ * than about ones that will not.
+ *
+ * @param {Quadric3} q1
+ * @param {Quadric3} q2
+ * @param {boolean} has_attributes whether {@link scratch_attribute_reduced} holds this pair's
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
+function placement_cost(q1, q2, has_attributes, x, y, z) {
+    // Cost can drift slightly negative for near-zero values due to fp noise.
+    const geometric = Math.abs(q1.evaluate(x, y, z) + q2.evaluate(x, y, z));
+
+    if (!has_attributes) {
+        return geometric;
+    }
+
+    return geometric + Math.abs(quadric3_evaluate(scratch_attribute_reduced, 0, x, y, z));
+}
+
+/**
+ * Move `out_target` to the cheapest placement near it that turns no surviving triangle over, or
+ * report that the pair has none.
+ *
+ * **A placement that folds is not an impossible collapse, and this is where the two stop being
+ * conflated.** What the quadric hands back is the unconstrained minimum of a convex cost. Keeping
+ * every surviving triangle facing the way it did is a *constraint* on that minimum — a linear one,
+ * as {@link bt_edge_collapse_fold_limit} derives, so the placements that satisfy it are a convex set
+ * and the constrained minimum is the thing this should be choosing. Testing the unconstrained
+ * answer and abandoning the collapse when it fails is the classic way of getting that wrong, and it
+ * is expensive: measured over one 479k-triangle Zorah primitive, 12% to 15% of every candidate
+ * collapse scored was discarded that way — and it is not a tail, it is the whole build, which is how
+ * a level of the DAG that could still have been halved came to be reported as having no coarser
+ * form at all.
+ *
+ * The constrained minimum lies on the boundary whenever the unconstrained one is outside, and the
+ * boundary is reached along a segment: the cost is convex with its minimum at `out_target`, so along
+ * a segment ending there it falls monotonically, and the best placement on that segment is simply
+ * the furthest one the fold limit allows. That makes this exact in one dimension rather than a
+ * search — what is heuristic is only the choice of where to measure *from*.
+ *
+ * Three anchors, and they are the three points the surface already passes through: either endpoint,
+ * or the middle of the edge. An anchor that folds on its own is no anchor and is skipped; when all
+ * three do, the pair really has nothing this can offer and the collapse is refused.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} v1
+ * @param {number} v2
+ * @param {Quadric3} q1
+ * @param {Quadric3} q2
+ * @param {boolean} has_attributes
+ * @param {Float32Array|number[]} out_target the wanted placement, replaced by the chosen one
+ * @returns {boolean} `false` when every anchor folds, and the collapse has no placement at all
+ */
+function constrain_placement(mesh, v1, v2, q1, q2, has_attributes, out_target) {
+    if (!bt_edge_collapse_would_fold(mesh, v1, v2, out_target)) {
+        return true;
+    }
+
+    mesh.vertex_read_coordinate(scratch_coord_a, 0, v1);
+    mesh.vertex_read_coordinate(scratch_coord_b, 0, v2);
+
+    // Tracked separately rather than read off `best`, which cannot say the difference between "no
+    // anchor held" and "one did, at a price that overflowed" — a quadric carrying the planes of a
+    // few hundred thousand source triangles is not far off it.
+    let placed = false;
+
+    let best = Number.POSITIVE_INFINITY;
+
+    for (let anchor = 0; anchor < 3; anchor++) {
+        if (anchor === 0) {
+            scratch_anchor.set(scratch_coord_a);
+        } else if (anchor === 1) {
+            scratch_anchor.set(scratch_coord_b);
+        } else {
+            scratch_anchor[0] = (scratch_coord_a[0] + scratch_coord_b[0]) * 0.5;
+            scratch_anchor[1] = (scratch_coord_a[1] + scratch_coord_b[1]) * 0.5;
+            scratch_anchor[2] = (scratch_coord_a[2] + scratch_coord_b[2]) * 0.5;
+        }
+
+        const limit = bt_edge_collapse_fold_limit(mesh, v1, v2, scratch_anchor, out_target);
+
+        if (limit < 0) {
+            continue;
+        }
+
+        const travel = limit * FOLD_LIMIT_TRAVEL;
+
+        scratch_candidate[0] = scratch_anchor[0] + (out_target[0] - scratch_anchor[0]) * travel;
+        scratch_candidate[1] = scratch_anchor[1] + (out_target[1] - scratch_anchor[1]) * travel;
+        scratch_candidate[2] = scratch_anchor[2] + (out_target[2] - scratch_anchor[2]) * travel;
+
+        if (bt_edge_collapse_would_fold(mesh, v1, v2, scratch_candidate)) {
+            /*
+             The limit is exact in real arithmetic and this is not real arithmetic: a fan whose
+             triangles are already slivers can put the crossing and the anchor within a few ulps of
+             each other, and half of nothing is still nothing. The anchor is feasible by
+             construction, so fall back to it rather than to a search for how much less to travel.
+            */
+            scratch_candidate.set(scratch_anchor);
+        }
+
+        const cost = placement_cost(
+            q1, q2, has_attributes,
+            scratch_candidate[0], scratch_candidate[1], scratch_candidate[2]
+        );
+
+        if (!placed || cost < best) {
+            placed = true;
+            best = cost;
+            scratch_placement.set(scratch_candidate);
+        }
+    }
+
+    if (!placed) {
+        return false;
+    }
+
+    out_target[0] = scratch_placement[0];
+    out_target[1] = scratch_placement[1];
+    out_target[2] = scratch_placement[2];
+
+    return true;
+}
+
 /**
  * Evaluate a potential edge collapse: choose the optimal surviving vertex position
  * and return the quadric-based cost. Returns Infinity if the edge cannot be collapsed.
@@ -116,7 +276,9 @@ function count_edge_faces(mesh, edge_id) {
  *     attributes the channels the collapse carries, or `null` to carry none
  * @param {BtWedgeSet|null} wedges which corners of each vertex shade as one
  * @param {Float32Array|number[]} out_target Target position is written here.
- * @returns {number}
+ * @returns {number} the price at the placement written, which is the placement the collapse would
+ *     actually use — so the queue this feeds is ordered on what the collapses cost rather than on
+ *     what they would have cost somewhere they are not allowed to go
  */
 function evaluate_edge_collapse(
     mesh, edge_id, quadratics, restricted_vertices, attributes, wedges, out_target
@@ -146,9 +308,9 @@ function evaluate_edge_collapse(
         return Number.POSITIVE_INFINITY;
     }
 
-    let attribute_cost = 0;
+    const has_attributes = attributes !== null;
 
-    if (attributes !== null) {
+    if (has_attributes) {
         reduce_pair_attributes(mesh, v1, v2, attributes, wedges, scratch_attribute_reduced);
     }
 
@@ -160,7 +322,7 @@ function evaluate_edge_collapse(
         scratch_combined_q.copy(q1);
         scratch_combined_q.add(q2);
 
-        if (attributes !== null) {
+        if (has_attributes) {
             /*
              The channels decide where the vertex goes, and this is where they do it. `A` and `b` of
              the reduced attribute quadric are what is left of them after the exact solve for their
@@ -187,24 +349,34 @@ function evaluate_edge_collapse(
         }
     }
 
-    const tx = out_target[0];
-    const ty = out_target[1];
-    const tz = out_target[2];
-
-    if (attributes !== null) {
-        // What the channels still cost once each has been given its best value at this position --
-        // in units of length, because the weights put them there.
-        attribute_cost = Math.abs(quadric3_evaluate(scratch_attribute_reduced, 0, tx, ty, tz));
+    if (v1_restricted || v2_restricted) {
+        /*
+         A pin takes the placement with it, so there is no segment to slide along and a fold here is
+         final. Refused with the price rather than by the caller, so the queue never holds an edge
+         whose cost describes a collapse that will not be performed.
+        */
+        if (bt_edge_collapse_would_fold(mesh, v1, v2, out_target)) {
+            return Number.POSITIVE_INFINITY;
+        }
+    } else if (!constrain_placement(mesh, v1, v2, q1, q2, has_attributes, out_target)) {
+        return Number.POSITIVE_INFINITY;
     }
 
-    // Cost can drift slightly negative for near-zero values due to fp noise.
-    return Math.abs(q1.evaluate(tx, ty, tz) + q2.evaluate(tx, ty, tz)) + attribute_cost;
+    return placement_cost(
+        q1, q2, has_attributes, out_target[0], out_target[1], out_target[2]
+    );
 }
 
 /**
  * Re-score every edge in the disk cycle of `survivor` that is currently in the heap.
  * Edges that were never inserted (e.g. both endpoints restricted) are left untouched.
  *
+ * Left untouched including the ones that were left out because they had no placement at the time,
+ * which is a real limit and a deliberate one: an edge is excluded when *both* its fans leave it
+ * nowhere to go, and a collapse one edge away is unlikely to change that. Re-admitting them here was
+ * built and measured — it moved a 479k-triangle Zorah primitive from 34 levels to 33, and cost 60%
+ * of the build time to do it.
+ *
  * @param {BinaryTopology} mesh
  * @param {number} survivor
  * @param {Quadric3[]} quadratics
@@ -818,9 +990,24 @@ function collapse_kills_protected_face(mesh, edge_id, protected_faces) {
  * removed. If the target cannot be reached (e.g. too many restricted vertices),
  * simplification stops early without failing.
  *
- * A collapse that would turn a surviving triangle inside out is refused however cheap the quadric
- * says it is ({@link bt_edge_collapse_would_fold}) -- the quadric cannot see a fold, because a flat
- * region scores zero for every placement in its plane.
+ * No collapse ever turns a surviving triangle inside out, and the quadric cannot help with that: it
+ * cannot see a fold at all, because a flat region scores zero for every placement in its plane. So
+ * the placement is *constrained* rather than merely checked. Where the quadric's own answer folds,
+ * the collapse is re-placed at the best point that does not — see {@link constrain_placement}, and
+ * {@link bt_edge_collapse_fold_limit} for why that point can be found exactly instead of hunted for.
+ * A collapse is refused only when the pair has no such placement anywhere, which is a statement
+ * about the geometry rather than about the quadric's preference.
+ *
+ * Every edge is priced at the placement it would actually use, including the constrained ones, and
+ * the queue is ordered on that. It is the expensive way round — the constraint costs a walk of both
+ * the pair's fans, and pricing happens once per edge at the start and again for every neighbour of
+ * every collapse, which measures at 1.4x to 2.5x the build time of the alternative. The alternative
+ * is to order on the unconstrained price, which is a genuine lower bound ({@link placement_cost}),
+ * and settle only on the way out of the queue. That was built and measured, and it is not here: the
+ * greedy order it produces is approximate, and on a pinwheel whose whole rim is pinned it stopped at
+ * 28 faces against a target of 21 — which is precisely the shape a vgeo group step hands this, since
+ * such a step pins its entire outer boundary. A cheaper order that cannot finish a pinned
+ * simplification is no bargain.
  *
  * **Topology is not preserved**, and cannot be here. The other standard guard, the *link condition*
  * ({@link bt_edge_collapse_breaks_link_condition}), refuses collapses that weld together two parts
@@ -836,21 +1023,36 @@ function collapse_kills_protected_face(mesh, edge_id, protected_faces) {
  * At the end of the call the mesh is cleaned up so that no dangling loops, edges,
  * or vertices remain in the topology.
  *
- * The return value is the **object-space distance** the surface moved: the largest, over every
- * vertex, of that vertex's accumulated quadric evaluated where the vertex ended up, normalized by
- * the quadric's weight. Because a survivor inherits its victim's quadric, this measures deviation
- * from the mesh as it stood when the call began — not merely from the step before.
+ * The return value is the **object-space distance** the surface moved: the largest reading taken at
+ * any collapse the call performed, a collapse being read by evaluating *each* of its two endpoints'
+ * accumulated quadrics at the placement the survivor is about to take, each normalized by its own
+ * weight. Because a survivor inherits its victim's quadric, every such reading is a deviation from
+ * the mesh as it stood when the call began — not merely from the step before.
+ *
+ * **At the collapses, and per endpoint, and both of those are what keep it from diluting.** The
+ * weight is what makes the value a length ({@link Quadric3#distance}) and it is also a divisor that
+ * grows every time a vertex absorbs another. A vertex that flattens a spike and then spends the rest
+ * of the call swallowing the plane around it ends up standing mostly for planes it sits exactly on,
+ * and a single reading taken at the end divides the spike it destroyed by all of them — measured on
+ * a unit spike at the centre of a pinned grid, the same spike came back at 0.64 on a 7-vertex grid
+ * and at 0.040 on a 33-vertex one, which is the reported error falling as the surface grows.
+ * Reading at every collapse catches the spike while the quadric is still mostly about it. Reading
+ * the two endpoints apart rather than summed stops a small victim's residual being averaged into a
+ * large survivor's untouched history, which is that same dilution one collapse at a time.
  *
- * It is taken *before* faceless vertices are cleaned away, and that is not an implementation detail.
- * A patch that is consumed entirely leaves a vertex behind that belongs to no face; that vertex is
- * the only thing still holding the quadric of everything that used to be there, and reading the mesh
- * after cleanup would find no trace of it. A soup of separate triangles simplifies by *deleting*
- * them, and measuring survivors alone reports the deletion of ninety per cent of a model as costing
- * nothing at all.
+ * Nothing is given up by no longer scanning the survivors, and it is a domination rather than a
+ * coincidence. What the scan would read off a survivor is its *merged* quadric at the placement its
+ * last collapse chose — and a merged quadric's reading is the weight-weighted mean of its two parts'
+ * readings at that same point, so it can never exceed the larger of the two this already took there.
+ * Every value the scan could report is therefore one this maximum has seen or beaten, and the
+ * maximum holds the earlier and sharper readings besides. A patch consumed entirely, which leaves
+ * behind a faceless vertex that the cleanup then sweeps, is read at the collapse that consumed it
+ * instead of in the window between the last collapse and the sweep.
  *
- * A caller that needs deviation from something *older* than this call's input — a mesh several
- * simplification passes back — supplies its own quadrics through
- * {@link bt_mesh_simplify_with_quadrics} and keeps them across passes.
+ * So what comes back is what *this call's* collapses cost. A caller carrying quadrics across calls
+ * through {@link bt_mesh_simplify_with_quadrics} carries the maximum across them too — and the
+ * deviation a vertex arrives already carrying is, by construction, a reading that the call which
+ * placed it there has already returned.
  *
  * `protected_faces` names faces that must still be there when the call returns. Pinning vertices
  * does not by itself protect the *edges* between them: a collapse elsewhere in the fan can take away
@@ -974,6 +1176,14 @@ export function bt_mesh_simplify_with_quadrics(
     // Tracked from here on rather than re-counted, so progress costs nothing per iteration.
     let current_face_count = face_pool.count();
 
+    /**
+     * The largest object-space distance any collapse so far has put the surface from the one the
+     * quadrics remember. See {@link bt_mesh_simplify} for why it is a running maximum over the
+     * collapses rather than one sweep of the survivors at the end.
+     * @type {number}
+     */
+    let deviation = 0;
+
     if (current_face_count <= target_face_count) {
         return 0;
     }
@@ -1066,14 +1276,16 @@ export function bt_mesh_simplify_with_quadrics(
             continue;
         }
 
-        // `evaluate_edge_collapse` has just written the placement into `scratch_target`, which is
-        // what this needs and why it is tested here rather than beside the link condition above.
-        // Quadric cost is blind to the fold: a flat region scores zero for every placement in its
-        // plane, so nothing in the price stops a one-ring that is not star-shaped about the target
-        // from turning inside out.
-        if (bt_edge_collapse_would_fold(mesh, v1, v2, scratch_target)) {
-            continue;
-        }
+        /*
+         An invariant now, not a filter. `evaluate_edge_collapse` has just written the placement
+         into `scratch_target`, and it returns a finite price only for a placement it has itself
+         confirmed folds nothing -- so a fold reaching this point is this file being wrong, which is
+         what an assertion is for and what a `continue` would have hidden.
+        */
+        assert.notOk(
+            bt_edge_collapse_would_fold(mesh, v1, v2, scratch_target),
+            'the placement a finite collapse price was quoted for must not fold'
+        );
 
         const face_deaths = count_edge_faces(mesh, edge_id);
 
@@ -1086,6 +1298,18 @@ export function bt_mesh_simplify_with_quadrics(
         const pre_survivor = mesh.edge_read_vertex1(edge_id);
         const pre_victim = mesh.edge_read_vertex2(edge_id);
 
+        const target_x = scratch_target[0];
+        const target_y = scratch_target[1];
+        const target_z = scratch_target[2];
+
+        // Priced before the accumulation below, which is the merge that would dilute it, and each
+        // endpoint against its own weight for the same reason.
+        deviation = Math.max(
+            deviation,
+            quadratics[pre_survivor].distance(target_x, target_y, target_z),
+            quadratics[pre_victim].distance(target_x, target_y, target_z)
+        );
+
         // Before the accumulation below, which is what makes the blend fallback weigh the two
         // endpoints' own histories rather than the survivor's already carrying the victim's. And
         // before the topology mutates, which is what lets the faces about to die say which corners
@@ -1125,11 +1349,6 @@ export function bt_mesh_simplify_with_quadrics(
         );
     }
 
-    // Measured here, before the cleanup below, because a vertex left behind by a patch that was
-    // consumed whole is faceless and about to be removed — and it is the only thing still carrying
-    // the quadric of the geometry that used to be there.
-    const deviation = measure_deviation(mesh, quadratics);
-
     // Drop any loose loops/edges/verts produced during collapses, preserving
     // restricted vertices even if they ended up isolated.
     cleanup_faceless_preserving_restricted(mesh, restricted_vertices);
@@ -1137,33 +1356,6 @@ export function bt_mesh_simplify_with_quadrics(
     return deviation;
 }
 
-/**
- * The largest distance any vertex now sits from the surface its quadric remembers.
- *
- * @param {BinaryTopology} mesh
- * @param {Quadric3[]} quadratics
- * @returns {number}
- */
-function measure_deviation(mesh, quadratics) {
-    const vertex_pool = mesh.vertices;
-
-    let result = 0;
-
-    for (let v = 0; v < vertex_pool.size; v++) {
-        if (!vertex_pool.is_allocated(v) || quadratics[v] === null || quadratics[v] === undefined) {
-            continue;
-        }
-
-        mesh.vertex_read_coordinate(scratch_coord_a, 0, v);
-
-        result = Math.max(
-            result, quadratics[v].distance(scratch_coord_a[0], scratch_coord_a[1], scratch_coord_a[2])
-        );
-    }
-
-    return result;
-}
-
 /**
  * Variant of bt_mesh_cleanup_faceless_references that never releases a restricted
  * vertex even when it has no remaining edges.

package/src/core/geom/3d/topology/struct/binary/query/bt_edge_collapse_fold_limit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * How far from `from` toward `to` may a collapse of `survivor`-`victim` place the surviving vertex
+ * and still turn no surviving triangle over?
+ *
+ * Both fans are walked, because both endpoints move: the victim onto the placement by definition,
+ * and the survivor too wherever the caller puts it somewhere other than where it already sits. The
+ * union of the two is the set of faces the collapse reshapes, which is what makes the answer
+ * symmetric in the two endpoints -- a caller that has not yet settled which of them survives can
+ * rely on that.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} survivor the endpoint that stays allocated
+ * @param {number} victim the endpoint that is removed
+ * @param {Float32Array|number[]} from the placement to measure from, at `t = 0`
+ * @param {Float32Array|number[]} to the placement wanted, at `t = 1`
+ * @param {number} [from_offset]
+ * @param {number} [to_offset]
+ * @returns {number} where the first surviving triangle reaches **zero** area, so the placements that
+ *     fold nothing are `t` in `[0, limit)` -- open at the top, since zero area is refused along with
+ *     a flip, and a caller therefore takes a fraction of this rather than this. `1` when nothing on
+ *     the segment folds, and `-1` when `from` itself does, which is the one answer no amount of
+ *     sliding recovers from.
+ */
+export function bt_edge_collapse_fold_limit(mesh: BinaryTopology, survivor: number, victim: number, from: Float32Array | number[], to: Float32Array | number[], from_offset?: number, to_offset?: number): number;
+//# sourceMappingURL=bt_edge_collapse_fold_limit.d.ts.map

package/src/core/geom/3d/topology/struct/binary/query/bt_edge_collapse_fold_limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_edge_collapse_fold_limit.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/query/bt_edge_collapse_fold_limit.js"],"names":[],"mappings":"AA4LA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4EAZW,MAAM,UACN,MAAM,QACN,YAAY,GAAC,MAAM,EAAE,MACrB,YAAY,GAAC,MAAM,EAAE,gBACrB,MAAM,cACN,MAAM,GACJ,MAAM,CAsBlB"}