@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/build/level/vgeo_partition_into_groups.js

@@ -0,0 +1,337 @@
+import { assert } from "../../../../../../core/assert.js";
+import { aabb3_from_v3_array } from "../../../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
+import { v3_morton_encode_bounded } from "../../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
+import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../../format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
+import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "../../format/cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
+import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "../../format/page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
+import { vgeo_graph_components } from "../partition/vgeo_graph_components.js";
+import { vgeo_partition_subgraph } from "../partition/vgeo_partition_subgraph.js";
+
+/**
+ * Fixed so that the same frontier always groups the same way.
+ * @readonly
+ * @type {number}
+ */
+const GROUP_SEED = 0x6D05;
+
+/**
+ * Bundle clusters that have no one to merge with along a Morton curve.
+ *
+ * A cluster alone in its connected component cannot be coarsened: halving its triangles leaves one
+ * cluster where there was one cluster, and the DAG stands still. The only way it ever reaches a root
+ * is bundled with geometry it shares no edge with, and the only thing left to choose them by is
+ * where they are. That is a real cost — a cluster spanning two islands carries a sphere containing
+ * both — which is why this is the fallback and adjacency is the rule.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number[]} loose cluster indices, each alone in its component
+ * @param {number} group_size
+ * @returns {number[][]} groups of at least two; a single leftover is returned to the frontier
+ */
+function bundle_loose_clusters(frontier, loose, group_size) {
+    if (loose.length < 2) {
+        return [];
+    }
+
+    // Gathered rather than read through the cluster list twice: the bounds and the codes are the
+    // same points, and this is the shape `vgeo_split_face_set_packed` already packs in.
+    const centres = new Float32Array(loose.length * 3);
+
+    loose.forEach((cluster, index) => {
+        const sphere = frontier.clusters[cluster].bounds_sphere;
+
+        centres[index * 3] = sphere[0];
+        centres[index * 3 + 1] = sphere[1];
+        centres[index * 3 + 2] = sphere[2];
+    });
+
+    const bounds = new Float32Array(6);
+
+    aabb3_from_v3_array(bounds, centres, centres.length);
+
+    /**
+     * @type {Map<number, number>}
+     */
+    const codes = new Map();
+
+    loose.forEach((cluster, index) => {
+        codes.set(cluster, v3_morton_encode_bounded(
+            centres[index * 3], centres[index * 3 + 1], centres[index * 3 + 2], bounds
+        ));
+    });
+
+    const order = loose.slice();
+
+    order.sort((a, b) => (codes.get(a) - codes.get(b)) || (a - b));
+
+    const result = [];
+
+    let bundle = [];
+    let triangles = 0;
+    let vertices = 0;
+    let packable = true;
+
+    for (const index of order) {
+        const cluster = frontier.clusters[index];
+
+        // Leaves small enough to end up in one cluster between them are worth bundling past the
+        // group size: what happens to them is a re-cut at no error, not a simplification, so a
+        // bigger bundle costs nothing in fidelity and is the difference between a scene of small
+        // parts filling its clusters and running them at a tenth of capacity. Anything else stops at
+        // the group size, where the size is a real trade against LOD lockstep.
+        const packs = packable
+            && cluster.child_group === undefined
+            && triangles + cluster.triangle_count <= VGEO_MAX_CLUSTER_TRIANGLE_COUNT
+            && vertices + cluster.vertex_count <= VGEO_MAX_CLUSTER_VERTEX_COUNT;
+
+        if (bundle.length >= group_size && !packs) {
+            result.push(bundle);
+
+            bundle = [];
+            triangles = 0;
+            vertices = 0;
+            packable = true;
+        }
+
+        bundle.push(index);
+
+        triangles += cluster.triangle_count;
+        vertices += cluster.vertex_count;
+
+        packable = packable && cluster.child_group === undefined;
+    }
+
+    if (bundle.length === 1 && result.length > 0) {
+        // A bundle of one merges nothing. Handing it to the bundle before it costs one cluster of
+        // spatial spread and is the difference between the frontier shrinking and it standing still.
+        result[result.length - 1].push(bundle[0]);
+    } else if (bundle.length > 1) {
+        result.push(bundle);
+    }
+
+    return result.filter((group) => group.length >= 2);
+}
+
+/**
+ * Fold every one-cluster piece into the adjacent piece it shares the most boundary with.
+ *
+ * The partitioner produces these constantly — it optimizes cut, not contiguity, so splitting its
+ * parts into connected pieces routinely leaves a cluster standing on its own. Such a cluster is not
+ * out of options, though: it sits inside a component that has plenty of neighbours, and the right
+ * answer is the nearest of them, not the proximity pool. Letting it fall through to the pool is how
+ * a lone shell sixty metres away ends up merged with a fragment of something else entirely.
+ *
+ * One forward pass is enough. Folding only ever grows a piece and empties the one it came from, so
+ * it cannot turn a piece of two into a piece of one — the singletons are exactly the ones present
+ * when the pass starts, and a singleton that has already absorbed another is no longer one.
+ *
+ * @param {number[][]} pieces of a single connected component of the band, each non-empty; every
+ *     cluster in a singleton piece therefore has a neighbour in some other piece here
+ * @param {object} cluster_graph as {@link vgeo_build_cluster_graph} returns
+ * @returns {number[][]} non-empty pieces, with no singletons
+ */
+function absorb_singleton_pieces(pieces, cluster_graph) {
+    if (pieces.length < 2) {
+        return pieces;
+    }
+
+    /**
+     * `cluster -> index of the piece holding it`.
+     * @type {Map<number, number>}
+     */
+    const piece_of = new Map();
+
+    const alive = pieces.map((piece) => piece.slice());
+
+    alive.forEach((piece, index) => {
+        for (const cluster of piece) {
+            piece_of.set(cluster, index);
+        }
+    });
+
+    for (let index = 0; index < alive.length; index++) {
+        if (alive[index].length !== 1) {
+            continue;
+        }
+
+        const cluster = alive[index][0];
+
+        /**
+         * `piece index -> boundary shared with this cluster`.
+         * @type {Map<number, number>}
+         */
+        const shared = new Map();
+
+        for (let i = cluster_graph.edge_addresses[cluster]; i < cluster_graph.edge_addresses[cluster + 1]; i++) {
+            const target = piece_of.get(cluster_graph.adjacency[i]);
+
+            if (target === undefined || target === index) {
+                continue;
+            }
+
+            shared.set(target, (shared.get(target) ?? 0) + cluster_graph.edge_weights[i]);
+        }
+
+        let best = -1;
+        let best_weight = -1;
+
+        // Sorted, so that two pieces sharing the same boundary length resolve the same way every
+        // time rather than however the adjacency happened to be walked.
+        for (const [target, weight] of Array.from(shared.entries()).sort((a, b) => a[0] - b[0])) {
+            if (weight > best_weight) {
+                best = target;
+                best_weight = weight;
+            }
+        }
+
+        assert.notEqual(
+            best, -1,
+            'a lone cluster inside a connected component must border another piece of it'
+        );
+
+        alive[best].push(cluster);
+        alive[best].sort((a, b) => a - b);
+
+        piece_of.set(cluster, best);
+
+        alive[index] = [];
+    }
+
+    return alive.filter((piece) => piece.length > 0);
+}
+
+/**
+ * Partition a band of the frontier into groups of roughly `group_size`.
+ *
+ * The partition runs **inside each connected component** of the cluster graph, not across the band as
+ * a whole. Partitioning globally and splitting the disconnected parts afterwards looks equivalent and
+ * is not: a scene assembled from thousands of separate shells has a cluster graph in thousands of
+ * pieces, and a balanced global partition draws each part from several of them, so the connectivity
+ * split then shreds nearly every group down to a single cluster.
+ *
+ * What is left over after that — every cluster alone in its component — is bundled by proximity
+ * instead, because for those clusters there is no adjacency left to respect and no other way to the
+ * root.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number[]} band cluster indices this round may consume, ascending
+ * @param {object} cluster_graph as {@link vgeo_build_cluster_graph} returns
+ * @param {number} group_size
+ * @returns {number[][]} groups of at least two clusters each; clusters left out stay in the frontier
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_partition_into_groups(frontier, band, cluster_graph, group_size) {
+    const membership = new Int32Array(frontier.clusters.length).fill(-1);
+
+    /**
+     * Dense rather than a `Map`, and hoisted out of the component loop so it is one allocation per
+     * level. See {@link vgeo_partition_subgraph} for why the density is load-bearing rather than a
+     * micro-optimisation.
+     * @type {Uint32Array}
+     */
+    const local_index = new Uint32Array(frontier.clusters.length);
+
+    for (const cluster of band) {
+        membership[cluster] = 0;
+    }
+
+    const components = vgeo_graph_components(
+        cluster_graph.edge_addresses, cluster_graph.adjacency, band, membership, 0
+    );
+
+    const result = [];
+
+    /**
+     * Clusters with nobody adjacent to merge with.
+     * @type {number[]}
+     */
+    const loose = [];
+
+    let token = 0;
+
+    /**
+     * @param {number[]} piece
+     */
+    function accept(piece) {
+        if (piece.length < 2) {
+            loose.push(piece[0]);
+
+            return;
+        }
+
+        // The format caps a group at 4096 clusters. Nothing the size policy produces comes near it,
+        // but the cap is hard, so the chunking is here rather than assumed away.
+        for (let start = 0; start < piece.length; start += VGEO_MAX_GROUP_CLUSTER_COUNT) {
+            const chunk = piece.slice(start, start + VGEO_MAX_GROUP_CLUSTER_COUNT);
+
+            if (chunk.length < 2) {
+                loose.push(chunk[0]);
+
+                continue;
+            }
+
+            result.push(chunk);
+        }
+    }
+
+    for (const component of components) {
+        if (component.length < 2) {
+            // Alone in its component: no adjacency left anywhere, so proximity is the only rule that
+            // can still place it.
+            loose.push(component[0]);
+
+            continue;
+        }
+
+        if (component.length <= group_size) {
+            accept(component);
+
+            continue;
+        }
+
+        /**
+         * @type {number[][]}
+         */
+        const pieces = [];
+
+        const part_count = Math.ceil(component.length / group_size);
+
+        token++;
+
+        for (const cluster of component) {
+            membership[cluster] = token;
+        }
+
+        const parts = vgeo_partition_subgraph(
+            cluster_graph, component, membership, token, part_count, GROUP_SEED, local_index
+        );
+
+        for (const part of parts) {
+            token++;
+
+            for (const cluster of part) {
+                membership[cluster] = token;
+            }
+
+            for (const piece of vgeo_graph_components(
+                cluster_graph.edge_addresses, cluster_graph.adjacency, part, membership, token
+            )) {
+                pieces.push(piece);
+            }
+        }
+
+        for (const piece of absorb_singleton_pieces(pieces, cluster_graph)) {
+            accept(piece);
+        }
+    }
+
+    for (const bundle of bundle_loose_clusters(frontier, loose, group_size)) {
+        result.push(bundle);
+    }
+
+    result.sort((a, b) => a[0] - b[0]);
+
+    return result;
+}

