@woosh/meep-engine 3.28.0 → 3.29.0

package/src/core/geom/3d/quadric/quadric_attribute_reduce.js

@@ -0,0 +1,104 @@
+import { QUADRIC3_SIZE } from "./QUADRIC3_SIZE.js";
+
+/**
+ * The 3-D quadric an attribute quadric becomes once its attributes have been solved out of it.
+ *
+ * ## Why there is one at all
+ *
+ * The accumulated form is a quadratic in `3 + m` unknowns — a position and a value per channel. But
+ * the channels appear in it only as `-2 s_i (G_i . v + D_i) + s_i^2 W`, which is minimised exactly,
+ * with no search, at `s_i = (G_i . v + D_i) / W`. Substituting that back removes them, and what is
+ * left is a quadric in the position alone:
+ *
+ * ```
+ * A = P - SUM_i (G_i G_i^T) / W
+ * b = q - SUM_i (D_i G_i)   / W
+ * c = r - SUM_i (D_i^2)     / W
+ * ```
+ *
+ * That is the whole reason to hold Hoppe's form rather than the `(3 + m)`-dimensional lift: placing
+ * the vertex stays a 3x3 solve however many channels the mesh carries, and the channels' influence
+ * on *where it goes* is not lost — it is in `A` and `b`.
+ *
+ * The output is {@link Quadric3}-shaped, so `quadric3_optimize` places the vertex and
+ * `quadric3_evaluate` reads the attribute error at a position, both unchanged.
+ *
+ * ## What its weight is not
+ *
+ * Slot 10 carries the accumulated triangle count, as the header did. It is **not** a plane count,
+ * and {@link quadric3_distance} on this quadric is not a length: the value is an attribute residual
+ * in whatever units the caller's weights put it in. A caller wanting a length evaluates the *pure
+ * geometric* quadric at the position this one helped choose, which is the whole of the units
+ * discipline (`VIRTUAL_GEOMETRY_DESIGN.md` §3).
+ *
+ * A quadric that has accumulated nothing has no attributes to solve out and reduces to zero, which
+ * is what an empty quadric should add to a sum.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination, `QUADRIC3_SIZE` elements from
+ *     `out_offset`, overwritten
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} q `quadric_attribute_size(components)` elements from `q_offset`
+ * @param {number} q_offset
+ * @param {number} components number of scalar channels
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_reduce(out, out_offset, q, q_offset, components) {
+    const weight = q[q_offset + 10];
+
+    if (weight <= 0) {
+        for (let i = 0; i < QUADRIC3_SIZE; i++) {
+            out[out_offset + i] = 0;
+        }
+
+        return;
+    }
+
+    let a00 = q[q_offset];
+    let a01 = q[q_offset + 1];
+    let a02 = q[q_offset + 2];
+    let a11 = q[q_offset + 4];
+    let a12 = q[q_offset + 5];
+    let a22 = q[q_offset + 7];
+
+    let b0 = q[q_offset + 3];
+    let b1 = q[q_offset + 6];
+    let b2 = q[q_offset + 8];
+
+    let c = q[q_offset + 9];
+
+    for (let component = 0; component < components; component++) {
+        const tail = q_offset + QUADRIC3_SIZE + component * 4;
+
+        const gx = q[tail];
+        const gy = q[tail + 1];
+        const gz = q[tail + 2];
+        const d = q[tail + 3];
+
+        a00 -= gx * gx / weight;
+        a01 -= gx * gy / weight;
+        a02 -= gx * gz / weight;
+        a11 -= gy * gy / weight;
+        a12 -= gy * gz / weight;
+        a22 -= gz * gz / weight;
+
+        b0 -= d * gx / weight;
+        b1 -= d * gy / weight;
+        b2 -= d * gz / weight;
+
+        c -= d * d / weight;
+    }
+
+    out[out_offset] = a00;
+    out[out_offset + 1] = a01;
+    out[out_offset + 2] = a02;
+    out[out_offset + 3] = b0;
+    out[out_offset + 4] = a11;
+    out[out_offset + 5] = a12;
+    out[out_offset + 6] = b1;
+    out[out_offset + 7] = a22;
+    out[out_offset + 8] = b2;
+    out[out_offset + 9] = c;
+    out[out_offset + 10] = weight;
+}

package/src/core/geom/3d/quadric/quadric_attribute_set_from_triangle.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Set an attribute quadric to one triangle's contribution: how much a candidate `(position,
+ * attributes)` disagrees with the linear field this triangle's corners describe.
+ *
+ * ## What the field is
+ *
+ * Over a triangle, an attribute that interpolates its three corners is an affine function of
+ * position, `s(p) = g . p + d`. Three corner values give three equations in four unknowns; the
+ * fourth is that the field does not vary *off* the surface, `g . n = 0`, which is what makes it a
+ * function of the surface rather than of space. With `e1 = b - a`, `e2 = c - a` and `n` their unit
+ * cross product:
+ *
+ * ```
+ * g = ( (s_b - s_a) * (e2 x n) + (s_c - s_a) * (n x e1) ) / |e1 x e2|
+ * d = s_a - g . a
+ * ```
+ *
+ * The error of a candidate `(v, s)` against this triangle is then `(g . v + d - s)^2` per channel,
+ * and what is accumulated here is everything in that expression that does not involve `s`, plus the
+ * two terms per channel that do. {@link quadric_attribute_reduce} does the rest, once, at solve
+ * time.
+ *
+ * ## Weights
+ *
+ * `g` carries units of *attribute per length*, so the error above is dimensionless while the
+ * geometric quadric beside it evaluates to a squared length. Adding those without saying how they
+ * compare is meaningless, so each channel carries a weight with units of length and the field is
+ * built over `weight * s` rather than over `s`. {@link quadric_attribute_solve} divides it back out.
+ *
+ * ## Slivers
+ *
+ * `g` divides by twice the triangle's area, so a sliver produces an enormous gradient off a
+ * negligible amount of surface. A triangle whose corners are within `EPSILON` of collinear
+ * contributes nothing at all rather than that: the quadric is zeroed and `false` comes back.
+ * The test is on the sine of the corner angle rather than on the area, so it names slivers and not
+ * merely small triangles — a small well-shaped triangle has a large gradient *and means it*.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination, `quadric_attribute_size(components)`
+ *     elements from `out_offset`, overwritten
+ * @param {number} out_offset
+ * @param {number} components number of scalar channels
+ * @param {ArrayLike<number>} weights one per channel, `components` elements
+ * @param {number} ax first corner
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx second corner
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} cx third corner
+ * @param {number} cy
+ * @param {number} cz
+ * @param {ArrayLike<number>} values the attribute vector the three corners are read out of
+ * @param {number} a_offset first corner's record within `values`
+ * @param {number} b_offset
+ * @param {number} c_offset
+ * @returns {boolean} whether the triangle described a field at all
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_set_from_triangle(out: number[] | Float32Array | Float64Array, out_offset: number, components: number, weights: ArrayLike<number>, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, values: ArrayLike<number>, a_offset: number, b_offset: number, c_offset: number): boolean;
+//# sourceMappingURL=quadric_attribute_set_from_triangle.d.ts.map

package/src/core/geom/3d/quadric/quadric_attribute_set_from_triangle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadric_attribute_set_from_triangle.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric_attribute_set_from_triangle.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,yDAvBW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAElC,MAAM,cACN,MAAM,WACN,UAAU,MAAM,CAAC,MACjB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,UACN,UAAU,MAAM,CAAC,YACjB,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CAkGnB"}

package/src/core/geom/3d/quadric/quadric_attribute_set_from_triangle.js

@@ -0,0 +1,158 @@
+import { assert } from "../../../assert.js";
+import { EPSILON } from "../../../math/EPSILON.js";
+import { QUADRIC3_SIZE } from "./QUADRIC3_SIZE.js";
+
+/**
+ * Set an attribute quadric to one triangle's contribution: how much a candidate `(position,
+ * attributes)` disagrees with the linear field this triangle's corners describe.
+ *
+ * ## What the field is
+ *
+ * Over a triangle, an attribute that interpolates its three corners is an affine function of
+ * position, `s(p) = g . p + d`. Three corner values give three equations in four unknowns; the
+ * fourth is that the field does not vary *off* the surface, `g . n = 0`, which is what makes it a
+ * function of the surface rather than of space. With `e1 = b - a`, `e2 = c - a` and `n` their unit
+ * cross product:
+ *
+ * ```
+ * g = ( (s_b - s_a) * (e2 x n) + (s_c - s_a) * (n x e1) ) / |e1 x e2|
+ * d = s_a - g . a
+ * ```
+ *
+ * The error of a candidate `(v, s)` against this triangle is then `(g . v + d - s)^2` per channel,
+ * and what is accumulated here is everything in that expression that does not involve `s`, plus the
+ * two terms per channel that do. {@link quadric_attribute_reduce} does the rest, once, at solve
+ * time.
+ *
+ * ## Weights
+ *
+ * `g` carries units of *attribute per length*, so the error above is dimensionless while the
+ * geometric quadric beside it evaluates to a squared length. Adding those without saying how they
+ * compare is meaningless, so each channel carries a weight with units of length and the field is
+ * built over `weight * s` rather than over `s`. {@link quadric_attribute_solve} divides it back out.
+ *
+ * ## Slivers
+ *
+ * `g` divides by twice the triangle's area, so a sliver produces an enormous gradient off a
+ * negligible amount of surface. A triangle whose corners are within `EPSILON` of collinear
+ * contributes nothing at all rather than that: the quadric is zeroed and `false` comes back.
+ * The test is on the sine of the corner angle rather than on the area, so it names slivers and not
+ * merely small triangles — a small well-shaped triangle has a large gradient *and means it*.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination, `quadric_attribute_size(components)`
+ *     elements from `out_offset`, overwritten
+ * @param {number} out_offset
+ * @param {number} components number of scalar channels
+ * @param {ArrayLike<number>} weights one per channel, `components` elements
+ * @param {number} ax first corner
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx second corner
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} cx third corner
+ * @param {number} cy
+ * @param {number} cz
+ * @param {ArrayLike<number>} values the attribute vector the three corners are read out of
+ * @param {number} a_offset first corner's record within `values`
+ * @param {number} b_offset
+ * @param {number} c_offset
+ * @returns {boolean} whether the triangle described a field at all
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_set_from_triangle(
+    out, out_offset, components, weights,
+    ax, ay, az, bx, by, bz, cx, cy, cz,
+    values, a_offset, b_offset, c_offset
+) {
+    assert.isNonNegativeInteger(components, 'components');
+
+    const size = QUADRIC3_SIZE + components * 4;
+
+    for (let i = 0; i < size; i++) {
+        out[out_offset + i] = 0;
+    }
+
+    const e1x = bx - ax;
+    const e1y = by - ay;
+    const e1z = bz - az;
+
+    const e2x = cx - ax;
+    const e2y = cy - ay;
+    const e2z = cz - az;
+
+    const nx = e1y * e2z - e1z * e2y;
+    const ny = e1z * e2x - e1x * e2z;
+    const nz = e1x * e2y - e1y * e2x;
+
+    const determinant = Math.sqrt(nx * nx + ny * ny + nz * nz);
+
+    const e1_length = Math.sqrt(e1x * e1x + e1y * e1y + e1z * e1z);
+    const e2_length = Math.sqrt(e2x * e2x + e2y * e2y + e2z * e2z);
+
+    // `determinant` is `|e1| |e2| sin(angle)`, so this is the sine, and a scale-free sliver test.
+    if (determinant <= EPSILON * e1_length * e2_length) {
+        return false;
+    }
+
+    const unit_nx = nx / determinant;
+    const unit_ny = ny / determinant;
+    const unit_nz = nz / determinant;
+
+    // The two columns of the inverse that the corner differences multiply: e2 x n, and n x e1.
+    const p1x = e2y * unit_nz - e2z * unit_ny;
+    const p1y = e2z * unit_nx - e2x * unit_nz;
+    const p1z = e2x * unit_ny - e2y * unit_nx;
+
+    const p2x = unit_ny * e1z - unit_nz * e1y;
+    const p2y = unit_nz * e1x - unit_nx * e1z;
+    const p2z = unit_nx * e1y - unit_ny * e1x;
+
+    for (let component = 0; component < components; component++) {
+        const weight = weights[component];
+
+        const sa = values[a_offset + component] * weight;
+        const sb = values[b_offset + component] * weight;
+        const sc = values[c_offset + component] * weight;
+
+        const db = (sb - sa) / determinant;
+        const dc = (sc - sa) / determinant;
+
+        const gx = db * p1x + dc * p2x;
+        const gy = db * p1y + dc * p2y;
+        const gz = db * p1z + dc * p2z;
+
+        const d = sa - (gx * ax + gy * ay + gz * az);
+
+        // P += g g^T, in the header's `A` slots
+        out[out_offset] += gx * gx;
+        out[out_offset + 1] += gx * gy;
+        out[out_offset + 2] += gx * gz;
+        out[out_offset + 4] += gy * gy;
+        out[out_offset + 5] += gy * gz;
+        out[out_offset + 7] += gz * gz;
+
+        // q += d g, in the header's `b` slots
+        out[out_offset + 3] += d * gx;
+        out[out_offset + 6] += d * gy;
+        out[out_offset + 8] += d * gz;
+
+        // r += d^2, in the header's `c` slot
+        out[out_offset + 9] += d * d;
+
+        const tail = out_offset + QUADRIC3_SIZE + component * 4;
+
+        out[tail] = gx;
+        out[tail + 1] = gy;
+        out[tail + 2] = gz;
+        out[tail + 3] = d;
+    }
+
+    // One triangle, weighing one -- the convention `quadric3_set_from_vector4` sets for the
+    // geometric quadric this one is summed with, and what makes the two commensurate.
+    out[out_offset + 10] = 1;
+
+    return true;
+}

package/src/core/geom/3d/quadric/quadric_attribute_size.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How many elements an attribute quadric over `components` scalar channels occupies.
+ *
+ * `QUADRIC3_SIZE` of header — which is a {@link Quadric3} in layout as well as in size, so every
+ * `quadric3_*` function reads it — followed by four per channel: the accumulated gradient and the
+ * accumulated offset of that channel's linear field.
+ *
+ * This is Hoppe's form (*New Quadric Metric for Simplifying Meshes with Appearance Attributes*,
+ * 1999) rather than the naive lift of Garland & Heckbert's metric into `3 + m` dimensions, which
+ * would need `(m + 4)(m + 5) / 2` elements and a solve of the same order. Both answer the same
+ * question; at five channels this is 31 elements against 36, at thirteen it is 63 against 136, and
+ * the placement solve stays 3x3 either way.
+ *
+ * @param {number} components number of scalar channels
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_size(components: number): number;
+//# sourceMappingURL=quadric_attribute_size.d.ts.map

package/src/core/geom/3d/quadric/quadric_attribute_size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadric_attribute_size.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric_attribute_size.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,mDANW,MAAM,GACJ,MAAM,CAOlB"}

package/src/core/geom/3d/quadric/quadric_attribute_size.js

@@ -0,0 +1,24 @@
+import { QUADRIC3_SIZE } from "./QUADRIC3_SIZE.js";
+
+/**
+ * How many elements an attribute quadric over `components` scalar channels occupies.
+ *
+ * `QUADRIC3_SIZE` of header — which is a {@link Quadric3} in layout as well as in size, so every
+ * `quadric3_*` function reads it — followed by four per channel: the accumulated gradient and the
+ * accumulated offset of that channel's linear field.
+ *
+ * This is Hoppe's form (*New Quadric Metric for Simplifying Meshes with Appearance Attributes*,
+ * 1999) rather than the naive lift of Garland & Heckbert's metric into `3 + m` dimensions, which
+ * would need `(m + 4)(m + 5) / 2` elements and a solve of the same order. Both answer the same
+ * question; at five channels this is 31 elements against 36, at thirteen it is 63 against 136, and
+ * the placement solve stays 3x3 either way.
+ *
+ * @param {number} components number of scalar channels
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_size(components) {
+    return QUADRIC3_SIZE + components * 4;
+}

package/src/core/geom/3d/quadric/quadric_attribute_solve.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The attribute values that best explain everything a quadric has accumulated, at a given position.
+ *
+ * `s_i = (G_i . v + D_i) / W`, which is exact rather than iterative: the channels enter the
+ * accumulated error only quadratically and separably, so each one's minimum is where its derivative
+ * is zero and there is nothing to search. {@link quadric_attribute_reduce} is the same substitution
+ * seen from the other side.
+ *
+ * The result is a **fit**, not an average, and it is not confined to the values that went in. That is
+ * correct and is the point: a linear field extrapolates, and a vertex placed a little outside the
+ * patch it stands for should carry the value the patch's field has *there*. A caller whose channel
+ * has a range — a colour, say — clamps afterwards; a caller whose channel is a direction
+ * renormalizes.
+ *
+ * Nothing comes back for a quadric that has accumulated nothing. There is no field to evaluate, and
+ * inventing one would be worse than leaving the caller its own value.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination, `components` elements from
+ *     `out_offset`, written only when this returns `true`
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} q `quadric_attribute_size(components)` elements from `q_offset`
+ * @param {number} q_offset
+ * @param {number} components number of scalar channels
+ * @param {ArrayLike<number>} weights one per channel, the same ones the quadric was built with
+ * @param {number} x position to evaluate the field at
+ * @param {number} y
+ * @param {number} z
+ * @returns {boolean} whether there was a field to evaluate
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_solve(out: number[] | Float32Array | Float64Array, out_offset: number, q: ArrayLike<number>, q_offset: number, components: number, weights: ArrayLike<number>, x: number, y: number, z: number): boolean;
+//# sourceMappingURL=quadric_attribute_solve.d.ts.map

package/src/core/geom/3d/quadric/quadric_attribute_solve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadric_attribute_solve.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric_attribute_solve.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,6CAfW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAElC,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,cACN,MAAM,WACN,UAAU,MAAM,CAAC,KACjB,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAyBnB"}

package/src/core/geom/3d/quadric/quadric_attribute_solve.js

@@ -0,0 +1,55 @@
+import { QUADRIC3_SIZE } from "./QUADRIC3_SIZE.js";
+
+/**
+ * The attribute values that best explain everything a quadric has accumulated, at a given position.
+ *
+ * `s_i = (G_i . v + D_i) / W`, which is exact rather than iterative: the channels enter the
+ * accumulated error only quadratically and separably, so each one's minimum is where its derivative
+ * is zero and there is nothing to search. {@link quadric_attribute_reduce} is the same substitution
+ * seen from the other side.
+ *
+ * The result is a **fit**, not an average, and it is not confined to the values that went in. That is
+ * correct and is the point: a linear field extrapolates, and a vertex placed a little outside the
+ * patch it stands for should carry the value the patch's field has *there*. A caller whose channel
+ * has a range — a colour, say — clamps afterwards; a caller whose channel is a direction
+ * renormalizes.
+ *
+ * Nothing comes back for a quadric that has accumulated nothing. There is no field to evaluate, and
+ * inventing one would be worse than leaving the caller its own value.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination, `components` elements from
+ *     `out_offset`, written only when this returns `true`
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} q `quadric_attribute_size(components)` elements from `q_offset`
+ * @param {number} q_offset
+ * @param {number} components number of scalar channels
+ * @param {ArrayLike<number>} weights one per channel, the same ones the quadric was built with
+ * @param {number} x position to evaluate the field at
+ * @param {number} y
+ * @param {number} z
+ * @returns {boolean} whether there was a field to evaluate
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_solve(
+    out, out_offset, q, q_offset, components, weights, x, y, z
+) {
+    const weight = q[q_offset + 10];
+
+    if (weight <= 0) {
+        return false;
+    }
+
+    for (let component = 0; component < components; component++) {
+        const tail = q_offset + QUADRIC3_SIZE + component * 4;
+
+        const value = (q[tail] * x + q[tail + 1] * y + q[tail + 2] * z + q[tail + 3]) / weight;
+
+        // Built over `weight * s` so the residual would compare with a squared length; this is where
+        // that comes back off.
+        out[out_offset + component] = value / weights[component];
+    }
+
+    return true;
+}

package/src/core/geom/3d/quadric/quadric_attribute_sub.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Subtract one attribute quadric from another, elementwise — the inverse of
+ * {@link quadric_attribute_add}.
+ *
+ * What it is for is the same thing {@link quadric3_sub} is for: recovering what a pass *added* to a
+ * quadric, when two passes started from the same one. Two group steps sharing a pinned boundary
+ * vertex each begin from that vertex's quadric and each fold their own victims onto it, so the two
+ * results overlap by exactly the quadric they both began with; adding them whole would count the
+ * source under that vertex twice.
+ *
+ * The difference of two quadrics is not itself a sum of anything, and its weight can come out
+ * negative. Nothing here objects — a gain is meant to be added back to the quadric it was measured
+ * against, not evaluated on its own.
+ *
+ * @param {number[]|Float32Array|Float64Array} out `quadric_attribute_size(components)` elements from
+ *     `out_offset`; may alias either input
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} a
+ * @param {number} a_offset
+ * @param {ArrayLike<number>} b subtracted from `a`
+ * @param {number} b_offset
+ * @param {number} components number of scalar channels
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_sub(out: number[] | Float32Array | Float64Array, out_offset: number, a: ArrayLike<number>, a_offset: number, b: ArrayLike<number>, b_offset: number, components: number): void;
+//# sourceMappingURL=quadric_attribute_sub.d.ts.map

package/src/core/geom/3d/quadric/quadric_attribute_sub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadric_attribute_sub.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric_attribute_sub.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAElC,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,cACN,MAAM,QAWhB"}

package/src/core/geom/3d/quadric/quadric_attribute_sub.js

@@ -0,0 +1,35 @@
+import { QUADRIC3_SIZE } from "./QUADRIC3_SIZE.js";
+
+/**
+ * Subtract one attribute quadric from another, elementwise — the inverse of
+ * {@link quadric_attribute_add}.
+ *
+ * What it is for is the same thing {@link quadric3_sub} is for: recovering what a pass *added* to a
+ * quadric, when two passes started from the same one. Two group steps sharing a pinned boundary
+ * vertex each begin from that vertex's quadric and each fold their own victims onto it, so the two
+ * results overlap by exactly the quadric they both began with; adding them whole would count the
+ * source under that vertex twice.
+ *
+ * The difference of two quadrics is not itself a sum of anything, and its weight can come out
+ * negative. Nothing here objects — a gain is meant to be added back to the quadric it was measured
+ * against, not evaluated on its own.
+ *
+ * @param {number[]|Float32Array|Float64Array} out `quadric_attribute_size(components)` elements from
+ *     `out_offset`; may alias either input
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} a
+ * @param {number} a_offset
+ * @param {ArrayLike<number>} b subtracted from `a`
+ * @param {number} b_offset
+ * @param {number} components number of scalar channels
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_sub(out, out_offset, a, a_offset, b, b_offset, components) {
+    const size = QUADRIC3_SIZE + components * 4;
+
+    for (let i = 0; i < size; i++) {
+        out[out_offset + i] = a[a_offset + i] - b[b_offset + i];
+    }
+}

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

@@ -107,6 +107,21 @@ export class BinaryDataBlock {
      * @param {number} source_id element id in `source`
      */
     copy_record(id: number, source: BinaryDataBlock, source_id: number): void;
