@woosh/meep-engine 3.0.2 → 3.2.0

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js

@@ -1,66 +1,66 @@
-import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
-import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
-
-/**
- * Knobs the builder pipeline exposes.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoBuildOptions {
-    /**
-     * Which codec page blobs are stored under — {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}.
-     * Compressed by default, and there is no case where turning it off makes a file smaller: the
-     * encoder stores a page raw whenever compressing it would not shrink it, per page.
-     *
-     * What it costs a reader is one LZ4 block decode per page installed, into the buffer the page
-     * was going to be copied into anyway. What it saves is transfer and disk on every fetch of
-     * every page, forever.
-     *
-     * @type {number}
-     */
-    codec = VGEO_CODEC_LZ4;
-
-    /**
-     * How close two source vertices have to be to count as one point, as a fraction of the
-     * geometry's own bounding-box diagonal. **Leave it alone.** It is the one knob here that can
-     * quietly change the surface rather than how the surface is cut up, and the default is chosen
-     * against what the storage and the source formats can actually resolve, not against taste:
-     *
-     * - Below it, the float32 quantum. Two coordinates cannot be nearer than one step of the format
-     *   they are stored in — `sqrt(3) * 2^-23` of the mesh's coordinate magnitude, so about `1e-7`
-     *   of the diagonal for a mesh sitting around its own origin. A ratio near that asks for bit
-     *   equality and leaves genuinely coincident points unwelded, which cracks the surface along
-     *   every seam the exporter did not happen to write twice from the same bits.
-     * - Above it, the finest feature a source can carry. The coarsest position quantization anyone
-     *   ships — `gltfpack`'s 14-bit default — puts its quantum at `6.1e-5` of the extent, so nothing
-     *   in such a file is finer than that. The default sits six times below it: near enough to the
-     *   quantum to absorb any arithmetic noise around it, far enough under to never merge two
-     *   positions the source meant to keep apart.
-     *
-     * Raise it and the weld starts eating geometry — on the dragon of `DragonAttenuation.glb`,
-     * `1e-3` costs 10,401 of its 91,216 faces and opens 3,312 boundary edges in what was a closed
-     * mesh. Lower it and seams stop fusing, the clusterer shreds the mesh along each one, and the
-     * cracks appear at runtime instead of in the build log.
-     *
-     * Raw scan data pays something at the default too, but to the short-edge pre-pass rather than to
-     * the merge — see the builder README's note on `dragon_vrip.ply`, where 8,562 of the 8,603 lost
-     * faces are the pre-pass deleting slivers it should be collapsing. That is a defect with its own
-     * fix, not a reason to move the tolerance off what the arithmetic supports.
-     *
-     * @type {number}
-     */
-    weld_ratio = 1e-5;
-
-    /**
-     * Target decoded bytes per page. Informational in the file; the format forbids readers from
-     * assuming it.
-     * @type {number}
-     */
-    nominal_page_size = 256 * 1024;
-
-    /**
-     * @type {VGeoLevelOptions}
-     */
-    level_options = new VGeoLevelOptions();
-}
+import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
+import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
+
+/**
+ * Knobs the builder pipeline exposes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoBuildOptions {
+    /**
+     * Which codec page blobs are stored under — {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}.
+     * Compressed by default, and there is no case where turning it off makes a file smaller: the
+     * encoder stores a page raw whenever compressing it would not shrink it, per page.
+     *
+     * What it costs a reader is one LZ4 block decode per page installed, into the buffer the page
+     * was going to be copied into anyway. What it saves is transfer and disk on every fetch of
+     * every page, forever.
+     *
+     * @type {number}
+     */
+    codec = VGEO_CODEC_LZ4;
+
+    /**
+     * How close two source vertices have to be to count as one point, as a fraction of the
+     * geometry's own bounding-box diagonal. **Leave it alone.** It is the one knob here that can
+     * quietly change the surface rather than how the surface is cut up, and the default is chosen
+     * against what the storage and the source formats can actually resolve, not against taste:
+     *
+     * - Below it, the float32 quantum. Two coordinates cannot be nearer than one step of the format
+     *   they are stored in — `sqrt(3) * 2^-23` of the mesh's coordinate magnitude, so about `1e-7`
+     *   of the diagonal for a mesh sitting around its own origin. A ratio near that asks for bit
+     *   equality and leaves genuinely coincident points unwelded, which cracks the surface along
+     *   every seam the exporter did not happen to write twice from the same bits.
+     * - Above it, the finest feature a source can carry. The coarsest position quantization anyone
+     *   ships — `gltfpack`'s 14-bit default — puts its quantum at `6.1e-5` of the extent, so nothing
+     *   in such a file is finer than that. The default sits six times below it: near enough to the
+     *   quantum to absorb any arithmetic noise around it, far enough under to never merge two
+     *   positions the source meant to keep apart.
+     *
+     * Raise it and the weld starts eating geometry — on the dragon of `DragonAttenuation.glb`,
+     * `1e-3` costs 10,401 of its 91,216 faces and opens 3,312 boundary edges in what was a closed
+     * mesh. Lower it and seams stop fusing, the clusterer shreds the mesh along each one, and the
+     * cracks appear at runtime instead of in the build log.
+     *
+     * Raw scan data pays something at the default too, but to the short-edge pre-pass rather than to
+     * the merge — see the builder README's note on `dragon_vrip.ply`, where 8,562 of the 8,603 lost
+     * faces are the pre-pass deleting slivers it should be collapsing. That is a defect with its own
+     * fix, not a reason to move the tolerance off what the arithmetic supports.
+     *
+     * @type {number}
+     */
+    weld_ratio = 1e-5;
+
+    /**
+     * Target decoded bytes per page. Informational in the file; the format forbids readers from
+     * assuming it.
+     * @type {number}
+     */
+    nominal_page_size = 256 * 1024;
+
+    /**
+     * @type {VGeoLevelOptions}
+     */
+    level_options = new VGeoLevelOptions();
+}

