@woosh/meep-engine 3.29.0 → 3.31.0

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

@@ -1,5 +1,6 @@
+import { bt_edge_count_faces } from "../query/bt_edge_count_faces.js";
 import { assert } from "../../../../../../assert.js";
-import { Uint32Heap } from "../../../../../../collection/heap/Uint32Heap.js";
+import { IndexedFloatMinHeap } from "../../../../../../collection/heap/IndexedFloatMinHeap.js";
 import { Quadric3 } from "../../../../quadric/Quadric3.js";
 import { QUADRIC3_SIZE } from "../../../../quadric/QUADRIC3_SIZE.js";
 import { quadric3_add } from "../../../../quadric/quadric3_add.js";
@@ -8,7 +9,9 @@ import { quadric_attribute_add } from "../../../../quadric/quadric_attribute_add
 import { quadric_attribute_reduce } from "../../../../quadric/quadric_attribute_reduce.js";
 import { quadric_attribute_size } from "../../../../quadric/quadric_attribute_size.js";
 import { quadric_attribute_solve } from "../../../../quadric/quadric_attribute_solve.js";
+import { tri3_closest_point } from "../../../../triangle/tri3_closest_point.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 +27,55 @@ 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);
+const scratch_old_survivor = new Float32Array(3);
+const scratch_old_victim = new Float32Array(3);
+const scratch_fan_a = new Float32Array(3);
+const scratch_fan_b = new Float32Array(3);
+const scratch_fan_c = new Float32Array(3);
+const scratch_closest = new Float64Array(3);
+
+/**
+ * How near a point has to be to a triangle before it counts as sitting *on* it, as a fraction of the
+ * coordinates involved.
+ *
+ * Vertex coordinates are stored as `float32`, so twenty-four bits of mantissa is all the mesh can
+ * say about where its own surface is, and {@link tri3_closest_point} spends a few of them on the two
+ * divisions its barycentric solve takes. Below that, a reported distance is not a measurement of the
+ * geometry, it is a measurement of the storage — and it cannot be allowed through, because a flat
+ * surface has to report **exactly** zero. Not nearly zero: the cut has an explicit zero-error case
+ * (`project((s, 0)) === 0`), and the camera-inside-sphere rule that sends a cluster to `+Infinity`
+ * is conditioned on `r_e > 0`. A flat cluster carrying `1.6e-14` takes the second path and becomes
+ * undrawable at close range, which is the exact bug that convention exists to prevent.
+ *
+ * `2^-20` rather than `2^-24`, leaving the four bits the solve can lose. On a ten-unit mesh that is
+ * a distance of about `1e-5`, some three orders below anything a pixel threshold can see.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ON_THE_SURFACE = 2 ** -20;
+
+/**
+ * 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
@@ -71,37 +123,250 @@ let scratch_dying_loops = new Uint32Array(8);
 let scratch_attribute_values = new Float64Array(0);
 
 /**
- * Count the number of still-live faces attached to an edge via its radial loop cycle.
- * Orphan loops (whose face was already killed by a prior collapse) are skipped so
- * that callers tracking running face totals don't double-decrement.
+ * How far `point` sits from the surface still attached to `vertex` — the closest point on any
+ * triangle in its one-ring.
+ *
+ * Every face is visited twice, once per incident edge, and that is left alone: deduplicating means a
+ * set per collapse, and a one-ring is a dozen triangles.
  *
  * @param {BinaryTopology} mesh
- * @param {number} edge_id
- * @returns {number}
+ * @param {number} vertex
+ * @param {ArrayLike<number>} point
+ * @returns {number} the distance, or `-1` where the vertex has no surface left at all
  */
