Three.ez/InstancedMesh2 - Enhanced InstancedMesh with frustum culling, fast raycasting (BVH), sorting, visibility management, LOD, skinning and more

agargaro · August 15, 2024, 1:27pm

Three.ez - InstancedMesh2

Simplify your three.js application development with three.ez!

InstancedMesh2 is an alternative version of InstancedMesh with enhanced features for performance and usability:

Per-instance frustum culling: skip rendering for out-of-view instances.
Sorting: reduce overdraw and manage transparent objects efficiently.
Spatial indexing (dynamic BVH): speed up raycasting and frustum culling.
Dynamic capacity: add or remove instances seamlessly.
Per-instance visibility: toggle visibility for each instance individually.
Per-instance opacity: set opacity for each instance individually.
Object3D-like instances: use instances like Object3D with transforms and custom data.
Per-instance uniforms: assign unique shader data to individual instances.
Level of Detail (LOD): dynamically adjust instance detail based on distance.
Shadow LOD: optimize shadow rendering with lower detail for distant instances.
Skinning: apply skeletal animations to instances for more complex and dynamic movements.

const myInstancedMesh = new InstancedMesh2(geometry, material);

myInstancedMesh.addInstances(count, (obj, index) => {
  obj.position.x = index;
});

Live Examples

Vanilla

Dynamic adding with BVH (thanks to Saumac)

Using three.ez/main

Using other libraries

Threlte
React-three-fiber (thanks to Saumac)

Need help?

Join us on Discord or open an issue on GitHub.

Like it?

If you like this project, please leave a star. Thank you!

Documentation

The documentation is available here.

Installation

You can install it via npm using the following command:

npm install @three.ez/instanced-mesh

Or you can import it from CDN:

<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three/examples/jsm/",
    "@three.ez/instanced-mesh": "https://cdn.jsdelivr.net/npm/@three.ez/instanced-mesh/build/index.js",
    "bvh.js": "https://cdn.jsdelivr.net/npm/bvh.js/build/index.js"
  }
}
</script>

Features

Per-instance frustum culling

Avoiding rendering objects outside the camera frustum can drastically improve performance (especially for complex geometries).

Frustum culling by default is performed by iterating all instances, but it is possible to speed up this process by creating a spatial indexing data structure (BVH).

By default perObjectFrustumCulled is true.

Sorting

Sorting can be used to decrease overdraw and render transparent objects.

It’s possible to improve sort performance adding a customSort, like built-in createRadixSort.

By default sortObjects is false.

import { createRadixSort } from '@three.ez/instanced-mesh';

myInstancedMesh.sortObjects = true;
myInstancedMesh.customSort = createRadixSort(myInstancedMesh);

Spatial indexing (dynamic BVH)

To speed up raycasting and frustum culling, a spatial indexing data structure can be created to contain the boundingBoxes of all instances.

This works very well if the instances are mostly static (updating a BVH can be expensive) and scattered in world space.

Setting a margin makes BVH updating faster, but may make raycasting and frustum culling slightly slower.

myInstancedMesh.computeBVH({ margin: 0 });

Dynamic capacity

Manage a dynamic number of instances, automatically expanding the data buffers as needed to accommodate additional instances.

If not specified, capacity is 1000.

const myInstancedMesh = new InstancedMesh2(geometry, material, { capacity: count }); 

myInstancedMesh.addInstances(count, (obj, index) => { ... }); // add instances and expand buffer if necessary

myInstancedMesh.removeInstances(id0, idx, ...);

myInstancedMesh.clearInstances(); // remove all instances

Per-instance visibility

Set the visibility status of each instance:

myInstancedMesh.setVisibilityAt(index, false);
myInstancedMesh.instances[0].visible = false; // if instances array is created

Per-instance opacity

Set the opacity of each instance:

myInstancedMesh.setOpacityAt(index, 0.5);
myInstancedMesh.instances[0].opacity = 0.5; // if instances array is created

Object3D-like instances

It’s possible to create an array of InstancedEntity (Object3D-like) in order to easily manipulate instances, using more memory.

const myInstancedMesh = new InstancedMesh2(geometry, material, { createEntities: true });

myInstancedMesh.instances[0].customData = {};
myInstancedMesh.instances[0].position.random();
myInstancedMesh.instances[0].rotateX(Math.PI);
myInstancedMesh.instances[0].updateMatrix(); // necessary after transformations

Per-instance uniforms

Assign unique shader uniforms to each instance, working with every materials.

myInstancedMesh.initUniformsPerInstance({ fragment: { metalness: 'float', roughness: 'float', emissive: 'vec3' } });

myInstancedMesh.setUniformAt(index, 'metalness', 0.5);
myInstancedMesh.instances[0].setUniform('emissive', new Color('white')); // if instances array is created