package/src/shade/renderer/geometry/virtual/build/VGeoBuildResult.js

@@ -1,32 +1,32 @@
-/**
- * The finished asset plus what it took.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoBuildResult {
-    /**
-     * The whole file; `capacity` is its length.
-     * @type {BinaryBuffer}
-     */
-    buffer = null;
-
-    /**
-     * @type {VGeoLevelSummary[]}
-     */
-    levels = [];
-
-    page_count = 0;
-    total_clusters = 0;
-    total_groups = 0;
-    source_vertex_count = 0;
-    source_face_count = 0;
-
-    /**
-     * Object-space distance {@link VGeoBuildOptions#weld_ratio} came to for this geometry. Reported
-     * rather than configured — it is what a person asking "why did that seam open" needs, and the
-     * only way to see the ratio in the units the mesh is actually in.
-     * @type {number}
-     */
-    weld_distance = 0;
-}
+/**
+ * The finished asset plus what it took.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoBuildResult {
+    /**
+     * The whole file; `capacity` is its length.
+     * @type {BinaryBuffer}
+     */
+    buffer = null;
+
+    /**
+     * @type {VGeoLevelSummary[]}
+     */
+    levels = [];
+
+    page_count = 0;
+    total_clusters = 0;
+    total_groups = 0;
+    source_vertex_count = 0;
+    source_face_count = 0;
+
+    /**
+     * Object-space distance {@link VGeoBuildOptions#weld_ratio} came to for this geometry. Reported
+     * rather than configured — it is what a person asking "why did that seam open" needs, and the
+     * only way to see the ratio in the units the mesh is actually in.
+     * @type {number}
+     */
+    weld_distance = 0;
+}

package/src/shade/renderer/geometry/virtual/build/VGeoFaceGraph.js