package/src/shade/renderer/geometry/virtual/build/level/vgeo_run_round.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One round: pick a band, group it, simplify each group, and report what it produced.
+ *
+ * Every group is speculative and judged on its own. One that comes back with no fewer clusters than
+ * it consumed is simply dropped — its clusters return to the frontier, to be grouped differently by
+ * a later round — rather than failing the round for everyone else. A group that cannot be
+ * simplified is no different in kind from a group that could not be formed, and the frontier already
+ * knows what to do with those: nothing, for now.
+ *
+ * The round as a whole is accepted only when it *strictly* shrinks the frontier. Failing that it
+ * widens the band, and failing that it grows the group — small groups starve the simplifier, and a
+ * wider band gives a fine region coarser neighbours to merge with.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number} level of the parents this round would produce
+ * @param {VGeoLevelOptions} options
+ * @returns {{steps: VGeoGroupStep[], repacks: VGeoGroupRepack[], merged: Set<number>}|undefined}
+ *     what to commit and which frontier clusters it consumed; `undefined` when nothing this round
+ *     could try made the frontier smaller
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_run_round(frontier: VGeoFrontier, level: number, options: VGeoLevelOptions): {
+    steps: VGeoGroupStep[];
+    repacks: VGeoGroupRepack[];
+    merged: Set<number>;
+} | undefined;
+//# sourceMappingURL=vgeo_run_round.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/vgeo_run_round.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_run_round.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_run_round.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8DATW,MAAM,8BAEJ;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,IAAI,MAAM,CAAC,CAAA;CAAC,GAAC,SAAS,CAyG/F"}