Level of Detail (LOD)

Improve rendering performance by dynamically adjusting the detail level of instances based on their distance from the camera.

Use simplified geometries for distant objects to optimize resources.

myInstancedMesh.addLOD(geometryMid, material, 50);
myInstancedMesh.addLOD(geometryLow, material, 200);

Shadow LOD

Optimize shadow rendering by reducing the detail level of instances casting shadows based on their distance from the camera.

myInstancedMesh.addShadowLOD(geometryMid);
myInstancedMesh.addShadowLOD(geometryLow, 100);

Skinning

Apply skeletal animations to instances for more complex and dynamic movements.

myInstancedMesh.initSkeleton(skeleton);

mixer.update(time);
myInstancedMesh.setBonesAt(index);

Raycasting tips

If you are not using a BVH, you can set the raycastOnlyFrustum property to true to avoid iterating over all instances.

It’s recommended to use three-mesh-bvh to create a geometry BVH.

Special thanks to

References

PavelBoytchev · August 15, 2024, 1:37pm

So, you have your own implementation of BVH?

agargaro · August 15, 2024, 1:44pm

Yes but actually… I lied on readme (it uses also bvh.js package) have to fix it!

I created a separate package for BVH management with a generic implementation (no dependencies on three.js) so that it can be easily used with any application (it can be used also for BatchedMesh for example).

I will document that repository shortly as well; the usage is very simple. Here you can find how it is used in a wrapper (to handle frustum culling and raycasting):

github.com

three-ez/instanced-mesh/blob/e6c3bc14c0e68ca9889082ac54b3e7be36f62a58/src/objects/InstancedMeshBVH.ts

import { Box3, Matrix4, Raycaster } from 'three';
import { BVH, BVHNode, FloatArray, HybridBuilder, WebGLCoordinateSystem } from 'bvh.js';
import { InstancedMesh2 } from './InstancedMesh2.js';

type NodeData = {};
type LeafData = number; // instance id

export class InstancedMeshBVH {
    public target: InstancedMesh2;
    public geoBoundingBox: Box3;
    public bvh: BVH<NodeData, LeafData>;
    public map = new Map<number, BVHNode<NodeData, LeafData>>();
    protected _arrayType: typeof Float32Array | typeof Float64Array;

    constructor(target: InstancedMesh2<any, any, any>, margin = 0, highPrecision = false) {
        this.target = target;
        if (!target.geometry.boundingBox) target.geometry.computeBoundingBox();
        this.geoBoundingBox = target.geometry.boundingBox;
        this._arrayType = highPrecision ? Float64Array : Float32Array;
        this.bvh = new BVH(new HybridBuilder(margin), WebGLCoordinateSystem);

This file has been truncated. show original

manthrax · August 16, 2024, 5:51am

That 1m trees demo is sick.

agargaro · August 16, 2024, 1:45pm

Thank you sensei!

I will post an open world demo soon

agargaro · November 5, 2024, 10:10pm

I am finalizing the new feature: shadow LODs

Here is an example:

const boxGeo = new BoxGeometry(100, 1000, 100);
const trees = new InstancedMesh2(main.renderer, count, treeGLTF.geometry, treeGLTF.material);
trees.addLOD(boxGeo, new MeshLambertMaterial(), 100);
trees.addShadowLOD(trees.geometry);
trees.addShadowLOD(boxGeo, 50);

agargaro · March 25, 2025, 10:21pm

Post updated to release 0.3.1 with all new features.

sdog_m · April 18, 2025, 7:15am

        this.rectInstanceMesh.addInstances(1, (obj, index) => {
          let map = texureLoader.load(data.topMap)
          obj.owner.material[0].map = map
        })

I set it up according to the code above, and all instances apply the same texture
How to set different textures for each instance ?

agargaro · April 18, 2025, 4:36pm

It is not a good idea to use texureLoader.load() in the onAddInstance callback.

In order to use a different texture per instance, you should pass as uniform a DataArrayTexture that contains the various textures and set a textureIndex as uniform per instance. After that you should overwrite the fragment shader of your material.

An user on the discord channel has already solved this problem, I will post a small demo in the next few days

Topic		Replies	Views
InstancedMesh2 - Easy handling and frustum culling Discussion	42	3200	October 25, 2024
InstancedMesh LOD - 1 million instances Showcase culling , bvh , lod , instanced-mesh	4	364	September 16, 2024
InstancedMesh add/remove Questions instanced-mesh	4	2222	February 8, 2021
Question about InstancedMesh Questions instanced-mesh	1	906	January 3, 2020
BatchedMesh for InstancedBufferGeometry Questions batchedmesh	4	88	October 30, 2024