@@ -1,103 +1,103 @@
-import {
-    bt_face_read_triangle_vertices
-} from "../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
-
-/**
- * A face-adjacency graph together with the mesh it came from, kept so that repeated splits over the
- * same level do not rebuild it.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-const scratch_triangle = new Uint32Array(3);
-
-export class VGeoFaceGraph {
-    /**
-     * @type {BinaryTopology}
-     */
-    mesh = null;
-
-    /**
-     * CSR over dense face-graph vertices; edge weights are shared-edge counts.
-     * @type {MetisGraph}
-     */
-    graph = null;
-
-    /**
-     * `vertex_face_ids[dense] = face id`.
-     * @type {Uint32Array}
-     */
-    vertex_face_ids = null;
-
-    /**
-     * Scratch stamp for unique-vertex counting, one entry per mesh vertex slot.
-     * @type {Int32Array}
-     */
-    vertex_stamp = null;
-
-    /**
-     * Monotonic stamp value, so the scratch never needs clearing.
-     * @type {number}
-     */
-    stamp = 0;
-
-    /**
-     * Scratch `graph vertex -> its position in the member list being split right now`, one entry per
-     * graph vertex. Only the entries of that member list mean anything, which is all
-     * {@link vgeo_split_face_set}'s partition step ever reads: it consults this exclusively for
-     * neighbours the membership stamp has already confirmed are members.
-     *
-     * Dense rather than a `Map` because the keys are dense face-graph vertices to begin with, and
-     * because a `Map` cannot answer this question at all past 2^24 entries — the leaf cut runs over
-     * every face of the mesh at once, so a mesh of more than 16.7M triangles in one connected
-     * component would otherwise stop the builder dead.
-     * @type {Uint32Array}
-     */
-    member_index = null;
-
-    /**
-     * @param {BinaryTopology} mesh
-     * @param {BinaryTopologyFaceGraph} face_graph
-     */
-    constructor(mesh, face_graph) {
-        this.mesh = mesh;
-        this.graph = face_graph.graph;
-        this.vertex_face_ids = face_graph.vertex_face_ids;
-        this.vertex_stamp = new Int32Array(mesh.vertices.size).fill(-1);
-        this.member_index = new Uint32Array(face_graph.graph.vertex_count);
-    }
-
-    /**
-     * How many distinct mesh vertices a set of dense face-graph vertices touches.
-     *
-     * @param {number[]|Int32Array} members dense face-graph vertices
-     * @returns {number}
-     */
-    count_unique_vertices(members) {
-        const stamp = this.stamp++;
-
-        let count = 0;
-
-        const vertex_face_ids = this.vertex_face_ids;
-        const mesh = this.mesh;
-        const vertex_stamp = this.vertex_stamp;
-
-        for (const member of members) {
-
-            const face = vertex_face_ids[member];
-            bt_face_read_triangle_vertices(scratch_triangle, mesh, face);
-
-            for (let i = 0; i < 3; i++) {
-                const vertex = scratch_triangle[i];
-
-                if (vertex_stamp[vertex] !== stamp) {
-                    vertex_stamp[vertex] = stamp;
-                    count++;
-                }
-            }
-        }
-
-        return count;
-    }
-}
+import {
+    bt_face_read_triangle_vertices
+} from "../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
+
+/**
+ * A face-adjacency graph together with the mesh it came from, kept so that repeated splits over the
+ * same level do not rebuild it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const scratch_triangle = new Uint32Array(3);
+
+export class VGeoFaceGraph {
+    /**
+     * @type {BinaryTopology}
+     */
+    mesh = null;
+
+    /**
+     * CSR over dense face-graph vertices; edge weights are shared-edge counts.
+     * @type {MetisGraph}
+     */
+    graph = null;
+
+    /**
+     * `vertex_face_ids[dense] = face id`.
+     * @type {Uint32Array}
+     */
+    vertex_face_ids = null;
+
+    /**
+     * Scratch stamp for unique-vertex counting, one entry per mesh vertex slot.
+     * @type {Int32Array}
+     */
+    vertex_stamp = null;
+
+    /**
+     * Monotonic stamp value, so the scratch never needs clearing.
+     * @type {number}
+     */
+    stamp = 0;
+
+    /**
+     * Scratch `graph vertex -> its position in the member list being split right now`, one entry per
+     * graph vertex. Only the entries of that member list mean anything, which is all
+     * {@link vgeo_split_face_set}'s partition step ever reads: it consults this exclusively for
+     * neighbours the membership stamp has already confirmed are members.
+     *
+     * Dense rather than a `Map` because the keys are dense face-graph vertices to begin with, and
+     * because a `Map` cannot answer this question at all past 2^24 entries — the leaf cut runs over
+     * every face of the mesh at once, so a mesh of more than 16.7M triangles in one connected
+     * component would otherwise stop the builder dead.
+     * @type {Uint32Array}
+     */
+    member_index = null;
+
+    /**
+     * @param {BinaryTopology} mesh
+     * @param {BinaryTopologyFaceGraph} face_graph
+     */
+    constructor(mesh, face_graph) {
+        this.mesh = mesh;
+        this.graph = face_graph.graph;
+        this.vertex_face_ids = face_graph.vertex_face_ids;
+        this.vertex_stamp = new Int32Array(mesh.vertices.size).fill(-1);
+        this.member_index = new Uint32Array(face_graph.graph.vertex_count);
+    }
+
+    /**
+     * How many distinct mesh vertices a set of dense face-graph vertices touches.
+     *
+     * @param {number[]|Int32Array} members dense face-graph vertices
+     * @returns {number}
+     */
+    count_unique_vertices(members) {
+        const stamp = this.stamp++;
+
+        let count = 0;
+
+        const vertex_face_ids = this.vertex_face_ids;
+        const mesh = this.mesh;
+        const vertex_stamp = this.vertex_stamp;
+
+        for (const member of members) {
+
+            const face = vertex_face_ids[member];
+            bt_face_read_triangle_vertices(scratch_triangle, mesh, face);
+
+            for (let i = 0; i < 3; i++) {
+                const vertex = scratch_triangle[i];
+
+                if (vertex_stamp[vertex] !== stamp) {
+                    vertex_stamp[vertex] = stamp;
+                    count++;
+                }
+            }
+        }
+
+        return count;
+    }
+}

