@jaimebboyjt/three-scatter v0.0.6

Three scatter

Is my attempt to replicate a GScatter (plugin for blender) in Three.js

Installation

pnpm i @jaimebboyjt/three-scatter

Why to use it

Three.js already comes with MeshSurfaceSampler you can think in three-scatter as an "extension" of it. I said it in quotes because is not quite true, three-scatter the approach is different and it comes with method to help scatter your Meshes.

Use three-scatter if you:

• Would like to scatter complex models (3D models with animations, rigging, etc)
• Want to align your model to the surface base, easily
• Would like to tweak in real-time (or with panels) seeds, or any property of your 3D model to scatter
• Want to remove collisions, easily.

NOTE: if performance is your must, MeshSurfaceSampler is your go to, I provided a debug option to help you, but MeshSurfaceSampler is much more performance since you can (and probably should) use InstancedMesh

Demos

• Multi-models: https://stackblitz.com/edit/vitejs-vite-kebufehm?file=package.json
• Animated models: https://stackblitz.com/edit/vitejs-vite-7fz6pccr?file=src%2Fmain.js
• TresJs: https://stackblitz.com/edit/vitejs-vite-qpspyyen?file=src%2Fcomponents%2FTheExperience.vue

How to use it

Basic (constructor)

import { ThreeScatter } from 'three-scatter'

// Surface: Geometry from which to sample
// Model: 3D model or models to scatter
// Count: Number of samples

const scatter = new ThreeScatter(surface, model, count);
scene.add(scatter);

You can also scatter more than one model:

const scatter = new ThreeScatter(surface, [model1, model2], count);

Modifying all the 3D objects

three-scatter comes with lots of handy method for you, one of the most common ones is setAll that allow you affect all the scattered models.

const scatter = new ThreeScatter(surface, [model1, model2, model3], count);

scatter.setAll((model, index) => {
  model.scale.set(0.1, 0.1, 0.1);
});

Methods

setSeeds(seed: number)

scatter.setSeeds(5); // tweak it and find the right value for you

Align models Y+up

// This method will align Y+up with the normals of the surface
scatter.alignToSurfaceNormal();

Remove collisions

// This method will remove the model that has collisions with other scattered model 
scatter.removeCollisions();

Clear group

// Dispose all the geometries and material and remove all the meshes
scatter.cleanGroup();

Get faces

// return all the faces of the surface sample, using a Triangle: https://threejs.org/docs/?q=triangle#api/en/math/Triangle
scatter.getFaces();

Get positions

// return all the positions, useful if you want to display specifics positions in your scene
scatter.getPositions();

Options

ThreeScatter allows you more control using optional parameters.

const scatter = new ThreeScatter(surface, model, count, {
  seeds<number>: 1, // seed to begin with
  useSkeletonUtils<boolean>: true // Necessary when you are scattering 3D models with rigging/animations
  randomFn<() => number>: Math.random() // if you want to have control over the random function, has to return a value from 0 to 1
});

Debug mode

ThreeScatter comes with a debug mode that will replace all your models with a low poly mesh, and find the right position, easily.

const scatter = new ThreeScatter(surface, model, count, {
  debug<boolean>: true,
  debugGeometry<Geometry>: new THREE.SphereGeometry(0.5, 3, 2) ,
  debugMaterial<Material>: new THREE.MeshBasicMaterial({ color: 0x800080 }),
});

You can also use the setDebug and removeDebug methods to control it after ThreeScatter is instantiated

scatter.setDebug(); // or
scatter.removeDebug();

TODO

• [] Distribution (when more than one model to scatter) should be base on %
• [] Distribution by axis (base on the normals)
• [] Avoid corners
• [] Density
• [] Merge geometries?

Contributing

We are open to contributions, please read the contributing guide to get started.

License

MIT

Sponsors

Be the first to support this project here ☺️.