mrdoob · agargaro · Jun 7, 2025 · Jun 8, 2025
diff --git a/examples/files.json b/examples/files.json
@@ -7,6 +7,7 @@
 		"webgl_animation_skinning_morph",
 		"webgl_animation_multiple",
 		"webgl_animation_walk",
+		"webgl_batch_lod_bvh",
 		"webgl_camera",
 		"webgl_camera_array",
 		"webgl_camera_logarithmicdepthbuffer",

diff --git a/examples/screenshots/webgl_batch_lod_bvh.jpg b/examples/screenshots/webgl_batch_lod_bvh.jpg
diff --git a/examples/tags.json b/examples/tags.json
@@ -13,6 +13,7 @@
 	"physics_rapier_joints": [ "external" ],
 	"physics_rapier_character_controller": [ "external" ],
 	"physics_rapier_vehicle_controller": [ "external" ],
+	"webgl_batch_lod_bvh": [ "external", "accelerate", "performance", "extension", "plugin", "library", "three.ez" ],
 	"webgl_clipping": [ "solid" ],
 	"webgl_clipping_advanced": [ "solid" ],
 	"webgl_clipping_intersection": [ "solid" ],

diff --git a/examples/webgl_batch_lod_bvh.html b/examples/webgl_batch_lod_bvh.html
@@ -0,0 +1,276 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<title>three.js raycaster - bvh</title>
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
+		<link type="text/css" rel="stylesheet" href="main.css">
+		<style>
+			a {
+				text-decoration: underline;
+			}
+		</style>
+	</head>
+
+	<body>
+		<div id="info">
+			<a href="https://threejs.org" target="_blank" rel="noopener">three.js</a> batch lod bvh - <a href="https://github.com/agargaro/batched-mesh-extensions" target="_blank" rel="noopener">@three.ez/batched-mesh-extensions</a><br/>
+			BatchedMesh with 10 geometries and 500k instances. Each geometry has 5 LODs (4 generated with meshoptimizer). <br>
+			Frustum culling and raycasting are accelerated by using BVHs (TLAS & BLAS). <br>
+			See <a href="https://github.com/agargaro/batched-mesh-extensions" target="_blank" rel="noopener">main project repository</a> for more information and examples on BatchedMesh extensions.
+		</div>
+
+		<script type="importmap">
+			{
+				"imports": {
+					"three": "../build/three.module.js",
+					"three/addons/": "./jsm/",
+
+					"three-mesh-bvh": "https://cdn.jsdelivr.net/npm/[email protected]/build/index.module.js",
+
+					"@three.ez/batched-mesh-extensions": "https://cdn.jsdelivr.net/npm/@three.ez/[email protected]/build/webgl.js",
+					"bvh.js": "https://cdn.jsdelivr.net/npm/[email protected]/build/index.js",
+
+					"@three.ez/simplify-geometry": "https://cdn.jsdelivr.net/npm/@three.ez/[email protected]/build/index.js",
+					"meshoptimizer": "https://cdn.jsdelivr.net/npm/[email protected]/+esm"
+				}
+			}
+		</script>
+
+		<script type="module">
+
+			import * as THREE from 'three';
+			import Stats from 'three/addons/libs/stats.module.js';
+			import { MapControls } from 'three/addons/controls/MapControls.js';
+			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
+
+			import { acceleratedRaycast, computeBatchedBoundsTree } from 'three-mesh-bvh';
+
+			import { createRadixSort, extendBatchedMeshPrototype, getBatchedMeshLODCount } from '@three.ez/batched-mesh-extensions';
+			import { performanceRangeLOD, simplifyGeometriesByErrorLOD } from '@three.ez/simplify-geometry';
+
+			// add and override BatchedMesh methods ( @three.ez/batched-mesh-extensions )
+			extendBatchedMeshPrototype();
+
+			// add the extension functions ( three-mesh-bvh )
+			THREE.Mesh.prototype.raycast = acceleratedRaycast;
+			THREE.BatchedMesh.prototype.computeBoundsTree = computeBatchedBoundsTree;
+
+			let stats;
+			let camera, scene, renderer;
+
+			const instancesCount = 500000;
+			let batchedMesh;
+			let lastHoveredInstance = null;
+			const lastHoveredColor = new THREE.Color();
+			const yellow = new THREE.Color( 'yellow' );
+
+			const raycaster = new THREE.Raycaster();
+			const mouse = new THREE.Vector2( 1, 1 );
+			const position = new THREE.Vector3();
+			const quaternion = new THREE.Quaternion();
+			const scale = new THREE.Vector3( 1, 1, 1 );
+			const matrix = new THREE.Matrix4();
+			const color = new THREE.Color();
+
+			init();
+
+			async function init() {
+
+				// environment
+				camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.1, 600 );
+				camera.position.set( 0, 10, 50 );
+
+				scene = new THREE.Scene();
+				scene.fog = new THREE.Fog( 0x000000, 500, 600 );
+
+				const ambient = new THREE.AmbientLight();
+				scene.add( camera, ambient );
+
+				const dirLight = new THREE.DirectionalLight( 'white', 2 );
+				camera.add( dirLight, dirLight.target );
+
+				// renderer
+				renderer = new THREE.WebGLRenderer( { antialias: true } );
+				renderer.setPixelRatio( window.devicePixelRatio );
+				renderer.setSize( window.innerWidth, window.innerHeight );
+				document.body.appendChild( renderer.domElement );
+
+				raycaster.firstHitOnly = true;
+
+				stats = new Stats();
+				document.body.appendChild( stats.dom );
+
+				const controls = new MapControls( camera, renderer.domElement );
+				controls.maxPolarAngle = Math.PI / 2;
+
+				const geometries = [
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 1, 1 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 1, 2 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 1, 3 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 1, 4 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 1, 5 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 2, 1 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 2, 3 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 3, 1 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 4, 1 ),
+					new THREE.TorusKnotGeometry( 1, 0.4, 256, 32, 5, 3 )
+				];
+
+				// generate 4 LODs (levels of detail) for each geometry
+				const geometriesLODArray = await simplifyGeometriesByErrorLOD( geometries, 4, performanceRangeLOD );
+
+				// create BatchedMesh
+				const { vertexCount, indexCount, LODIndexCount } = getBatchedMeshLODCount( geometriesLODArray );
+				batchedMesh = new THREE.BatchedMesh( instancesCount, vertexCount, indexCount, new THREE.MeshStandardMaterial( { metalness: 0.2, roughness: 0.2 } ) );
+
+				// enable radix sort for better performance
+				batchedMesh.customSort = createRadixSort( batchedMesh );
+
+				// add geometries and their LODs to the batched mesh ( all LODs share the same position array )
+				for ( let i = 0; i < geometriesLODArray.length; i ++ ) {
+
+					const geometryLOD = geometriesLODArray[ i ];
+					const geometryId = batchedMesh.addGeometry( geometryLOD[ 0 ], - 1, LODIndexCount[ i ] );
+					batchedMesh.addGeometryLOD( geometryId, geometryLOD[ 1 ], 15 );
+					batchedMesh.addGeometryLOD( geometryId, geometryLOD[ 2 ], 75 );
+					batchedMesh.addGeometryLOD( geometryId, geometryLOD[ 3 ], 125 );
+					batchedMesh.addGeometryLOD( geometryId, geometryLOD[ 4 ], 200 );
+
+				}
+
+				// place instances in a 2D grid with randomized rotation and color
+				const sqrtCount = Math.ceil( Math.sqrt( instancesCount ) );
+				const size = 5.5;
+				const start = ( sqrtCount / - 2 * size ) + ( size / 2 );
+
+				for ( let i = 0; i < instancesCount; i ++ ) {
+
+					const r = Math.floor( i / sqrtCount );
+					const c = i % sqrtCount;
+					const id = batchedMesh.addInstance( Math.floor( Math.random() * geometriesLODArray.length ) );
+					position.set( c * size + start, 0, r * size + start );
+					quaternion.random();
+					batchedMesh.setMatrixAt( id, matrix.compose( position, quaternion, scale ) );
+					batchedMesh.setColorAt( id, color.setHSL( Math.random(), 0.6, 0.5 ) );
+
+				}
+
+				// compute blas (bottom-level acceleration structure) bvh ( three-mesh-bvh )
+				batchedMesh.computeBoundsTree();
+
+				// compute tlas (top-level acceleration structure) bvh ( @three.ez/batched-mesh-extensions )
+				batchedMesh.computeBVH( THREE.WebGLCoordinateSystem );
+
+				scene.add( batchedMesh );
+
+				// set up gui
+				const config = {
+					freeze: false,
+					useBVH: true,
+					useLOD: true
+				};
+
+				const bvh = batchedMesh.bvh;
+				const lods = batchedMesh._geometryInfo.map( x => x.LOD );
+				const onBeforeRender = batchedMesh.onBeforeRender;
+
+				const gui = new GUI();
+
+				gui.add( batchedMesh, 'instanceCount' ).disable();
+
+				gui.add( config, 'freeze' ).onChange( v => {
+
+					batchedMesh.onBeforeRender = v ? () => {} : onBeforeRender;
+
+				} );
+
+				const frustumCullingFolder = gui.addFolder( 'Frustum culling & raycasting' );
+				frustumCullingFolder.add( config, 'useBVH' ).onChange( v => {
+
+					batchedMesh.bvh = v ? bvh : null;
+
+				} );
+
+				const geometriesFolder = gui.addFolder( 'Geometries' );
+				geometriesFolder.add( config, 'useLOD' ).onChange( v => {
+
+					const geometryInfo = batchedMesh._geometryInfo;
+					for ( let i = 0; i < geometryInfo.length; i ++ ) {
+
+						geometryInfo[ i ].LOD = v ? lods[ i ] : null;
+
+					}
+
+				} );
+
+				document.addEventListener( 'pointermove', onPointerMove );
+				window.addEventListener( 'resize', onWindowResize );
+				onWindowResize();
+
+				renderer.setAnimationLoop( animate );
+
+			}
+
+
+			function onPointerMove( event ) {
+
+				event.preventDefault();
+
+				mouse.x = ( event.clientX / window.innerWidth ) * 2 - 1;
+				mouse.y = - ( event.clientY / window.innerHeight ) * 2 + 1;
+
+				raycast();
+
+			}
+
+
+			function onWindowResize() {
+
+				camera.aspect = window.innerWidth / window.innerHeight;
+				camera.updateProjectionMatrix();
+
+				renderer.setSize( window.innerWidth, window.innerHeight );
+
+			}
+
+			function raycast() {
+
+				raycaster.setFromCamera( mouse, camera );
+				const intersection = raycaster.intersectObject( batchedMesh );
+
+				const batchId = intersection.length > 0 ? intersection[ 0 ].batchId : null;
+
+				if ( lastHoveredInstance === batchId ) return;
+
+				if ( lastHoveredInstance ) {
+
+					batchedMesh.setColorAt( lastHoveredInstance, lastHoveredColor );
+
+				}
+
+				if ( batchId ) {
+
+					batchedMesh.getColorAt( batchId, lastHoveredColor );
+					batchedMesh.setColorAt( batchId, yellow );
+
+				}
+
+				lastHoveredInstance = batchId;
+
+			}
+
+			function animate() {
+
+				stats.begin();
+
+				renderer.render( scene, camera );
+
+				stats.end();
+
+			}
+
+		</script>
+
+	</body>
+</html>