+    /**
+     * Do two records hold the same bytes?
+     *
+     * Bytes, not values, and that is the point: this is the test a *wedge* is defined by — a set of
+     * corners at one vertex that shade identically — and identity has to be exact for the grouping
+     * to be an equivalence relation. A tolerance is not transitive, so grouping by one would depend
+     * on the order the corners were visited in, and two runs over the same mesh could disagree.
+     *
+     * Every byte of the record, so a block gaining a layer needs nothing here.
+     *
+     * @param {number} a element id in this block
+     * @param {number} b element id in this block
+     * @returns {boolean}
+     */
+    record_equal(a: number, b: number): boolean;
     /**
      * Take on another block's layers and contents.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"BinaryDataBlock.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryDataBlock.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAwCI;;OAEG;IACH,kBAFW,iBAAiB,EAM3B;IAED;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;OAEG;IACH,0BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAJW,cAAc,cACd,MAAM,GACJ,eAAe,CAa3B;IAED;;;OAGG;IACH,0BAFW,MAAM,QAUhB;IAED;;;OAGG;IACH,sBAEC;IAED;;OAEG;IACH,aAQC;IAED;;;;;;;;OAQG;IACH,QAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAJW,MAAM,UACN,eAAe,aACf,MAAM,QAchB;IAED;;;;;;;;OAQG;IACH,YAFW,eAAe,QAyBzB;IA8CL;;;;OAIG;IACH,4BAFU,OAAO,CAE0B;;CAP1C;6BAlTY,OAAO,8CAA8C,EAAE,cAAc;gCACrE,OAAO,wBAAwB,EAAE,iBAAiB;gCAJ/B,sBAAsB"}
+{"version":3,"file":"BinaryDataBlock.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryDataBlock.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAwCI;;OAEG;IACH,kBAFW,iBAAiB,EAM3B;IAED;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;OAEG;IACH,0BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAJW,cAAc,cACd,MAAM,GACJ,eAAe,CAa3B;IAED;;;OAGG;IACH,0BAFW,MAAM,QAUhB;IAED;;;OAGG;IACH,sBAEC;IAED;;OAEG;IACH,aAQC;IAED;;;;;;;;OAQG;IACH,QAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAJW,MAAM,UACN,eAAe,aACf,MAAM,QAchB;IAED;;;;;;;;;;;;;OAaG;IACH,gBAJW,MAAM,KACN,MAAM,GACJ,OAAO,CAqBnB;IAED;;;;;;;;OAQG;IACH,YAFW,eAAe,QAyBzB;IA8CL;;;;OAIG;IACH,4BAFU,OAAO,CAE0B;;CAP1C;6BArVY,OAAO,8CAA8C,EAAE,cAAc;gCACrE,OAAO,wBAAwB,EAAE,iBAAiB;gCAJ/B,sBAAsB"}

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

@@ -233,6 +233,41 @@ export class BinaryDataBlock {
         );
     }
 
+    /**
+     * Do two records hold the same bytes?
+     *
+     * Bytes, not values, and that is the point: this is the test a *wedge* is defined by — a set of
+     * corners at one vertex that shade identically — and identity has to be exact for the grouping
+     * to be an equivalence relation. A tolerance is not transitive, so grouping by one would depend
+     * on the order the corners were visited in, and two runs over the same mesh could disagree.
+     *
+     * Every byte of the record, so a block gaining a layer needs nothing here.
+     *
+     * @param {number} a element id in this block
+     * @param {number} b element id in this block
+     * @returns {boolean}
+     */
+    record_equal(a, b) {
+        if (a === b) {
+            return true;
+        }
+
+        const record_size = this.#record_size;
+
+        const from_a = a * record_size;
+        const from_b = b * record_size;
+
+        const data = this.#data_uint8;
+
+        for (let offset = 0; offset < record_size; offset++) {
+            if (data[from_a + offset] !== data[from_b + offset]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
     /**
      * Take on another block's layers and contents.
      *