@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/playground/skinned_blas_refit/sweep_views.js

@@ -0,0 +1,135 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { diff_traced_against_rasterized } from "./diff_traced_against_rasterized.js";
+
+/**
+ * Run the traced-against-rasterized comparison from many directions and report the worst.
+ *
+ * One view proves nothing. Every check that has come back clean so far has come back clean from
+ * *a* camera, and the disagreement people actually see is reported from cameras they orbited to —
+ * so "which views fail" is the question, and answering it by looking is what has cost the most time
+ * on this.
+ *
+ * Views are placed on a sphere around the instance being examined, at several elevations including
+ * from below, because a mesh of long thin slivers presents completely differently edge-on than
+ * face-on and a horizon-only ring would miss half of it.
+ *
+ * The camera is driven directly rather than through the orbital controller, so a sweep does not
+ * depend on the controller's state and leaves it where it found it.
+ */
+
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera
+ * @param {Scene} options.scene
+ * @param {Mesh} options.mesh the instance to orbit and to frame on
+ * @param {function(boolean): void} [options.suspend]
+ * @param {number} [options.azimuths]
+ * @param {number[]} [options.elevations] radians; negative looks up from below
+ * @param {number} [options.distance] multiples of the instance's bounding radius
+ * @param {number} [options.samples] samples per pixel at each view
+ * @returns {Promise<object>}
+ */
+export async function sweep_views({
+                                      renderer,
+                                      camera,
+                                      scene,
+                                      mesh,
+                                      suspend = () => undefined,
+                                      azimuths = 8,
+                                      elevations = [-0.9, -0.3, 0.3, 0.9],
+                                      distance = 2.2,
+                                      samples = 6,
+                                  }) {
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const record = await scene_context.scene_database.debug_table_read_element(
+        'meshes',
+        scene_context.mesh_row_of(mesh)
+    );
+
+    const box = record.bounding_box;
+
+    const centre = new Vector3(
+        (box[0] + box[3]) / 2,
+        (box[1] + box[4]) / 2,
+        (box[2] + box[5]) / 2
+    );
+
+    const radius = Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]) * 0.5;
+
+    const kept = {
+        position: [...camera.transform.position],
+        near: camera.near,
+        far: camera.far,
+    };
+
+    camera.near = radius * 0.01;
+    camera.far = radius * 400;
+
+    const views = [];
+
+    for (const elevation of elevations) {
+        for (let step = 0; step < azimuths; step++) {
+            const azimuth = step / azimuths * Math.PI * 2;
+
+            const range = radius * distance;
+
+            camera.transform.position.set(
+                centre.x + range * Math.cos(elevation) * Math.cos(azimuth),
+                centre.y + range * Math.sin(elevation),
+                centre.z + range * Math.cos(elevation) * Math.sin(azimuth)
+            );
+
+            camera.transform.lookAt(centre);
+
+            const result = await diff_traced_against_rasterized({
+                renderer,
+                camera,
+                scene,
+                suspend,
+                samples,
+            });
+
+            views.push({
+                elevation: +elevation.toFixed(2),
+                azimuth: +(azimuth * 180 / Math.PI).toFixed(0),
+                covered: result.covered,
+                raster_only: result.raster_only,
+                traced_only: result.traced_only,
+                raster_only_pct: result.raster_only_pct,
+                largest: result.largest_components[0] ?? 0,
+                median: result.median_component,
+                converging: result.still_converging,
+                position: [...camera.transform.position].map(v => +v.toFixed(3)),
+            });
+        }
+    }
+
+    camera.transform.position.set(...kept.position);
+    camera.transform.lookAt(centre);
+    camera.near = kept.near;
+    camera.far = kept.far;
+
+    const worst = views.slice().sort((a, b) => b.largest - a.largest);
+
+    // A view whose largest one-directional component is a real blob is a view where something is
+    // actually absent, not a view with more silhouette than the others.
+    const suspicious = views.filter(view =>
+        !view.converging && view.largest >= 400 && view.raster_only > view.traced_only * 2);
+
+    const result = {
+        views,
+        worst: worst.slice(0, 5),
+        suspicious,
+        verdict: suspicious.length === 0
+            ? `pass — ${views.length} views, worst blob ${worst[0]?.largest ?? 0} px, `
+            + `median component ${worst[0]?.median ?? 0} px; nothing is missing from any of them`
+            : `FAIL — ${suspicious.length} of ${views.length} views lose geometry under the tracer, `
+            + `worst blob ${Math.max(...suspicious.map(v => v.largest))} px`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/skinned_blas_refit/verify_instance_bounds.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The AABB of a box's eight corners under a transform.
+ *
+ * Eight corners rather than two: any rotation in the matrix makes a componentwise transform of the
+ * min and max meaningless, which is the trap that makes this worth writing down. Michelle's root
+ * carries the file's axis conversion, so her boxes are rotated and a two-corner comparison reports
+ * violations that are not there and misses ones that are.
+ *
+ * @param {ArrayLike<number>} box `[min.xyz, max.xyz]`
+ * @param {ArrayLike<number>} matrix column-major 4x4
+ * @returns {number[]} `[min.xyz, max.xyz]`
+ */
+export function transformed_box(box: ArrayLike<number>, matrix: ArrayLike<number>): number[];
+/**
+ * Check every mesh in the scene.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {PerspectiveCamera} [options.camera] rendered a few times first, so the bounds-refresh
+ * chain has published something to check
+ * @param {number} [options.tolerance] fraction of an instance's own size it may escape by
+ * @returns {Promise<object>}
+ */
+export function verify_instance_bounds({ renderer, scene, camera, tolerance }: {
+    renderer: Renderer;
+    scene: Scene;
+    camera?: PerspectiveCamera;
+    tolerance?: number;
+}): Promise<object>;
+//# sourceMappingURL=verify_instance_bounds.d.ts.map

package/src/shade/playground/skinned_blas_refit/verify_instance_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_instance_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_instance_bounds.js"],"names":[],"mappings":"AAoFA;;;;;;;;;;;GAWG;AACH,qCAJW,UAAU,MAAM,CAAC,UACjB,UAAU,MAAM,CAAC,GACf,MAAM,EAAE,CAqBpB;AAuCD;;;;;;;;;;GAUG;AACH;IAP6B,QAAQ;IACX,KAAK;IACQ,MAAM;IAEjB,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CA4E3B"}

package/src/shade/playground/skinned_blas_refit/verify_instance_bounds.js

@@ -0,0 +1,240 @@
+import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+
+/**
+ * Does every instance's published world box actually contain its geometry?
+ *
+ * This is upstream of the tree and cheap to get wrong, and getting it wrong looks exactly like a
+ * broken BVH. `chunk_ray_query_nearest` tests the TLAS leaf's world AABB *before* it transforms the
+ * ray and enters the BLAS:
+ *
+ * ```wgsl
+ * if(!aabb3_intersects_ray(node.bounds, ...)){ ...; continue; }
+ * ```
+ *
+ * So a leaf box smaller than the geometry it stands for is a hard clip. Rays that would have hit
+ * the parts sticking out never get to ask the BLAS about them, and those parts are simply absent
+ * from the traced image while the rasterizer — which consults no such box — draws them. The pieces
+ * that go missing are the outlying ones, which is the tell: a compact core survives and the
+ * extremities do not.
+ *
+ * The rasterizer cannot detect this and neither can any amount of checking the tree, because the
+ * tree is fine. Only the composition is wrong.
+ *
+ * The check is exact rather than statistical: eight corners of the geometry's own bounding box,
+ * through the node matrix the shader uses, against the box the shader tests. No sampling, no
+ * thresholds, no images.
+ */
+
+/**
+ * Read a range of a GPU buffer back to the CPU.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer must carry `COPY_SRC`
+ * @param {number} offset bytes
+ * @param {number} size bytes
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const aligned_offset = Math.floor(offset / 4) * 4;
+    const slack = offset - aligned_offset;
+    const aligned_size = Math.ceil((size + slack) / 4) * 4;
+
+    const staging = device.createBuffer({
+        label: 'verify/bounds readback',
+        size: aligned_size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'verify/bounds readback' });
+
+    encoder.copyBufferToBuffer(buffer, aligned_offset, staging, 0, aligned_size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(slack, slack + size);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Apply a column-major 4x4 to a point.
+ *
+ * @param {ArrayLike<number>} m
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number[]}
+ */
+function transform_point(m, x, y, z) {
+    const w = m[3] * x + m[7] * y + m[11] * z + m[15];
+
+    const inverse_w = w === 0 ? 1 : 1 / w;
+
+    return [
+        (m[0] * x + m[4] * y + m[8] * z + m[12]) * inverse_w,
+        (m[1] * x + m[5] * y + m[9] * z + m[13]) * inverse_w,
+        (m[2] * x + m[6] * y + m[10] * z + m[14]) * inverse_w,
+    ];
+}
+
+/**
+ * The AABB of a box's eight corners under a transform.
+ *
+ * Eight corners rather than two: any rotation in the matrix makes a componentwise transform of the
+ * min and max meaningless, which is the trap that makes this worth writing down. Michelle's root
+ * carries the file's axis conversion, so her boxes are rotated and a two-corner comparison reports
+ * violations that are not there and misses ones that are.
+ *
+ * @param {ArrayLike<number>} box `[min.xyz, max.xyz]`
+ * @param {ArrayLike<number>} matrix column-major 4x4
+ * @returns {number[]} `[min.xyz, max.xyz]`
+ */
+export function transformed_box(box, matrix) {
+    const low = [Infinity, Infinity, Infinity];
+    const high = [-Infinity, -Infinity, -Infinity];
+
+    for (let corner = 0; corner < 8; corner++) {
+        const point = transform_point(
+            matrix,
+            box[(corner & 1) ? 3 : 0],
+            box[(corner & 2) ? 4 : 1],
+            box[(corner & 4) ? 5 : 2]
+        );
+
+        for (let axis = 0; axis < 3; axis++) {
+            low[axis] = Math.min(low[axis], point[axis]);
+            high[axis] = Math.max(high[axis], point[axis]);
+        }
+    }
+
+    return [...low, ...high];
+}
+
+/**
+ * How far `inner` pokes out of `outer`, per axis, as a fraction of `inner`'s own size.
+ *
+ * Relative so the answer means the same thing whatever the asset's units are, and signed per side
+ * so the report says which way it escaped.
+ *
+ * @param {number[]} inner
+ * @param {number[]} outer
+ * @returns {{worst: number, sides: object[]}}
+ */
+function containment_error(inner, outer) {
+    const sides = [];
+
+    let worst = 0;
+
+    for (let axis = 0; axis < 3; axis++) {
+        const span = Math.max(1e-9, inner[axis + 3] - inner[axis]);
+
+        const below = (outer[axis] - inner[axis]) / span;
+        const above = (inner[axis + 3] - outer[axis + 3]) / span;
+
+        if (below > 0) {
+            sides.push({ axis, side: 'min', escapes_by: +below.toFixed(4) });
+
+            worst = Math.max(worst, below);
+        }
+
+        if (above > 0) {
+            sides.push({ axis, side: 'max', escapes_by: +above.toFixed(4) });
+
+            worst = Math.max(worst, above);
+        }
+    }
+
+    return { worst, sides };
+}
+
+/**
+ * Check every mesh in the scene.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {PerspectiveCamera} [options.camera] rendered a few times first, so the bounds-refresh
+ * chain has published something to check
+ * @param {number} [options.tolerance] fraction of an instance's own size it may escape by
+ * @returns {Promise<object>}
+ */
+export async function verify_instance_bounds({ renderer, scene, camera, tolerance = 1e-3 }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const geometries = graphics.geometries;
+
+    if (camera !== undefined) {
+        for (let i = 0; i < 8; i++) {
+            renderer.render(camera, scene, 0);
+
+            await device.queue.onSubmittedWorkDone();
+        }
+    }
+
+    const stride = GEOMETRY_METADATA_STRUCT.aligned_size;
+
+    const box_offset = GEOMETRY_METADATA_STRUCT.fields.find(f => f.name === 'bounding_box').offset;
+
+    const rows = [];
+
+    for (const mesh of scene.instances.instances) {
+        const row = scene_context.mesh_row_of(mesh);
+
+        if (row === undefined) {
+            continue;
+        }
+
+        const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+
+        const geometry_index = record.geometry;
+
+        const geometry_box = [...new Float32Array(await read_back(
+            device,
+            geometries.buffer_metadata,
+            geometry_index * stride + box_offset,
+            24
+        ))];
+
+        // the same matrix `chunk_ray_query_nearest` inverts to put the ray in geometry space
+        const world_box = transformed_box(geometry_box, mesh.transform_global.matrix);
+
+        const error = containment_error(world_box, record.bounding_box);
+
+        rows.push({
+            name: mesh.name ?? mesh.constructor.name,
+            skinned: mesh.isSkinnedMesh === true,
+            row,
+            geometry_index,
+            geometry_box: geometry_box.map(v => +v.toFixed(3)),
+            geometry_in_world: world_box.map(v => +v.toFixed(3)),
+            published: [...record.bounding_box].map(v => +v.toFixed(3)),
+            worst_escape: +error.worst.toFixed(4),
+            escapes: error.sides,
+        });
+    }
+
+    const failures = rows.filter(entry => entry.worst_escape > tolerance);
+
+    const result = {
+        rows,
+        failures,
+        verdict: failures.length === 0
+            ? `pass — all ${rows.length} instances are contained by the box the TLAS tests them with`
+            : `FAIL — ${failures.length} of ${rows.length} instances stick out of their own TLAS box, `
+            + `worst by ${(Math.max(...failures.map(f => f.worst_escape)) * 100).toFixed(1)}% of its `
+            + `size. Rays are being clipped before they reach the BLAS, and the traced image loses `
+            + `whatever sticks out.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/skinned_blas_refit/verify_leaf_triangles.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {object} [options.owner] the identity the tree is registered under
+ * @param {object} [options.target] an explicit refit target, for a tree whose owner handle is not
+ * reachable — a skinned clone's metadata row lives inside the skinning context. Every copy of a
+ * geometry shares one topology, so a clone's target is the source's with its own `node_word_offset`
+ * substituted, and that is composable from the published lookup alone.
+ * @param {number} options.geometry_index the row whose vertices the leaves index into
+ * @param {number} [options.tolerance] fraction of a leaf's own size a vertex may sit outside by
+ * @returns {Promise<object>}
+ */
+export function verify_leaf_triangles({ renderer, owner, target: explicit_target, geometry_index, tolerance, }: {
+    renderer: Renderer;
+    owner?: object;
+    target?: object;
+    geometry_index: number;
+    tolerance?: number;
+}): Promise<object>;
+//# sourceMappingURL=verify_leaf_triangles.d.ts.map

package/src/shade/playground/skinned_blas_refit/verify_leaf_triangles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js"],"names":[],"mappings":"AA4DA;;;;;;;;;;;GAWG;AACH;IAV6B,QAAQ;IACT,KAAK,GAAtB,MAAM;IACW,MAAM,GAAvB,MAAM;IAIU,cAAc,EAA9B,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAmI3B"}

package/src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js

@@ -0,0 +1,202 @@
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import {
+    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
+} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
+import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { shader_blas_audit_leaf_triangles } from "./shader_blas_audit_leaf_triangles.js";
+
+/**
+ * Does every leaf's box actually contain the triangle a ray will test inside it?
+ *
+ * This is the seam nothing else covers. The refit fills a leaf's box using
+ * `geometry_read_triangle_bounds`; `ray_query_blas_nearest` fetches the triangle it tests using
+ * `geometry_read_triangle_vertices`. Two functions, one encoded payload, and every check so far has
+ * only ever exercised the first — the structural tests confirm the tree is a consistent tree, and a
+ * tree consistently bounding the *wrong* triangles is consistent.
+ *
+ * When they disagree the failure is silent and view-dependent: a ray descends into a box, tests a
+ * triangle that is elsewhere, misses, and a whole meshlet is absent from the traced image while the
+ * rasterizer — which never consults the tree — draws it.
+ *
+ * So this runs the intersector's reader over every leaf on the live asset and holds its answer
+ * against the box the tree carries. Containment, not equality: a leaf's box is allowed to be
+ * larger than its triangle, and under deformation it will be, because the refit and this audit can
+ * run a frame apart. It is not allowed to be somewhere else.
+ */
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} offset
+ * @param {number} size
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const staging = device.createBuffer({
+        label: 'audit/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'audit/readback' });
+
+    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(0);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {object} [options.owner] the identity the tree is registered under
+ * @param {object} [options.target] an explicit refit target, for a tree whose owner handle is not
+ * reachable — a skinned clone's metadata row lives inside the skinning context. Every copy of a
+ * geometry shares one topology, so a clone's target is the source's with its own `node_word_offset`
+ * substituted, and that is composable from the published lookup alone.
+ * @param {number} options.geometry_index the row whose vertices the leaves index into
+ * @param {number} [options.tolerance] fraction of a leaf's own size a vertex may sit outside by
+ * @returns {Promise<object>}
+ */
+export async function verify_leaf_triangles({
+                                                renderer,
+                                                owner,
+                                                target: explicit_target,
+                                                geometry_index,
+                                                tolerance = 1e-3,
+                                            }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const geometries = graphics.geometries;
+    const blas = geometries.blas;
+    const meshlets = geometries.meshlets;
+
+    const target = explicit_target ?? blas.get_refit_target(owner);
+
+    if (target === undefined) {
+        throw new Error('that owner has no resident tree');
+    }
+
+    const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
+
+    const out_bytes = leaf_count * 6 * Float32Array.BYTES_PER_ELEMENT;
+
+    const out_bounds = device.createBuffer({
+        label: 'audit/leaf triangles',
+        size: out_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'audit/leaf triangles');
+
+    shader_blas_audit_leaf_triangles.dispatchLinear({
+        encoder: cmd,
+        element_count: leaf_count,
+        bindings: {
+            settings: cmd.allocateTransientValueBuffer(BLAS_LEAF_BOUNDS_SETTINGS_STRUCT, {
+                leaf_count,
+                node_word_offset,
+                leaf_nodes_offset,
+                geometry_index,
+            }),
+            leaf_nodes: blas.buffer_leaf_nodes,
+            geometries: geometries.buffer_metadata,
+            meshlet_metadata: meshlets.buffer_metadata,
+            meshlet_data: meshlets.buffer_data,
+            nodes: blas.buffer_data,
+            out_bounds,
+        },
+    });
+
+    cmd.finish();
+
+    await device.queue.onSubmittedWorkDone();
+
+    const intersector = new Float32Array(await read_back(device, out_bounds, 0, out_bytes));
+
+    const leaves = new Uint32Array(await read_back(
+        device,
+        blas.buffer_leaf_nodes,
+        leaf_nodes_offset * Uint32Array.BYTES_PER_ELEMENT,
+        leaf_count * Uint32Array.BYTES_PER_ELEMENT
+    ));
+
+    const node_bytes = Math.max(...leaves) * BVH2_NODE_STRUCT.size + BVH2_NODE_STRUCT.size;
+
+    const nodes = new Float32Array(await read_back(
+        device,
+        blas.buffer_data,
+        node_word_offset * Uint32Array.BYTES_PER_ELEMENT,
+        node_bytes
+    ));
+
+    out_bounds.destroy();
+
+    let escaped = 0;
+    let worst = 0;
+
+    const examples = [];
+
+    for (let i = 0; i < leaf_count; i++) {
+        const base = leaves[i] * BVH_NODE_STRIDE_WORDS + BVH_NODE_BOUNDS_WORD;
+
+        const source = i * 6;
+
+        let error = 0;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const span = Math.max(1e-9, nodes[base + axis + 3] - nodes[base + axis]);
+
+            error = Math.max(
+                error,
+                (nodes[base + axis] - intersector[source + axis]) / span,
+                (intersector[source + axis + 3] - nodes[base + axis + 3]) / span
+            );
+        }
+
+        if (error > tolerance) {
+            escaped += 1;
+
+            if (examples.length < 5) {
+                examples.push({
+                    leaf: i,
+                    node: leaves[i],
+                    tree_box: [0, 1, 2, 3, 4, 5].map(k => +nodes[base + k].toFixed(3)),
+                    intersector_box: [0, 1, 2, 3, 4, 5].map(k => +intersector[source + k].toFixed(3)),
+                    escapes_by: +error.toFixed(4),
+                });
+            }
+        }
+
+        worst = Math.max(worst, error);
+    }
+
+    const result = {
+        leaf_count,
+        escaped,
+        worst: +worst.toFixed(5),
+        examples,
+        verdict: escaped === 0
+            ? `pass — all ${leaf_count} leaves bound the triangle the intersector fetches for them`
+            : `FAIL — ${escaped} of ${leaf_count} leaves bound a different triangle than the `
+            + `intersector tests, worst by ${(worst * 100).toFixed(1)}% of the leaf's own size. `
+            + `Rays descend into those boxes, test a triangle that is elsewhere, and miss.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Run the check.
+ *
+ * Two samples, taken far enough apart in the dance that the pose is meaningfully different. Each
+ * sample holds the two boxes against each other; the pair holds the tree against *itself* over
+ * time, which is what catches a refit that runs but reads the source's rest-pose vertices — the
+ * boxes would agree at every sample and never move.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} [options.tolerance] relative box disagreement to accept
+ * @returns {Promise<object>} the samples and the verdict
+ */
+export function verify_skinned_blas_refit({ renderer, camera, scene, mesh, tolerance, }: {
+    renderer: Renderer;
+    camera: PerspectiveCamera;
+    scene: Scene;
+    mesh: SkinnedMesh;
+    tolerance?: number;
+}): Promise<object>;
+/**
+ * Does each leaf's box belong to the triangle that leaf names?
+ *
+ * The check above cannot see this, and it is worth being explicit about why. Its two properties —
+ * root box equals the metadata box, every internal node equals its children's union — are both
+ * invariant under *any* permutation of triangles among leaves. Deal the same set of triangle boxes
+ * out to the wrong leaves and the union of all of them is unchanged, so the root still matches, and
+ * the climb still computes each node from whatever its children hold. A tree that fits every
+ * triangle to the wrong leaf passes both and traces garbage: a ray descends into a box, tests the
+ * triangle the leaf names, and that triangle is somewhere else entirely.
+ *
+ * The way to see it is to refit a geometry that is **not** deforming, and hold the result against
+ * the tree it was copied from. The CPU builder put each leaf's box there with the correspondence
+ * that is correct by construction; the refit recomputes those boxes from the vertex buffer. Nothing
+ * moved in between, so the two have to be the same bytes — and a permutation is exactly what stops
+ * them being.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {MeshletGeometry} options.geometry a geometry nothing deforms
+ * @returns {Promise<object>}
+ */
+export function verify_leaf_correspondence({ renderer, geometry }: {
+    renderer: Renderer;
+    geometry: MeshletGeometry;
+}): Promise<object>;
+//# sourceMappingURL=verify_skinned_blas_refit.d.ts.map

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAkF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA4F3B"}