-function count_edge_faces(mesh, edge_id) {
-    const l0 = mesh.edge_read_loop(edge_id);
+function distance_to_vertex_fan(mesh, vertex, point) {
+    let edge = mesh.vertex_read_edge(vertex);
 
-    if (l0 === NULL_POINTER) {
-        return 0;
+    if (edge === NULL_POINTER) {
+        return -1;
     }
 
     const face_pool = mesh.faces;
 
-    let count = 0;
-    let l = l0;
+    const start_edge = edge;
+
+    let nearest_sqr = Number.POSITIVE_INFINITY;
+
+    // What the coordinates in play are worth, for {@link ON_THE_SURFACE} below. Float32 loses
+    // precision in proportion to magnitude, so the threshold has to be stated against the geometry
+    // rather than as a distance.
+    let scale_sqr = point[0] * point[0] + point[1] * point[1] + point[2] * point[2];
 
     do {
-        const f = mesh.loop_read_face(l);
+        const first_loop = mesh.edge_read_loop(edge);
+
+        let loop = first_loop;
+
+        while (loop !== NULL_POINTER) {
+            const face = mesh.loop_read_face(loop);
+
+            if (face !== NULL_POINTER && face_pool.is_allocated(face)) {
+                const la = mesh.face_read_loop(face);
+                const lb = mesh.loop_read_next(la);
+                const lc = mesh.loop_read_next(lb);
+
+                if (mesh.loop_read_next(lc) === la) {
+                    mesh.vertex_read_coordinate(scratch_fan_a, 0, mesh.loop_read_vertex(la));
+                    mesh.vertex_read_coordinate(scratch_fan_b, 0, mesh.loop_read_vertex(lb));
+                    mesh.vertex_read_coordinate(scratch_fan_c, 0, mesh.loop_read_vertex(lc));
+
+                    scale_sqr = Math.max(
+                        scale_sqr,
+                        scratch_fan_a[0] * scratch_fan_a[0]
+                            + scratch_fan_a[1] * scratch_fan_a[1]
+                            + scratch_fan_a[2] * scratch_fan_a[2],
+                        scratch_fan_b[0] * scratch_fan_b[0]
+                            + scratch_fan_b[1] * scratch_fan_b[1]
+                            + scratch_fan_b[2] * scratch_fan_b[2],
+                        scratch_fan_c[0] * scratch_fan_c[0]
+                            + scratch_fan_c[1] * scratch_fan_c[1]
+                            + scratch_fan_c[2] * scratch_fan_c[2]
+                    );
+
+                    nearest_sqr = Math.min(nearest_sqr, tri3_closest_point(
+                        scratch_closest, 0,
+                        point[0], point[1], point[2],
+                        scratch_fan_a[0], scratch_fan_a[1], scratch_fan_a[2],
+                        scratch_fan_b[0], scratch_fan_b[1], scratch_fan_b[2],
+                        scratch_fan_c[0], scratch_fan_c[1], scratch_fan_c[2]
+                    ));
+                }
+            }
+
+            loop = mesh.loop_read_radial_next(loop);
 
-        if (f !== NULL_POINTER && face_pool.is_allocated(f)) {
-            count++;
+            if (loop === first_loop) {
+                break;
+            }
         }
 
-        l = mesh.loop_read_radial_next(l);
-    } while (l !== l0 && l !== NULL_POINTER);
+        edge = mesh.edge_read_vertex1(edge) === vertex
+            ? mesh.edge_read_v1_disk_next(edge)
+            : mesh.edge_read_v2_disk_next(edge);
+    } while (edge !== start_edge && edge !== NULL_POINTER);
+
+    if (nearest_sqr === Number.POSITIVE_INFINITY) {
+        return -1;
+    }
 
-    return count;
+    if (nearest_sqr <= scale_sqr * ON_THE_SURFACE * ON_THE_SURFACE) {
+        return 0;
+    }
+
+    return Math.sqrt(nearest_sqr);
+}
+
+/**
+ * Distance from the point `from` holds to `(x, y, z)`.
+ *
+ * @param {ArrayLike<number>} from
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
+function distance_from(from, x, y, z) {
+    const dx = x - from[0];
+    const dy = y - from[1];
+    const dz = z - from[2];
+
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+ * 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;
 }
 
 /**
@@ -116,7 +381,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 +413,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 +427,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,31 +454,41 @@ 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
  * @param {Set<number>} restricted_vertices
  * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}|null} attributes
  * @param {BtWedgeSet|null} wedges
- * @param {Uint32Heap} heap
+ * @param {IndexedFloatMinHeap} heap
  */
 function update_neighbor_costs(
     mesh, survivor, quadratics, restricted_vertices, attributes, wedges, heap
@@ -234,14 +511,14 @@ function update_neighbor_costs(
             next_e = mesh.edge_read_v2_disk_next(curr_e);
         }
 
-        const idx = heap.find_index_by_id(curr_e);
-
-        if (idx !== -1) {
+        // `contains` asserts the id against the queue's own index length, which is the check the
+        // keyed lookup actually needs -- a collapse only ever kills edges, so it cannot fail.
+        if (heap.contains(curr_e)) {
             const cost = evaluate_edge_collapse(
                 mesh, curr_e, quadratics, restricted_vertices, attributes, wedges, scratch_target
             );
 
-            heap.__update_score_by_index(idx, cost);
+            heap.update(curr_e, cost);
         }
 
         curr_e = next_e;
@@ -818,9 +1095,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 +1128,50 @@ 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 an **upper bound, in object-space distance, on how far the surface moved** —
+ * not an estimate of it. That distinction is the whole job: the runtime divides this number by the
+ * camera distance and calls the result pixels of error, so wherever it reads low the cut draws a
+ * cluster it should have refined and nothing downstream can tell.
+ *
+ * **It is carried per vertex and composed by the triangle inequality.** Each vertex holds a bound on
+ * how far it now sits from the surface the caller started from, zero at the source. A collapse
+ * charges what it moved the *surface*, on top of whatever the pair already carried:
+ *
+ * ```
+ * bound[survivor] = max( bound[v1], bound[v2] ) + max over the pair's former positions
+ *                                                of their distance to the survivor's one-ring
+ * ```
  *
- * 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.
+ * **The increment is not how far the vertices went, and that distinction is the whole of it.** A
+ * vertex sliding within its own plane moves and the surface does not, and flat geometry is mostly
+ * that — charging the movement makes a flat wall refine forever, which is the one thing the
+ * refinement metric is not allowed to do (`VIRTUAL_GEOMETRY_DESIGN.md` §4, the flat-wall test that
+ * density heuristics were rejected on). Measured: charging movement reported `15.9` where the
+ * surface had moved `0.98`, and `41.6` on the same shape with a larger plane around it — the old
+ * dilution's mirror image, growing with surface that never moved. Charging the distance from each
+ * former position to the geometry now standing in its place is zero for the sliding case by
+ * construction, because the former position is still *on* that geometry.
  *
- * 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.
+ * Where the one-ring is empty the patch was consumed whole, there is no surface left to measure
+ * against, and the movement is the only evidence there is.
+ *
+ * **Why not the quadric, which is right there and tighter.** Because it is a mean and a mean is
+ * never a bound. The quadric's reading at a placement is the weighted average of the squared
+ * distances to every plane the vertex stands for, so a vertex that destroyed one feature and stands
+ * for a thousand planes it sits exactly on reports the feature divided by all of them. That is not a
+ * tuning error and no amount of choosing *when* to read fixes it — measured against the distance the
+ * surface actually moved, sampled at the source vertices, the quadric reading came back at 0.34 of
+ * it on a closed pyramid, 0.58 on an octahedron and 0.62 on a spike standing off a plane. The
+ * quadric still decides **where** the vertex goes, which is what it is good at; it no longer decides
+ * what that cost.
+ *
+ * The price is looseness, and it is real: the bound accumulates the movement of every collapse a
+ * vertex has been through rather than measuring the result against the source. It is the trade the
+ * metric has to make to be usable as a threshold.
+ *
+ * A caller that simplifies in several passes hands its own `bounds` array and keeps it across them,
+ * which is what makes the accumulation mean anything; each call then returns the largest bound any
+ * of *its own* collapses produced.
  *
  * `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
@@ -863,7 +1184,8 @@ function collapse_kills_protected_face(mesh, edge_id, protected_faces) {
  * @param {number} target_face_count Desired face count after simplification.
  * @param {Set<number>} [restricted_vertices] Vertices that must not move or be removed.
  * @param {Set<number>} [protected_faces] Faces that must not be removed.
- * @returns {number} object-space distance the surface moved, `0` when no collapse was performed
+ * @returns {number} an upper bound on the object-space distance the surface moved, `0` when no
+ *     collapse was performed
  */
 export function bt_mesh_simplify(
     mesh,
@@ -948,7 +1270,13 @@ export function bt_mesh_simplify(
  *     caller that carries no values may still care which corners of the result belong together, and
  *     a set that is not maintained is a set whose ids go stale — corners of one vertex would resolve
  *     to different wedges and every consumer downstream would see a seam that is not there.
- * @returns {number} object-space distance the surface moved, `0` when no collapse was performed
+ * @param {Float64Array} [bounds] how far each vertex already sits from the surface the caller is
+ *     measuring against, indexed by vertex id and **mutated in place**. Omitted, every vertex starts
+ *     on it and the answer is this call's own movement; supplied and kept across calls, the answer
+ *     accumulates from wherever the caller first started measuring — the same thing `quadratics`
+ *     does for the placement.
+ * @returns {number} an upper bound on the object-space distance the surface moved, `0` when no
+ *     collapse was performed
  */
 export function bt_mesh_simplify_with_quadrics(
     mesh,
@@ -957,7 +1285,8 @@ export function bt_mesh_simplify_with_quadrics(
     protected_faces,
     quadratics,
     attributes = null,
-    wedges = null
+    wedges = null,
+    bounds = null
 ) {
     assert.defined(mesh, 'mesh');
     assert.notNull(mesh, 'mesh');
@@ -974,6 +1303,22 @@ 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 bound any collapse so far has produced. See {@link bt_mesh_simplify} for why it is
+     * a bound carried per vertex rather than a reading taken off the quadric.
+     * @type {number}
+     */
+    let deviation = 0;
+
+    /**
+     * Zero for every vertex when the caller is not keeping its own: with nothing carried in, the
+     * surface being measured against is the one this call was handed.
+     * @type {Float64Array}
+     */
+    const deviation_bounds = bounds === null
+        ? new Float64Array(mesh.vertices.size)
+        : bounds;
+
     if (current_face_count <= target_face_count) {
         return 0;
     }
@@ -995,7 +1340,10 @@ export function bt_mesh_simplify_with_quadrics(
     }
 
     const edge_pool = mesh.edges;
-    const heap = new Uint32Heap(edge_pool.size);
+    // Slot capacity as well as id capacity: the heap holds at most one entry per edge, and the
+    // default would start at 64 slots and grow through the initial fill. This is the allocation
+    // `new Uint32Heap(edge_pool.size)` made before the queue changed.
+    const heap = new IndexedFloatMinHeap(edge_pool.size, edge_pool.size);
 
     for (let e = 0; e < edge_pool.size; e++) {
         if (!edge_pool.is_allocated(e)) {
@@ -1024,7 +1372,7 @@ export function bt_mesh_simplify_with_quadrics(
     let iterations = 0;
 
     while (
-        !heap.is_empty()
+        heap.size !== 0
         && current_face_count > target_face_count
         && iterations < max_iterations
     ) {
@@ -1066,16 +1414,18 @@ 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);
+        const face_deaths = bt_edge_count_faces(mesh, edge_id);
 
         // bt_edge_collapse keeps v1 as the survivor. If v2 is the pinned endpoint,
         // swap the edge's slots so the pinned vertex ends up in the v1 position.
@@ -1086,6 +1436,21 @@ 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];
+
+        /*
+         Where the surface is about to stop being, kept because nothing in the mesh will say so
+         afterwards. What it cost is measured below, once there is something to measure against.
+        */
+        mesh.vertex_read_coordinate(scratch_old_survivor, 0, pre_survivor);
+        mesh.vertex_read_coordinate(scratch_old_victim, 0, pre_victim);
+
+        const carried_base = Math.max(
+            deviation_bounds[pre_survivor], deviation_bounds[pre_victim]
+        );
+
         // 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
@@ -1120,16 +1485,31 @@ export function bt_mesh_simplify_with_quadrics(
         // are still intact.
         current_face_count -= bt_vertex_fuse_duplicate_edges(mesh, survivor);
 
+        // What the collapse cost the surface — see {@link bt_mesh_simplify}. Measured here rather
+        // than before, because the geometry it is measured against is the one the collapse just
+        // produced, and after the fuse rather than before, because a degenerate left in the fan
+        // would be the nearest thing in it.
+        const from_survivor = distance_to_vertex_fan(mesh, survivor, scratch_old_survivor);
+        const from_victim = distance_to_vertex_fan(mesh, survivor, scratch_old_victim);
+
+        const increment = Math.max(
+            from_survivor < 0
+                ? distance_from(scratch_old_survivor, target_x, target_y, target_z)
+                : from_survivor,
+            from_victim < 0
+                ? distance_from(scratch_old_victim, target_x, target_y, target_z)
+                : from_victim
+        );
+
+        deviation_bounds[survivor] = carried_base + increment;
+
+        deviation = Math.max(deviation, deviation_bounds[survivor]);
+
         update_neighbor_costs(
             mesh, survivor, quadratics, restricted_vertices, attributes, wedges, heap
         );
     }
 
-    // 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 +1517,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.