package/src/shade/renderer/geometry/virtual/build/level/vgeo_run_round.js

@@ -0,0 +1,147 @@
+import { bt_mesh_build_face_graph } from "../../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
+import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
+import { vgeo_build_cluster_graph } from "./vgeo_build_cluster_graph.js";
+import { vgeo_build_group_step } from "./vgeo_build_group_step.js";
+import { vgeo_error_bands } from "./vgeo_error_bands.js";
+import { vgeo_partition_into_groups } from "./vgeo_partition_into_groups.js";
+import { vgeo_try_repack } from "./vgeo_try_repack.js";
+
+/**
+ * The frontier's clusters ordered by error, which is what a band is a slice of.
+ *
+ * @param {VGeoFrontier} frontier
+ * @returns {{order: number[], errors: number[]}} cluster indices ascending by error, and their
+ *     errors in the same order
+ */
+function order_by_error(frontier) {
+    const order = frontier.clusters.map((cluster, index) => index);
+
+    order.sort(
+        (a, b) => (frontier.clusters[a].self_error - frontier.clusters[b].self_error) || (a - b)
+    );
+
+    return { order, errors: order.map((index) => frontier.clusters[index].self_error) };
+}
+
+/**
+ * One round: pick a band, group it, simplify each group, and report what it produced.
+ *
+ * Every group is speculative and judged on its own. One that comes back with no fewer clusters than
+ * it consumed is simply dropped — its clusters return to the frontier, to be grouped differently by
+ * a later round — rather than failing the round for everyone else. A group that cannot be
+ * simplified is no different in kind from a group that could not be formed, and the frontier already
+ * knows what to do with those: nothing, for now.
+ *
+ * The round as a whole is accepted only when it *strictly* shrinks the frontier. Failing that it
+ * widens the band, and failing that it grows the group — small groups starve the simplifier, and a
+ * wider band gives a fine region coarser neighbours to merge with.
+ *
+ * @param {VGeoFrontier} frontier
+ * @param {number} level of the parents this round would produce
+ * @param {VGeoLevelOptions} options
+ * @returns {{steps: VGeoGroupStep[], repacks: VGeoGroupRepack[], merged: Set<number>}|undefined}
+ *     what to commit and which frontier clusters it consumed; `undefined` when nothing this round
+ *     could try made the frontier smaller
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_run_round(frontier, level, options) {
+    const face_graph = new VGeoFaceGraph(
+        frontier.mesh.topology, bt_mesh_build_face_graph(frontier.mesh.topology), frontier.wedges
+    );
+
+    const cluster_graph = vgeo_build_cluster_graph(frontier, face_graph);
+
+    const ordered = order_by_error(frontier);
+
+    const bands = vgeo_error_bands(
+        ordered.errors, options.error_band_growth, options.error_band_min_fraction
+    );
+
+    let group_size = options.group_size;
+
+    for (; ;) {
+        for (const range of bands) {
+            const band = ordered.order.slice(range.start, range.end);
+
+            band.sort((a, b) => a - b);
+
+            const groups = vgeo_partition_into_groups(frontier, band, cluster_graph, group_size);
+
+            if (groups.length === 0) {
+                continue;
+            }
+
+            const group_of_face = new Int32Array(frontier.mesh.topology.faces.size).fill(-1);
+
+            groups.forEach((group, group_index) => {
+                for (const cluster of group) {
+                    for (const face of frontier.cluster_faces[cluster]) {
+                        group_of_face[face] = group_index;
+                    }
+                }
+            });
+
+            const steps = [];
+            const repacks = [];
+
+            let consumed = 0;
+            let produced = 0;
+
+            const merged = new Set();
+
+            groups.forEach((group, group_index) => {
+                const parent_target = Math.max(
+                    1, Math.ceil(group.length * options.simplification_ratio)
+                );
+
+                const repack = vgeo_try_repack(frontier, group, parent_target);
+
+                if (repack !== undefined) {
+                    repacks.push(repack);
+
+                    consumed += group.length;
+                    produced += repack.clusters.length;
+
+                    for (const cluster of group) {
+                        merged.add(cluster);
+                    }
+
+                    return;
+                }
+
+                const step = vgeo_build_group_step(
+                    frontier, group, group_of_face, group_index, level, options
+                );
+
+                if (step === undefined || step.parent_clusters.length >= group.length) {
+                    // Refused. Nothing has been mutated — the step worked on a copy of the geometry
+                    // and a copy of the quadrics — so its clusters simply stay where they are.
+                    return;
+                }
+
+                steps.push(step);
+
+                consumed += group.length;
+                produced += step.parent_clusters.length;
+
+                for (const cluster of group) {
+                    merged.add(cluster);
+                }
+            });
+
+            if (produced < consumed) {
+                return { steps, repacks, merged };
+            }
+        }
+
+        // No band made progress. Growing the group gives the simplifier more interior to work with
+        // relative to its locked perimeter, which is the thing that stalls first.
+        if (group_size >= frontier.clusters.length) {
+            return undefined;
+        }
+
+        group_size = Math.min(frontier.clusters.length, group_size * 2);
+    }
+}

package/src/shade/renderer/geometry/virtual/build/level/vgeo_stitch_frontier.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Stitch a round's output back into one mesh: freshly simplified clusters, and the clusters the
+ * round left alone, side by side.
+ *
+ * Vertices are unified by the id they had in the frontier below, never by position: a vertex two
+ * groups share is pinned, so both carry it unmoved and unmistakably, while a vertex only one group
+ * holds is its own even if a collapse happened to place it exactly where another landed. An
+ * untouched cluster names its vertices in that same space, so it stitches to its simplified
+ * neighbour along exactly the boundary that neighbour was forbidden to move.
+ *
+ * **Wedges are unified the same way and separately**, by the frontier wedge each contributed corner
+ * came from. Two contributions that share a pinned boundary vertex name the same wedges there, so
+ * they arrive as one and the seam shades continuously; a wedge only one group has — one a collapse
+ * inside it adopted, say — is its own, which is right, because its corners are that group's alone.
+ * The new frontier's wedge ids are handed out here, and they are what the round's accumulated
+ * attribute quadrics are re-indexed into.
+ *
+ * @param {VGeoContribution[]} contributions parallel to the clusters of the frontier being built
+ * @param {(BinaryDataLayer|null)[]} template_layers the channels the frontier below carries, which
+ *     the frontier being stitched carries too
+ * @returns {{mesh: VirtualGeometryMesh, cluster_faces: number[][], source_vertex_ids: Uint32Array, wedges: BtWedgeSet, source_wedge_ids: Uint32Array}}
+ *     the two id maps naming, for every vertex and every wedge of the new mesh, the one of the old
+ *     mesh it came from — which is how the accumulated quadrics follow it across the seam
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_stitch_frontier(contributions: VGeoContribution[], template_layers: (BinaryDataLayer | null)[]): {
+    mesh: VirtualGeometryMesh;
+    cluster_faces: number[][];
+    source_vertex_ids: Uint32Array;
+    wedges: BtWedgeSet;
+    source_wedge_ids: Uint32Array;
+};
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+//# sourceMappingURL=vgeo_stitch_frontier.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/vgeo_stitch_frontier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_stitch_frontier.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_stitch_frontier.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oDAVW,gBAAgB,EAAE,mBAClB,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB;IAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,iBAAiB,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,WAAW,CAAA;CAAC,CAmNrJ;oCAzOmC,gCAAgC;2BANzC,qEAAqE"}