@driftengine/physics 3.61.0

package/dist/decompose.js

@@ -0,0 +1,979 @@
+import { hullShape } from './shape.js';
+import { createMassProperties, shapeMassProperties } from './mass.js';
+import { MAX_BODY_PARTS } from './compoundContact.js';
+/** The default `maxHulls`, chosen so a decomposed body is well inside `MAX_BODY_PARTS`. */
+export const DEFAULT_MAX_HULLS = 16;
+/** The default and maximum grids. See `DecomposeOptions.resolution`. */
+export const DEFAULT_RESOLUTION = 64;
+export const MAX_RESOLUTION = 256;
+const OUTSIDE = 0;
+const SURFACE = 1;
+const INSIDE = 2;
+/**
+ * The directions a region's extreme corners are kept along, as integer vectors.
+ *
+ * **Fifty of them, and every one is integers**, so the table is built by arithmetic and nothing here
+ * reaches for a transcendental the determinism gate would refuse — `packages/physics/src` is a
+ * declared root of it and this file is inside the scan.
+ *
+ * They are an octahedron's own directions taken three ways: its six vertices, the twelve midpoints
+ * of its edges, the eight centres of its faces, and the twenty-four points halfway between a vertex
+ * and an edge midpoint. That is a 50-DOP, whose worst angular gap leaves a support hull within about
+ * two per cent of the true hull of the same corners — small against a region that is a fraction of
+ * the mesh, and measured by `Decomposition.coverage` rather than trusted.
+ *
+ * **Fifty and not sixty-four** because these four families are what an octahedron gives without
+ * inventing a direction; the next family would be twenty-four more and overrun `hullShape`'s cap of
+ * sixty-four points. Nothing is gained by padding the set to the cap.
+ */
+const DIRECTIONS = buildDirections();
+/** How many, which is also the most points any part can carry. */
+export const SUPPORT_DIRECTIONS = DIRECTIONS.length / 3;
+function buildDirections() {
+    const families = [
+        [1, 0, 0],
+        [1, 1, 0],
+        [1, 1, 1],
+        [2, 1, 0],
+    ];
+    const seen = new Set();
+    const out = [];
+    for (const [a, b, c] of families) {
+        /*
+         * Every distinct permutation of the family's magnitudes, with every sign on every non-zero
+         * component. A zero has one sign and not two, which is what keeps (1,0,0) from arriving twice.
+         */
+        for (const p of permutations(a, b, c)) {
+            for (let s = 0; s < 8; s++) {
+                const x = p[0] * (s & 1 ? -1 : 1);
+                const y = p[1] * (s & 2 ? -1 : 1);
+                const z = p[2] * (s & 4 ? -1 : 1);
+                const key = `${x},${y},${z}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push(x, y, z);
+            }
+        }
+    }
+    return new Int32Array(out);
+}
+function permutations(a, b, c) {
+    const all = [
+        [a, b, c],
+        [a, c, b],
+        [b, a, c],
+        [b, c, a],
+        [c, a, b],
+        [c, b, a],
+    ];
+    const seen = new Set();
+    const out = [];
+    for (const p of all) {
+        const key = p.join(',');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(p);
+    }
+    return out;
+}
+export function decomposeConvex(positions, indices, options = {}) {
+    const resolution = Math.trunc(options.resolution ?? DEFAULT_RESOLUTION);
+    const maxHulls = Math.trunc(options.maxHulls ?? DEFAULT_MAX_HULLS);
+    const concavity = options.concavity ?? 0.05;
+    const fill = options.fill ?? 'solid';
+    if (resolution < 4 || resolution > MAX_RESOLUTION) {
+        throw new Error(`decomposeConvex: resolution must be between 4 and ${MAX_RESOLUTION}, got ${resolution}`);
+    }
+    if (maxHulls < 1 || maxHulls > MAX_BODY_PARTS) {
+        throw new Error(`decomposeConvex: maxHulls must be between 1 and ${MAX_BODY_PARTS}, got ${maxHulls}`);
+    }
+    if (!(concavity >= 0) || concavity >= 1) {
+        throw new Error(`decomposeConvex: concavity must be at least 0 and below 1, got ${concavity}`);
+    }
+    if (indices.length % 3 !== 0) {
+        throw new Error(`decomposeConvex: ${indices.length} indices is not a whole number of triangles`);
+    }
+    if (indices.length === 0)
+        throw new Error('decomposeConvex: no triangles');
+    const grid = buildGrid(positions, resolution);
+    const state = new Uint8Array(grid.nx * grid.ny * grid.nz);
+    voxelise(positions, indices, grid, state);
+    if (fill === 'solid')
+        fillOutside(grid, state);
+    /*
+     * `fillOutside` marks what the flood reached; everything it did not reach and did not already own
+     * is interior. Under `'surface'` the pass never ran, so nothing is interior and the shell stands
+     * alone — which is the whole difference between the two settings.
+     */
+    const solid = new Uint8Array(state.length);
+    let solidCells = 0;
+    for (let i = 0; i < state.length; i++) {
+        const s = state[i] ?? OUTSIDE;
+        if (s === SURFACE || (fill === 'solid' && s === INSIDE)) {
+            solid[i] = 1;
+            solidCells++;
+        }
+    }
+    if (solidCells === 0) {
+        throw new Error('decomposeConvex: the mesh occupied no cells — it is thinner than one cell at this resolution');
+    }
+    const regions = growRegions(grid, solid, concavity);
+    mergeRegions(regions, maxHulls, concavity, grid.cell * grid.cell * grid.cell);
+    const parts = buildParts(grid, solid, regions);
+    const cellVolume = grid.cell * grid.cell * grid.cell;
+    const sourceVolume = solidCells * cellVolume;
+    let hullVolume = 0;
+    for (const part of parts.parts)
+        hullVolume += part.volume;
+    return {
+        parts: parts.parts,
+        sourceVolume,
+        hullVolume,
+        bloat: (hullVolume - sourceVolume) / sourceVolume,
+        coverage: parts.covered / solidCells,
+        resolution,
+        cells: state.length,
+    };
+}
+/**
+ * Cubic cells, sized by the longest axis, with one cell of padding on every side.
+ *
+ * **The padding is what makes the flood fill correct rather than nearly correct.** A mesh whose face
+ * sits exactly on the grid's boundary would have no outside cell on that side to flood from, and the
+ * fill would leave the whole slab beyond it marked interior — a solid wall where the model has a
+ * flat back. One ring of empty cells removes the case entirely.
+ */
+function buildGrid(positions, resolution) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let i = 0; i + 2 < positions.length; i += 3) {
+        const x = positions[i];
+        const y = positions[i + 1];
+        const z = positions[i + 2];
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (z < minZ)
+            minZ = z;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+        if (z > maxZ)
+            maxZ = z;
+    }
+    if (!(maxX >= minX))
+        throw new Error('decomposeConvex: no positions');
+    const spanX = maxX - minX;
+    const spanY = maxY - minY;
+    const spanZ = maxZ - minZ;
+    const longest = Math.max(spanX, Math.max(spanY, spanZ));
+    if (!(longest > 0))
+        throw new Error('decomposeConvex: the mesh has no extent');
+    const cell = longest / resolution;
+    /* Two cells of padding in each axis, one at each end, hence the +2 on every count. */
+    const nx = Math.max(1, Math.ceil(spanX / cell)) + 2;
+    const ny = Math.max(1, Math.ceil(spanY / cell)) + 2;
+    const nz = Math.max(1, Math.ceil(spanZ / cell)) + 2;
+    return {
+        originX: minX - cell,
+        originY: minY - cell,
+        originZ: minZ - cell,
+        cell,
+        nx,
+        ny,
+        nz,
+    };
+}
+/** Cell index from coordinates. x fastest, then y, then z — the order every walk here uses. */
+function at(grid, x, y, z) {
+    return x + grid.nx * (y + grid.ny * z);
+}
+/**
+ * Every cell a triangle touches, marked `SURFACE`.
+ *
+ * The overlap test is the standard thirteen-axis separating-axis test between a triangle and an
+ * axis-aligned box: the box's three face normals, the triangle's own normal, and the nine cross
+ * products of a triangle edge with a box axis. It uses multiplication, addition, `Math.abs`,
+ * `Math.min` and `Math.max` and nothing else, which is what keeps it inside the determinism gate.
+ *
+ * **Conservative on purpose.** A cell that the triangle only grazes is marked, so a surface is never
+ * one cell thin where it should be closed — a hole in the shell is what lets the flood fill escape
+ * and turn a solid into a hollow one, and it is much cheaper to over-mark than to detect that later.
+ */
+function voxelise(positions, indices, grid, state) {
+    /*
+     * **The cell box is grown by one part in a million, and that is the difference between a shell
+     * that holds and one with a hole straight through it.**
+     *
+     * A face lying exactly in a cell boundary plane is not an edge case in this domain — it is what
+     * every floor, wall, lid and cap in every model does, and the fans that close a prism are two of
+     * them. Such a face is exactly tangent to the boxes on both sides, so the plane test compares two
+     * quantities that are equal in exact arithmetic and differ by a rounding step in this one. When it
+     * falls the wrong way *neither* neighbour is marked, the flood walks straight through the gap, and
+     * the whole interior comes back empty.
+     *
+     * Measured on a closed twenty-four-sided prism of true volume 3.106: the fill answered 3.57, 0.56,
+     * 0.47, 3.37, 3.33, 3.31, 0.20 and 0.17 at resolutions 32 through 96 — correct at four of them and
+     * the bare shell at the other four, with nothing in the shape to explain which. The escape path
+     * ran down the axis and out through the base, whose disc sits exactly on the boundary between two
+     * cell rows.
+     *
+     * **Growing the box is the right direction to be wrong in.** This marking is conservative by
+     * design: a cell marked that need not be costs a little accuracy at the surface, and a cell missed
+     * that should be marked is a hole. The epsilon is ten orders of magnitude above the rounding it
+     * covers and six below a cell, so it can decide a tangency and can decide nothing else.
+     */
+    const TANGENCY = 1e-6;
+    const half = grid.cell * (0.5 + TANGENCY);
+    for (let t = 0; t + 2 < indices.length; t += 3) {
+        const i0 = indices[t] * 3;
+        const i1 = indices[t + 1] * 3;
+        const i2 = indices[t + 2] * 3;
+        const ax = positions[i0];
+        const ay = positions[i0 + 1];
+        const az = positions[i0 + 2];
+        const bx = positions[i1];
+        const by = positions[i1 + 1];
+        const bz = positions[i1 + 2];
+        const cx = positions[i2];
+        const cy = positions[i2 + 1];
+        const cz = positions[i2 + 2];
+        const loX = cellOf(Math.min(ax, Math.min(bx, cx)), grid.originX, grid.cell, grid.nx);
+        const hiX = cellOf(Math.max(ax, Math.max(bx, cx)), grid.originX, grid.cell, grid.nx);
+        const loY = cellOf(Math.min(ay, Math.min(by, cy)), grid.originY, grid.cell, grid.ny);
+        const hiY = cellOf(Math.max(ay, Math.max(by, cy)), grid.originY, grid.cell, grid.ny);
+        const loZ = cellOf(Math.min(az, Math.min(bz, cz)), grid.originZ, grid.cell, grid.nz);
+        const hiZ = cellOf(Math.max(az, Math.max(bz, cz)), grid.originZ, grid.cell, grid.nz);
+        for (let z = loZ; z <= hiZ; z++) {
+            const centreZ = grid.originZ + (z + 0.5) * grid.cell;
+            for (let y = loY; y <= hiY; y++) {
+                const centreY = grid.originY + (y + 0.5) * grid.cell;
+                for (let x = loX; x <= hiX; x++) {
+                    const index = at(grid, x, y, z);
+                    if (state[index] === SURFACE)
+                        continue;
+                    const centreX = grid.originX + (x + 0.5) * grid.cell;
+                    if (triangleTouchesBox(ax - centreX, ay - centreY, az - centreZ, bx - centreX, by - centreY, bz - centreZ, cx - centreX, cy - centreY, cz - centreZ, half)) {
+                        state[index] = SURFACE;
+                    }
+                }
+            }
+        }
+    }
+}
+/** Which cell a coordinate falls in, clamped into the grid. */
+function cellOf(value, origin, cell, count) {
+    const raw = Math.floor((value - origin) / cell);
+    return Math.min(count - 1, Math.max(0, raw));
+}
+/**
+ * The thirteen-axis test, with the triangle already translated so the box is at the origin.
+ *
+ * `half` is the box's half-extent, the same on all three axes because the cells are cubes.
+ */
+function triangleTouchesBox(ax, ay, az, bx, by, bz, cx, cy, cz, half) {
+    /* The box's own three axes first: they reject the great majority of candidates for one compare. */
+    if (Math.min(ax, Math.min(bx, cx)) > half || Math.max(ax, Math.max(bx, cx)) < -half)
+        return false;
+    if (Math.min(ay, Math.min(by, cy)) > half || Math.max(ay, Math.max(by, cy)) < -half)
+        return false;
+    if (Math.min(az, Math.min(bz, cz)) > half || Math.max(az, Math.max(bz, cz)) < -half)
+        return false;
+    const e0x = bx - ax;
+    const e0y = by - ay;
+    const e0z = bz - az;
+    const e1x = cx - bx;
+    const e1y = cy - by;
+    const e1z = cz - bz;
+    const e2x = ax - cx;
+    const e2y = ay - cy;
+    const e2z = az - cz;
+    /* The triangle's own plane against the box. */
+    const nx = e0y * e1z - e0z * e1y;
+    const ny = e0z * e1x - e0x * e1z;
+    const nz = e0x * e1y - e0y * e1x;
+    const d = nx * ax + ny * ay + nz * az;
+    const reach = half * (Math.abs(nx) + Math.abs(ny) + Math.abs(nz));
+    if (d > reach || d < -reach)
+        return false;
+    /* And the nine edge-by-axis crosses. */
+    if (!axisTest(e0z, -e0y, ay, az, by, bz, cy, cz, half))
+        return false;
+    if (!axisTest(-e0z, e0x, ax, az, bx, bz, cx, cz, half))
+        return false;
+    if (!axisTest(e0y, -e0x, ax, ay, bx, by, cx, cy, half))
+        return false;
+    if (!axisTest(e1z, -e1y, ay, az, by, bz, cy, cz, half))
+        return false;
+    if (!axisTest(-e1z, e1x, ax, az, bx, bz, cx, cz, half))
+        return false;
+    if (!axisTest(e1y, -e1x, ax, ay, bx, by, cx, cy, half))
+        return false;
+    if (!axisTest(e2z, -e2y, ay, az, by, bz, cy, cz, half))
+        return false;
+    if (!axisTest(-e2z, e2x, ax, az, bx, bz, cx, cz, half))
+        return false;
+    if (!axisTest(e2y, -e2x, ax, ay, bx, by, cx, cy, half))
+        return false;
+    return true;
+}
+/**
+ * One separating-axis test, in the plane the axis lives in.
+ *
+ * Every one of the nine crosses has a zero component, so each reduces to a two-dimensional dot
+ * product against the two triangle corners that are not on the edge — which is why this takes two
+ * multipliers and three pairs of coordinates instead of three vectors.
+ */
+function axisTest(u, v, a0, a1, b0, b1, c0, c1, half) {
+    const pa = u * a0 + v * a1;
+    const pb = u * b0 + v * b1;
+    const pc = u * c0 + v * c1;
+    const lo = Math.min(pa, Math.min(pb, pc));
+    const hi = Math.max(pa, Math.max(pb, pc));
+    const reach = half * (Math.abs(u) + Math.abs(v));
+    return !(lo > reach || hi < -reach);
+}
+/**
+ * Everything the outside can reach, marked `OUTSIDE`; everything else becomes `INSIDE`.
+ *
+ * A breadth-first flood from every cell of the grid's boundary. The padding `buildGrid` added
+ * guarantees that boundary is empty, so the flood always has somewhere to start.
+ */
+function fillOutside(grid, state) {
+    const visited = new Uint8Array(state.length);
+    const queue = new Int32Array(state.length);
+    let head = 0;
+    let tail = 0;
+    const push = (index) => {
+        if (visited[index] === 1 || state[index] === SURFACE)
+            return;
+        visited[index] = 1;
+        queue[tail++] = index;
+    };
+    for (let z = 0; z < grid.nz; z++) {
+        for (let y = 0; y < grid.ny; y++) {
+            for (let x = 0; x < grid.nx; x++) {
+                const onBoundary = x === 0 ||
+                    y === 0 ||
+                    z === 0 ||
+                    x === grid.nx - 1 ||
+                    y === grid.ny - 1 ||
+                    z === grid.nz - 1;
+                if (onBoundary)
+                    push(at(grid, x, y, z));
+            }
+        }
+    }
+    while (head < tail) {
+        const index = queue[head++];
+        const x = index % grid.nx;
+        const y = Math.floor(index / grid.nx) % grid.ny;
+        const z = Math.floor(index / (grid.nx * grid.ny));
+        if (x > 0)
+            push(index - 1);
+        if (x < grid.nx - 1)
+            push(index + 1);
+        if (y > 0)
+            push(index - grid.nx);
+        if (y < grid.ny - 1)
+            push(index + grid.nx);
+        if (z > 0)
+            push(index - grid.nx * grid.ny);
+        if (z < grid.nz - 1)
+            push(index + grid.nx * grid.ny);
+    }
+    for (let i = 0; i < state.length; i++) {
+        if (state[i] === SURFACE)
+            continue;
+        state[i] = visited[i] === 1 ? OUTSIDE : INSIDE;
+    }
+}
+/**
+ * Every solid cell claimed by a maximal box of solid cells.
+ *
+ * **Seeds are exact boxes, and that is what makes the result stable.** The first version of this
+ * grew a region by breadth-first search while its own bounding box stayed 95% full, which sounds
+ * like the same thing and is not: on a curved wall it produced regions that filled their box well
+ * enough to be accepted while wrapping far enough around the ring that the hull over them enclosed
+ * the cavity. The consequence was a decomposition that was excellent at one resolution and useless
+ * at the next — measured on a twenty-four-sided cup, **0.2% bloat at resolution 64 and 118% at 80**,
+ * with nothing between them to explain it. A box is convex, entirely, always, so a seed's hull is
+ * the seed and no resolution can make it otherwise. Every instability above came out of the seeding
+ * rather than out of the merge that follows it.
+ *
+ * **Cells are visited in index order, x fastest**, and each unclaimed one starts a box that extends
+ * a whole layer at a time in a fixed direction order while every cell of that layer is solid and
+ * unclaimed. A layer is accepted or it is not; a partial one is never taken, which is the property
+ * that keeps the box solid.
+ */
+function growRegions(grid, solid, concavity) {
+    void concavity;
+    const of = new Int32Array(solid.length).fill(-1);
+    const count = [];
+    const bounds = [];
+    /** Whether every cell of an inclusive box is solid and unclaimed. */
+    const layerFree = (x0, y0, z0, x1, y1, z1) => {
+        if (x0 < 0 || y0 < 0 || z0 < 0)
+            return false;
+        if (x1 >= grid.nx || y1 >= grid.ny || z1 >= grid.nz)
+            return false;
+        for (let z = z0; z <= z1; z++) {
+            for (let y = y0; y <= y1; y++) {
+                for (let x = x0; x <= x1; x++) {
+                    const index = at(grid, x, y, z);
+                    if (solid[index] !== 1 || of[index] !== -1)
+                        return false;
+                }
+            }
+        }
+        return true;
+    };
+    for (let seed = 0; seed < solid.length; seed++) {
+        if (solid[seed] !== 1 || of[seed] !== -1)
+            continue;
+        const region = count.length;
+        let minX = seed % grid.nx;
+        let minY = Math.floor(seed / grid.nx) % grid.ny;
+        let minZ = Math.floor(seed / (grid.nx * grid.ny));
+        let maxX = minX;
+        let maxY = minY;
+        let maxZ = minZ;
+        /*
+         * Six directions, in a fixed order, repeated until a whole pass adds nothing. Fixed order and
+         * whole layers are together what make two machines produce the same boxes from the same grid.
+         */
+        for (let growing = true; growing;) {
+            growing = false;
+            if (layerFree(minX - 1, minY, minZ, minX - 1, maxY, maxZ)) {
+                minX--;
+                growing = true;
+            }
+            if (layerFree(maxX + 1, minY, minZ, maxX + 1, maxY, maxZ)) {
+                maxX++;
+                growing = true;
+            }
+            if (layerFree(minX, minY - 1, minZ, maxX, minY - 1, maxZ)) {
+                minY--;
+                growing = true;
+            }
+            if (layerFree(minX, maxY + 1, minZ, maxX, maxY + 1, maxZ)) {
+                maxY++;
+                growing = true;
+            }
+            if (layerFree(minX, minY, minZ - 1, maxX, maxY, minZ - 1)) {
+                minZ--;
+                growing = true;
+            }
+            if (layerFree(minX, minY, maxZ + 1, maxX, maxY, maxZ + 1)) {
+                maxZ++;
+                growing = true;
+            }
+        }
+        for (let z = minZ; z <= maxZ; z++) {
+            for (let y = minY; y <= maxY; y++) {
+                for (let x = minX; x <= maxX; x++)
+                    of[at(grid, x, y, z)] = region;
+            }
+        }
+        count.push((maxX - minX + 1) * (maxY - minY + 1) * (maxZ - minZ + 1));
+        bounds.push(minX, minY, minZ, maxX, maxY, maxZ);
+    }
+    const total = count.length;
+    const directions = SUPPORT_DIRECTIONS;
+    const supports = new Float64Array(total * directions * 3);
+    const bestDot = new Float64Array(total * directions).fill(-Infinity);
+    for (let region = 0; region < total; region++) {
+        const b = region * 6;
+        for (let corner = 0; corner < 8; corner++) {
+            const cx = bounds[b + (corner & 1 ? 3 : 0)] + (corner & 1 ? 1 : 0);
+            const cy = bounds[b + (corner & 2 ? 4 : 1)] + (corner & 2 ? 1 : 0);
+            const cz = bounds[b + (corner & 4 ? 5 : 2)] + (corner & 4 ? 1 : 0);
+            const px = grid.originX + cx * grid.cell;
+            const py = grid.originY + cy * grid.cell;
+            const pz = grid.originZ + cz * grid.cell;
+            offerSupport(supports, bestDot, region, px, py, pz);
+        }
+    }
+    const regions = {
+        of,
+        count: Int32Array.from(count),
+        bounds: Int32Array.from(bounds),
+        parent: new Int32Array(total).map((_, i) => i),
+        neighbours: [],
+        supports,
+        bestDot,
+        live: total,
+        total,
+    };
+    for (let i = 0; i < total; i++)
+        regions.neighbours.push(new Set());
+    /*
+     * Adjacency, from one walk over the grid looking only forward. Looking both ways would find every
+     * pair twice and the set would answer the same, so the walk is halved.
+     */
+    for (let z = 0; z < grid.nz; z++) {
+        for (let y = 0; y < grid.ny; y++) {
+            for (let x = 0; x < grid.nx; x++) {
+                const index = at(grid, x, y, z);
+                const a = of[index];
+                if (a < 0)
+                    continue;
+                if (x + 1 < grid.nx)
+                    link(regions, a, of[index + 1]);
+                if (y + 1 < grid.ny)
+                    link(regions, a, of[index + grid.nx]);
+                if (z + 1 < grid.nz)
+                    link(regions, a, of[index + grid.nx * grid.ny]);
+            }
+        }
+    }
+    return regions;
+}
+/** Keep a point if it reaches further along any direction than what the region already had. */
+function offerSupport(supports, bestDot, region, x, y, z) {
+    const directions = SUPPORT_DIRECTIONS;
+    for (let d = 0; d < directions; d++) {
+        const dot = DIRECTIONS[d * 3] * x +
+            DIRECTIONS[d * 3 + 1] * y +
+            DIRECTIONS[d * 3 + 2] * z;
+        const k = region * directions + d;
+        if (dot <= bestDot[k])
+            continue;
+        bestDot[k] = dot;
+        supports[k * 3] = x;
+        supports[k * 3 + 1] = y;
+        supports[k * 3 + 2] = z;
+    }
+}
+function link(regions, a, b) {
+    if (b < 0 || a === b)
+        return;
+    regions.neighbours[a].add(b);
+    regions.neighbours[b].add(a);
+}
+function find(regions, id) {
+    let root = id;
+    while (regions.parent[root] !== root)
+        root = regions.parent[root];
+    let walk = id;
+    while (regions.parent[walk] !== walk) {
+        const next = regions.parent[walk];
+        regions.parent[walk] = root;
+        walk = next;
+    }
+    return root;
+}
+/**
+ * Neighbouring regions merged until the count is one a body can hold, then while it is free.
+ *
+ * **Two phases, measured two ways, and the split is the whole design.** Reaching the part budget
+ * takes as many merges as there are regions, which is thousands: those are ordered by the cheap box
+ * measure, which is good at saying *which* merge is least bad and useless at saying whether any
+ * merge is worth making. Going below the budget takes at most a handful, and each of those asks the
+ * real question — how much of the merged hull would not be solid — because that is the only measure
+ * that separates a convex solid, where merging costs nothing, from a cavity, where it costs the
+ * cavity.
+ *
+ * **The tie-break is the determinism.** Two candidates with the same cost are ordered by their lower
+ * region id and then their higher one. Without it a heap orders equal costs by insertion, and two
+ * runs that inserted in a different order decompose the same mesh differently.
+ */
+function mergeRegions(regions, maxHulls, concavity, cellVolume) {
+    /*
+     * **Is the whole thing convex? Asked once, before anything is merged, because the pairwise merge
+     * below cannot answer it.** Greedy merging judges one pair at a time, and on a slanted solid every
+     * individual step looks bad while the end state is free: two boxes of a staircase have a notch
+     * between them, so their hull is a fifth empty and the merge is refused — even where merging *all*
+     * of them gives back the solid exactly.
+     *
+     * Measured on a tetrahedron, which is as convex as a shape can be: **sixteen parts and 20.3%
+     * bloat**, where the answer is one part and nothing. A crate, a wedge, a rock and a wheel are all
+     * this case, and it is much the most common thing a bake will meet.
+     *
+     * One hull over every region's supports answers it for the cost of a single `hullShape`.
+     */
+    if (regions.live > 1 && wholeConcavity(regions, cellVolume) <= concavity) {
+        for (let i = 1; i < regions.total; i++) {
+            const a = find(regions, 0);
+            const b = find(regions, i);
+            if (a !== b)
+                merge(regions, a, b);
+        }
+        return;
+    }
+    const heap = new CandidateHeap();
+    for (let a = 0; a < regions.total; a++) {
+        for (const b of regions.neighbours[a]) {
+            if (b > a)
+                heap.push(cost(regions, a, b), a, b);
+        }
+    }
+    while (regions.live > maxHulls) {
+        const top = heap.pop();
+        if (top === null)
+            break;
+        const a = find(regions, top.a);
+        const b = find(regions, top.b);
+        if (a === b)
+            continue;
+        /* A stale entry: one of the two has merged since, so its cost is no longer the pair's. */
+        const current = cost(regions, a, b);
+        if (current !== top.cost) {
+            heap.push(current, a, b);
+            continue;
+        }
+        merge(regions, a, b);
+        const root = find(regions, a);
+        for (const other of regions.neighbours[root]) {
+            heap.push(cost(regions, root, other), Math.min(root, other), Math.max(root, other));
+        }
+    }
+    /*
+     * The tail. At most `maxHulls` regions remain, so every adjacent pair can be measured properly and
+     * the answers cached; a merge invalidates only the pairs its region is part of.
+     */
+    const measured = new Map();
+    const keyOf = (a, b) => Math.min(a, b) * (regions.total + 1) + Math.max(a, b);
+    for (;;) {
+        let bestCost = Infinity;
+        let bestA = -1;
+        let bestB = -1;
+        for (let i = 0; i < regions.total; i++) {
+            const a = find(regions, i);
+            if (a !== i)
+                continue;
+            for (const raw of regions.neighbours[a]) {
+                const b = find(regions, raw);
+                if (b === a)
+                    continue;
+                const lo = Math.min(a, b);
+                const hi = Math.max(a, b);
+                const key = keyOf(lo, hi);
+                let value = measured.get(key);
+                if (value === undefined) {
+                    value = hullConcavity(regions, lo, hi, cellVolume);
+                    measured.set(key, value);
+                }
+                /* Ties resolve by the pair's ids, for the reason the heap has a tie-break. */
+                if (value < bestCost ||
+                    (value === bestCost && (lo < bestA || (lo === bestA && hi < bestB)))) {
+                    bestCost = value;
+                    bestA = lo;
+                    bestB = hi;
+                }
+            }
+        }
+        if (bestA < 0 || bestCost > concavity)
+            break;
+        merge(regions, bestA, bestB);
+        if (regions.live <= 1)
+            break;
+        const root = find(regions, bestA);
+        for (const key of [...measured.keys()]) {
+            const lo = Math.floor(key / (regions.total + 1));
+            const hi = key % (regions.total + 1);
+            if (find(regions, lo) === root || find(regions, hi) === root)
+                measured.delete(key);
+        }
+    }
+}
+/**
+ * The fraction of the hull over two regions that would not be solid.
+ *
+ * **The real measure, and the reason the support sets exist.** A region is a union of boxes, so its
+ * extreme point along any direction is a corner of one of them, and the hull over those points is
+ * the hull over the region. Comparing that hull's volume against the cells actually held says
+ * exactly what merging would cost: nothing for two halves of a cylinder, and the whole cavity for
+ * two walls facing each other across one.
+ *
+ * Measured at 1.09 ms for a fifty-point hull, which is why `mergeRegions` asks it about a hundred
+ * and fifty times and not a hundred and fifty thousand.
+ */
+function hullConcavity(regions, a, b, cellVolume) {
+    const directions = SUPPORT_DIRECTIONS;
+    const points = new Float32Array(directions * 3);
+    for (let d = 0; d < directions; d++) {
+        const ka = a * directions + d;
+        const kb = b * directions + d;
+        const from = regions.bestDot[kb] > regions.bestDot[ka] ? kb : ka;
+        points[d * 3] = regions.supports[from * 3];
+        points[d * 3 + 1] = regions.supports[from * 3 + 1];
+        points[d * 3 + 2] = regions.supports[from * 3 + 2];
+    }
+    const volume = shapeMassProperties(hullShape(points), 1, CONCAVITY_MASS).volume;
+    if (!(volume > 0))
+        return 1;
+    const solid = (regions.count[a] + regions.count[b]) * cellVolume;
+    return Math.max(0, (volume - solid) / volume);
+}
+/** The same question asked of every live region at once: is this solid already convex? */
+function wholeConcavity(regions, cellVolume) {
+    const directions = SUPPORT_DIRECTIONS;
+    const points = new Float32Array(directions * 3);
+    const best = new Float64Array(directions).fill(-Infinity);
+    let cells = 0;
+    for (let i = 0; i < regions.total; i++) {
+        if (find(regions, i) !== i)
+            continue;
+        cells += regions.count[i];
+        for (let d = 0; d < directions; d++) {
+            const k = i * directions + d;
+            if (regions.bestDot[k] <= best[d])
+                continue;
+            best[d] = regions.bestDot[k];
+            points[d * 3] = regions.supports[k * 3];
+            points[d * 3 + 1] = regions.supports[k * 3 + 1];
+            points[d * 3 + 2] = regions.supports[k * 3 + 2];
+        }
+    }
+    const volume = shapeMassProperties(hullShape(points), 1, CONCAVITY_MASS).volume;
+    if (!(volume > 0))
+        return 1;
+    return Math.max(0, (volume - cells * cellVolume) / volume);
+}
+/** Reused by `hullConcavity`, which the tail calls once per candidate pair. */
+const CONCAVITY_MASS = createMassProperties();
+/**
+ * How empty the box around two regions would be if they became one.
+ *
+ * **The cheap half of a two-part rule, and it only ever orders merges the budget forces.** Six
+ * integer compares and a divide, against a hull whose volume costs a millisecond, so this is what
+ * can be asked thousands of times while a mesh's regions come down to the part budget.
+ *
+ * **What it cannot answer is whether a merge is *free*, and three attempts to make it were wrong in
+ * three different ways.** A fixed threshold on this number can never join the last two halves of a
+ * cylinder, whose box is 21.5% empty however it is cut — a convex prism came back as eight parts.
+ * Scoring the change against the emptier parent fixes that and then runs away: each merge licenses
+ * the next against a laxer number, and a cup's wall merged around its own ring until the vessel was
+ * one hull holding 57% more than the cup. Anchoring the allowance so it cannot rise stops the
+ * runaway and brings back the eight-part prism. **A box cannot tell a convex solid from a cavity**,
+ * and that is not a rule to be tuned into existence. `hullConcavity` is what answers it, and
+ * `mergeRegions` calls it only where the count is small enough to afford one.
+ */
+function cost(regions, a, b) {
+    const ab = a * 6;
+    const bb = b * 6;
+    const minX = Math.min(regions.bounds[ab], regions.bounds[bb]);
+    const minY = Math.min(regions.bounds[ab + 1], regions.bounds[bb + 1]);
+    const minZ = Math.min(regions.bounds[ab + 2], regions.bounds[bb + 2]);
+    const maxX = Math.max(regions.bounds[ab + 3], regions.bounds[bb + 3]);
+    const maxY = Math.max(regions.bounds[ab + 4], regions.bounds[bb + 4]);
+    const maxZ = Math.max(regions.bounds[ab + 5], regions.bounds[bb + 5]);
+    const union = (maxX - minX + 1) * (maxY - minY + 1) * (maxZ - minZ + 1);
+    const taken = regions.count[a] + regions.count[b];
+    return (union - taken) / union;
+}
+function merge(regions, a, b) {
+    /* The lower id survives, so a decomposition's part order follows the grid walk that made it. */
+    const keep = Math.min(a, b);
+    const gone = Math.max(a, b);
+    regions.parent[gone] = keep;
+    regions.count[keep] = regions.count[keep] + regions.count[gone];
+    const kb = keep * 6;
+    const gb = gone * 6;
+    for (let i = 0; i < 3; i++) {
+        regions.bounds[kb + i] = Math.min(regions.bounds[kb + i], regions.bounds[gb + i]);
+        regions.bounds[kb + 3 + i] = Math.max(regions.bounds[kb + 3 + i], regions.bounds[gb + 3 + i]);
+    }
+    const directions = SUPPORT_DIRECTIONS;
+    for (let d = 0; d < directions; d++) {
+        const kk = keep * directions + d;
+        const kg = gone * directions + d;
+        if (regions.bestDot[kg] <= regions.bestDot[kk])
+            continue;
+        regions.bestDot[kk] = regions.bestDot[kg];
+        regions.supports[kk * 3] = regions.supports[kg * 3];
+        regions.supports[kk * 3 + 1] = regions.supports[kg * 3 + 1];
+        regions.supports[kk * 3 + 2] = regions.supports[kg * 3 + 2];
+    }
+    const into = regions.neighbours[keep];
+    for (const other of regions.neighbours[gone]) {
+        const root = find(regions, other);
+        if (root !== keep)
+            into.add(root);
+    }
+    into.delete(gone);
+    into.delete(keep);
+    regions.neighbours[gone] = new Set();
+    regions.live--;
+}
+/** A candidate merge, in a binary heap ordered by cost then by the pair's two ids. */
+class CandidateHeap {
+    costs = [];
+    as = [];
+    bs = [];
+    push(cost, a, b) {
+        this.costs.push(cost);
+        this.as.push(a);
+        this.bs.push(b);
+        let i = this.costs.length - 1;
+        while (i > 0) {
+            const parent = (i - 1) >> 1;
+            if (!this.less(i, parent))
+                break;
+            this.swap(i, parent);
+            i = parent;
+        }
+    }
+    pop() {
+        if (this.costs.length === 0)
+            return null;
+        const top = { cost: this.costs[0], a: this.as[0], b: this.bs[0] };
+        const last = this.costs.length - 1;
+        this.swap(0, last);
+        this.costs.pop();
+        this.as.pop();
+        this.bs.pop();
+        let i = 0;
+        for (;;) {
+            const left = i * 2 + 1;
+            const right = left + 1;
+            let best = i;
+            if (left < this.costs.length && this.less(left, best))
+                best = left;
+            if (right < this.costs.length && this.less(right, best))
+                best = right;
+            if (best === i)
+                break;
+            this.swap(i, best);
+            i = best;
+        }
+        return top;
+    }
+    less(i, j) {
+        const ci = this.costs[i];
+        const cj = this.costs[j];
+        if (ci !== cj)
+            return ci < cj;
+        const ai = this.as[i];
+        const aj = this.as[j];
+        if (ai !== aj)
+            return ai < aj;
+        return this.bs[i] < this.bs[j];
+    }
+    swap(i, j) {
+        const c = this.costs[i];
+        this.costs[i] = this.costs[j];
+        this.costs[j] = c;
+        const a = this.as[i];
+        this.as[i] = this.as[j];
+        this.as[j] = a;
+        const b = this.bs[i];
+        this.bs[i] = this.bs[j];
+        this.bs[j] = b;
+    }
+}
+/**
+ * Each live region's extreme corners along `DIRECTIONS`, and the hull over them.
+ *
+ * One walk over the grid. A solid cell offers its eight corners to its region's support set, which
+ * keeps whichever reach furthest along each direction; the set is then deduplicated by `hullShape`
+ * itself, so a boxy region arrives as its eight corners and a rounded one as up to fifty.
+ *
+ * **Coverage is measured here rather than assumed**, by asking whether each cell's centre lies
+ * inside the hull its own region produced. A support set is inscribed in the true hull of the
+ * corners it was drawn from, so a cell at a corner no direction points at can fall outside — and
+ * that is the one way this function loses material instead of adding it.
+ */
+function buildParts(grid, solid, regions) {
+    const directions = SUPPORT_DIRECTIONS;
+    const order = [];
+    const slotOf = new Map();
+    for (let i = 0; i < regions.total; i++) {
+        const root = find(regions, i);
+        if (slotOf.has(root))
+            continue;
+        slotOf.set(root, order.length);
+        order.push(root);
+    }
+    const best = new Float64Array(order.length * directions).fill(-Infinity);
+    const point = new Float64Array(order.length * directions * 3);
+    for (let z = 0; z < grid.nz; z++) {
+        for (let y = 0; y < grid.ny; y++) {
+            for (let x = 0; x < grid.nx; x++) {
+                const index = at(grid, x, y, z);
+                if (solid[index] !== 1)
+                    continue;
+                const slot = slotOf.get(find(regions, regions.of[index]));
+                for (let corner = 0; corner < 8; corner++) {
+                    const cxCell = x + (corner & 1);
+                    const cyCell = y + (corner & 2 ? 1 : 0);
+                    const czCell = z + (corner & 4 ? 1 : 0);
+                    const px = grid.originX + cxCell * grid.cell;
+                    const py = grid.originY + cyCell * grid.cell;
+                    const pz = grid.originZ + czCell * grid.cell;
+                    for (let d = 0; d < directions; d++) {
+                        const dot = DIRECTIONS[d * 3] * px +
+                            DIRECTIONS[d * 3 + 1] * py +
+                            DIRECTIONS[d * 3 + 2] * pz;
+                        const k = slot * directions + d;
+                        if (dot <= best[k])
+                            continue;
+                        best[k] = dot;
+                        point[k * 3] = px;
+                        point[k * 3 + 1] = py;
+                        point[k * 3 + 2] = pz;
+                    }
+                }
+            }
+        }
+    }
+    const cellVolume = grid.cell * grid.cell * grid.cell;
+    /* A plane test wants a tolerance in the units the planes are in, which is the grid's own. */
+    const slack = grid.cell * 1e-3;
+    const mass = createMassProperties();
+    const parts = [];
+    const shapes = [];
+    for (let slot = 0; slot < order.length; slot++) {
+        const points = new Float32Array(directions * 3);
+        for (let d = 0; d < directions; d++) {
+            const k = (slot * directions + d) * 3;
+            points[d * 3] = point[k];
+            points[d * 3 + 1] = point[k + 1];
+            points[d * 3 + 2] = point[k + 2];
+        }
+        const shape = hullShape(points);
+        shapes.push(shape);
+        const volume = shapeMassProperties(shape, 1, mass).volume;
+        const cells = regions.count[order[slot]];
+        parts.push({ points: shape.vertices, volume, fill: (cells * cellVolume) / volume });
+    }
+    let covered = 0;
+    for (let z = 0; z < grid.nz; z++) {
+        for (let y = 0; y < grid.ny; y++) {
+            for (let x = 0; x < grid.nx; x++) {
+                const index = at(grid, x, y, z);
+                if (solid[index] !== 1)
+                    continue;
+                const slot = slotOf.get(find(regions, regions.of[index]));
+                const px = grid.originX + (x + 0.5) * grid.cell;
+                const py = grid.originY + (y + 0.5) * grid.cell;
+                const pz = grid.originZ + (z + 0.5) * grid.cell;
+                if (insideHull(shapes[slot], px, py, pz, slack))
+                    covered++;
+            }
+        }
+    }
+    return { parts, covered };
+}
+/** Whether a point is on the inner side of every one of a hull's face planes. */
+function insideHull(shape, x, y, z, slack) {
+    const planes = shape.facePlanes;
+    for (let i = 0; i + 3 < planes.length; i += 4) {
+        const d = planes[i] * x +
+            planes[i + 1] * y +
+            planes[i + 2] * z -
+            planes[i + 3];
+        if (d > slack)
+            return false;
+    }
+    return true;
+}