@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -1,6 +1,13 @@
 import { assert } from "../../../../../../assert.js";
 import { Uint32Heap } from "../../../../../../collection/heap/Uint32Heap.js";
 import { Quadric3 } from "../../../../quadric/Quadric3.js";
+import { QUADRIC3_SIZE } from "../../../../quadric/QUADRIC3_SIZE.js";
+import { quadric3_add } from "../../../../quadric/quadric3_add.js";
+import { quadric3_evaluate } from "../../../../quadric/quadric3_evaluate.js";
+import { quadric_attribute_add } from "../../../../quadric/quadric_attribute_add.js";
+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 { NULL_POINTER } from "../BinaryTopology.js";
 import { bt_edge_collapse_would_fold } from "../query/bt_edge_collapse_would_fold.js";
 import { bt_loop_kill } from "./bt_loop_kill.js";
@@ -18,6 +25,51 @@ const scratch_coord_b = new Float32Array(3);
 const scratch_target = new Float32Array(3);
 const scratch_combined_q = new Quadric3();
 
+/**
+ * The pair's summed attribute quadric, and its reduction. Grown to whatever channel count the
+ * current call carries and reused across every candidate it scores — `evaluate_edge_collapse` runs
+ * once per heap insert and again for every neighbour of every collapse, and an allocation there is
+ * an allocation per edge per round.
+ * @type {Float64Array}
+ */
+let scratch_attribute_sum = new Float64Array(0);
+
+/**
+ * @type {Float64Array}
+ */
+const scratch_attribute_reduced = new Float64Array(QUADRIC3_SIZE);
+
+/**
+ * One wedge group's reduction, on its way into the sum over groups.
+ * @type {Float64Array}
+ */
+const scratch_group_reduced = new Float64Array(QUADRIC3_SIZE);
+
+/**
+ * The wedges of a candidate's two endpoints, the survivor's first, and the local union-find that
+ * groups them. Only the multi-wedge path touches these, which on smooth geometry is never.
+ * @type {Uint32Array}
+ */
+let scratch_wedge_ids = new Uint32Array(0);
+
+/**
+ * @type {Uint32Array}
+ */
+let scratch_wedge_group = new Uint32Array(0);
+
+/**
+ * The corners of the faces a collapse would destroy, as `(at a, at b)` pairs. Two on a manifold
+ * edge, which is why it starts small and grows.
+ * @type {Uint32Array}
+ */
+let scratch_dying_loops = new Uint32Array(8);
+
+/**
+ * The fitted attribute record, on its way onto the survivor.
+ * @type {Float64Array}
+ */
+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
@@ -60,10 +112,15 @@ function count_edge_faces(mesh, edge_id) {
  * @param {number} edge_id
  * @param {Quadric3[]} quadratics
  * @param {Set<number>} restricted_vertices
+ * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}|null}
+ *     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}
  */
-function evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices, out_target) {
+function evaluate_edge_collapse(
+    mesh, edge_id, quadratics, restricted_vertices, attributes, wedges, out_target
+) {
     const v1 = mesh.edge_read_vertex1(edge_id);
     const v2 = mesh.edge_read_vertex2(edge_id);
 
@@ -89,6 +146,12 @@ function evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices,
         return Number.POSITIVE_INFINITY;
     }
 
+    let attribute_cost = 0;
+
+    if (attributes !== null) {
+        reduce_pair_attributes(mesh, v1, v2, attributes, wedges, scratch_attribute_reduced);
+    }
+
     if (v1_restricted) {
         mesh.vertex_read_coordinate(out_target, 0, v1);
     } else if (v2_restricted) {
@@ -97,6 +160,22 @@ function evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices,
         scratch_combined_q.copy(q1);
         scratch_combined_q.add(q2);
 
+        if (attributes !== null) {
+            /*
+             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
+             own values, so a collapse across a crease or a texture seam is pulled away from the
+             placement that would smear it.
+
+             Only `optimize` reads this sum. Its weight slot is now a plane count plus a triangle
+             count, which is not a quantity, and nothing downstream takes a distance from it -- the
+             cost below is the two pure geometric quadrics, evaluated separately.
+             */
+            quadric3_add(
+                scratch_combined_q, 0, scratch_combined_q, 0, scratch_attribute_reduced, 0
+            );
+        }
+
         if (!scratch_combined_q.optimize(out_target)) {
             // Singular combined tensor: fall back to the midpoint
             mesh.vertex_read_coordinate(scratch_coord_a, 0, v1);
@@ -112,8 +191,14 @@ function evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices,
     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));
+    }
+
     // 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));
