perf(utils): applyBVH helper for opting scenes into accelerated raycasts

[salmanmkc]

the SDK's per-frame interaction raycaster (Input.performRaycastOnScene) walks every triangle of every mesh under xb.core.scene via THREE.Raycaster.intersectObject (recursive). for demos with non-trivial scene geometry the per-triangle walk dominates the main thread. surfaced in a portals trace where the call chain intersectTriangle -> _computeIntersections -> raycast -> xb.intersect accounted for ~550 ms over a 12 s window.

three-mesh-bvh's accelerated raycaster solves this but has to be opted into per geometry. two public helpers added in src/utils/BVHRaycast:

• enableAcceleratedRaycast(): installs the THREE.Mesh prototype patch + BufferGeometry.computeBoundsTree helper. idempotent across callers so multiple subsystems can ping it safely.
• applyBVH(root, {recursive?}): walks the tree and builds a bounds tree on every mesh's geometry. demos opt in by calling this on the root of their scene after meshes are added.

three-mesh-bvh is loaded as an optional dynamic import (devDependency, type-only build import, await import('three-mesh-bvh') with try/catch). apps without it in their importmap don't break, they just don't get the accelerated raycast. both helpers are async and resolve to false in that case. same pattern as troika-three-text in TextView.

applyBVH skips SkinnedMesh (animated vertices invalidate the bind-pose bvh, and three's SkinnedMesh.raycast overrides the patched prototype anyway) and BatchedMesh (needs three-mesh-bvh's separate computeBatchedBoundsTree building per-draw-range trees on this.boundsTrees). InstancedMesh is kept in, its per-instance _mesh.raycast() does route through the patched Mesh.prototype so the bvh on the shared geometry accelerates each instance test.

geometries without a bounds tree continue using the stock raycaster, so flipping the prototype patch on globally is safe for existing code that never calls applyBVH.

opted in demos/portals by calling xb.applyBVH(this) at the end of PortalGalleryScene.init() after all 5 immersive scenes are added.

measured impact

portals demo trace before vs after (this PR + #371 both applied):

function	original portals trace	this trace	change
intersectTriangle	167 ms	34 ms	-80%
getVertexPosition	137 ms	50 ms	-64%
checkGeometryIntersection	178 ms	12 ms	-93%
_computeIntersections	68 ms	16 ms	-77%
WebGLRenderer.setSize	154 ms	1 ms	-99% (from #371)
getProgramInfoLog	124 ms	49 ms	-60% (incidental, prob fewer shader compiles)

idle went from 8% -> 60% of the trace window. massive frame-budget recovery on a demo that does interaction raycasting + occlusion.

12 tests cover the helpers: prototype patch install / idempotency, recursive build + recursive=false, dispose, per-subclass skip filter (SkinnedMesh, BatchedMesh) + InstancedMesh build, a mixed-tree filter test (all 4 subclass types in one applyBVH call, locks the policy in), end-to-end raycast through the patched path, and cold-dispose safety. 310 tests total.

related: #367 (BVH for face_mirror's per-landmark raycasts; refactored to depend on this PR's util). #371 (occlusion pass setSize fix, contributes the setSize row above).

[ruofeidu]

Awesome!

We discussed BVH years ago in XR Blocks before releasing, but didn't end up with external demos, since while three-mesh-bvh accelerates raycasting from O(n) to O(log n), it is not a silver bullet and comes with significant trade-offs in buildling the tree & memory overhead. And it may break dynamic geometry. The BVH assumes the vertices are static. For simple UI panels, basic primitives, or low-poly elements, the stock linear triangle traversal is so fast that the overhead of traversing a tree structure actually makes the BVH slower (not to mention the wasted build time). But it's a good thing to add on! But it should absolutely NOT be enabled globally.

BVH should only be applied to dense, static environmental meshes (like the Portals demo with multiple loaded immersive worlds, or static 3DGS photogrammetry scans). For simple UI, dynamic objects, and characters, the stock three.js raycaster is both safer and more efficient.

---

Some issues found by Gemini:

Minor Issue to Consider (The SkinnedMesh Trap):
In src/utils/BVHRaycast.ts, applyBVH does the following:

if (obj instanceof THREE.Mesh && obj.geometry) {
  // ... compute bounds tree ...
}

Because THREE.SkinnedMesh and THREE.InstancedMesh inherit from THREE.Mesh, the instanceof check evaluates to true. This means applyBVH will spend CPU time and memory generating a bounds tree on them. However, SkinnedMesh and InstancedMesh override .raycast() on their own prototypes in three.js. Since enableAcceleratedRaycast() only patches THREE.Mesh.prototype.raycast, the BVH acceleration will actually be ignored for them, falling back to stock raycasting anyway.

Recommendation: You may want to skip computing the bounds tree for them to save time and memory:

if (
  obj instanceof THREE.Mesh && 
  !(obj instanceof THREE.SkinnedMesh) && 
  !(obj instanceof THREE.InstancedMesh) &&
  obj.geometry
) {

[salmanmkc]

Awesome!

We discussed BVH years ago in XR Blocks before releasing, but didn't end up with external demos, since while three-mesh-bvh accelerates raycasting from O(n) to O(log n), it is not a silver bullet and comes with significant trade-offs in buildling the tree & memory overhead. And it may break dynamic geometry. The BVH assumes the vertices are static. For simple UI panels, basic primitives, or low-poly elements, the stock linear triangle traversal is so fast that the overhead of traversing a tree structure actually makes the BVH slower (not to mention the wasted build time). But it's a good thing to add on! But it should absolutely NOT be enabled globally.

BVH should only be applied to dense, static environmental meshes (like the Portals demo with multiple loaded immersive worlds, or static 3DGS photogrammetry scans). For simple UI, dynamic objects, and characters, the stock three.js raycaster is both safer and more efficient.

Some issues found by Gemini:

Minor Issue to Consider (The SkinnedMesh Trap): In src/utils/BVHRaycast.ts, applyBVH does the following:

if (obj instanceof THREE.Mesh && obj.geometry) {
  // ... compute bounds tree ...
}

Because THREE.SkinnedMesh and THREE.InstancedMesh inherit from THREE.Mesh, the instanceof check evaluates to true. This means applyBVH will spend CPU time and memory generating a bounds tree on them. However, SkinnedMesh and InstancedMesh override .raycast() on their own prototypes in three.js. Since enableAcceleratedRaycast() only patches THREE.Mesh.prototype.raycast, the BVH acceleration will actually be ignored for them, falling back to stock raycasting anyway.

Recommendation: You may want to skip computing the bounds tree for them to save time and memory:

if (
  obj instanceof THREE.Mesh && 
  !(obj instanceof THREE.SkinnedMesh) && 
  !(obj instanceof THREE.InstancedMesh) &&
  obj.geometry
) {

thanks Ruofei! that makes sense as per the rationale

and great points, yeah so have updated the docstring so hopefully it makes it a bit easier to know when to apply, dense/static/environmental only, not UI/primitives/dynamic. portals only applies it on its own script subtree, not xb.core.scene, gallery part is the most important here cause the rings, etc.

skinned skip yep. on the instanced one though, i don't think gemini's right, InstancedMesh.raycast calls _mesh.raycast() per instance, which goes through the patched Mesh.prototype and short-circuits to geometry.boundsTree. so the bvh actually does get consulted on the shared geometry, kept it in. swapped in a BatchedMesh skip though, that one really does need the batched helpers (computeBatchedBoundsTree builds per-range trees on this.boundsTrees).

added a test that asserts the per-subclass policy, that will hopefully prevent drifts for this part