package/src/shade/renderer/geometry/virtual/build/VGeoGatheredFaces.js

@@ -1,25 +1,25 @@
-/**
- * A face set gathered into standalone, locally-indexed form.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoGatheredFaces {
-    /**
-     * `3 * vertex_count` local coordinates.
-     * @type {Float32Array}
-     */
-    positions = new Float32Array(0);
-
-    /**
-     * `3 * triangle_count` local vertex indices.
-     * @type {Uint32Array}
-     */
-    indices = new Uint32Array(0);
-
-    /**
-     * Vertex ids in the mesh this was pulled out of, one per local vertex, in first-use order.
-     * @type {Uint32Array}
-     */
-    vertex_ids = new Uint32Array(0);
-}
+/**
+ * A face set gathered into standalone, locally-indexed form.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoGatheredFaces {
+    /**
+     * `3 * vertex_count` local coordinates.
+     * @type {Float32Array}
+     */
+    positions = new Float32Array(0);
+
+    /**
+     * `3 * triangle_count` local vertex indices.
+     * @type {Uint32Array}
+     */
+    indices = new Uint32Array(0);
+
+    /**
+     * Vertex ids in the mesh this was pulled out of, one per local vertex, in first-use order.
+     * @type {Uint32Array}
+     */
+    vertex_ids = new Uint32Array(0);
+}

package/src/shade/renderer/geometry/virtual/build/VGeoLevel.js

@@ -1,33 +1,33 @@
-/**
- * One band of the DAG.
- *
- * A level is an ordinal, not a generation: `clusters` are the clusters the round of that index
- * created, while `groups` are the groups the round *above* consumed — and those groups may hold
- * clusters from any level at or below their own, because a cluster no round could use waits in the
- * frontier until one can. What the ordinal guarantees is the only thing the format needs from it:
- * every group sits strictly below the group holding its parents, so laying pages out by descending
- * level makes every child reference point forward in the file.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoLevel {
-    /**
-     * `0` = leaves.
-     * @type {number}
-     */
-    index = 0;
-
-    /**
-     * The clusters this level's round created.
-     * @type {VirtualGeometryCluster[]}
-     */
-    clusters = [];
-
-    /**
-     * The groups that sit in this level's band — the ones the round above consumed. Empty for the
-     * top level until the caller assigns its root group.
-     * @type {VirtualGeometryGroup[]}
-     */
-    groups = [];
-}
+/**
+ * One band of the DAG.
+ *
+ * A level is an ordinal, not a generation: `clusters` are the clusters the round of that index
+ * created, while `groups` are the groups the round *above* consumed — and those groups may hold
+ * clusters from any level at or below their own, because a cluster no round could use waits in the
+ * frontier until one can. What the ordinal guarantees is the only thing the format needs from it:
+ * every group sits strictly below the group holding its parents, so laying pages out by descending
+ * level makes every child reference point forward in the file.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevel {
+    /**
+     * `0` = leaves.
+     * @type {number}
+     */
+    index = 0;
+
+    /**
+     * The clusters this level's round created.
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters = [];
+
+    /**
+     * The groups that sit in this level's band — the ones the round above consumed. Empty for the
+     * top level until the caller assigns its root group.
+     * @type {VirtualGeometryGroup[]}
+     */
+    groups = [];
+}

package/src/shade/renderer/geometry/virtual/build/VGeoLevelOptions.js