+    return Math.abs(q1.evaluate(tx, ty, tz) + q2.evaluate(tx, ty, tz)) + attribute_cost;
 }
 
 /**
@@ -124,9 +209,13 @@ function evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices,
  * @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
  */
-function update_neighbor_costs(mesh, survivor, quadratics, restricted_vertices, heap) {
+function update_neighbor_costs(
+    mesh, survivor, quadratics, restricted_vertices, attributes, wedges, heap
+) {
     let curr_e = mesh.vertex_read_edge(survivor);
 
     if (curr_e === NULL_POINTER) {
@@ -148,7 +237,10 @@ function update_neighbor_costs(mesh, survivor, quadratics, restricted_vertices,
         const idx = heap.find_index_by_id(curr_e);
 
         if (idx !== -1) {
-            const cost = evaluate_edge_collapse(mesh, curr_e, quadratics, restricted_vertices, scratch_target);
+            const cost = evaluate_edge_collapse(
+                mesh, curr_e, quadratics, restricted_vertices, attributes, wedges, scratch_target
+            );
+
             heap.__update_score_by_index(idx, cost);
         }
 
@@ -156,6 +248,504 @@ function update_neighbor_costs(mesh, survivor, quadratics, restricted_vertices,
     } while (curr_e !== start_e && curr_e !== NULL_POINTER);
 }
 
+/**
+ * The corners of every face a collapse of `(a, b)` would destroy, as pairs — the corner at `a`
+ * followed by the corner at `b` — written into {@link scratch_dying_loops}.
+ *
+ * **The faces a collapse destroys are not only the ones on the edge it names.** They are the ones
+ * holding *both* endpoints: the edge's own, the ones on any parallel edge {@link bt_edge_kill_parallels}
+ * clears first, and the ones {@link bt_vertex_fuse_duplicate_edges} finds degenerate afterwards. That
+ * is {@link collapse_kills_protected_face}'s contract, written down there and true here for the same
+ * reason — and a triangle holding both endpoints has an edge between them, so walking the disk cycle
+ * for edges to `b` finds all of them.
+ *
+ * Walking one radial cycle instead would miss the parallel edges, and a wedge whose only dying face
+ * is on one of those would be adopted by the survivor rather than merged into it: two corner groups
+ * that are one piece of surface, left as two, which is a crease where the mesh has none.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} how many pairs were written
+ */
+function collect_dying_faces(mesh, a, b) {
+    let count = 0;
+
+    let edge = mesh.vertex_read_edge(a);
+
+    if (edge === NULL_POINTER) {
+        return 0;
+    }
+
+    const start_edge = edge;
+    const face_pool = mesh.faces;
+
+    do {
+        const at_v1 = mesh.edge_read_vertex1(edge) === a;
+
+        const other = at_v1 ? mesh.edge_read_vertex2(edge) : mesh.edge_read_vertex1(edge);
+
+        if (other === b) {
+            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 next_loop = mesh.loop_read_next(loop);
+
+                    const at_a = mesh.loop_read_vertex(loop) === a ? loop : next_loop;
+
+                    if (scratch_dying_loops.length < (count + 1) * 2) {
+                        const grown = new Uint32Array(Math.max(8, (count + 1) * 4));
+
+                        grown.set(scratch_dying_loops);
+
+                        scratch_dying_loops = grown;
+                    }
+
+                    scratch_dying_loops[count * 2] = at_a;
+                    scratch_dying_loops[count * 2 + 1] = at_a === loop ? next_loop : loop;
+
+                    count++;
+                }
+
+                loop = mesh.loop_read_radial_next(loop);
+
+                if (loop === first_loop) {
+                    break;
+                }
+            }
+        }
+
+        edge = at_v1 ? mesh.edge_read_v1_disk_next(edge) : mesh.edge_read_v2_disk_next(edge);
+    } while (edge !== start_edge && edge !== NULL_POINTER);
+
+    return count;
+}
+
+/**
+ * Which wedges of a collapse's two endpoints would become one, and the reduced attribute quadric
+ * that follows from it.
+ *
+ * **A live face is what says two corners shade as one.** Each face on the edge holds one corner at
+ * each endpoint, and that face is about to die into the survivor — so whatever those two corners
+ * were, they are one corner's worth of surface afterwards. Everything else the two vertices carry
+ * stays apart. That rule needs no tolerance and no comparison of values, which matters: two
+ * neighbours on a smoothly curved surface have genuinely different normals, so a rule that merged
+ * only equal values would invent a crease at every collapse a sphere has.
+ *
+ * Each resulting group is reduced separately and the reductions summed, because each group solves
+ * for its own value ({@link quadric_attribute_reduce} is the substitution of that solve). Summing
+ * the quadrics first and reducing once would be the claim that all of them share one value, which
+ * is the thing a seam denies.
+ *
+ * **A collapse with no face to destroy is a fuse of two points, not a simplification of a surface**,
+ * and it is treated as one group. Nothing survives to hold the corners apart, and the alternative
+ * leaves the victim's accumulated history on a wedge that may have no corners left to carry it. Rare,
+ * and measured rather than assumed: 6 of 6,195 collapses over a 12,288-triangle sphere's whole DAG.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} v1
+ * @param {number} v2
+ * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}} attributes
+ * @param {BtWedgeSet} wedges
+ * @param {Float64Array} out `QUADRIC3_SIZE` elements, overwritten
+ */
+function reduce_pair_attributes(mesh, v1, v2, attributes, wedges, out) {
+    const components = attributes.components;
+    const size = quadric_attribute_size(components);
+
+    const quadrics = attributes.quadrics;
+
+    const first_1 = wedges.first_of_vertex[v1];
+    const first_2 = wedges.first_of_vertex[v2];
+
+    /*
+     One wedge each, which is every vertex of a mesh with no seams and the overwhelming majority of
+     one that has them. They can only end up in the same group, so the answer is the sum of the two
+     reduced once -- exactly the arithmetic this had before wedges existed, kept on the path that
+     runs once per edge per round.
+     */
+    if (
+        first_1 !== NULL_POINTER && wedges.next_of_wedge[first_1] === NULL_POINTER
+        && first_2 !== NULL_POINTER && wedges.next_of_wedge[first_2] === NULL_POINTER
+    ) {
+        quadric_attribute_add(
+            scratch_attribute_sum, 0,
+            quadrics, first_1 * size, quadrics, first_2 * size,
+            components
+        );
+
+        quadric_attribute_reduce(out, 0, scratch_attribute_sum, 0, components);
+
+        return;
+    }
+
+    let count = 0;
+
+    for (let w = first_1; w !== NULL_POINTER; w = wedges.next_of_wedge[w]) {
+        count++;
+    }
+
+    for (let w = first_2; w !== NULL_POINTER; w = wedges.next_of_wedge[w]) {
+        count++;
+    }
+
+    if (scratch_wedge_ids.length < count) {
+        scratch_wedge_ids = new Uint32Array(count);
+        scratch_wedge_group = new Uint32Array(count);
+    }
+
+    let n = 0;
+
+    for (let w = first_1; w !== NULL_POINTER; w = wedges.next_of_wedge[w]) {
+        scratch_wedge_ids[n] = w;
+        scratch_wedge_group[n] = n;
+        n++;
+    }
+
+    const first_count = n;
+
+    for (let w = first_2; w !== NULL_POINTER; w = wedges.next_of_wedge[w]) {
+        scratch_wedge_ids[n] = w;
+        scratch_wedge_group[n] = n;
+        n++;
+    }
+
+    const dying = collect_dying_faces(mesh, v1, v2);
+
+    for (let pair = 0; pair < dying; pair++) {
+        local_union(
+            local_index(wedges.find(wedges.of_loop[scratch_dying_loops[pair * 2]]), n),
+            local_index(wedges.find(wedges.of_loop[scratch_dying_loops[pair * 2 + 1]]), n)
+        );
+    }
+
+    if (dying === 0 && first_count > 0) {
+        /*
+         Whatever the second vertex holds joins the first's first wedge, and the first's *other*
+         wedges are left alone -- which is exactly what {@link carry_wedges} does when the edge has no
+         face, and the two have to agree or the price of a collapse is not the price of the collapse
+         that happens. (Which of the pair survives is decided after this runs, so a swapped pair
+         scores the mirror of what it will do; the shape of the partition is the same either way and
+         this is a heuristic over 0.1% of collapses.)
+         */
+        for (let i = first_count; i < n; i++) {
+            local_union(0, i);
+        }
+    }
+
+    out.fill(0, 0, QUADRIC3_SIZE);
+
+    for (let group = 0; group < n; group++) {
+        if (local_find(group) !== group) {
+            continue;
+        }
+
+        let members = 0;
+
+        for (let i = 0; i < n; i++) {
+            if (local_find(i) !== group) {
+                continue;
+            }
+
+            const from = scratch_wedge_ids[i] * size;
+
+            if (members === 0) {
+                for (let element = 0; element < size; element++) {
+                    scratch_attribute_sum[element] = quadrics[from + element];
+                }
+            } else {
+                quadric_attribute_add(
+                    scratch_attribute_sum, 0, scratch_attribute_sum, 0, quadrics, from, components
+                );
+            }
+
+            members++;
+        }
+
+        quadric_attribute_reduce(scratch_group_reduced, 0, scratch_attribute_sum, 0, components);
+
+        quadric3_add(out, 0, out, 0, scratch_group_reduced, 0);
+    }
+}
+
+/**
+ * Where a wedge id sits in {@link scratch_wedge_ids}, or `-1`.
+ *
+ * A scan rather than a map: it is over the wedges of two vertices, which is two on a crease and one
+ * on everything else.
+ *
+ * @param {number} wedge
+ * @param {number} count
+ * @returns {number}
+ */
+function local_index(wedge, count) {
+    for (let i = 0; i < count; i++) {
+        if (scratch_wedge_ids[i] === wedge) {
+            return i;
+        }
+    }
+
+    return -1;
+}
+
+/**
+ * @param {number} index
+ * @returns {number}
+ */
+function local_find(index) {
+    let root = index;
+
+    while (scratch_wedge_group[root] !== root) {
+        root = scratch_wedge_group[root];
+    }
+
+    return root;
+}
+
+/**
+ * @param {number} a index into {@link scratch_wedge_ids}, or `-1` for a wedge not among them
+ * @param {number} b
+ */
+function local_union(a, b) {
+    if (a < 0 || b < 0) {
+        return;
+    }
+
+    const root_a = local_find(a);
+    const root_b = local_find(b);
+
+    if (root_a !== root_b) {
+        scratch_wedge_group[root_b] = root_a;
+    }
+}
+
+/**
+ * Move the survivor's attribute record onto the value the pair between them stands for, when there
+ * is no field to fit one from.
+ *
+ * The fallback, not the rule. A vertex whose every incident triangle was a sliver -- or which has
+ * none left at all -- has an attribute quadric of no weight, and a quadric of no weight has no field
+ * to evaluate. Blending is what is left, and it is a reasonable answer rather than a good one: it is
+ * confined to the values that went in, where a fit is not, and it says nothing about where the
+ * vertex ended up.
+ *
+ * Blended by accumulated quadric weight, which is how much source surface each endpoint speaks for:
+ * a vertex that a dozen collapses have folded into already represents a dozen vertices' worth of the
+ * original, and taking half its word against a vertex that represents one would let whichever side
+ * of a merge happened to be shorter of history pull the value across.
+ *
+ * Two endpoints that have accumulated nothing have no claim over one another, and split it.
+ *
+ * @param {Float64Array} values indexed by wedge id, `components` elements each
+ * @param {number} components
+ * @param {number} survivor wedge
+ * @param {number} victim wedge
+ * @param {number} survivor_weight
+ * @param {number} victim_weight
+ */
+function blend_attributes(values, components, survivor, victim, survivor_weight, victim_weight) {
+    const total = survivor_weight + victim_weight;
+
+    const survivor_share = total > 0 ? survivor_weight / total : 0.5;
+    const victim_share = 1 - survivor_share;
+
+    const survivor_base = survivor * components;
+    const victim_base = victim * components;
+
+    for (let component = 0; component < components; component++) {
+        values[survivor_base + component] =
+            values[survivor_base + component] * survivor_share
+            + values[victim_base + component] * victim_share;
+    }
+}
+
+/**
+ * Merge the pair's wedges, and — where there are values riding along — decide what the survivor
+ * carries and give it the victim's accumulated fields.
+ *
+ * **The merge happens whether or not anything is being carried.** A wedge set is a statement about
+ * which corners of the result belong together, and a set that stops tracking collapses is a set
+ * whose ids go stale: the victim's loops arrive at the survivor still naming the victim's wedge, and
+ * every consumer downstream reads a seam where there is none. Measured, because it got past a
+ * byte-identity gate and was caught by an unrelated assertion instead: a round over a mesh with no
+ * channels at all cut clusters of 132 vertices against a ceiling of 128.
+ *
+ * Once per **wedge**, because a vertex has one position and not one appearance. The survivor comes
+ * out of this holding its own wedges, whichever of the victim's merged into them, and whichever of
+ * the victim's did not — those simply move, still carrying what they always did.
+ * {@link reduce_pair_attributes} is the rule for which is which, and it is the same walk.
+ *
+ * Every wedge that ends up on the survivor is fitted afresh, not only the merged ones: the vertex
+ * moved, and a field is evaluated *at a position*.
+ *
+ * A merged wedge's quadric absorbs its partner's first, so the fit it is then asked for is over
+ * *everything* the pair has ever stood for — which is what makes the answer a deviation from the
+ * source rather than from the step before it, exactly as the geometric quadric's is.
+ *
+ * Then the value: the position it is being moved to, plugged into the field those accumulated
+ * triangles describe. Where there is no field — a wedge every one of whose triangles was a sliver,
+ * or which has no triangles left — {@link blend_attributes} is the fallback, applied at the merge so
+ * that a wedge with nothing to fit from still ends up between the two values rather than on one of
+ * them. A successful fit overwrites it. (Two victim wedges merging into one survivor wedge, which
+ * takes a non-manifold edge, blend the second against the first's result; it is a fallback inside a
+ * fallback and it is confined to the values that went in either way.)
+ *
+ * **A restricted survivor is given the victim's fields and none of its values.** Its position does
+ * not move, but the fit at that unchanged position would still come out different, because `W`, `G`
+ * and `D` under it have grown. That would break the one thing pinning is for: a vertex two groups
+ * share must carry byte-identical values in both. It keeps the quadric so that a *later* step, one
+ * that is free to move it, fits from the whole history rather than from the fragment it started
+ * with. A wedge it *adopts* is a wedge the other group never had, carrying corners that are this
+ * group's alone, so it is no exception to that.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {BtWedgeSet} wedges
+ * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}|null} attributes
+ * @param {number} survivor
+ * @param {number} victim
+ * @param {boolean} survivor_restricted
+ * @param {number} survivor_weight geometric quadric weight, for the fallback
+ * @param {number} victim_weight
+ * @param {Float32Array|number[]} target where the survivor is being moved to
+ */
+function carry_wedges(
+    mesh, wedges, attributes, survivor, victim, survivor_restricted,
+    survivor_weight, victim_weight, target
+) {
+    const dying = collect_dying_faces(mesh, survivor, victim);
+
+    for (let pair = 0; pair < dying; pair++) {
+        absorb_wedge(
+            wedges, attributes,
+            wedges.find(wedges.of_loop[scratch_dying_loops[pair * 2]]),
+            wedges.find(wedges.of_loop[scratch_dying_loops[pair * 2 + 1]]),
+            survivor_restricted, survivor_weight, victim_weight
+        );
+    }
+
+    if (dying === 0 && wedges.first_of_vertex[survivor] !== NULL_POINTER) {
+        // A fuse of two points rather than a simplification of a surface; see
+        // {@link reduce_pair_attributes}, whose cost model this has to agree with.
+        const into = wedges.find(wedges.first_of_vertex[survivor]);
+
+        for (
+            let wedge = wedges.first_of_vertex[victim];
+            wedge !== NULL_POINTER;
+            wedge = wedges.next_of_wedge[wedge]
+        ) {
+            absorb_wedge(
+                wedges, attributes, into, wedges.find(wedge),
+                survivor_restricted, survivor_weight, victim_weight
+            );
+        }
+    }
+
+    // The survivor's own list, less whatever merged into something else, then the victim's on top of
+    // it. The loops themselves are not touched: a corner's wedge id goes stale and `find` resolves
+    // it, which is the whole reason nothing has to go looking for a corner in order to move it.
+    relist_wedges(wedges, survivor, survivor);
+    relist_wedges(wedges, victim, survivor);
+
+    if (survivor_restricted || attributes === null) {
+        return;
+    }
+
+    const components = attributes.components;
+
+    for (
+        let wedge = wedges.first_of_vertex[survivor];
+        wedge !== NULL_POINTER;
+        wedge = wedges.next_of_wedge[wedge]
+    ) {
+        const fitted = quadric_attribute_solve(
+            scratch_attribute_values, 0,
+            attributes.quadrics, wedge * quadric_attribute_size(components), components,
+            attributes.weights,
+            target[0], target[1], target[2]
+        );
+
+        if (fitted) {
+            attributes.values.set(
+                scratch_attribute_values.subarray(0, components), wedge * components
+            );
+        }
+    }
+}
+
+/**
+ * Make `other` part of `wedge`: its accumulated field, and — for the case where there turns out to
+ * be no field to fit from — its value.
+ *
+ * @param {BtWedgeSet} wedges
+ * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}|null} attributes
+ * @param {number} wedge root that survives, the survivor's
+ * @param {number} other root that does not, the victim's
+ * @param {boolean} survivor_restricted
+ * @param {number} survivor_weight
+ * @param {number} victim_weight
+ */
+function absorb_wedge(
+    wedges, attributes, wedge, other, survivor_restricted, survivor_weight, victim_weight
+) {
+    if (!wedges.merge(wedge, other)) {
+        // Already one wedge. A manifold edge's two faces name the same pair twice, which is the
+        // common case rather than an oddity, so this is the guard that keeps a quadric from being
+        // counted into itself.
+        return;
+    }
+
+    if (attributes === null) {
+        return;
+    }
+
+    const components = attributes.components;
+    const size = quadric_attribute_size(components);
+
+    quadric_attribute_add(
+        attributes.quadrics, wedge * size,
+        attributes.quadrics, wedge * size,
+        attributes.quadrics, other * size,
+        components
+    );
+
+    if (!survivor_restricted) {
+        blend_attributes(
+            attributes.values, components, wedge, other, survivor_weight, victim_weight
+        );
+    }
+}
+
+/**
+ * Move every wedge of `from` onto `to`, dropping the ones that are no longer their own root.
+ *
+ * `from === to` is a compaction in place, which is what the survivor needs: its own wedges can have
+ * merged into each other, through a victim wedge that touched both.
+ *
+ * @param {BtWedgeSet} wedges
+ * @param {number} from vertex
+ * @param {number} to vertex
+ */
+function relist_wedges(wedges, from, to) {
+    let wedge = wedges.first_of_vertex[from];
+
+    wedges.detach_all(from);
+
+    while (wedge !== NULL_POINTER) {
+        const next = wedges.next_of_wedge[wedge];
+
+        if (wedges.find(wedge) === wedge) {
+            wedges.attach(wedge, to);
+        }
+
+        wedge = next;
+    }
+}
+
 /**
  * Would collapsing this edge destroy a face the caller asked to keep?
  *
@@ -316,7 +906,48 @@ export function bt_mesh_simplify(
  * @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.
+ * `attributes` is per-vertex data that travels *through* the collapse rather than being re-derived
+ * from the result. Whatever a merged vertex is to carry has to be decided here, from the values
+ * being merged: the mesh a collapse leaves behind is a different surface, and a value read off it
+ * afterwards describes that one rather than the one the caller started with.
+ *
+ * It is carried per **wedge** — a set of corners at one vertex that shade as one — so a hard edge
+ * or a texture seam survives a collapse instead of being averaged away. Which of the pair's wedges
+ * become one is decided by the faces the collapse destroys, in {@link reduce_pair_attributes}; a
+ * mesh with no seams has one wedge per vertex, every collapse merges the pair, and all of this is
+ * the arithmetic it always was.
+ *
+ * It is **fitted**, not inherited and not averaged. Each channel varies affinely over a triangle, so
+ * every triangle a wedge has ever absorbed says what that channel should be at any position; the
+ * survivor takes the value that best explains all of them at once, at the position it is being moved
+ * to ({@link quadric_attribute_solve}). Those same accumulated fields also reach the *placement* and
+ * the cost, through {@link quadric_attribute_reduce} -- so a collapse that would smear a crease or a
+ * texture seam is both moved away from it and priced for it. A vertex with no field to fit from
+ * falls back to a weighted blend, and a **restricted** survivor is left exactly as it is, for the
+ * same reason its position is.
+ *
+ * The values themselves mean nothing here. A caller whose record holds a direction or a flag rather
+ * than a quantity has to say so afterwards, over the array this leaves behind.
+ *
+ * What the call **returns** is still the pure geometric quadric's answer, evaluated at wherever the
+ * higher-dimensional metric put each vertex. Solving in one metric and reporting in the other is
+ * what keeps the number an object-space length (`VIRTUAL_GEOMETRY_DESIGN.md` §3).
+ *
  * @param {Quadric3[]} quadratics indexed by vertex id, one per allocated vertex; mutated in place
+ * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}|null} [attributes]
+ *     per-wedge records to carry through the collapses, with the attribute quadrics that fit them
+ *     ({@link bt_mesh_compute_wedge_attribute_quadrics}) and the per-channel weights those were
+ *     built with. `values` and `quadrics` are indexed by **wedge id**;
+ *     {@link bt_wedges_per_vertex} is the set where that is the vertex id. `null` to carry nothing,
+ *     which is what every caller but the virtual-geometry builder does. {@link bt_mesh_simplify_by_error}
+ *     is not among them at all — it is a separate implementation with its own cost function, and so
+ *     is untouched by any of this, which matters because it simplifies to a *tolerance* that an
+ *     attribute term would quietly move.
+ * @param {BtWedgeSet|null} [wedges] which corners of each vertex shade as one, **mutated in place**
+ *     as the collapses merge them. Required when `attributes` is given, and useful without it: a
+ *     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
  */
 export function bt_mesh_simplify_with_quadrics(
@@ -324,7 +955,9 @@ export function bt_mesh_simplify_with_quadrics(
     target_face_count,
     restricted_vertices,
     protected_faces,
-    quadratics
+    quadratics,
+    attributes = null,
+    wedges = null
 ) {
     assert.defined(mesh, 'mesh');
     assert.notNull(mesh, 'mesh');
@@ -345,6 +978,22 @@ export function bt_mesh_simplify_with_quadrics(
         return 0;
     }
 
+    if (attributes !== null) {
+        assert.notNull(wedges, 'wedges, which carrying attributes requires');
+
+        const size = quadric_attribute_size(attributes.components);
+
+        // Grown, never shrunk: a build is thousands of calls over the same handful of channel
+        // counts, and every one of them would otherwise allocate.
+        if (scratch_attribute_sum.length < size) {
+            scratch_attribute_sum = new Float64Array(size);
+        }
+
+        if (scratch_attribute_values.length < attributes.components) {
+            scratch_attribute_values = new Float64Array(attributes.components);
+        }
+    }
+
     const edge_pool = mesh.edges;
     const heap = new Uint32Heap(edge_pool.size);
 
@@ -357,7 +1006,9 @@ export function bt_mesh_simplify_with_quadrics(
             continue;
         }
 
-        const cost = evaluate_edge_collapse(mesh, e, quadratics, restricted_vertices, scratch_target);
+        const cost = evaluate_edge_collapse(
+            mesh, e, quadratics, restricted_vertices, attributes, wedges, scratch_target
+        );
 
         if (cost === Number.POSITIVE_INFINITY) {
             continue;
@@ -407,7 +1058,9 @@ export function bt_mesh_simplify_with_quadrics(
             continue;
         }
 
-        const cost = evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices, scratch_target);
+        const cost = evaluate_edge_collapse(
+            mesh, edge_id, quadratics, restricted_vertices, attributes, wedges, scratch_target
+        );
 
         if (cost === Number.POSITIVE_INFINITY) {
             continue;
@@ -433,6 +1086,20 @@ 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);
 
+        // 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
+        // shade as one.
+        if (wedges !== null) {
+            carry_wedges(
+                mesh, wedges, attributes, pre_survivor, pre_victim,
+                restricted_vertices.has(pre_survivor),
+                quadratics[pre_survivor].weight,
+                quadratics[pre_victim].weight,
+                scratch_target
+            );
+        }
+
         // Accumulate victim's quadric onto the survivor before the topology mutates.
         quadratics[pre_survivor].add(quadratics[pre_victim]);
         quadratics[pre_victim] = null;
@@ -453,7 +1120,9 @@ export function bt_mesh_simplify_with_quadrics(
         // are still intact.
         current_face_count -= bt_vertex_fuse_duplicate_edges(mesh, survivor);
 
-        update_neighbor_costs(mesh, survivor, quadratics, restricted_vertices, heap);
+        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