npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@three.ez/instanced-mesh

v0.3.0-alpha.2

Published

Enhanced InstancedMesh with frustum culling, fast raycasting (using BVH), sorting, visibility management and more.

Downloads

1,077

Readme

Discord npm Stars BundlePhobia Quality Gate Status DeepScan grade

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

const myInstancedMesh = new InstancedMesh2(geometry, material);

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

🧑‍💻 Live Examples

Stackblitz (Vite + Typescript)

Glitch (Javascript)

Frameworks

📚 Documentation

The tutorial is available here. The API 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>

❔ Questions?

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! ❤️

🚀 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.instancesCount = 10; // change instances count

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, { createInstances: 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(({ 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);

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