@@ -1,62 +1,62 @@
-/**
- * How the round loop of {@link vgeo_build_levels} is allowed to behave.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoLevelOptions {
-    /**
-     * Clusters a group starts out holding. Grows when a round fails to make progress — small groups
-     * starve the simplifier (the locked perimeter dominates), large ones lock a big spatial
-     * footprint into LOD lockstep.
-     * @type {number}
-     */
-    group_size = 4;
-
-    /**
-     * Fraction of a group's *clusters* the step above it should come to. The design's halving,
-     * stated as the thing the DAG is actually for.
-     *
-     * A triangle ratio is a means and this is the end, and asking directly is what keeps parents
-     * full: the simplifier is given the triangle count that many clusters hold, rather than half of
-     * whatever the children happened to contain. Where the children are already full the two are the
-     * same number. Where they are not, this asks for less destruction, because the reduction is
-     * available from packing the geometry better instead.
-     * @type {number}
-     */
-    simplification_ratio = 0.5;
-
-    /**
-     * How much error a single round is allowed to span, as a multiple of the band's floor. `1` would
-     * admit only the exact minimum and turn every distinct error value into its own round; a large
-     * value admits the whole frontier every time and is the level sweep this replaced.
-     *
-     * Four, measured. On a 98k-triangle sphere against a full sweep: 31% fewer clusters merged into
-     * groups more than twice as coarse as themselves, and 8% fewer at four times, for one extra
-     * level. Two is tighter on the first count — 41% fewer — but costs fourteen levels, and every
-     * level is a page band and a dependent fetch on the way down.
-     * @type {number}
-     */
-    error_band_growth = 4;
-
-    /**
-     * Least share of the frontier a round is allowed to work on, whatever the octave says.
-     *
-     * The octave alone offers no guarantee of progress: geometry whose error is spread thinly and
-     * continuously — a UV sphere, whose poles carry triangles a fraction of the size of its
-     * equator's — puts only a handful of clusters in any one octave, and the build inches forward a
-     * few merges per round. That is not merely slow, it is unbounded: `level_count` is a u8, and a
-     * round loop whose count scales with the cluster count rather than its logarithm will run out of
-     * levels on a real asset. Widening the band until it holds a fixed share of the frontier bounds
-     * the depth logarithmically, and costs error uniformity only where the octave had nothing.
-     * @type {number}
-     */
-    error_band_min_fraction = 0.25;
-
-    /**
-     * Refuse to build past this many levels. `level_count` is a u8 in the container, and a build
-     * that has not converged by then has something else wrong with it.
-     * @type {number}
-     */
-    max_levels = 255;
-}
+/**
+ * How the round loop of {@link vgeo_build_levels} is allowed to behave.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevelOptions {
+    /**
+     * Clusters a group starts out holding. Grows when a round fails to make progress — small groups
+     * starve the simplifier (the locked perimeter dominates), large ones lock a big spatial
+     * footprint into LOD lockstep.
+     * @type {number}
+     */
+    group_size = 4;
+
+    /**
+     * Fraction of a group's *clusters* the step above it should come to. The design's halving,
+     * stated as the thing the DAG is actually for.
+     *
+     * A triangle ratio is a means and this is the end, and asking directly is what keeps parents
+     * full: the simplifier is given the triangle count that many clusters hold, rather than half of
+     * whatever the children happened to contain. Where the children are already full the two are the
+     * same number. Where they are not, this asks for less destruction, because the reduction is
+     * available from packing the geometry better instead.
+     * @type {number}
+     */
+    simplification_ratio = 0.5;
+
+    /**
+     * How much error a single round is allowed to span, as a multiple of the band's floor. `1` would
+     * admit only the exact minimum and turn every distinct error value into its own round; a large
+     * value admits the whole frontier every time and is the level sweep this replaced.
+     *
+     * Four, measured. On a 98k-triangle sphere against a full sweep: 31% fewer clusters merged into
+     * groups more than twice as coarse as themselves, and 8% fewer at four times, for one extra
+     * level. Two is tighter on the first count — 41% fewer — but costs fourteen levels, and every
+     * level is a page band and a dependent fetch on the way down.
+     * @type {number}
+     */
+    error_band_growth = 4;
+
+    /**
+     * Least share of the frontier a round is allowed to work on, whatever the octave says.
+     *
+     * The octave alone offers no guarantee of progress: geometry whose error is spread thinly and
+     * continuously — a UV sphere, whose poles carry triangles a fraction of the size of its
+     * equator's — puts only a handful of clusters in any one octave, and the build inches forward a
+     * few merges per round. That is not merely slow, it is unbounded: `level_count` is a u8, and a
+     * round loop whose count scales with the cluster count rather than its logarithm will run out of
+     * levels on a real asset. Widening the band until it holds a fixed share of the frontier bounds
+     * the depth logarithmically, and costs error uniformity only where the octave had nothing.
+     * @type {number}
+     */
+    error_band_min_fraction = 0.25;
+
+    /**
+     * Refuse to build past this many levels. `level_count` is a u8 in the container, and a build
+     * that has not converged by then has something else wrong with it.
+     * @type {number}
+     */
+    max_levels = 255;
+}