Babylon.js comes with an integrated support for level of detail.

This feature allows you to specify different meshes based on distance to viewer (by default), or screen coverage.
For instance, here is how to define 4 levels of details for a given mesh, with distance comparison :

```javascript
const knot00 = BABYLON.Mesh.CreateTorusKnot("knot0", 0.5, 0.2, 128, 64, 2, 3, scene);
const knot01 = BABYLON.Mesh.CreateTorusKnot("knot1", 0.5, 0.2, 32, 16, 2, 3, scene);
const knot02 = BABYLON.Mesh.CreateTorusKnot("knot2", 0.5, 0.2, 24, 12, 2, 3, scene);
const knot03 = BABYLON.Mesh.CreateTorusKnot("knot3", 0.5, 0.2, 16, 8, 2, 3, scene);

knot00.addLODLevel(15, knot01);
knot00.addLODLevel(30, knot02);
knot00.addLODLevel(45, knot03);
knot00.addLODLevel(55, null);
```

The first parameter used with `addLODLevel` defines the distance to the camera. Beyond this distance, the specified level is used.

Each level is independent and can have its own material.
By defining a level of detail to null, you disable rendering of the current mesh, when it is viewed beyond the indicated distance to camera.

When a mesh is used as a level of detail for another mesh, it is linked to it and cannot be rendered directly.

You can remove a LOD level by using `removeLODLevel`:

```javascript
knot00.removeLODLevel(knot02);
knot00.removeLODLevel(null);
```

You can alternatively add LOD levels by specifying screen coverage cutoff limits. Screen coverage is computed as a ratio between 0 and 1 of the mesh's rendered screen surface area, over the total screen surface area. This method has the notable advantage over distance comparison to be scale-independant, as a big object rendered from a long distance, can still be big on the screen.

To specify that your LOD levels use screen coverage instead of distance, use :

```javascript
knot00.useLODScreenCoverage = true;
```

Now, all LOD levels cutoff values will be interpreted as screen coverages.

Be careful of 2 things though :

First, values must be between 0 and 1 :

```javascript
knot00.addLODLevel(0.1, knot01);
```

Second, a bigger value means a bigger size on the screen, and thus a more detailed LOD. This is the opposite order than with distance, where a big distance meant a smaller size, and therefore a less detailed LOD :

```javascript
knot00.addLODLevel(0.7, knot01);
knot00.addLODLevel(0.1, knot02);
knot00.addLODLevel(0.01, knot03);
```

Try: <Playground id="#QE7KM" title="LOD Demo" description="Simple example of using the LOD system."/>

## Using LOD and instances

By default, instances will use LOD defined on root mesh. You do not have to specify anything on instances:

```javascript
const count = 3;
const scale = 4;

const knot00 = BABYLON.Mesh.CreateTorusKnot("knot0", 0.5, 0.2, 128, 64, 2, 3, scene);
const knot01 = BABYLON.Mesh.CreateTorusKnot("knot1", 0.5, 0.2, 32, 16, 2, 3, scene);
const knot02 = BABYLON.Mesh.CreateTorusKnot("knot2", 0.5, 0.2, 24, 12, 2, 3, scene);
const knot03 = BABYLON.Mesh.CreateTorusKnot("knot3", 0.5, 0.2, 16, 8, 2, 3, scene);

knot00.setEnabled(false);

knot00.addLODLevel(15, knot01);
knot00.addLODLevel(30, knot02);
knot00.addLODLevel(45, knot03);
knot00.addLODLevel(55, null);

for (let x = -count; x <= count; x++) {
    for (let y = -count; y <= count; y++) {
        for (let z = 5; z < 10; z++) {
            const knot = knot00.createInstance("knotI"),
            knot.position = new BABYLON.Vector3(x * scale, y * scale, z * scale);
        }
    }
}
```

Try: <Playground id="#14ESWC" title="LOD and Instances Demo" description="Simple example of using the LOD system with instances."/>

# Billboard Mode

Billboard is a special mode for meshes, ensuring that the mesh is always facing towards the camera. This is commonly used to display information to the user, sprites or particles for instance.

Example :
```javascript
box.billboardMode = 7;
```

Billboard Mode Values:

value|Type
-----|-------------
0 | BILLBOARDMODE_NONE
1 | BILLBOARDMODE_X
2 | BILLBOARDMODE_Y
4 | BILLBOARDMODE_Z
7 | BILLBOARDMODE_ALL

<Playground id="#ANE052#1" title="Simple Example of Mesh Billboard Mode" description="Simple example of setting a mesh to use Billboard Mode."/>


## Copies, Clones and Instances

Often you want to save memory or draw calls when rendering a scene. There are several methods to do this using clones, instances, thin instances and the solid particle system. Each of which provides advantages and disadvantages.

## The Creation of Different Types of Mesh

There is a large variety of meshes that you can create. The range falls into four broad categories, the first three of which requiring a single Babylon.js method to build.

1. Set Shapes - which usually have names in everyday use and their forms are well known and recognized. Examples include the box, sphere, cone and plane. These shapes are created with a method having the form _Create&lt;MeshType&gt_

2. Parametric Shapes - these have no everyday names and are formed through data sets and tend to have irregular shapes. Examples include ribbons, extrusions, and irregular convex or concave polygons. They are created mainly with _Create&lt;MeshType&gt_ and also with _Extrude&lt;MeshType&gt_

3. Polyhedra - three dimensional regular solids including octahedron, dodecahedron, icosahedron and icosphere. The method of creating these is _createPolyhedron_ along with a number for the basic shapes and an array of vertices for a wider range of shapes or _createIcoSphere_.

4. Custom - those you design yourself and build from your own set of vertices connected into triangular facets as you choose.

The current way to create a mesh is using _MeshBuilder_

```javascript
const mesh = BABYLON.MeshBuilder.Create < MeshType > (name, options, scene);
```

The _options_ object will have different properties according to the type of mesh and can be empty {}. The scene parameter is optional and defaults to the current scene.

There is an older deprecated method, retained for backwards compatibility, which uses _Mesh_ and a string of parameters

```javascript
const mesh = BABYLON.Mesh.Create<MeshType>(name, required_param1, required_param2, ..., scene, optional_parameter1, ........);
```

The scene parameter is compulsory when used with optional parameters. You will still find this method in playgrounds.

## What are Decals for

These are usually used to add details on meshes (bullets hole, local details, etc...).
A decal is either a mesh produced from a subset of a previous one with a small offset in order to appear on top of it, or an additional texture applied to a mesh (a "decal map").

### Mesh Decals

Creation Example :

```javascript
const decal = BABYLON.MeshBuilder.CreateDecal("decal", mesh, { position: myPos }, scene);
```

Don't forget the _mesh_ parameter; this is the mesh to which the decal is applied.

Properties, all optional :

| property | value | default value |
| -------- | -------------------------------------------------------------------------------------- | ------------- |
| position | _(Vector3)_ position of the decal (World coordinates) | (0, 0, 0) |
| normal | _(Vector3)_ the normal of the mesh where the decal is applied onto (World coordinates) | Vector3.Up |
| size | _(Vector3)_ the x, y, z sizes of the decal | (1, 1, 1) |
| angle | _(number)_ the angle to rotate the decal | 0 |

<Playground id="#1BAPRM#73" title="Simple Example of Decals" description="Simple example of pasting decals in a Babylon.js scene."/> click on the cat.

Starting with v5.28.0, decals can be created for rigged meshes and two new options are available:

| property | value | default value |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| localMode | defines that the computations should be done with the local mesh coordinates instead of the world space coordinates. Use this mode if you want the decal to be parented to the source mesh and move/rotate with it. | false |
| cullBackFaces | defines if the back faces should be removed from the decal mesh | false |

 
Note that `localMode=true` is automatically enforced for rigged meshes (when `sourceMesh.skeleton !== null`) otherwise it would not work. Also, you should probably always set `localMode` to `true` even for non rigged meshes as it will allow your decal to follow the source mesh even if this mesh moves/rotates.

The `cullBackFaces` option set to `true` will make sure the faces that are back facing the direction of projection (the inverse direction of the `normal` option) won't be created. It can help you avoid leaking a texture in the back of an object if your decal size is too big in the z dimension (`size.z`).

For eg:

![Projection box](/img/features/decals/decal_projbox.jpg)

In this picture, the red box materializes the projection box and has the `size` dimensions passed in `options`.

As the projection box extends farther from the back, with `cullBackFaces=false` the projected texture will be visible on the back:

| front | back |
| -------------------------------------------------- | ---------------------------------------------------- |
| ![Front](/img/features/decals/decal_front.jpg!350) | ![Back](/img/features/decals/decal_back_nok.jpg!350) |

 
With `cullBackFaces=true` however, the projected texture will not be visible on the back:

| front | back |
| -------------------------------------------------- | --------------------------------------------------- |
| ![Front](/img/features/decals/decal_front.jpg!350) | ![Back](/img/features/decals/decal_back_ok.jpg!300) |

 
Of course, you can try to lower the dimensions of the projection box:

![Projection box](/img/features/decals/decal_projbox_small.jpg)

It will work even with `cullBackFaces=false` as the box does not extends past the back. But even this reduced box is too big if we want to create a decal on the arm, for example. For the arm, you would need a very tiny box, but then this tiny box may be too tiny if we project on another part of the body... So, you would need to adjust the size depending on where you create the decal, which can be tedious and difficult to achieve in practice. Using `cullBackFaces=true` with a relatively big box will work in all cases without worrying about where the decal is created.

You can use this PG to experiment with decals: <Playground id="#EEUVTY#199" title="Decals with rigged and moving meshes" description="Example of pasting decals for rigged meshes."/>

You can move over the dude / cube / mesh and left click to create a permanent decal. The "Cull back faces of decal" checkbox lets you experiment with the `cullBackFaces` option.

Note that the decal is created with `localMode=true`, that's why it works as expected for the sphere and the box (the decal will follow the rotation/movement of the mesh).

### Texture Decals (or Decal Maps)

Decal Maps are new in Babylon.js since 5.49.0. They are a way to add decal to a mesh without having to create a new mesh. It is a texture that is applied to a mesh in such a way that it appears to be a decal on the mesh.

The advantage of Decal Maps over Mesh Decals is that they are much faster to create and render. Also, they can be applied to meshes with morph targets or any other custom vertex deformation, which is not the case with Mesh Decals. The main drawback is that you need an additional texture for each mesh you want to apply a decal map to. Other problems are:
* If your mesh has large extensions, you may need to use large decal textures to get enough detail for the decals.
* You cannot selectively remove some decals and not others in a decal texture: you can either remove them all (by deleting the decal texture or turning off the effect in the mesh), or none.
* The texture coordinates of the mesh must be unique, which means that each triangle in the mesh must correspond to a different texture area.
* Mipmaps are generally necessary to limit aliasing problems. If you often update a large number of decal textures, this can have a substantial impact on performance.

Decal Maps have two aspects: creating the texture/adding decals, and applying the texture to a mesh.

**Note**: Decal Maps are only supported for standard and PBR materials!

#### Creating the Decal Map

There is a new class called `MeshUVSpaceRenderer` which can be used to create and update a decal map. The main method is `renderTexture`, which allows you to add a decal to the texture:

```javascript	
const decalMap = new BABYLON.MeshUVSpaceRenderer(mesh, scene);
const texture = new BABYLON.Texture("bullet.png", scene);
const decalSize = new BABYLON.Vector3(1, 1, 1);
// find the position and the normal of the mesh where you want to add the decal
...
decalMap.renderTexture(texture, position, normal, decalSize) ;
```
Whenever you need to add a new decal to the map, just call `renderTexture`. This is much faster than creating a new mesh decal and you can do it several times per frame without any problem (think "machine gun burst").

#### Rendering a mesh with a decal map

Once you have created the decal map, you can apply it to a mesh using the `decalMap` property of the mesh and enable support for the decal map in the material:
```javascript
mesh.decalMap = decalMap;
mesh.material.decalMap.isEnabled = true;
```

Note that you must enable support for decal maps (`material.decalMap.isEnabled = true`) before rendering with the material! This is because a material plugin must be added to a material before the first rendering, and decal map is implemented by the material plugin mechanism.
However, you can disable/enable the decal map rendering at any time by updating `decalMap.isEnabled`. You can even start in a disabled state and enable it later, but the important thing is to set a value to `material.decalMap.isEnabled` (or even just access `material.decalMap`) before the first rendering. If you don't do this, `material.decalMap` will always return `null`.

Here are sample playgrounds that show how to use decal maps. Click on the meshes to add decals: 
- <Playground id="#9BVW2S#60" title="Decal maps" description="Example of using decal maps." image="/img/playgroundsAndNMEs/pg-9BVW2S-49.png"/>
- <Playground id="#N10DXG#17" title="Decal Graffiti" description="Add graffiti with decal maps." image="/img/playgroundsAndNMEs/textureDecals_graffiti.jpg" />

#### Using Decal Maps with ES6 and Tree Shaking

Decal maps are an optional feature that is not supported by default by the standard and PBR materials, to avoid an increase in code size if you do not use it.
To enable support when using ES6 and Tree Shaking, see [Babylon.js ES6 support with Tree Shaking](/setup/frameworkPackages/es6Support#tree-shaking).

In ES6 with Tree Shaking, another way to enable decal map support without having to update each material individually is to globally enable decal map plugin injection in all materials:
```javascript
BABYLON.RegisterMaterialPlugin("DecalMap", (material) => {
 material.decalMap = new BABYLON.DecalMapConfiguration(material);
 material.decalMap.isEnabled = true;
 return material.decalMap;
}) ;
```

If you do this, you should import the file `Meshes/abstractMesh.decalMap` and not `Materials/material.decalMap`!

# How to Draw Bounding Boxes

It's pretty easy to draw bounding boxes around a mesh in Babylon. You can think of a bounding box as visual box that your object(s) fit inside of perfectly. It encompasses the outer "bounds" of your object.

# Drawing a bounding box around a single object

Let's start by drawing a bounding box around a single object. You can follow along with the default [playground](https://playground.babylonjs.com/).

Let's say that you have a sphere in your scene that you've affecionately named "sphere".

To draw the bounding box around your sphere, all you need to do is set the showBoundingBox property to true.

Like this :
```javascript
sphere.showBoundingBox = true;
```
Pretty simple right? 

Here is a playground where you can see it working. <Playground id="#4F33I3" title="Drawing A Box Around A Single Object" description="Simple example of drawing a bounding box around a single object."/>

# Drawing a bounding box around multiple objects

Ok so let's make it a little more complicated. Let's say that your scene also has a ground plane in it that you've lovingly named "ground" and you'd like to draw a bounding box around the area that encomposes both the sphere and ground. 

To do this, we're going to get the minimum and maximum values of the bounding information of both meshes and compare them with special methods that compares two vector 3 values and gives you the minimum and maximum values. Then we'll set the sphere's bounding information to this new min and max. Let's try it out.

Let's start by declaring four new variables that will hold the minimum and maximum bounding information for the sphere and the ground. Like this:

```javascript
let sphereMin = sphere.getBoundingInfo().boundingBox.minimum;
let sphereMax = sphere.getBoundingInfo().boundingBox.maximum;

let groundMin = ground.getBoundingInfo().boundingBox.minimum;
let groundMax = ground.getBoundingInfo().boundingBox.maximum;
```

Ok and now let's declare 2 new variables and use those special methods metioned above to compare the min and max bounding info of both meshes.

```javascript
let newMin = BABYLON.Vector3.Minimize(sphereMin, groundMin);
let newMax = BABYLON.Vector3.Maximize(sphereMax, groundMax);
```

So now newMin and newMax are the minimum and maximum bounds of both objects! So next we will set the sphere's bounding information to a new set of bounding data based on newMin and newMax

```javascript
sphere.setBoundingInfo(new BABYLON.BoundingInfo(newMin, newMax));
```

And finally, just like before, we then display the sphere's bounding box.

```javascript
sphere.showBoundingBox = true;
```

TA DA!!! Here it is working in a playground: <Playground id="#4F33I3#1" title="Drawing A Box Around Multiple Objects" description="Simple example of drawing a bounding box around multiple objects."/>

# A better approach

Ok so there's a problem with the technique we used above. We actually changed the bounding info of the sphere to the new bounding information that encompasses both the sphere and the ground. There's actually a better way to do this, and that's to leave the sphere's bounding information alone and instead, introduce parenting into the equation!!!!

To start, let's create a new generic mesh like this:

```javascript
let parent = new BABYLON.Mesh("parent", scene);
```

And now let's use this generic mesh as the parent of the sphere and the ground;

```javascript
sphere.setParent(parent);
ground.setParent(parent);
```

Lastly, instead of setting the bounding information and displaying the bounding box of the sphere, let's change that to the parent instead.

```javascript
parent.setBoundingInfo(new BABYLON.BoundingInfo(newMin, newMax));
 
parent.showBoundingBox = true;
```

So here's what our playground looks like now. <Playground id="#4F33I3#2" title="A Better Approach For Bounding Boxes" description="Better example of drawing bounding boxes."/>

Notice something wrong? Our bounding box doesn't line up with the bounds of our objects anymore does it? There's a very good reason for that. It's because up until this point we are using LOCAL coordinates instead of world coordinates! So technically the bounding box that we're seeing is the right size, but it's drawn around the parent mesh...which in this case has it's pivot at the origin. You can clearly see the problem when you comment out this line:

```javascript
sphere.position.y = 1;
```

See that here in this playground: <Playground id="#4F33I3#3" title="A Fixed Better Approach For Bounding Boxes" description="Better example of drawing bounding boxes fixed."/>

Make a bit more sense? But what about if you wanted to get the world bounds of the positioned objects? It's actually pretty easy to do. We'll make a couple of minor modifications to the sphereMin, sphereMax, groundMin, groundMax values like this:

```javascript
let sphereMin = sphere.getBoundingInfo().boundingBox.minimumWorld;
let sphereMax = sphere.getBoundingInfo().boundingBox.maximumWorld;

let groundMin = ground.getBoundingInfo().boundingBox.minimumWorld;
let groundMax = ground.getBoundingInfo().boundingBox.maximumWorld;
```

Nice! That looks more like what you were probably expecting doesn't it?

Here's the updated playground to check out. <Playground id="#4F33I3#4" title="World Transform Bounding Boxes" description="Simple example of drawing bounding boxes in world space."/>

# One last trick

So what happens if you have a whole bunch of objects and you want to get the bounding box of all of them? You wouldn't want to do that manually for each one right? So we'll introduce a loop into the mix!

Like earlier, we'll make sure that we have a parent mesh, and that each object we want to include in the bounding box will be parented to that parent mesh.

The fun technique here is that we can loop through an array of every "child mesh" of the parent. Let's start by declaring a new variable that will be an array of all of the parent's child meshes.

```javascript
let childMeshes = parent.getChildMeshes();
```

Next, let's declare two new variables that will hold the minimum and maximum bounding values.

```javascript
let min = childMeshes[0].getBoundingInfo().boundingBox.minimumWorld;
let max = childMeshes[0].getBoundingInfo().boundingBox.maximumWorld;
```

We're setting the starting values of these min and max variables to the world min and world max bounding information for the first child mesh.

Now we can loop through all of the child meshes and continually update the min and max values with the new bounding information of each comparative mesh. It looks like this:

```javascript
for(let i=0; i<childMeshes.length; i++){
 let meshMin = childMeshes[i].getBoundingInfo().boundingBox.minimumWorld;
 let meshMax = childMeshes[i].getBoundingInfo().boundingBox.maximumWorld;

 min = BABYLON.Vector3.Minimize(min, meshMin);
 max = BABYLON.Vector3.Maximize(max, meshMax);
 }
```

SWEET! We did it! Nice job! Here's the playground result of those changes. <Playground id="#4F33I3#6" title="Loop Through Meshes to Draw Bounding Box" description="Simple example of looping through meshes to draw an overall bounding box."/>

To dive even further into bounding boxes, make sure to check out the API as well

# API

- [boundingBox](/typedoc/classes/babylon.boundingbox)

## How To Draw Curves

If you want to draw a circular path then it is easy enough to generate the points, in the XY plane, for this using

```javascript
const path = [];
for(let theta = 0; theta < 2 * Math.PI; theta +=deltaTheta ) {
 path.push(new BABYLON.Vector3(radius * Math.cos(theta), radius * Math.sin(theta), 0));
```

When you are of a mind to do it you can work out some quite complex paths by hand.

What follows is how to draw some mathematical curves by using the Babylon.js _Curve3_ object, from which you can extract the array of points you need to draw lines, ribbons, tubes and extruded shapes.

The general form is

```javascript
const curve = BABYLON.Curve3.Create.CURVETYPE(parameters);
```

## Arc Through Three Points

Available from version 5.0.0.
Given three points in space, not in a straight line, it is always possible to draw join the points up using a circular arc or to draw a circle through the three points.

```javascript
const arc = BABYLON.Curve3.ArcThru3Points(first, second, third, steps, closed, fullCircle);
```

- **first** _Vector3_ the first point the arc must pass through.
- **second** _Vector3_ the second point the arc must pass through.
- **third** _Vector3_ the third point the arc must pass through.
- **steps** _number_ the larger the number of steps the more detailed the arc.
- **closed** _boolean_ optional with default false, when true forms the chord from the first and third point
- **fullCircle** _boolean_ optional with default false, when true forms the complete circle through the three points

This static method returns an instance of _Curve3_. 
Just use the Curve3 _getPoints()_ method to fill your array : _getPoints()_ returns an array of successive _Vector3_. 
The _length()_ method returns the curve length.

```javascript
const path = arc.getPoints();
const l = arc.length();
```

<Playground id="#KENEJP#3" title="Arc" description="Open arc."/>

<Playground id="#KENEJP#4" title="Segment" description="Segment."/>

<Playground id="#KENEJP#5" title="Full Circle" description="Full Circle."/>

## Quadratic Bezier Curve

http://en.wikipedia.org/wiki/B%C3%A9zier_curve#Quadratic_curves

![Wikipedia Quadratic Bezier Curve](https://upload.wikimedia.org/wikipedia/commons/3/3d/B%C3%A9zier_2_big.gif)

```javascript
const bezier2 = BABYLON.Curve3.CreateQuadraticBezier(origin, control, destination, nb_of_points);
```

- **origin** : _Vector3_ the origin point,
- **control** : _Vector3_ the control point,
- **destination** : _Vector3_ the destination point,
- **nb_of_points** : _number_ number of points wanted in the path array.

This static method returns an instance of _Curve3_. 
Just use the Curve3 _getPoints()_ method to fill your array : _getPoints()_ returns an array of successive _Vector3_. 
The _length()_ method returns the curve length.

```javascript
const path = bezier2.getPoints();
const l = bezier2.length();
```

<Playground id="#W0XSPA" title="Drawing A Bezier Quadratic Curve" description="Simple example of drawing a bezier quadratic curve."/>

## Cubic Bezier curve

http://en.wikipedia.org/wiki/B%C3%A9zier_curve# Higher-order_curves

![Wikipedia Cubic Bezier Curve](https://upload.wikimedia.org/wikipedia/commons/d/db/B%C3%A9zier_3_big.gif)

```javascript
const bezier3 = BABYLON.Curve3.CreateCubicBezier(origin, control1, control2, destination, nb_of_points);
```

- **origin** : _Vector3_ the origin point,
- **control1** : _Vector3_ the first control point,
- **control2** : _Vector3_ the second control point,
- **destination** : _Vector3_ the destination point,
- **nb_of_points** : _number_ the wanted final curve number of points in the array.

This static method returns an instance of _Curve3_. 
Just use the Curve3 _getPoints()_ method to fill your array : _getPoints()_ returns an array of successive _Vector3_. 
The _length()_ method returns the curve length.

```javascript
const path = bezier3.getPoints();
const l = bezier3.length();
```

<Playground id="#EY3EW4" title="Drawing A Bezier Cubic Curve" description="Simple example of drawing a bezier cubic curve."/>

## Hermite Spline

http://en.wikipedia.org/wiki/Cubic_Hermite_spline

![Hermite Spline](/img/how_to/Mesh/hermite.jpg)

```javascript
const hermite = BABYLON.Curve3.CreateHermiteSpline(p1, t1, p2, t2, nbPoints);
```

- **p1** : _Vector3_ the origin point,
- **t1** : _Vector3_ the origin tangent vector,
- **p2** : _Vector3_ the destination point,
- **t2** : _Vector3_ the destination tangent vector,
- **nbPoints** : _number_ the wanted final curve number of points in the array.

This static method returns an instance of _Curve3_. 
Just use the Curve3 _getPoints()_ method to fill your array : _getPoints()_ returns an array of successive _Vector3_. 
The _length()_ method returns the curve length.

```javascript
const path = hermite.getPoints();
const l = hermite.length();
```

<Playground id="#P94GHL" title="Drawing A Hermite Spline" description="Simple example of drawing a Hermite Spline curve."/>

## Catmull-Rom Spline

https://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull.E2.80.93Rom_spline

![Wikibooks Cubic Hermite spline](https://upload.wikimedia.org/wikipedia/commons/1/1c/Finite_difference_spline_example.png)

```javascript
const nbPoints = 20; // the number of points between each Vector3 control points
const points = [vec1, vec2, ..., vecN]; // an array of Vector3 the curve must pass through : the control points
const closed = true; // closes the curve when true
const catmullRom = BABYLON.Curve3.CreateCatmullRomSpline(points, nbPoints, closed);
```

- **points** : _Vector3_ an array of Vector3 (the control points) the curve will pass through,
- **nbPoints** : _number_ the wanted curve number of points between each control point,
- **closed** : _boolean_ optional with default _false_; available from BJS V3.3; when true forms a closed curve.

This static method returns an instance of _Curve3_. 
Just use the Curve3 _getPoints()_ method to fill your array : _getPoints()_ returns an array of successive _Vector3_. 
The _length()_ method returns the curve length.

```javascript
const path = catmullRom.getPoints();
const l = catmullRom.length();
```

<Playground id="#1AU0M4" title="Drawing A Catmull-Rom Spline Open Curve" description="Simple example of drawing a Catmull-Rom Spline Open Curve."/>
<Playground id="#1AU0M4#18" title="Drawing A Catmull-Rom Spline Closed Curve" description="Simple example of drawing a Catmull-Rom Spline Closed Curve."/>

## Hermite Quaternion Spline

```javascript
BABYLON.Quaternion.Hermite(point0, tangent0, point1, tangent1, amount);
```

allows the interpolation of quaternions for use in animation. As a quaternion is a 4D object how can you visualize the Hermite quaternion spline that the interpolation uses? By representing the hyperspline in 3D space.

This is achieved by mapping a rotation quaternion onto a 3D vector.

### The Math

What is needed if a function $f$ from rotation quaternions to 3D vectors of the form

$f(x, y, z, w) = (x_{v}, y_{v}, z_{v})$

For a rotation quaternion there are two things to note:

1. &nbsp; $x^2 + y^2 + z^2 + w^2 = 1$
2. &nbsp; $(x, y, z, w)$ and $(-x, -y, -z, -w)$ are equivalent.

The equivalence of $(x, y, z, w)$ and $(-x, -y, -z, -w)$ can be seen in the following

<Playground id="#9S6YUQ" title="Equivalent Rotation Quaternions" description="Scale by -1 produces equivalent rotation quaternions."/>

It follows that set of rotation quaternions $(x, y, z, w)$ where $x^2 + y^2 + z^2 + w^2 = 1$ and $-1 \leq x, y, z, \leq 1$ and $0 \leq w \leq 1$ covers all possible rotations.

$x^2 + y^2 + z^2 + w^2 = 1$ and so 
$x^2 + y^2 + z^2 = 1 - w^2$ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- Eq 1

Since $0 \leq w \leq 1$ then $0 < 1 \leq (1 + w) \leq 2$

Dividing Eq 1 by $(1 + w)^2$, which can never be $0$

$x^2 + y^2 + z^2 \over (1 + w)^2$ = $(1 - w^2) \over (1 + w)^2$ = $(1 - w) \over (1 + w)$

This gives the mapping

$f(x, y, z, w)$ = ($x \over (1 + w)$, $y\over (1 + w)$, $z\over (1 + w)$ )

Each rotation quaternion where $0 \leq w \leq 1$ is mapped onto one of a series of concentric spherical shells of radius, $r$,

$0 \leq r^2$ = $(1 - w) \over (1 + w)$ $\leq 1$.

![Hermite Quaternion Spline](/img/how_to/Mesh/quatshells.png)

The center of the shells represents the rotation quaternion $(0, 0, 0, 1)$, the outer, white ,, is a unit sphere where $w = 0$.

The process can be reversed, the inverse function $f^{-1}$ returns the rotation quaternion from a point $(x, y, z)$ from the shells.

Since the radius, r, of the sphere at $(x, y, z)$ is such that $r^2 = x^2 + y^2 + z^2$ and

$r^2$ = $(1 - w) \over (1 + w)$ then

$w$ = $(1 - r^2) \over (1 + r^2)$ and

$1 + w$ = $2 \over (1 + r^2)$ and

$f^{-1}(x, y, z)$ = ($2x \over (1 + r^2)$, $2y \over (1 + r^2)$, $2z \over (1 + r^2)$, $(1 - r^2) \over (1 + r^2)$)

### Drawing

The following function will return a Curve3 within a unit sphere representing a Hermite quaternion spline in 3D space using the math above.

```javascript
const hermiteQuarternionSpline = (p1, t1, p2, t2, nbPoints) => {
 const hermite = new Array();
 const step = 1.0 / nbPoints;
 for (let i = 0; i <= nbPoints; i++) {
 const q = BABYLON.Quaternion.Hermite(p1, t1, p2, t2, i * step);
 q.normalize();
 if (q.w < 0) {
 q.scaleInPlace(-1);
 }
 const v = new BABYLON.Vector3(q.x / (1 + q.w), q.y / (1 + q.w), q.z / (1 + q.w));
 hermite.push(v);
 }
 return new BABYLON.Curve3(hermite);
};
```

- **p1** : _Quaternion_ the origin point,
- **t1** : _Quaternion_ the origin tangent vector,
- **p2** : _Quaternion_ the destination point,
- **t2** : _Quaternion_ the destination tangent vector,
- **nbPoints** : _number_ the wanted final curve number of points in the array.

**Warning** 
Using BABYON.Quaternion.RotationAxis(axis, angle) to create any of p1, t1, p2, t2 does not produce the expected results. Other means of producing rotation quaternions other than a direct creation should also be checked to ensure the one produced is of the range required for the mapping to work.

To produce a vector on the outer , requires a rotation quaternion with $w = 0$

Take the rotation quaternion from

```javascript
new BABYLON.Quaternion(1, 1, 1, 0).normalize(); //giving (0.5774, 0.5774, 0.5774, 0) to 4 dp
```

However using

```javascript
BABYON.Quaternion.RotationAxis(new BABYLON.Vector3(1, 1, 1), 0); // gives (0, 0, 0, 1)
```

and whilst this may be an equivalent quaternion it places the vector at the center of the shells not on the outer ,. 
**End Warning**

<Playground id="#4B0VBG" title="Hermite Quaternion Spline" description="Hermite quaternion spline represented in 3D space."/>

As it is difficult to visualize the spline from pure quaternions it would be useful if there was an editor to draw the representation of the spline in 3D space.

### A (Very) Basic Editor

<Playground id="#4B0VBG#1" title="Hermite Quaternion Editor" description="Hermite quaternion spline Editor 3D space."/>

This playgound allows you to drag representatives of the start (green) and end (red) quaternions within the unit sphere in 3D space. The representation of the start and end quaternion tangents (purple) are attached to the respective start and end controls. The tangents may also be dragged around (invisible) sphere shells centered on the start and end controls. The shells, and hence radius, may be adjusted using the up and down arrow keys (or w and x) for the selected control. Whilst dragging or adjusting the radius the camera is detached. The camera will be attached whenever any dragging is ended or when using keys you can attach it by pressing the spacebar.

The representation of the spline in 3D space is drawn as you adjust the controls. To apply the Hermite quaternion spline created to the box click on the animate button.

## Custom Curve3 Object

You can also make your own Curve3 object from a simple array of successive Vector3. 
Why would you do this and not just use the points to draw a line? 
Because the _Curve3_ object has a useful method, the _continue()_ method, that allows you place the start of one _Curve3_ onto the end of another _Curve3_ without any calculations to match the start and end points of the curves.

### Example 1

Create an array of Vector3 along a simple sinus curve.

```javascript
const mySinus = [];
for (let i = 0; i < 30; i++) {
 mySinus.push(new BABYLON.Vector3(i, Math.sin(i / 10), 0));
}
const mySinusCurve = new BABYLON.Curve3(mySinus);
```

You would like to continue your _mySinus_ curve with a _bezier3_ curve and then join on a _bezier2_.

```javascript
const myFullCurve = mySinusCurve.continue(bezier3).continue(bezier2);
```

The _continue()_ method returns a new _Curve3_ object and leaves _mySinusCurve3_, _bezier3_ and _bezier2_ unchanged.

If you then need to draw the curve or use it for whatever you want you just get the array of points with the _getPoints()_ method. This method simply returns an array of successive _Vector3_.

```javascript
const path = myFullCurve.getPoints();
const extruded = BABYLON.Mesh.ExtrudeShape("extrudedShape", shape, path, 1, 0, scene);
```

If you need then to know the curve length, just use the _**length()**_ method.

```javascript
const l = myFullCurve.length();
```

<Playground id="#00JR7Z" title="Joining Curves" description="Simple example of joining curves."/>

### Example 2

Here is an example where a Hermite Spline is used to close smoothly a concatenation of two Bezier curves. As the spline is closing the curves the first and last points of the open continued curve need to be read from the array.

- The first and last points of the concatenation are used as last and first point of the Hermite spline.
- The first and last segments of the concatenation are used as last and first tangent vectors of the Hermite. Since these segments are quite small, they are scaled according to the concatenation _length_ so the longer the concatenation, the more curved the spline.

```javascript
// two concatened cubic Bezier
const cubicA = BABYLON.Curve3.CreateCubicBezier(vA0, vA1, vA2, vA3, 50);
const cubicB = BABYLON.Curve3.CreateCubicBezier(vB0, vB1, vB2, vB3, 50);
const continued = cubicA.continue(cubicB);

// initial Hermite values from continued first and last segments
const t = continued.length() / 2; // tangent scale factor
const points = continued.getPoints();
const p1 = points[points.length - 1]; // last continued point = first hermite point
const t1 = p1.subtract(points[points.length - 2]).scale(t); // last segment scaled = hermite tangent t1
const p2 = points[0]; // first continued point = last hermite point
const t2 = points[1].subtract(p2).scale(t); // first segment scaled = hermite tangent t2

const hermite = BABYLON.Curve3.CreateHermiteSpline(p1, t1, p2, t2, 50);
continued = continued.continue(hermite);

// finally drawing a smooth closed curve
const closedCurve = BABYLON.MeshBuilder.CreateLines("closed", { points: continued.getPoints() }, scene);
```

<Playground id="#2GCEVH" title="Closed Joined Curves" description="Simple example of closed joined curves."/>

The orange and yellow curves are the original Bezier curves. 
In light blue, these two curves are continued by each other and a hermite curve is also added in continuation to close the path.

## What is morphing ?

This part is about the way to morph some kind of meshes. 
For now, it concerns only ribbons, tubes, extruded shapes and lines.

When talking about morphing, we mean here changing the vertices positions of an existing mesh. Indices remain unchanged. This means the mesh keeps the same number of vertices, the same faces between vertices and it remains the same object in your code.
Only its vertices change their coordinates.

If you handle a box or another fixed basic shape, it's quite easy to access to vertices positions because your mesh has an expected shape. For example, you can guess a box has 4 vertices per face. 
But when handling parametric shapes like ribbons, tubes, etc, it becomes very difficult to guess how and where vertices were positioned by the mesh constructor algorithm. For a tube, for instance, you only know the axis path you gave to build it (and radius, tessellation, of course).

So you will learn here how to update the shape of an existing mesh and how to morph it in the render loop.

## Ribbon

### _ribbon updatable parameter : pathArray_

_(reminder : only points positions can change in the path array, not the number of points. Please see the summary at the bottom of this page for more details)_

Let's create a ribbon. 
As explained in the Ribbon tutorial part, a good way to create a ribbon is to fill many arrays with _Vector3_ with two _for_ loops : one for each path, another one for the array of paths : the _pathArray_.

Here we create a simple plane ribbon in the xOz plane

```javascript
// path function
const pathFunction = function (k) {
 const path = [];
 for (let i = 0; i < 60; i++) {
 const x = i - 30;
 const y = 0;
 const z = k;
 path.push(new BABYLON.Vector3(x, y, z));
 }
 return path;
};
// ribbon creation
const sideO = BABYLON.Mesh.BACKSIDE;
const pathArray = [];
for (let i = -20; i < 20; i++) {
 pathArray.push(pathFunction(i * 2));
}
const mesh = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, false, false, 0, scene, true, sideO);
```

example : <Playground id="#1MSEBT" title="Dynamic Mesh Morph Example 1" description="Simple example of dynamically morphing a mesh."/> _(please rotate the cam to see it)_

The important key to notice is that we set the **_updatable_** parameter to **_true_** in the _CreateRibbon()_ method : the one just between the _scene_ and the _sideO_ parameters.

We can now imagine we want to change this existing ribbon _y_ coordinates according to a sinus function. So for each path in the existing _pathArray_ array we just change _Vector3_ coordinates. 
Note we don't create new paths or a new _pathArray_ array. We just access with indexes to every element and just change values.

```javascript
const updatePath = function (path) {
 for (let i = 0; i < path.length; i++) {
 const x = path[i].x;
 const z = path[i].z;
 const y = 20 * Math.sin(i / 10);
 path[i].x = x;
 path[i].y = y;
 path[i].z = z;
 }
};

// update pathArray
for (let p = 0; p < pathArray.length; p++) {
 updatePath(pathArray[p]);
}
```

The way to update then our existing mesh is quite simple : let's just re-use the _CreateRibbon()_ method and give it this mesh as last parameter with our modified _pathArray_.

```javascript
mesh = BABYLON.Mesh.CreateRibbon(null, pathArray, null, null, null, null, null, null, mesh);
```

The other parameters than _pathArray_ and _mesh_ are just ignored when updating, so they can be set to _null_ for better understanding. 
The _CreateRibbon()_ method thus updates the given ribbon and returns it. 
You can also use the other call signature :

```javascript
mesh = BABYLON.MeshBuilder.CreateRibbon(null, { pathArray: pathArray, instance: mesh });
```

example : <Playground id="#1MSEBT#1" title="Dynamic Mesh Morph Example 2" description="Simple example of dynamically morphing a mesh."/>

Well, we just updated our ribbon's shape once for now.

If we now want its shape to evolve dynamically, we just have to set the _pathArray_ computation (fixed to change with an extra _k_ parameter) and the _CreateRibbon()_ call inside the render loop.

```javascript
const updatePath = function (path, k) {
 for (let i = 0; i < path.length; i++) {
 const x = path[i].x;
 const z = path[i].z;
 const y = 20 * Math.sin(i / 10) * Math.sin(k + z / 40);
 path[i].x = x;
 path[i].y = y;
 path[i].z = z;
 }
};

// path array population ...
const mesh = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, false, false, 0, scene, true);

// morphing
const k = 0;
scene.registerBeforeRender(function () {
 // path array update
 for (let p = 0; p < pathArray.length; p++) {
 updatePath(pathArray[p], k);
 }
 // ribbon update
 mesh = BABYLON.Mesh.CreateRibbon(null, pathArray, null, null, null, null, null, null, mesh);
 // or also :
 // mesh = BABYLON.MeshBuilder.CreateRibbon(null, {pathArray: pathArray, instance: mesh});
 k += 0.05;
});
```

example : <Playground id="#1MSEBT#3" title="Dynamic Mesh Morph Example 3" description="Simple example of dynamically morphing a mesh."/>

## Lines and DashedLines

### _lines and dashed lines updatable parameter : points_

### _lines optional updatable parameter : colors_

_(reminder : only points positions can change, not the number of points. Please see the summary at the bottom of this page for more details)_

Once we got the understanding for ribbons, we can apply it to Lines or DashedLines.
It's even easier as Lines just require a path of points as parameter.

```javascript
const points1 = [v1, v2, ..., vN]; // vector3 array
let lines = BABYLON.MeshBuilder.CreateLines("lines", {points: points1, updatable: true}, scene, true);
let dashedLines = BABYLON.Mesh.CreateDashedLines("lines", points1, dashSize, gapSize, nb, scene, true);

lines = BABYLON.MeshBuilder.CreateLines(null, {points: points2, instance: lines});
dashedLines = BABYLON.MeshBuilder.CreateDashedLines(null, {points: points2, instance: dashedLines});
```

We can, of course, set the update method within the render loop.

example lines: <Playground id="#24PQRQ" title="Lines Example" description="Simple example of dynamically morphing a mesh with lines."/>
dashed lines: <Playground id="#XKYAE#3" title="Dashed Lines Example" description="Simple example of dynamically morphing a mesh with dashed lines."/>

## Tube

### _tube updatable parameters : path, radius, radiusFunction_

_(reminder : only points positions can change in the path, not the number of points. Please see the summary at the bottom of this page for more details)_

Nothing differs for tubes. Let's create a tube and then update it according to new _path_, _radius_ or _radiusFunction_ values :

```javascript
const path1 = [v1, ..., vN]; //vector3 array : tube axis1
const radius1 = 5;
const path2 = [u1, ..., uN]; // another vector3 array : tube axis2
const radius2 = 8;
const tube = BABYLON.Mesh.CreateTube("tube", path1, radius1, 12, null, cap, scene, true);
tube = BABYLON.MeshBuilder.CreateTube(null, {path: path2, radius: radius2, instance: tube});
```

Of course, it also works with the _radiusFunction_ parameter :

```javascript
const radiusFunction1 = function(i, distance) { ... };
const radiusFunction2 = function(i, distance) { ... };
let tube = BABYLON.MeshBuilder.CreateTube("tube", { path: path1, tessellation: 12, radiusFunction: radiusFunction1, cap, updatable: true }, scene);
tube = BABYLON.MeshBuilder.CreateTube(null, {path: path2, radiusFunction: radiusFunction2, instance: tube});
```

Example: <Playground id="#ACKC2#1" title="Tube Example" description="Simple example of dynamically morphing a tube."/>

As you can read at line 53, the _radiusFunction_ is redefined here at each iteration in the _registerBeforeRender_ loop because it uses the value of the incrementing parameter _k_ : the radius changes according to each path point position and according to k varying in the time.

## Extruded shape

### _extrusion updatable parameters for ExtrudeShape(): shape, path, scale, rotation_

### _extrusion updatable parameters for ExtrudeShapeCustom(): shape, path, scaleFunction, rotateFunction_

_(reminder : only points positions can change in the path, not the number of points. Please see the summary at the bottom of this page for more details)_

We can see extrusion as some tube generalization : a tube would be a circle _shape_ extruded along a path. 
So we have here the same update capabilities than for a tube (_path_ or shape _scale_ which would be the equivalent to tube _radius_) and some extra parameters : the _rotation_ step can be updated and the _shape_ itself also ! 
It is mandatory that the new _shape_ array has the same number of Vector3 than the _shape_ used to build the original instance. A good way to assure this is simply to keep the original _shape_ instance and to modify it instead of creating a new one (or to modify a copy of it).

```javascript
const shape1 = [s1, s2, ...sN]; // Vector3 array
const shape2 = [t1, t2, ...tN]; // another Vector3 array
const path1 = [p1, p2, ...pN]; // Vector3 array
const path2 = [q1, q2, ...qN]; // another Vector3 array
const scale1 = 1;
const scale2 = 3;
const rotation1 = 0;
const rotation2 = 0.2;
// extrusion
let extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", { shape: shape1, path: path1, scale: scale1, rotation: rotation1, cap, updatable: true }, scene);
// mesh update
extruded = BABYLON.MeshBuilder.ExtrudeShape(null, { shape: shape2, path: path2, scale: scale2, rotation: rotation2, instance: extruded });
```

Idem for _ExtrudeShapeCustom()_ accepting _scaleFunction_ and _rotationFunction_ parameters :

```javascript
// path and shape const declared before ...
const myScale1 = function(i, distance) { ... };
const myScale2 = function(i, distance) { ... };
const myRotation1 = function(i, distance) { ... };
const myRotation2 = function(i, distance) { ... };
// extrusion
let ext = BABYLON.Mesh.ExtrudeShapeCustom("ext", { shape: shape1, path: path1, scaleFunction: myScale1, rotationFunction: myRotation1, updatable: true, cap }, scene);
// mesh update
ext = BABYLON.MeshBuilder.ExtrudeShapeCustom(null,{shape: shape2, path: path2, scaleFunction: myScale2, rotationFunction: myRotation2, instance: ext});
```

Both new functions can be used in the render loop.

The funny part is, as _ExtrudeShape()_ and _ExtrudedShapeCustom()_ build the same mesh (only parameters change), you can create a simple extruded shape with _ExtrudeShape()_ and then morph it with _ExtrudeShapeCustom()_ if you need more complexity.

```javascript
let ext = BABYLON.Mesh.ExtrudeShape("ext", shape1, path1, scale1, rotation1, cap, scene, true);
// mesh update
ext = BABYLON.Mesh.ExtrudeShapeCustom(null, shape2, path2, myScale2, myRotation2, null, null, null, null, null, null, ext);
```

Example: <Playground id="#20IBWW#14" title="Extruded Shape Example" description="Simple example of dynamically morphing an extruded shape."/>

## Other shapes : updateMeshPositions

For now, we just talked about parametric shapes which can be updated with their own _CreateXXX()_ initial method.
But what about the other mesh types : boxes, spheres, cylinders, etc ?

There is no mean to update them with their initial _CreateXXX()_ because a box remains a box, a sphere remains a sphere whether you change their size, radius, etc.
So usually, the right way to change these basic shapes is to play with their `mesh.scale` property.

Nevertheleless, if you create your basic shape with its _updatable_ parameter set to true, you can access another way to morph/change the shape afterwards : the _updateMeshPositions()_ method.

This method needs two parameters :

- a _positionFunction_ which is js function which will modify the mesh _positions_ array,
- a _computeNormals_ boolean (default = true) to skip/unskip the normals re-computation after the mesh update .

```javascript
const box = BABYLON.MeshBuilder.CreateBox("box", { size: 5.0, updatable: true }, scene);
const positionFunction = function (positions) {
 // modify positions array values here
};
box.updateMeshPositions(positionFunction, true);
```

Example: <Playground id="#1UZIZC#6" title="Custom Shape Example" description="Simple example of dynamically morphing a custom shape."/>

## More speed : freezeNormals

The former _CreateXXX()_ update functions try to be as much optimized as possible to run fast in the render loop. 
However, you may need some more speed for any reason (huge mesh with dozens of thousands of vertices for instance). 
So, if your mesh doesn't need to reflect the light (emissive color only for instance), you can skip the normals re-computation which is a CPU consuming process. 
Use then the _freezeNormals()_ method just after your mesh is created :

```javascript
const tube = BABYLON.Mesh.CreateTube("tube", path, 3, 12, null, BABYLON.Mesh.NO_CAP, scene, true);
tube.freezeNormals();
// path update here ...
tube = BABYLON.Mesh.CreateTube(null, path, 3, null, null, null, null, null, null, tube);
```

If you need to reset the normals computation process on, use then once the _unfreezeNormals()_ method.

```javascript
tube.unfreezeNormals();
```

The normals will then be recomputed and re-applied on the next _CreateXXX()_ update call.

## Summary

- To create an updatable mesh, it is mandatory to set its _updatable_ parameter to _true_ when calling _CreateXXX()_ method.
- To update then an existing parametric shape, we just have to use the same _CreateXXX_ method as we used to construct it.
- Only the existing mesh and the data relative to new positions (path, pathArray, array of points) must be passed to this method, the other parameters are ignored.
- If we want to morph the mesh, we then use the _CreateXXX()_ method within the render loop. 
 In this case, it is important not to allocate new memory each frame : we access our arrays by indexes and just change values instead of creating new arrays, we access existing objects instead of instantiating new ones, etc. We also take care about the weight of each object (number of sides, number of vertices, etc).

example : if we need to update a Lines mesh in the render loop, it is to say to update the _points_ array each frame, it is better to change each array element values (_points[i].x = newXValue; points[i].y = newYValue; points[i].z = newZValue;_) in a _for_ loop instead of instantiating a new _points_ array.

Use case with a _path_ parameter as all parametric shapes have one :

```javascript
const path = [v1, v2, ..., vN]; // your own array, created once
const mesh = CreateXXX("mesh", path, etc, ..., scene, true); // updatable = true : creates your initial mesh
const computeValue = function(val1, val2) { ... }; // your update logic : returns a value in function of val1 and val2
const getParam = function() { ... }; // returns a param value evolving in the render loop
const updatePath = function(path, k) { // updates the existing path array elements
 for (let i = 0; i < path.length; i++) {
 const x = computeValue(path[i].x, k);
 const y = computeValue(path[i].y, k);
 const z = computeValue(path[i].z, k);
 path[i].x = x;
 path[i].y = y;
 path[i].z = z;
 }
};

scene.registerBeforeRender(function() {
 const k = getParam();
 updatePath(path, k);
 mesh = CreateXXX(null, path, null, ..., null, mesh);
});

```

# Edges Renderer

BABYLON.EdgesRenderer is a tool used to render edges on top of a mesh. Edges are rendered between two faces if the dot product of their normals is less than epsilon.

## How to use it

![Edge Renderer](/img/edgesRenderer.jpg)

You can enable edges rendering like this:

```javascript
const box = BABYLON.MeshBuilder.CreateBox("box1", { size: 2 }, scene);
box.enableEdgesRendering();
box.edgesWidth = 4.0;
box.edgesColor = new BABYLON.Color4(0, 0, 1, 1);
```

The `enableEdgesRendering` can be called with a custom epsilon (default value is 0.95).

```javascript
box.enableEdgesRendering(0.9999);
```

Dot product is the cosine of the angle between the vectors, so for default epsilon 0.95 the angle is acos(.95) ~= 18 degrees - so if the angle between two faces is less than that no line gets drawn.

If you need to turn-off edges rendering:

```javascript
box.disableEdgesRendering();
```

You can try edges rendering here: <Playground id="#TYAHX#10" title="Edge Rendering Example 1" description="Simple example of edge rendering."/>

If your mesh has instances, you can either use a renderer for each instance by enabling the edges rendering for each instance as explained above, or by using the source mesh renderer for all instances.

To do this, just set:

```javascript
sourceMesh.edgesShareWithInstances = true;
```

PG: <Playground id="#7BY3TM" title="Edge Rendering Example 2" description="Simple example of edge rendering."/>

## EdgesRenderer and Transparent meshes

The EdgesRenderer is the last component of a [rendering group](/features/featuresDeepDive/materials/advanced/transparent_rendering#rendering-groups) to be rendered, which can effect rendering when there are transparent meshes other than the one using the renderer. See this scene for an example:

![Edges rendering over transparent object](/img/features/edgesRenderer/edgesRenderer1.png)

<Playground id="#TYAHX#282" title="Edge renderer and Transparent Meshes" description="Shows the interaction between an edge renderer in an object and another, transparent, object."/>

You may notice that both the back box and the ground's edges renderers are rendering on top of the front, partially transparent mesh. That happens because the edges rendering happen after all other steps in the scene, even after the transparent (alpha blended) meshes are rendered. For more information on the rendering order of meshes, check the [Transparent Rendering](features/featuresDeepDive/materials/advanced/transparent_rendering#rendering-order) page. There are two possible solutions to this. One is to set the transparent objects' rendering group id to a higher value than the meshes with the edges renderer:

![Solution 1](/img/features/edgesRenderer/edgesRenderer2.png)

And another is to set `forceDepthWrite = true` on the transparent material:

![Solution 2](/img/features/edgesRenderer/edgesRenderer3.png)

Note that in this case, the edges renderer won't show up behind the transparent mesh.

# Facet Data

## What is FacetData ?

FacetData is a feature that can be enabled on a mesh. 
As it requires some extra memory, it's not enabled by default. 
This feature provides some methods and properties to access each facet of a mesh, like the facet positions, normals or the ability to retrieve all of a mesh facets in a given zone of the world space.

## What is a mesh facet ?

We use here the term "facet" in order to be not confused with the term "face". 
A mesh can have some planar faces. For example, a box has 6 sides, so 6 planar squared faces. Each of its faces are drawn at the WebGL level with 2 triangles. 
We call "facets" these elementary triangles.

## How to enable the facet data ?

The feature `facetData` can work for any mesh whatever it is created from BJS provided shapes (box, sphere, cylinder, tube, parametric shapes, etc), cloned ones or instances, merged ones or imported ones from an external source (Blender, etc). 
To enable this feature, just call once `updateFacetData()`. 
If the mesh belongs to some parent-child relationship, the feature is then not enabled for its parents or children.

```javascript
const mesh = BABYLON.MeshBuilder.CreateTorusKnot("t", { radius: 2.0 }, scene);
mesh.updateFacetData();
console.log(mesh.facetNb);
```

As soon as the feature is enabled, you can get the mesh total number of facets with the read-only property `.facetNb`.

The method `updateFacetData()` creates two permanent arrays : the mesh facet positions and facet normals. 
Moreover, it logically divides the mesh according to some partitioning and stores all the facets in this partitioning. 
Unless the mesh is updated or morphed afterwards, you don't need to call this method anymore once it has been done. 
If you don't need this feature any longer, you can disabled it to release the memory with `mesh.disableFacetData()`.

```javascript
mesh.updateFacetData();
console.log(mesh.isFacetDataEnabled); // displays "true"
mesh.disableFacetData();
console.log(mesh.isFacetDataEnabled); // displays "false"
```

The read-only property `.isFacetDataEnabled` returns the current state of the feature. 
Note that disposing the mesh will automatically disable its facet data.

## The facet data tools

### Facet position

The position of a facet is the position of its barycenter. 
You can get the position of the i-th facet of a mesh with `getFacetPosition(i)`. This returns a new `Vector3` that is the world coordinates of the facet center.

```javascript
const pos = mesh.getFacetPosition(50); // returns the world position of the mesh 50th facet
```

If you don't want to allocate a new `Vector3` per call, you can use `getFacetPositionToRef(i, ref)` instead.

```javascript
const pos = BABYLON.Vector3.Zero();
mesh.getFacetPositionToRef(50, pos); // stores the facet world position in the variable "pos"
```

Actually, in the internal array containing the facet positions, all the stored coordinates are computed in the mesh local space. 
If you need to get some facet local position, call `getFacetLocalPositions()` to get the array of the facet positions, then access the i-th element.

```javascript
const localPositions = mesh.getFacetLocalPositions(); // returns the array of facet positions in the local space
const localPos = localPositions[50]; // Vector3 : the 50th facet local position
```

### Facet normal

The normal of a facet is the normalized vector orthogonal to the facet plane. 
You can get the normal of the i-th facet of a mesh with `getFacetNormal(i)`. This returns a new `Vector3` that is the world coordinates of the facet normal.

```javascript
const norm = mesh.getFacetNormal(50); // returns the world normal of the mesh 50th facet
```

If you don't want to allocate a new `Vector3` per call, you can use `getFacetNormalToRef(i, ref)` instead.

```javascript
const norm = BABYLON.Vector3.Zero();
mesh.getFacetNormalToRef(50, norm); // stores the facet world normal in the variable "norm"
```

Like for the positions, in the internal array containing the facet normals, all the stored coordinates are computed in the mesh local space. 
If you need to get some facet local normal, call `getFacetLocalNormals()` to get the array of the facet local normals, then access the i-th element.

```javascript
const localNormals = mesh.getFacetLocalNormals(); // returns the array of facet normals in the local space
const localPos = localNormals[50]; // Vector3 : the 50th facet local position
```

#### Note

All the methods dealing with the world coordinates use the mesh world matrix. As you may know, this matrix is automatically computed on the render call. 
If you've just moved, scaled or rotated your mesh before calling the facetData methods using the world values and you're not sure about this, you can ever force the world matrix computation.

```javascript
mesh.rotate.y += 0.2; // the mesh will be rotated on the next render call, but I need a rotated normal
mesh.computeWorldMatrix(true); // force the world matrix computation
const norm = mesh.getFacetNormal(50); // returns the world normal of the mesh 50th facet
```

#### Examples :

Displaying all the facet normals of an icosphere: <Playground id="#1YTZAC" title="Displaying Facet Data" description="Simple example of displaying all the facet normals of an icosphere."/>
Just change the mesh shape, torus knot : <Playground id="#1YTZAC#1" title="Displaying Facet Data - Torus Knot" description="Simple example of displaying all the facet normals of a torus knot."/>
Smarter : set a box at a distance of 2 from the mesh 10th facet and keep it there, even if the mesh rotates: <Playground id="#1YTZAC#3" title="Displaying Facet Data" description="Simple example of displaying all the facet normals."/>
Of course, you can add some translation to the mesh and even some rotation to the box: <Playground id="#1YTZAC#4" title="Displaying Facet Data" description="Simple example of displaying all the facet normals."/>

Note also that the facet index is the same than the facet id `faceId` used by the pickingInfo object or the `faceId` used by the SPS when pickable.  
Here is an example combining pickingInfo, pickable SPS and facetData facet index: <Playground id="#2FPT1A#119" title="Combining pickingInfo and facetData" description="Simple example combining pickingInfo, pickable SPS and facetData facet index."/>
Just click and the ball is positionned at the clicked facet position, not a the clicked point.

### Mesh partitioning

The feature `facetData` provides also another tool called the mesh partitioning. 
The mesh is logically divided in 3D blocks aligned with the X, Y and Z axis in its local space. 
Here's an illustration about how this logical partitioning looks like (please wait until the skull is downloaded): <Playground id="#UZGNA#5" title="Mesh Partitioning" description="Simple example of mesh partitioning."/>
In order to improve the visibility, the planes along the axis Z weren't displayed. 
As you can see, there are by default 10 subdivisions on each axis. 
When you call `updateFacetData()`, the indexes of the all the facets are sorted in the partioning array according to the facet belonging to each block.

Thus you can get all the facet indexes from some local coordinates _(x, y, z)_ with `getFacetsAtLocalCoordinates(x, y, z)`.

```javascript
const indexes = mesh.getFacetsAtLocalCoordinates(x, y, z); // returns an array containing the facet indexes
if (indexes != null) {
 const worldPos = mesh.getFacetPosition(indexes[0]); // the world position of the first facet in the block
}
```

This method returns an array containing the indexes of the facet belonging to the block containing the point at the coordinates _(x, y, z)_. 
If _(x, y, z)_ aren't in any block or if there's no facet in the block containing _(x, y, z)_, it returns `null`. 
So you can retrieve this way all the facets near some position and do your own treatment. 
This method can be called as many times you need, even in the render loop. It doesn't allocate any object in memory.

Sometimes you don't need all the facets from a given block but only the closest facet to some world, but not local, coordinates. 
You can then use the method `getClosestFacetAtCoordinates(x, y, z)` what returns the index of the closest facet to the World coordinates _(x, y, z)_.

```javascript
const index = mesh.getClosestFacetAtCoordinates(x, y, z); // returns the index of the closest facet to (x, y, z)
if (index != null) {
 const worldPos = mesh.getFacetPosition(index); // the world position of this facet
}
```

The method returns just the index of the closest facet, if any. 
Actually the world coordinates _(x, y, z)_ are internally transformed to local coordinates in the mesh local system. 
If these local coordinates aren't in any block or if there's no facet in this block, it returns `null`. 
This method can be called as many times you need, even in the render loop.

This method can also compute for you the coordinates of the projection of _(x, y, z)_ on the closest facet plane. You can imagine this projection point as the contact point of _(x, y, z)_ on the facet, or the nearest point from _(x, y, z)_ on the facet. 
Just pass it a`Vector3` as a reference :

```javascript
const projected = BABYLON.Vector3.Zero();
const index = mesh.getClosestFacetAtCoordinates(x, y, z, projected); // sets the point "projected" world coordinates
if (index != null) {
 const worldPos = mesh.getFacetPosition(index); // the world position of this facet
 // use the vector3 projected here ...
}
```

You can even filter the returned facet index. 
Imagine that you want only the facet "facing" the coordinates _(x, y, z)_, it is to say the facet of which the dot product normal \* facetPosition*to*(x, y, z) is positive.

So just set the fifth parameter `checkFace` to `true` (default `false`) and the sixth parameter `facing?` to `true` (default `true`).

```javascript
const projected = BABYLON.Vector3.Zero();
const index = mesh.getClosestFacetAtCoordinates(x, y, z, projected, true); // just the "facing" closest facet
if (index != null) {
 const worldPos = mesh.getFacetPosition(index); // the world position of this facet
 // use the vector3 projected here ...
}
```

On the contrary, if you just want the closest facet "turning its back" to _(x, y, z)_, set `checkFace` to `true` and `facing?` to `false`.

```javascript
const projected = BABYLON.Vector3.Zero();
const index = mesh.getClosestFacetAtCoordinates(x, y, z, projected, true, false); // just the "turning back" closest facet
if (index != null) {
 const worldPos = mesh.getFacetPosition(index); // the world position of this facet
 // use the vector3 projected here ...
}
```

If you need it, this method exists also in the mesh local space. Everything is then expressed in the local space : _(x, y, z)_ and the returned coordinates of the projected point. 
Just call `getClosestFacetAtLocalCoordinates(x, y, z, projected, checkFace, facing?)` instead.

```javascript
const localProj = BABYLON.Vector3.Zero();
const index = mesh.getClosestFacetAtLocalCoordinates(x, y, z, localProj); // local projection
if (index != null) {
 const worldPos = mesh.getFacetPosition(index); // the world position of this facet
 // use the vector3 localProj here ...
}
```

#### Note

As said before, the returned facet indexes from all these former methods are the same values than the `PickingInfo` or pickable SPS `faceId` values.
So, you can easily mix all these features together. Ex : to get the facet normal from a picked mesh.

#### Example

A rotating torus knot with facet data enabled and a Solid Particle System (SPS) moving balls with simple custom physics :

- move the ball,
- get the torus closest facet to the particle,
- if any, bounce back the particle.

 <Playground id="#7ATLX" title="Rotating Torus Knot With Facet Data" description="Simple example of rotating torus knot with facet data."/>

### Tweaking the partitioning

By default, the partitioning is set to 10 subdivisions per axis. These subdivisions are applied to the mesh bounding box. 
Actually, it's a bit smarter. It divides the biggest bounding box dimension by 10 and adjust the other ones to their ratio to this biggest. 
Example : if the mesh is sized 200 on X, 100 on Z and 3 on Y, it will subdive X in 10 subdivisions, Z in 5 subdivisions and Y in only 1. 
10 subdivisions is an arbitrary default value. You can change it according to your mesh geometry. 
Just keep in mind these two principles :

- the subdivisions (blocks) must be bigger than the facets to get accurate results,
- the more subdivisions, the fastest the method `getClosestFacetAtCoordinates()`.

So if you deal with a huge mesh with plenty of very small facets like the BJS skull, you can easily set the subdivision number to 50, but if you deal with your own ribbon built with only one hundred big facets, you should probably reduce this number to 4. 
To set the number of subdivisions, just use the property `.partitioningSubdivisions`. It will be taken in account at the next call to `updateFacetData()` and can be changed at will.

```javascript
mesh.partitioningSubdivisions = 50; // set a bigger value than the default one (integer)
mesh.updateFacetData(); // now the internal partitioning has 50 blocks per axis
```

You can also enlarge a bit the space used by the blocks to have a bigger "detection zone" (remember that if _(x, y, z)_ is outside the block zone, the methods return `null`). 
By default, the block area is 1% bigger than the mesh bounding box in order to keep a little space between the peripheric blocks and their contained facets. 
You can set your own value with the property `.partitioningBBoxRatio` (default = 1.01). It will be taken in account at the next call to `updateFacetData()` and can be changed at will.

```javascript
mesh.partitioningBBoxRatio = 1.05; // 5% bigger than the bounding box instead of 1% bigger
mesh.updateFacetData(); // now the internal block area if 5% bigger than the bounding box
```

In order to understand, here are two examples : 
ratio = 1.20 (20% bigger) <Playground id="#UZGNA#6" title="Partitioning With a Larger Ratio" description="Simple example of partitioning with a larger ratio."/> 
ratio = 0.80 (20% smaller) <Playground id="#UZGNA#7" title="Partitioning With a Smaller Ratio" description="Simple example of partitioning with a smaller ratio."/> 
Those examples aren't pertinent, because the values are too big or too small : the block area is too far from the mesh or inside the mesh. 
Right values should keep between 1.0 and 1.10.

### Updating Facet Data

As said in the first part, you need to call once `updateFacetData()` to enable the feature. 
This is enough if the mesh geometry keep unchanged afterwards.

Nonetheless, if you update or morph your mesh afterwards, you need to call `updateFacetData()` again to force the partitioning recomputation.

```javascript
const mesh = myBlenderImportedMesh; // import some mesh from an external source
mesh.updateFacetData(); // enable facetData
// ... process here using the mesh with its current geometry and FacetData
if (condition) {
 customMorphFunction(mesh); // update the mesh geometry
 mesh.updateFacetData(); // update the facet data
}
```

`updateFacetData()` can be called on demand, even in the render loop. However this method as a CPU cost, actually exactly the same than the static method `ComputeNormals()`. 
So if your mesh has a very huge amount of facets like the BJS skul, this can take some times.

Some of the provided BJS mesh types are updatable/morphable by their dedicated methods : the parametric shapes and the SPS.

- the parametric shapes are updatable by calling again the method `CreateXXX()` with the parameter `instance`,
- the SPS is updated each call to `setParticles()`.

For these specific types of updatable meshes, you don't need to call `updateFacetData()` by your own, if the feature is already enabled.
It will be done automatically, generally in an optimized way, inside the process loop of the mesh geometry update.

```javascript
const paths = someArrayOfPaths;
const mesh = BABYLON.MeshBuilder.CreateRibbon("m", {pathArray: paths, updatable: true}, scene); // create an updatable ribbon
mesh.updateFacetData(); // enable the feature once
// morphing function : change the ribbon geometry
const morphRibbon = function(k) {
 for (let p = 0; p < paths.length; p++) {
 const path = paths[p];
 for (let i = 0; i < path.length) {
 path[i].y = Math.sin(k) * Math.cos(i);
 }
 }
}
const k = 0.0;
// render loop
scene.registerBeforeRender(function() {
 morphRibbon(k); // change the geometry
 BABYLON.MeshBuilder.CreateRibbon(null, {pathArray: paths, instance: mesh}); // actually morph the ribbon
 // No need for updateFacetData() here, CreateRibbon() just did it ... faster !
 k += 0.01;
});
```

Example : 
Custom simple physics on a dynamically morphed ribbon: <Playground id="#XVGK0#3" title="Physics On A Morphed Ribbon" description="Simple example of custom simple physics on a dynamically morphed ribbon."/>

### Facet Depth Sort

As you may know, for performance reasons, the facets of a given mesh are always drawn in the same order. This comes to visual issues when the mesh is transparent, concave and is no longer oriented in the right place from the camera :

<Playground id="#FWKUY0" title="Facet Depth Sort 1" description="Simple example of using facet depth sort."/>

This new feature solves the self transparency issue by sorting the mesh facets from some location (the camera position by default) just before drawing them. 
The mesh is **required** to be `updatable`. 
The depth sort is done on each call to `updateFacetData()`. It can be disabled at any time to save CPU cycles if the mesh and the camera don't move any more. 
Usage :

```javascript
// the mesh must be updatable
const mesh = BABYLON.MeshBuilder.CreateTorusKnot("mesh", {updatable: true}, scene);
mesh.material = mat; // transparent material
mesh.mustDepthSortFacets = true; // enable the depth sort, can be disabled at any time

scene.registerBeforeRender(function() {
mesh.updateFacetData(); // sort the facets each frame
```

Exampl: <Playground id="#FWKUY0#1" title="Facet Depth Sort 2" description="Simple example of using facet depth sort."/>

Depth sorted on the left, standard on the right.

If don't need the depth sort once enabled, you can simply stop to call `updateFacetData()`. 
If for some reasons, you still need to call `updateFacetData()` but you don't need the depth sort any longer, just disabled it with `mesh.mustDepthSortFacets = false`. 
In both cases, the facet will keep the last given order.

Note that if your mesh is a SPS (Solid Particle System), it's better to not enable the facet depth sort in the same time than the particle depth sort, simply because the underlying sort is done twice, so more CPU used and no gain. 
In this case, just choose what kind of sorting is better for you : at particle level (faster) or at facet level (more accurate).

As the facet depth sort reorganizes the mesh indices, it **can't work** with the MultiMaterials.

## Introduction

Gizmos are objects that can be attached to a node (mesh, bone, transform) to provide interaction. The GizmoManager and BoundingBox gizmo work with mesh. Whereas Position, scale and rotation gizmos are also usable with TransformNodes and Bones.

![Babylon.js Gizmos](/img/how_to/gui/gizmos.png)

Note: Gizmos will set/modify the [rotationQuaternion](/features/featuresDeepDive/mesh/transforms) of the attached node. After attaching, any rotation of the mesh should be done with the rotationQuaternion property instead of rotation.

## GizmoManager

To get a default gizmo setup, the GizmoManager class can be used.

```javascript
const gizmoManager = new BABYLON.GizmoManager(scene);
```

The gizmo manager will attach the enabled gizmo to whatever object in the scene that is selected by a pointer. To enable a gizmo, any of the following can be used:

```javascript
gizmoManager.positionGizmoEnabled = true;
gizmoManager.rotationGizmoEnabled = true;
gizmoManager.scaleGizmoEnabled = true;
gizmoManager.boundingBoxGizmoEnabled = true;
```

To specify the meshes which can have the gizmo attached, the attachableMeshes field can be set.

```javascript
gizmoManager.attachableMeshes = [mesh1, mesh2, mesh3];
```

To manually change the selected mesh, the gizmo manager's _attachToMesh_ method can be called and the usePointerToAttachGizmos field can be used to disable the manager's default pointer behavior.

```javascript
gizmoManager.usePointerToAttachGizmos = false;
gizmoManager.attachToMesh(mesh);
```

All the internal gizmos are accessible through the manager to support scenarios such as listening to drag events.

```javascript
gizmoManager.gizmos.scaleGizmo;
gizmoManager.gizmos.rotationGizmo;
gizmoManager.gizmos.positionGizmo;

gizmoManager.gizmos.positionGizmo.xGizmo.dragBehavior.onDragStartObservable.add(() => {
 console.log("Position gizmo's x axis started to be dragged");
});
gizmoManager.gizmos.positionGizmo.xGizmo.dragBehavior.onDragEndObservable.add(() => {
 console.log("Position gizmo's x axis drag was ended");
});
```

By default gizmo orientation is in local space so it will be rotated to match the rotation of the object that it is attached to. To change to world orientation, the updateGizmoRotationToMatchAttachedMesh property can be set to false:

```javascript
gizmoManager.gizmos.positionGizmo.updateGizmoRotationToMatchAttachedMesh = false;
```

Note: This is not supported on the scale gizmo

<Playground id="#4TBMBR#33" title="Gizmo Manager Example" description="Simple example of using the gizmo manager."/>

## Setup

Gizmos are displayed by a [UtilityLayerRenderer](/features/featuresDeepDive/mesh/utilityLayerRenderer) to not disrupt the existing scene state. If not specified, the default utility layer will be used.

The utility layers are independent of the scene or engine. After creating a gizmo it is exposed off of gizmo.gizmoLayer. If creating a gizmo without specifying a utility layer it will use the default utility layer’s UtilityLayerRenderer.DefaultUtilityLayer (for overlay gizmos like position/scale) and UtilityLayerRenderer.DefaultKeepDepthUtilityLayer (for occluded gizmos like bounding box) It is recommended to use these layers and reuse layers for most cases as every new utility layer comes with additional overhead.

```javascript
const utilLayer = new BABYLON.UtilityLayerRenderer(scene);
const gizmo = new BABYLON.AxisDragGizmo(new BABYLON.Vector3(1, 0, 0), BABYLON.Color3.FromHexString("#00b894"), utilLayer);
```

When created, the gizmo will not be attached to a node and will not be visible so the gizmo can be attached to a node to become active. Setting this to null will disable/hide the gizmo once again.

```javascript
gizmo.attachedMesh = sphere;
```

By default, the gizmo will be updated to match the attached node's rotation and position but these can be modified with the following

```javascript
// Keep the gizmo fixed to world rotation
gizmo.updateGizmoRotationToMatchAttachedMesh = false;
gizmo.updateGizmoPositionToMatchAttachedMesh = true;
```

<Playground id="#8GY6J8#210" title="Gizmo .glTF Setup Example" description="Simple example of how to set up a gizmo for a .glTF File."/>

## Position, scale and rotation gizmos

Default gizmos for position, rotation and scale on a single axis are supported

- <Playground id="#31M2AP#9" title="AxisDragGizmo Example" description="Simple example of how to use the AxisDragGizmo."/>
- <Playground id="#31M2AP#10" title="AxisScaleGizmo Example" description="Simple example of how to use the AxisScaleGizmo."/>
- <Playground id="#31M2AP#11" title="PlaneRotationGizmo Example" description="Simple example of how to use the PlaneRotationGizmo."/>

Snapping can be enabled on any of the single axis gizmos

```javascript
gizmo.snapDistance = 0.3;
gizmo.onSnapObservable.add((event) => {
 console.log(event);
});
```

A sensitivity factor can be customized for AxisScaleGizmo and ScaleGizmo. Default is 1, a higher value means more stretch for the same drag.

```javascript
gizmoScale.sensitivity = 3;
```

These gizmos internally use a [pointerDragBehavior](/features/featuresDeepDive/behaviors/meshBehaviors), this is exposed and can be used perform tasks before/during/after dragging a gizmo

```javascript
gizmo.dragBehavior.onDragObservable.add(() => {
 console.log("drag");
});
```

Classes for 3 axis gizmos are also provided which contain 3 of the single axis gizmos within

- <Playground id="#31M2AP#6" title="PositionGizmo Example" description="Simple example of how to use the PositionGizmo."/>
- <Playground id="#31M2AP#8" title="ScaleGizmo Example" description="Simple example of how to use the ScaleGizmo."/>
- <Playground id="#31M2AP#7" title="RotationGizmo Example" description="Simple example of how to use the RotationGizmo."/>

The single axis gizmos within these are exposed via the xGizmo, yGizmo and zGizmo properties. The scale gizmo also has a uniformScaleGizmo property which references center gizmo used to uniformly scale.

## Bounding box Gizmo

The BoundingBoxGizmo displays a bounding box around an object as well as controls to rotate and scale the object.

The enabled rotation axis can be customized with the following:

```javascript
// only enable rotation on x and y axis
gizmo.setEnabledRotationAxis("xy");
```

The size of rotation and scale controls on the gizmo can be adjusted by using the following controls:

```javascript
// The size of the rotation spheres attached to the bounding box (Default: 0.1)
gizmo.rotationSphereSize = 0.1;
// The size of the scale boxes attached to the bounding box (Default: 0.1)
gizmo.scaleBoxSize = 0.1;
// If set, the rotation spheres and scale boxes will increase in size based on the distance away from the camera to have a consistent screen size (Default: false)
gizmo.rotationSphereSize = false;
```

The following events are fired when dragging occurs on either the scale or rotation meshes of the bounding box.

```javascript
gizmo.onScaleBoxDragObservable.add(() => {
 console.log("scaleDrag");
});
gizmo.onScaleBoxDragEndObservable.add(() => {
 console.log("scaleEnd");
});
gizmo.onRotationSphereDragObservable.add(() => {
 console.log("rotDrag");
});
gizmo.onRotationSphereDragEndObservable.add(() => {
 console.log("rotEnd");
});
```

To drag around objects contained inside a bounding box, [Mesh Behaviors](/features/featuresDeepDive/behaviors/meshBehaviors) can be attached.
When using with models with complex geometry such as a custom GLTF file, the complex model should be set to not be pickable by pointers and wrapped in a pickable bounding box mesh to save on performance. A helper method to do this is provided.

```javascript
const boundingBox = BABYLON.BoundingBoxGizmo.MakeNotPickableAndWrapInBoundingBox(gltfMesh);
```

Additionally, the bounding box can ignore children of the attached mesh to add additional performance gain when needed.

```javascript
gizmo.ignoreChildren = true;
```

To only ignore certain children when computing the bounding box, the includeChildPredicate can be set.

```javascript
gizmo.includeChildPredicate = (m) => {
 return m == sphere2;
};
```

<Playground id="#SG9ZZB" title="Bounding Box Gizmo Example" description="Simple example of a bounding box gizmo."/>

UI can be attached to the bounding box using the [AttachToBoxBehavior](/features/featuresDeepDive/behaviors/meshBehaviors)

<Playground id="#8GY6J8#199" title="Bounding Box Gizmo .glTF Example" description="Simple example of how to use the Bounding Box Gizmo with a .glTF file."/>
<Playground id="#6E4LSB#15" title="Bounding Box Gizmo Animated .glTF Example" description="Simple example of how to use the Bounding Box Gizmo with an animated .glTF file."/>
<Playground id="#DEYAQ5#47" title="Bounding Box Gizmo Example" description="Simple example of how to use the Bounding Box Gizmo."/>

## Gizmo customization

To customize the visual appearance of an existing gizmo, create a mesh on the same utility layer and then setCustomMesh on the gizmo. Utility layers do not contain lights by default so it is recommended use a material with an emissive texture.

```javascript
const customMesh = BABYLON.MeshBuilder.CreateBox("", { size: 0.1 }, gizmo.gizmoLayer.utilityLayerScene);
customMesh.material = material;
gizmo.setCustomMesh(customMesh);
```

<Playground id="#7KX2R8#133" title="Gizmo Customization Example" description="Simple example of how to customize the gizmo."/>

## How To Make a Mesh Glow

Emissive meshes are equivalent to self lit meshes. Both the emissive color and texture of the material determine how the mesh will self lit. This can for instance help create a phosphorescent watch dial. Babylon JS supports natively emissive poperties in both the standard and PBR materials.

But how could we easily make the glow around those self lit areas ?

![illustration](/img/how_to/glow-layer/introduction.jpg)

## How to use ?

Only one line is needed to make all the emissive parts of a scene glow:

```javascript
const gl = new BABYLON.GlowLayer("glow", scene);
```

<Playground id="#LRFB2D#1" title="Glow Layer Example" description="Simple example of using the glow layer."/>

## Intensity Controls

By default, the glow layer is filled using the material emissive parameters (emissive result = emssive color _ emissive texture color _ emissive texture level). It will also use a blur kernel of 32 which might not be adapted to your visual requirements.

## Color Intensity

To control the intensity of the color in the glow layer, you can use the dedicated property:

```javascript
const gl = new BABYLON.GlowLayer("glow", scene);
gl.intensity = 0.5;
```

<Playground id="#LRFB2D#2" title="Glow Layer Color Intensity" description="Simple example of using the glow layer with color intensity."/>

### Blur Intensity

In order to control the shape of the blur, you can rely on the creation option:

- **mainTextureRatio**: Multiplication factor applied to the canvas size to compute the render target size used to generate the glowing objects (the smaller the faster).
- **mainTextureFixedSize**: Enforces a fixed size texture to ensure resize independant blur to prevent the shape of the blur to change according to the target device size.
- **blurKernelSize**: How big is the kernel of the blur texture.

```javascript
const gl = new BABYLON.GlowLayer("glow", scene, {
 mainTextureFixedSize: 1024,
 blurKernelSize: 64,
});
```

<Playground id="#LRFB2D#3" title="Glow Layer Blur Intensity" description="Simple example of using the glow layer with blur intensity."/>

### Controlling glow color per mesh

By default the glow layer will use emissive texture and emissive color to generate the glow color of every active mesh.
But you can override this behavior with the following callbacks:

- customEmissiveColorSelector: (mesh: Mesh, subMesh: SubMesh, material: Material, result: Color4) => void: Callback used to let the user override the color selection on a per mesh basis
- customEmissiveTextureSelector(mesh: Mesh, subMesh: SubMesh, material: Material) => Texture: Callback used to let the user override the texture selection on a per mesh basis

```javascript
const gl = new BABYLON.GlowLayer("glow", scene);
gl.customEmissiveColorSelector = function (mesh, subMesh, material, result) {
 if (mesh.name === "lightsaber") {
 result.set(1, 0, 1, 1);
 } else {
 result.set(0, 0, 0, 0);
 }
};
```

## Anti Aliasing

Depending on your setup, some aliasing artifacts might appear in the glow. To prevent this behavior, you can specify the number of samples to use for MSAA on the main render target. Please note that it will only work on WebGL2 capable browsers.

```javascript
const gl = new BABYLON.GlowLayer("glow", scene, {
 mainTextureSamples: 4,
});
```

<Playground id="#LRFB2D#4" title="Glow Layer Anti Aliasing" description="Simple example of using the glow layer with anti aliasing."/>

## Mesh Management

Some helper functions have been introduced to exclude or only include some meshes from the scene.

### Excluded Mesh

In order to exclude meshes from the glow layer you can use the dedicated function:

```javascript
const gl = new BABYLON.GlowLayer("glow", scene);
gl.addExcludedMesh(mesh);
```

<Playground id="#LRFB2D#29" title="Excluding Meshes From The Glow Layer" description="Simple example of excluding meshes from the glow layer."/>

### Include Only some Meshes

In order to include only a subset of meshes in the glow layer you can use the dedicated function:

```javascript
const gl = new BABYLON.GlowLayer("glow", scene);
gl.addIncludedOnlyMesh(mesh);
```

Using the function will automatically switch mode and only render the included meshes.

<Playground id="#LRFB2D#30" title="Including Specific Meshes In The Glow Layer" description="Simple example of including specific meshes in the glow layer."/>

### Using Glow with Node Materials

The Glow layer can also be combined with a [Node Material](/features/featuresDeepDive/materials/node_material/nodeMaterial) for endless possibilities. You can achieve this by utilizing masking in the node material, separating the emission texture from the base color texture, and then recompositing them together using the mesh's glow layer. Check out the following playground and video for a deeper explanation.

<Playground id="#7QCYPB" title="Using Glow Layer with Node Materials" description="Simple example of using a mesh's glow layer with a node material."/>

<Youtube id="5ZuM-WLqEPQ"/>

## How To Highlight a Mesh

How often did you search to highlight some of your meshes in a scene? Sounds easy at first but quickly becomes an issue dealing with edges, blur and antialiasing.

If you ever needed it, this tutorial is made for you.

![illustration](/img/how_to/highlight-mesh/introduction.png)

## How to use?

Before anything else, you must ensure that your engine was created with stencil on:

```javascript
const engine = new BABYLON.Engine(canvas, true, { stencil: true });
```

The HighlightLayer relies on stencil to determine which part of the image it needs to paint.

### Default Use Case

In the most basic shape, you only need to instantiate one highlight layer in your scene and add the meshes you want to highlight in it.

```javascript
// Add the highlight layer.
const hl = new BABYLON.HighlightLayer("hl1", scene);
hl.addMesh(sphere, BABYLON.Color3.Green());
```

The highlight color is driven by the second parameter of the `addMesh` method:

<Playground id="#1KUJ0A#305" title="Mesh Highlighting Example" description="Simple example of highlighting a mesh."/>

### Stop highlighting a Mesh

In case one highlighted mesh do not require highlights anymore, you can simply remove it from the layer:

```javascript
// Add the highlight layer.
const hl = new BABYLON.HighlightLayer("hl1", scene);
hl.addMesh(sphere, BABYLON.Color3.Green());
hl.removeMesh(sphere);
```

<Playground id="#1KUJ0A#102" title="Stop Mesh Highlighting" description="Simple example of stoping highlighting a mesh."/>

### Emissive Input

If you wish, you could also use the emissive texture as a source for the highlight color. Simply pass true as the third parameter of the add mesh method.

```javascript
hl1.addMesh(sphere, BABYLON.Color3.Black(), true);
```

<Playground id="#1KUJ0A#57" title="Mesh Highlighting Emissive Input" description="Simple example of using the emissive input with mesh hilighting."/>

You can notice here that one side of the sphere is glowing in yellow whereas the other one is grey. The color is not uniform.

## Going further

### Overlapping Highlights

The first thing you will probably notice is the fact that overlapping highlighted meshes are not showing highlights in common areas.

```javascript
// Add the highlight layer.
const hl = new BABYLON.HighlightLayer("hl1", scene);
hl.addMesh(sphere, BABYLON.Color3.Green());
hl.addMesh(ground, BABYLON.Color3.Red());
```

<Playground id="#1KUJ0A#1" title="Broken Overlapping Mesh Highlights" description="Simple example of broken overlapping mesh highlights."/>

This is the default behavior optimized for performance. If you are running your scenes on a fast enough machine, you can create several highlight layers to work around the issue:

```javascript
// Add the highlight layer.
const hl1 = new BABYLON.HighlightLayer("hl1", scene);
hl1.addMesh(sphere, BABYLON.Color3.White());
const hl2 = new BABYLON.HighlightLayer("hl2", scene);
hl2.addMesh(ground, BABYLON.Color3.Red());
```

<Playground id="#1KUJ0A#2" title="Overlapping Mesh Highlights" description="Simple example of overlapping mesh highlights."/>

### Blur Size

The second question you will probably have is the ability to animate the blur size of the highlight. You can dynamically change it at run time through the blur size property of the layer:

```javascript
// Add the highlight layer.
const hl2 = new BABYLON.HighlightLayer("hl2", scene);
hl2.addMesh(ground, BABYLON.Color3.Red());

const alpha = 0;
scene.registerBeforeRender(() => {
 alpha += 0.06;

 hl2.blurHorizontalSize = 0.3 + Math.cos(alpha) * 0.6 + 0.6;
 hl2.blurVerticalSize = 0.3 + Math.sin(alpha / 3) * 0.6 + 0.6;
});
```

<Playground id="#1KUJ0A#4" title="Blur Size Mesh Highlight" description="Simple example of blur size in the mesh highlight."/>

### Inner vs Outer Glow

Finally, you can easily enable/disable inner and outer glow on the highlight layer.

```javascript
// Add the highlight layer.
const hl1 = new BABYLON.HighlightLayer("hl1", scene);
hl1.addMesh(sphere, BABYLON.Color3.White());
hl1.outerGlow = false;

const hl2 = new BABYLON.HighlightLayer("hl2", scene);
hl2.addMesh(ground, BABYLON.Color3.Red());
hl2.innerGlow = false;
```

<Playground id="#1KUJ0A#3" title="Inner vs Outer Glow" description="Simple example of mesh highlighting with inner vs outer glow."/>

You can notice on the previous scene the white glowing only inside of the sphere and the red only outside of the plane.

### Exclude mesh

Depending on your scene, transparent meshes may not render correctly with other highlighted meshes:

<Playground id="#2FFOYQ#6" title="Broken Transparency Mesh Highlight" description="Simple example of broken transparency mesh highlighting."/>

In that case, try to exclude them from the highlight generation process in order to fix this:

```javascript
hl.addExcludedMesh(skybox1);
```

<Playground id="#2FFOYQ#7" title="Fixed Transparency Mesh Highlight" description="Simple example of fixed transparency mesh highlighting."/>

### Multi Camera

By default, the highlight layer will apply on all active cameras but it creates extra processing on the camera where it is not needed.

You can easily specify what camera your highlights are related to in the options:

```javascript
const hl1 = new BABYLON.HighlightLayer("hl1", scene, { camera: camera });
hl1.addMesh(sphere, BABYLON.Color3.Green());
```

<Playground id="#CDHKK#7" title="Multi-Camera" description="Simple example of mesh highlight handling with multiple cameras."/>

### Rendering Groups

If you rely on rendering groups in your application, be mindful that the highlights requires stencil and depth info of your scene to work accurately.

So you could disable the clear between rendering groups with the command: `scene.setRenderingAutoClearDepthStencil(1, false, false)` where the first parameter is the rendering group id, the second to prevent automatically clearing depth between groups and the last to prevent automatically clearing stencil information between groups.

## Options

The available members of the option object are:

- mainTextureRatio?: number - Multiplication factor apply to the canvas size to compute the render target size used to generated the glowing objects (the smaller the faster).
- mainTextureFixedSize?: number - Enforces a fixed size texture to ensure resize independent blur.
- blurTextureSizeRatio?: number - Multiplication factor apply to the main texture size in the first step of the blur to reduce the size of the picture to blur (the smaller the faster).
- blurVerticalSize?: number - How big in texel of the blur texture is the vertical blur.
- blurHorizontalSize?: number - How big in texel of the blur texture is the horizontal blur.
- alphaBlendingMode?: number - Alpha blending mode used to apply the blur. Default is combine.
- camera?: Camera - The camera attached to the layer (only this camera can see the highlights).
- isStroke?: boolean - Should we display highlight as a solid stroke?

You can pass them during the construction of the highlight layer:

```javascript
const hl1 = new BABYLON.HighlightLayer("hl1", scene, { camera: myCamera });
```


## Interactions
Possibly the most important interactions you can have are user interactions when picking a mesh in the scene for example. These can be achieved with scene observables. 

You often also need to find whether to meshes are intersecting or the relative position of a mesh with reference to another mesh, camera or point in space. These can be achieved in Babylon.js using *intersectsMesh*, for two meshes and for ray casting *Ray* and *intersect*.

## Native Babylon.js function

To easily merge a number of meshes to a single mesh use the static `MergeMeshes` of the `Mesh` class:

```javascript
const newMesh = BABYLON.Mesh.MergeMeshes(arrayOfMeshes, disposeSource, allow32BitsIndices, meshSubclass, subdivideWithSubMeshes, multiMultiMaterials);
```

| variable | description |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| arrayOfMeshes | An array of Meshes. They should all be of the same material. |
| disposeSource (optional) | When true (default), the source meshes will be disposed upon completion. |
| allow32BitsIndices (optional) | When the sum of the vertices > 64k, this must be set to true. |
| meshSubclass (optional) | When set, vertices inserted into this Mesh. Meshes can then be merged into a Mesh sub-class. |
| subdivideWithSubMeshes (optional) | When true (false default), subdivide mesh to his subMesh array with meshes source. |
| multiMultiMaterials (optional) | When true (false default), subdivide mesh and accept multiple multi materials, ignores subdivideWithSubMeshes. |

Since `multiMultiMaterials` defaults to false, the resulting merged mesh will have only one material applied to it (taken from the first mesh):

<Playground id="#INZ0Z0#5" title="Merged Meshes Example" description="Simple example of merging meshes together."/>

Compare with the following example which sets `multiMultiMaterials` to true:

<Playground id="#INZ0Z0#59" title="Merging Meshes With Multiple Materials" description="Simple example of merging meshes together with multiple materials."/>

See [this page](/features/featuresDeepDive/materials/using/multiMaterials) for more details on usage of merged meshes.

## Use your own merge function

If you want to merge meshes into a new one using a self implemented function, you can use the following code as basis and improve it to your needs:

Note: Careful, when you merge cloned mesh, you need to update the world matrix of the mesh with computeWorldMatrix before calling the function.

**Note: This article covers the internal merging process. You can also use `BABYLON.VertexData` object and its `merge()` function for a simpler solution.**

```javascript
const mergeMeshes = function (meshName, arrayObj, scene) {
 const arrayPos = [];
 const arrayNormal = [];
 const arrayUv = [];
 const arrayUv2 = [];
 const arrayColor = [];
 const arrayMatricesIndices = [];
 const arrayMatricesWeights = [];
 const arrayIndice = [];
 const savedPosition = [];
 const savedNormal = [];
 const newMesh = new BABYLON.Mesh(meshName, scene);
 const UVKind = true;
 const UV2Kind = true;
 const ColorKind = true;
 const MatricesIndicesKind = true;
 const MatricesWeightsKind = true;

 for (let i = 0; i != arrayObj.length; i++) {
 if (!arrayObj[i].isVerticesDataPresent([BABYLON.VertexBuffer.UVKind])) UVKind = false;
 if (!arrayObj[i].isVerticesDataPresent([BABYLON.VertexBuffer.UV2Kind])) UV2Kind = false;
 if (!arrayObj[i].isVerticesDataPresent([BABYLON.VertexBuffer.ColorKind])) ColorKind = false;
 if (!arrayObj[i].isVerticesDataPresent([BABYLON.VertexBuffer.MatricesIndicesKind])) MatricesIndicesKind = false;
 if (!arrayObj[i].isVerticesDataPresent([BABYLON.VertexBuffer.MatricesWeightsKind])) MatricesWeightsKind = false;
 }

 for (let i = 0; i != arrayObj.length; i++) {
 const ite = 0;
 const iter = 0;
 arrayPos[i] = arrayObj[i].getVerticesData(BABYLON.VertexBuffer.PositionKind);
 arrayNormal[i] = arrayObj[i].getVerticesData(BABYLON.VertexBuffer.NormalKind);
 if (UVKind) arrayUv = arrayUv.concat(arrayObj[i].getVerticesData(BABYLON.VertexBuffer.UVKind));
 if (UV2Kind) arrayUv2 = arrayUv2.concat(arrayObj[i].getVerticesData(BABYLON.VertexBuffer.UV2Kind));
 if (ColorKind) arrayColor = arrayColor.concat(arrayObj[i].getVerticesData(BABYLON.VertexBuffer.ColorKind));
 if (MatricesIndicesKind) arrayMatricesIndices = arrayMatricesIndices.concat(arrayObj[i].getVerticesData(BABYLON.VertexBuffer.MatricesIndicesKind));
 if (MatricesWeightsKind) arrayMatricesWeights = arrayMatricesWeights.concat(arrayObj[i].getVerticesData(BABYLON.VertexBuffer.MatricesWeightsKind));

 const maxValue = savedPosition.length / 3;

 arrayObj[i].computeWorldMatrix(true);
 const worldMatrix = arrayObj[i].getWorldMatrix();

 for (let ite = 0; ite != arrayPos[i].length; ite += 3) {
 const vertex = BABYLON.Vector3.TransformCoordinates(new BABYLON.Vector3(arrayPos[i][ite], arrayPos[i][ite + 1], arrayPos[i][ite + 2]), worldMatrix);
 savedPosition.push(vertex.x);
 savedPosition.push(vertex.y);
 savedPosition.push(vertex.z);
 }

 for (let iter = 0; iter != arrayNormal[i].length; iter += 3) {
 const vertex = BABYLON.Vector3.TransformNormal(new BABYLON.Vector3(arrayNormal[i][iter], arrayNormal[i][iter + 1], arrayNormal[i][iter + 2]), worldMatrix);
 savedNormal.push(vertex.x);
 savedNormal.push(vertex.y);
 savedNormal.push(vertex.z);
 }

 const tmp = arrayObj[i].getIndices();
 for (let it = 0; it != tmp.length; it++) {
 arrayIndice.push(tmp[it] + maxValue);
 }
 arrayIndice = arrayIndice.concat(tmp);

 arrayObj[i].dispose(false);
 }

 newMesh.setVerticesData(BABYLON.VertexBuffer.PositionKind, savedPosition, false);
 newMesh.setVerticesData(BABYLON.VertexBuffer.NormalKind, savedNormal, false);
 if (arrayUv.length > 0) newMesh.setVerticesData(BABYLON.VertexBuffer.UVKind, arrayUv, false);
 if (arrayUv2.length > 0) newMesh.setVerticesData(BABYLON.VertexBuffer.UV2Kind, arrayUv, false);
 if (arrayColor.length > 0) newMesh.setVerticesData(BABYLON.VertexBuffer.ColorKind, arrayUv, false);
 if (arrayMatricesIndices.length > 0) newMesh.setVerticesData(BABYLON.VertexBuffer.MatricesIndicesKind, arrayUv, false);
 if (arrayMatricesWeights.length > 0) newMesh.setVerticesData(BABYLON.VertexBuffer.MatricesWeightsKind, arrayUv, false);

 newMesh.setIndices(arrayIndice);
 return newMesh;
};
```

## Merging Meshes with Constructive Solid Geometry

You can also construct complex meshes by using `subtract`, `inverse`, `union`, and `intersect` methods of the [CSG](/typedoc/classes/babylon.csg) class.

For example, let's say you want to create a "pipe" shape with an inner and outer diameter (_i.e._, not just a "tube" mesh, which is a curved plane with no "thickness"). This can be constructed by first creating a "cylinder" mesh, and then _subtracting_ a "tube" mesh from the inside of it.

```typescript
function createPipe(diamInner: number, diamOuter: number, length: number, scene: BABYLON.Scene): BABYLON.Mesh {
 // Create the outer wall using a Cylinder mesh
 const mOuter = BABYLON.MeshBuilder.CreateCylinder(
 "mOuter",
 {
 diameter: diamOuter,
 height: length,
 },
 scene,
 );
 // Create the inner wall using a Tube mesh
 const mInner = BABYLON.MeshBuilder.CreateTube(
 "mInner",
 {
 path: [new BABYLON.Vector3(0, -length / 2, 0), new BABYLON.Vector3(0, length / 2, 0)],
 radius: diamInner / 2,
 sideOrientation: BABYLON.Mesh.DOUBLESIDE,
 },
 scene,
 );
 // Create CSG objects from each mesh
 const outerCSG = BABYLON.CSG.FromMesh(mOuter);
 const innerCSG = BABYLON.CSG.FromMesh(mInner);
 // Create a new CSG object by subtracting the inner tube from the outer cylinder
 const pipeCSG = outerCSG.subtract(innerCSG);
 // Create the resulting mesh from the new CSG object
 const mPipe = pipeCSG.toMesh("mPipe", null, scene);
 // Dispose of the meshes, no longer needed
 mInner.dispose();
 mOuter.dispose();
 scene.removeMesh(mInner);
 scene.removeMesh(mOuter);
 // Return the result
 return mPipe;
}
```

Playground example:
<Playground id="#L5T0DK" title="Pipe CSG Example" description="Creating a pipe from a cylinder and a tube using CSGs."/>

Subtract example:
<Playground id="#VYZEEQ#4" title="CSG Subtract Example" description="Simple example of using a CSG subtract operation."/>

## How To Use MeshExploder

`MeshExploder` takes an array of meshes and increases/decreases distance to a center `Mesh`.

```javascript
const newExplosion = new BABYLON.MeshExploder(meshes, centerMesh);

newExplosion.explode(); //Explodes meshes away from center. Default 1.0.
```

| variable | description |
| --------------------- | ----------------------------------------------------------------------------------------- |
| meshes | The array of meshes to explode/implode. |
| centerMesh (optional) | The mesh to be the center of explosion. Defaults to mesh closest to center of all meshes. |

`MeshExploder` explode function takes a number parameter to multiply the distance of explosion. Negative numbers implode. Zero resets meshes to original positions.

```javascript
newExplosion.explode(-2); //Implodes
newExplosion.explode(0); //Resets
```

## Example Usage

```javascript
const toExplodeArray = [];
const sphere1 = BABYLON.MeshBuilder.CreateSphere("sphere1", { segments: 12, diameter: 2 }, scene);
sphere1.position.y += 2;
toExplodeArray.push(sphere1);

for (let alpha = 0; alpha < Math.PI * 2; alpha += Math.PI / 10) {
 const sphere0 = BABYLON.MeshBuilder.CreateSphere("sphere0", { segments: 8, diameter: 0.5 }, scene);
 sphere0.position.y = 2;
 sphere0.position.z = Math.cos(alpha) * 1.25;
 sphere0.position.x = Math.sin(alpha) * 1.25;
 toExplodeArray.push(sphere0);
}

const newExplosion = new BABYLON.MeshExploder(toExplodeArray);

newExplosion.explode(2);
```

<Playground id="#SFI0DQ" title="Simple explosion" description="Simple example of creating an explosion." /> <Playground id="#PTT7L9#2" title="Larger explosion" description="Example of creating an explosion with thousands of meshes." />

# Example With Imported Objects

```javascript
const assetsManager = new BABYLON.AssetsManager(scene);
const meshTask = assetsManager.addMeshTask("model", "", "./", "model.gltf");

let meshes;

meshTask.onSuccess = function(task) {
 meshes = task.loadedMeshes;
}
assetsManager.load();
const newExplosion;
scene.executeWhenReady(function() {
 newExplosion = new BABYLON.MeshExploder(meshes);
 newExplosion.explode(2);
});
```

## Example Using the Babylon.js Viewer

```javascript
BabylonViewer.viewerManager.getViewerPromiseById("babylon-viewer").then(function (viewer) {
 viewerObservables(viewer);
});
let newExplosion;
function viewerObservables(viewer) {
 viewer.onModelLoadedObservable.add(function (model) {
 model.rootMesh.getScene().executeWhenReady(function () {
 newExplosion = new BABYLON.MeshExploder(model.meshes, model.meshes[0]);
 newExplosion.explode(2);
 });
 });
}
```

## Morph targets

Morph targets are a new feature introduced with Babylon.js v3.0.

![Morph Target Before and After](/img/how_to/morphtargets.jpg)

## Basics

Meshes can be deformed by using morph targets. A morph target must be built from a mesh with the **EXACT** same number of vertices as the original mesh.
Morph targets are used by the GPU to create the final geometry by applying the following formula:

final mesh = original mesh + sum((morph targets - original mesh) \* morph targets influences)

For instance, you can use morph targets to simulate the opening of a mouth. The initial mesh has a closed mouth. The morph target can be the same mesh but with an opened mouth. Then by changing the influence of the morph target (from 0 to 1) you can display either a closed or an opened mouth or a mix of both.

You can find live examples here:
<Playground id="#HPV2TZ#8" title="Animated Morph Targets" description="Simple example of animated morph targets."/>

The following two examples are best seen in the full Playground where sliders can be used to change the influencers
<Playground id="#HPV2TZ#2" title="Animated Morph Targets with Standard Material" description="Simple example of animated morph targets with standard material."/> 
<Playground id="#HPV2TZ#4" title="Animated Morph Targets with PBR Material" description="Simple example of animated morph targets with PBR material."/>

## How to Use Morph Targets

To use morph targets, you first have to create a `MorphTargetManager` and affect it to a mesh:

```javascript
const manager = new BABYLON.MorphTargetManager();
sphere.morphTargetManager = manager;
```

Then you can create `MorphTarget` either with the `FromMesh` static function:

```javascript
const target = BABYLON.MorphTarget.FromMesh(sphereTarget, "target", 0.25);
```

or simply by creating a target and specifying positions and normals:

```javascript
const target = new BABYLON.MorphTarget(name, influence);
target.setPositions(...);
target.setNormals(...);
```

Once done, you can specify the influence of a specific target with `target.influence = 0.25`

Targets with influence = 0 are disabled.

Here is a complete example with 4 targets:

```javascript
const scramble = function (data) {
 for (index = 0; index < data.length; index++) {
 data[index] += 0.1 * Math.random();
 }
};

// Main sphere
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere1", { segments: 16, diameter: 2 }, scene);

// Let's create some targets
const sphere2 = BABYLON.MeshBuilder.CreateSphere("sphere2", { segments: 16, diameter: 2 }, scene);
sphere2.setEnabled(false);
sphere2.updateMeshPositions(scramble);

const sphere3 = BABYLON.MeshBuilder.CreateSphere("sphere3", { segments: 16, diameter: 2 }, scene);
sphere3.setEnabled(false);

sphere3.scaling = new BABYLON.Vector3(2.1, 3.5, 1.0);
sphere3.bakeCurrentTransformIntoVertices();

const sphere4 = BABYLON.MeshBuilder.CreateSphere("sphere4", { segments: 16, diameter: 2 }, scene);
sphere4.setEnabled(false);
sphere4.updateMeshPositions(scramble);

const sphere5 = BABYLON.MeshBuilder.CreateSphere("sphere5", { segments: 16, diameter: 2 }, scene);
sphere5.setEnabled(false);

sphere5.scaling = new BABYLON.Vector3(1.0, 0.1, 1.0);
sphere5.bakeCurrentTransformIntoVertices();

// Create a manager and affect it to the sphere
const manager = new BABYLON.MorphTargetManager();
sphere.morphTargetManager = manager;

// Add the targets
const target0 = BABYLON.MorphTarget.FromMesh(sphere2, "sphere2", 0.25);
manager.addTarget(target0);

const target1 = BABYLON.MorphTarget.FromMesh(sphere3, "sphere3", 0.25);
manager.addTarget(target1);

const target2 = BABYLON.MorphTarget.FromMesh(sphere4, "sphere4", 0.25);
manager.addTarget(target2);

const target3 = BABYLON.MorphTarget.FromMesh(sphere5, "sphere5", 0.25);
manager.addTarget(target3);
```

At any time, you can remove a target with `manager.removeTarget(target)`

## How to Access Morph Targets in a glTF File

You can access a morph target influence on a mesh in a glTF file through the [morphTargetManager](/typedoc/classes/babylon.morphtargetmanager#gettarget) which is automatically created for a loaded glTF file containing morph targets. You can see how many influences are present on the mesh by writing to the console.

```javascript
console.log(mesh.morphTargetManager);
```

If you want to view or change the value of a morph target influence, it can be accessed by getting the influence from the array in the morphTargetManager by key value.

```javascript
myInfluence = mesh.morphTargetManager.getTarget(key);
```

See the following example for a full playground using morph targets from a glTF file.

- <Playground id="#9CLJEF" title="Morph Targets From a .glTF File" description="Simple example of using morph targets from a .glTF file."/>

## List of Morphable Properties

You can morph the following mesh attributes:

- position
- normal (can be turned of by calling `manager.enableNormalMorphing = false`)
- tangents (can be turned of by calling `manager.enableTangentMorphing = false`)
- uvs (can be turned of by calling `manager.enableUVMorphing = false`)

## Animating Morph Targets

You can animate any morph target influence by creating a [BABYLON.Animation](https://doc.babylonjs.com/features/featuresDeepDive/animation/animation_method) targeting the influence you wish to control. When creating your animation, you need to list "influence" as the property to be animated. This property will always be of type FLOAT.


```javascript
const myAnim = new BABYLON.Animation(name, "influence", frames_per_second, BABYLON.Animation.ANIMATIONTYPE_FLOAT, loop_mode);
```

To play the morph target animation, add the animation to the mesh that owns the [MorphTargetManager](https://doc.babylonjs.com/typedoc/classes/BABYLON.MorphTargetManager) so that the animation is easy to access later. You can then call `scene.beginAnimation` while targeting the specific morph target you want to animate.

```javascript
mesh.animations.push(myAnim);
scene.beginAnimation(morphTarget, from, to, true);
```

You can animate multiple morphs on the same mesh by creating a new animation for each morph and targeting the appropriate influence. If you want to play several morph animations simultaneously - such as playing blink animations on morph targets driving each individual eye - you can add these animations to an [animation group](https://doc.babylonjs.com/features/featuresDeepDive/animation/groupAnimations).

- <Playground id="#019CR7#2" title="Animating Morph Targets" description="Simple example of adding animation to a morph target"/>

## Use Morph Targets with Node Material

The [Node Material](/features/featuresDeepDive/materials/node_material) is a powerful tool that allows creating shaders without having to write GLSL. To use a Node Material in a mesh with Morph Targets, you need to add the Morph Target node to it so that vertex positions, normals and uvs properly respond to the effects of the morph:

![Use Morph Target with Node Material](/img/how_to/morphtargetnode.png)

<Playground id="#HPV2TZ#299" title="Using Node Material with Morph Targets" description="Use Morph Target node on the Node Material"/>

## Limitations

On WebGL2+ Babylon.js will use textures to store the targets so the only limit is the GPU memory. You can find an example of pretty large numbers of targets here: - <Playground id="#1PD3Q7#2" title="Lots of Morph Targets" description="Example showing a large number of morph targets."/>

On WebGL1, the system cannot store inside textures (it requires float textures) so as a fallback it will store the targets inside mesh vertices.

- Please be aware that most of the browsers are limited to 16 attributes per mesh. Adding a single morph target to a mesh add up to 4 new attributes (position + normal + tangents + uvs). This could quickly go beyond the max attributes limitation.
- All targets within a same manager must have the same vertices count
- A mesh and its MorphTargetManager must have the same vertices count

You can find a video explaining how morph targets work here:

<Youtube id="LBPRmGgU0PE"/>

## What Is Node Geometry

The `NodeGeometry` feature was inspired by Blender Geometry Nodes where you can use a node system to build geometry procedurally. Think about it like a postprocessing system for geometry. Ultimately it produces a geometry but with a procedural approach.

## Why Use Node Geometry?
Several reasons come to mind:
- The cost of downloading assets on the web is a strong limiting factor. Procedural data can help solve that by limiting the download to the core pieces that are assembled later by the `NodeGeometry` system
- The system is dynamic and can produce infinite variants at run time. While there are many digital content creation tools that can create procedural meshes with the same infinite possibilities, the limiting factor again becomes downloading assets created offline. Examples would be terrain or vegetation generation.
- It allows a new way of modelling in Babylon.js by assembling core shapes and playing around with a node system

## Example

Here is a complete example of an advanced `NodeGeometry` which is used to generate a city with different buildings:

<Playground id="#PYY6XE#70" title="Using NodeGeometry to generate a procedural city" description="Using NodeGeometry to generate a procedural city" image="/img/how_to/nge/01.jpg"/>

## How to Use

The `NodeGeometry` class is an utility class, meaning it is autonomous and does not require access to an engine or a scene. So instantiation is pretty simple:

```
const nodeGeometry = new BABYLON.NodeGeometry("my node geometry");
```

Once created, the system will expect you to create a flow from a source to an endpoint. In a nutshell, the `NodeGeometry` will process `VertexData` structure (See more in the section [Create Custom Meshes From Scratch](/features/featuresDeepDive/mesh/creation/custom/custom)).

By default, the `NodeGeometry` system supports the following sources:

- Box
- Capsule
- Cylinder
- Disc
- Grid
- Icosphere
- Mesh
- Plane
- Sphere
- Torus

Here is for example a complete graph that simply generates a sphere:

```
// Create node geometry
var nodegeo = new BABYLON.NodeGeometry("nodegeo");

// Create source sphere
var sphere = new BABYLON.SphereBlock("sphere");

// Create output
var output = new BABYLON.GeometryOutputBlock("geometryout");
nodegeo.outputBlock = output;
sphere.geometry.connectTo(output.geometry);
```

While this example is very simple, it isn't hard to imagine how adding more operations to the graph will present opportunities to alter the geometry flow which is represented by the `VertexData` provided by the source node. Updating that `VertexData` will influence the geometry passed to the `GeometryOutputBlock`.

The `GeometryOutputBlock` will collect the final VertexData that can then be used to generate a mesh:

```
// Build and instantiate mesh
nodegeo.build();
var mesh = nodegeo.createMesh("nodegeomesh");
```

## Updating the Geometry Flow

Now that we have the basics in place, we can start to introduce blocks which will update the data.

The simplest blocks will be the setXXX blocks which focus on generating data for a specific mesh component like positions, normals, colors, uvs, etc.:

- setPositionsBlock
- setNormalsBlock
- setTangentsBlock
- setColorsBlock
- setUVsBlock

These blocks are updating the `VertexData` by generating an entry per vertex inside the geometry. For that specific reason you can imagine them like a loop going through the list of vertices and inserting data from their input.

One way to insert data into the block is to simply use a `RandomBlock` which will generate a random value. In this example we are setting random positions for each vertex in the sphere:

```
// Create node geometry
var nodegeo = new BABYLON.NodeGeometry("nodegeo");

// Create source sphere
var sphere = new BABYLON.SphereBlock("sphere");

var setPositions = new BABYLON.SetPositionsBlock("set positions");
sphere.geometry.connectTo(setPositions.geometry);

var getRnd = new BABYLON.RandomBlock("random");
var rndMin = new BABYLON.GeometryInputBlock("rndMin", BABYLON.NodeGeometryBlockConnectionPointTypes.Vector3);
rndMin.value = BABYLON.Vector3.Zero();
var rndMax = new BABYLON.GeometryInputBlock("rndMax", BABYLON.NodeGeometryBlockConnectionPointTypes.Vector3);
rndMax.value = BABYLON.Vector3.One();
rndMin.output.connectTo(getRnd.min);
rndMax.output.connectTo(getRnd.max);
getRnd.output.connectTo(setPositions.positions);

// Create output
var output = new BABYLON.GeometryOutputBlock("geometryout");
nodegeo.outputBlock = output;
setPositions.output.connectTo(output.geometry); 

// Build and instantiate mesh
nodegeo.build();
var mesh = nodegeo.createMesh("nodegeomesh");

```

The `setPositionsBlock` will call the `RandomBlock` once per vertex to generate the final mesh:


![Using NodeGeometry to generate a random based sphere](/img/how_to/nge/02.jpg)

## Contextual Values

To go further you may want to READ from the geometry. To do that the system provides several contextual values that are capable of pulling data FROM the active geometry.

The active geometry is the geometry connected to the block that seeks to read contextual values. In our example below, that will be the `SetPositionsBlock`.

We can rewrite our graph but instead of adding random values directly we can add the normal of each vertex scaled by a random value to the position of each vertex.

The associated code is:

```
// Create node geometry
var nodeGeometry = new BABYLON.NodeGeometry("nodegeo");

// GeometryInputBlock
var Positions = new BABYLON.GeometryInputBlock("Positions");
Positions.contextualValue = BABYLON.NodeGeometryContextualSources.Positions;

// MathBlock
var Add = new BABYLON.MathBlock("Add");
Add.operation = BABYLON.MathBlockOperations.Add;

// MathBlock
var Multiply = new BABYLON.MathBlock("Multiply");
Multiply.operation = BABYLON.MathBlockOperations.Multiply;

// GeometryInputBlock
var Normals = new BABYLON.GeometryInputBlock("Normals");
Normals.contextualValue = BABYLON.NodeGeometryContextualSources.Normals;

// VectorConverterBlock
var Converter = new BABYLON.VectorConverterBlock("Converter");

// RandomBlock
var random = new BABYLON.RandomBlock("random");

// GeometryInputBlock
var Min = new BABYLON.GeometryInputBlock("Min", BABYLON.NodeGeometryBlockConnectionPointTypes.Float);
Min.value = 0;

// GeometryInputBlock
var Max = new BABYLON.GeometryInputBlock("Max", BABYLON.NodeGeometryBlockConnectionPointTypes.Float);
Max.value = 1;

// SetPositionsBlock
var setpositions = new BABYLON.SetPositionsBlock("set positions");

// SphereBlock
var sphere = new BABYLON.SphereBlock("sphere");

// GeometryOutputBlock
var geometryout = new BABYLON.GeometryOutputBlock("geometryout");

// Connections
sphere.geometry.connectTo(setpositions.geometry);
Positions.output.connectTo(Add.left);
Normals.output.connectTo(Multiply.left);
Min.output.connectTo(random.min);
Max.output.connectTo(random.max);
random.output.connectTo(Converter.xIn);
random.output.connectTo(Converter.yIn);
random.output.connectTo(Converter.zIn);
Converter.xyzOut.connectTo(Multiply.right);
Multiply.output.connectTo(Add.right);
Add.output.connectTo(setpositions.positions);
setpositions.output.connectTo(geometryout.geometry);

// Output nodes
nodeGeometry.outputBlock = geometryout;
nodeGeometry.build();
var mesh = nodeGeometry.createMesh("nodegeomesh");
```

Which will generate the following mesh:
![Using NodeGeometry to generate a random based sphere](/img/how_to/nge/03.jpg)


To better understand the graph, here is a visual representation. See the section on the [Node Geometry Editor](/features/featuresDeepDive/mesh/nodeGeometry#node-geometry-editor) below.
![NodeGeometry representation](/img/how_to/nge/04.jpg)

Please note that we used the `VectorConverter` to produce a Vector3 out of the `RandomBlock` generating a float.
We are also using the `MathBlock` twice to get Add and Multiply operations. We also have access to all trigonometry operations with the `GeometryTrigonometryBlock`.

To complete this graph, we need to add a `ComputeNormalsBlock` to make sure the normals are rebuilt using the new positions:
![NodeGeometry representation](/img/how_to/nge/06.jpg)

This will produce our weird random based sphere:
![Using NodeGeometry to generate a random based sphere](/img/how_to/nge/05.jpg)

The list of available contextual values contains the following:
- positions: Contextual value pointing at the positions array of the active geometry
- normals: Contextual value pointing at the normals array of the active geometry
- colors: Contextual value pointing at the colors array of the active geometry
- tangents: Contextual value pointing at the tangents array of the active geometry
- uvs1: Contextual value pointing at the uvs array of the active geometry
- uvs2: Contextual value pointing at the uvs2 array of the active geometry
- uvs3: Contextual value pointing at the uvs3 array of the active geometry
- uvs4: Contextual value pointing at the uvs4 array of the active geometry
- uvs5: Contextual value pointing at the uvs5 array of the active geometry
- uvs6: Contextual value pointing at the uvs6 array of the active geometry
- vertexID: Contextual value representing the vertex index of the current vertex of the active geometry
 
Many of the previous contextual values **CANNOT** be used with the `InstantiateOnFacesBlock` block. We will detail which of them can be used below.

## Node Geometry Editor

As we can see above, creating even a relatively simple `NodeGeometry` with code can quickly become very long. This is why we introduced a visual tool to help build `NodeGeometry` graphs.

## Instancing Geometries

Ok, now it is time to really unleash the core power of the `NodeGeometry`!

With the `InstantiateOnVerticesBlock` class and the `InstantiateOnFacesBlock` class, you have the opportunity to instantiate a new geometry per vertex - or multiple times per face.

So let's look at this graph:
![Using InstantiateOnVerticesBlock](/img/how_to/nge/08.jpg)

The `InstantiateOnVerticesBlock` block is used to place a box on each vertex of the sphere:
![Instancing boxes on a sphere](/img/how_to/nge/09.jpg)

You can apply rotation or scaling per instance by connecting values to the `rotation` and `scaling` inputs.

The `density` input can be used to affect a percentage of the overall vertices. For example, placing an instance of the box only on 15% of the active geometry's vertices.

The `InstantiateOnFacesBlock` class works similarly but will generate several instances per face. This block does not have a density input but instead a `count` input that will let you decide how many instances in total you want to distribute across all faces of the active geometry.

When using an `InstantiateOnFacesBlock`, you can only use the following contextual values:
- positions: Contextual value pointing at the positions array of the active geometry
- normals: Contextual value pointing at the normals array of the active geometry
- faceID: Contextual value representing the face index of the current face of the active geometry

## Controlling the Flow

The `ConditionalBlock` is the central block if we want to control what is going on with the geometry flow. It can help decide which branch of the node graph to take based on a condition that can be:
- Equals
- Not equals
- Greater than
- Greater or equals
- Lower than
- Lower or equals
- Xor
- Or
- And

For instance we can decide to have a new sphere made of boxes but we want one hemisphere to use one material and the other hemisphere to use another.
This graph will do it:
![Instancing boxes on a sphere with different material per hemisphere](/img/how_to/nge/16.jpg)

The `ConditionBlock` is used here with a Greater than setup and will then pick the value 0 or 1 based on the y value of the normal. The normal that is evaluated belongs to the active geometry. In this case, the active geomerty is the sphere as the sphere is the manipulated by the `InstantiateOnFacesBlock` block. If the y value of the normal is greater than 0.2 then it will pass a value of 0 to the `SetMaterialIDBlock`. Otherwise it will pass a value of 1.

The outcome:
![Instancing boxes on a sphere with different material per hemisphere](/img/how_to/nge/17.jpg)

## Random and Noise

In order to get random values, we have already seen the `RandomBlock`. However, there is another one that can be used which is the `NoiseBlock`.

This block will generate a noise pattern based on a Perlin noise algorithm.

Here is our example again with the `SetPositions` block:
![Using noise pattern](/img/how_to/nge/10.jpg)

Which will produce this mesh:
![Using noise pattern to generate a sphere](/img/how_to/nge/11.jpg)

## Material ID

If working with multiple mesh sources is desired, we can merge them easily with the `MergeBlock`:
![using MergeBlock in a graph](/img/how_to/nge/12.jpg)

Which will generate this mesh:
![Using MergeBlock to merge multiple geometries](/img/how_to/nge/13.jpg)

The generated mesh will be made of one unified geometry and be rendered with one draw call.

But we can go further and actually attach a material ID per geometry with the `SetMaterialID` block:
![using MergeBlock and SetMaterialID in a graph](/img/how_to/nge/14.jpg)

Which will generate this mesh:
![using MergeBlock and SetMaterialID for a mesh](/img/how_to/nge/15.jpg)

The mesh will now have a list of subMeshes in `mesh.subMeshes` and will be rendered with a [MultiMaterial](/features/featuresDeepDive/materials/using/multiMaterials) using one material per ID.

## Serialization

A `NodeGeometry` entity can be serialized to a json object:
```
geometry.serialize(true);
```
The boolean indicates if the geometry produced by the `MeshBlock` should also be serialized into the json object. Use caution when doing this becuase the resulting json can quickly become very heavy.

To load a `NodeGeometry` from a json object, call this code:
```
nodeGeometry.parseSerializedObject(json);
```

If using the Node Geometry Editor instead, `NodeGeometry` can be loaded directly from our snippet server:
```
const geometry = await BABYLON.NodeGeometry.ParseFromSnippetAsync("IJA02K#11");
```

## Loading and Updating From File
In addition to loading from the snippet server, node geometry can be loaded and parsed directly from local storage. This allows a common node geometry flow to be shared between multiple projects while allowing updates to input parameters or source meshes. [Asset Manager](/features/featuresDeepDive/importers/assetManager) is a great way to load node geometry files to your scene and can also be used to load meshes to use with the node geometry at the same time. Simply add a new [TextFileAssetTask](/features/featuresDeepDive/importers/assetManager#textfileassettask) for each node geometry file that needs to be loaded.

```javascript
const assetsManager = new BABYLON.AssetsManager(scene);
const nodeGeometryFile = assetsManager.addTextFileTask("load my node geometry", "nodeGeometry.json");

// load all tasks
assetsManager.load();
```

Asset Manager has a callback we can use to convert the loaded text into a JSON object and then parse to node geometry.

```javascript
// callback
assetsManager.onFinish = async (tasks) {
 console.log("all tasks successful", tasks);

 // files loaded as text need to be parsed to JSON to use
 const nodeGeometryJSON = JSON.parse(nodeGeometryFile.text);

 // parse json object into node geometry
 const nodeGeometry = await BABYLON.NodeGeometry.Parse(nodeGeometryJSON);
}
```
Remember that we still need to `build` the node geometry and then use `createMesh` to actually render it into the scene. However, before we build the node geometry, now is the time to get any node that may need to be assigned a value like a color, vector, or mesh. There are a few options for finding blocks within the graph such as `getBlockByName`, `getBlockByPredicate`, or `getInputBlocks`. These methods can be used to find specific blocks and set their values.

``` javascript
nodeGeometry.getBlockByName("my_vector").value = new BABYLON.Vector3(1.0, 0.0, 1.0);
nodeGeometry.getBlockByName("my_mesh").mesh = myLoadedMesh;
```

Once we are done setting parameters or attaching meshes to our node geometry, we then call `build` and `createMesh`.

```javascript
nodeGeometry.build();
const myGeometry = nodeGeometry.createMesh("myGeometry");
```

The order of operations here is important. If node geometry is built and then we try to update any values on the blocks within the graph, no changes will be seen until `nodeGeometry.build()` is called and we `createMesh` again. This also means that we can load and build a node geometry and keep it in memory until we need it with a call to `createMesh`. Or we could `dispose` of a mesh created from nodeGeometry and simply call `createMesh` again at a later point to bring the node geometry back into the scene. In this way node geometry acts a little like Asset Container where we always have the it in memory ready to create new meshes whenever we need them.

## Optimizations
The `NodeGeometry` class uses the CPU to process data. Which means that we have to be cautious if expecting to generate several meshes.

For instance let's take this graph:
![Instancing meshes on a sphere](/img/how_to/nge/07.jpg)

We can see that the `InstantiateOnVerticesBlock` will call the Transform of the geometry flow for each vertex of the sphere. Note the use of the `MergeBlock` to combine multiple geometries. In this case, as nothing in the instance part of the graph is using contextual values - such as reading positions or normals - we can ask the `GeometryTransformBlock` to not reevaluate its context on each call.

To do so simply call:
```
myBlock.evaluateContext = false;
```

## How To Use Path3D

A `Path3D` is a mathematical object created from a sequence of position vectors of points on a curve. Once obtained a Path3D can be used to determine the triplet of vectors tangent, normal and binormal of the curve for each of those points. Each triplet can then be used as a local system coordinate. You could set, for example, the camera direction to the normal as it follows the curve.

A `Path3D` object is simple to construct as follows

```javascript
const points = [v1, v2, ..., vn];          // array of Vector3
const path3d = new BABYLON.Path3D(points);
```

You can then get the array of tangents, normals and binormals as follows

```javascript
const tangents = path3D.getTangents();
const normals = path3D.getNormals();
const binormals = path3D.getBinormals();
```

each element of the arrays is a `Vector3` .

<Playground id="#2DLXYB#0" title="Tangents, Normals, and Binormals" description="Simple example of exploring tangents, normals, and binormals."/>

Please zoom in and rotate : tangents in red, normals in blue, binormal in green.

Notice, in the next example, how the the triplets slightly rotate when the curve goes more into depth. 
<Playground id="#2DLXYB#1" title="Tangents, Normals, and Binormals - Color Coded" description="Simple example of exploring color coded tangents, normals, and binormals."/>

Whilst at any point on the curve there is only one tangent there can be an infinite number of normals and hence binormals. If the default one does not suit you it is possible to [set the normal direction](/features/featuresDeepDive/mesh/path3D#set-the-normal)

## Path3D Methods

As well as `getTangents`, `getNormals` and `getBinormals` there are some other methods of `Path3D`.

### Get Curve Points

The `getCurve` method returns a copy of the initial `Vector3` array given to create the `Path3D` object.

```javascript
const curvePoints = path3d.getCurve();
```

### Get Distances

The `getDistances` method returns an array of distances from one curve point to the next in order of points and with 0 being the first distance.

For the array of points [(1, 0, 0), (5, 0, 0), (5, 1, 0)] the array of distances is [0, 4, 5].

```javascript
const distances = path3d.getDistances();
```

### Interpolation

You can get info about any virtual point (from 0.0 to 1.0) along the path by functions that interpolate between the path points. Those are the following:

`getPointAt`, `getTangentAt`, `getNormalAt`, `getBinormalAt`, `getDistanceAt`, `getPreviousPointIndexAt`, `getSubPositionAt`

### Copying (part of) the path

The `slice` method returns a new Path3D that is subpath (slice) of the original path. It takes a _start_ and _end_ position from 0.0 to 1.0, or negative values, which wrap back around from 1.0

### Update

In order to avoid memory re-allocation (when in the render loop for example) since the given _points_ array is internally copied, you can update an existing `Path3D` object with its `update()` method.

```javascript
const points1 = [v1, v2, ..., vn];          // array of Vector3
const path3d = new BABYLON.Path3D(points1);
const points2 = [u1, u2, ..., un];          // another array of Vector3
path3D.update(points2);
```

Tangents, normals and bi-normals are thus recomputed for this new path.

<Playground id="#2DLXYB#253" title="Update Path3D" description="Update a Path3D object and observe its results."/>

### Getting the closest position to a point

The `getClosestPositionTo` function returns the position, from 0.0 to 1.0, of the closest virtual point along the path to an arbitrary Vector3.

## Set The Normal

For any vector there are an infinite number of vectors at right angles to it.

![Multiple Normals](/img/how_to/Mesh/tangentnormals.jpg)

In creating a `Path3D` object Babylon.js assigns a default direction for the normal. If you want to set the direction of the normal yourself, you need to pass a vector for a second parameter to `Path3D` on creation or on update.

```javascript
const initialVector = new BABYLON.Vector3(0, 1, 0);
const otherVector = new BABYLON.Vector3(0, 0, 1);
const points = [v1, v2, ..., vn];          // array of Vector3
const path3d = new BABYLON.Path3D(points, initialVector);
// do stuff ...
path3d.update(points, otherVector);
```

The normal will be the projection of your parameter vector onto the plane orthogonal to the tangent at the point position.

As can been in the diagram below, when the parameter is a vertical vector (black), this is projected onto the plane orthoganal to the tangent vector (red) to form the normal (green).

![Curve Normal](/img/how_to/Mesh/planenormal.jpg)

The playground example shows what happens as the vector setting the normal direction is rotated.

<Playground id="#8ICWNU" title="Path3D with Rotating Normals" description="Simple example of Path3D with rotating normals."/>

## Normalization and tangent alignment

Apart from the first normal, there are two more parameters:

`raw`, boolean, **false** by default. If true the tangents, normals and binormals aren't normalized. Useful to depict path acceleration or speed.

`alignTangentsWithPath`, boolean, **false** by default. If true the tangents will be aligned with the path.

## Objects Following A Path

As mentioned in the beginning section, the position of points along the curve, together with the tangent, normal, and binormal vectors, can be used to guide the position and orientation of an object, creating interesting yet effortless animations.

<Playground id="#SGVUBC#38" title="Camera Following a Path" description="Example of a Camera animated to follow the positions and orientations along a Path3D object."/>

The playground above illustrates this technique. The Path3D is constructed as the combination of a few cubic Bèzier curves (but manually defining the points would work just fine). On each point of the path, its tangent and binormal vectors are passed as [arguments](/typedoc/classes/babylon.quaternion#fromlookdirectionrh) to the `FromLookDirectionRH()` method of the [Quaternion class](/features/featuresDeepDive/mesh/transforms/center_origin/rotation_quaternions), orienting the camera such that it looks down the tangent direction, and points up towards the binormal. We then set the sequences of positions and orientations as [animation keys](/features/featuresDeepDive/animation/animation_design), and play it. This idea isn't limited to Cameras, as it could also be used to define paths along which characters would walk in a game, for example.

## Simplify a Mesh with Auto-LOD

## About

[Level of Details](https://en.wikipedia.org/wiki/Level_of_detail) is a powerful tool that was added to Babylon.js in version 2.0. The concept is rather simple: when the camera is at a certain distance from the mesh, lowering the amount of faces displayed will increase performance without the user noticing the reduction.

LOD requires the developer to add a few meshes to the original mesh. One of the ways to create those meshes is simplification. Many 3D tools offer various simplification algorithms. It is sometimes called Decimation.

Starting with version 2.0, Babylon.js offers an in-browser simplification functionality that works asynchronously while trying not to disturb the rendering process. These LOD levels will be automatically added to the scene after finishing the calculation.

## Usage - Simplifying a mesh

Any object of the class BABYLON.Mesh has a "simplify" function with the following signature:

```javascript
public simplify(settings: Array<ISimplificationSettings>,
                parallelProcessing: boolean = true,
                type: SimplificationType = SimplificationType.QUADRATIC,
                successCallback?: () => void);
```

- **Settings**

The settings object has two parameters:

1. quality - a number between 0.0 and 1.0, defining the percentage of the decimation (1 being 100%)
2. distance - the distance from the object to which this LOD mesh will be added.
3. (since 2.1) optimizeMesh - should the mesh be optimized? (optional, defaults to false). More about optimization later.

A simple example for an array of settings would be:

```javascript
[
 { quality: 0.9, distance: 25, optimizeMesh: true },
 { quality: 0.3, distance: 50, optimizeMesh: true },
];
```

For the typescript users and the "new" lovers, a SimplificationSettings class exists. So, this can also be done:

```javascript
const settings: Array<ISimplificationSettings> = []; //in JS: const settings = [];
settings.push(new BABYLON.SimplificationSettings(0.8, 60));
settings.push(new BABYLON.SimplificationSettings(0.4, 150));
```

- **Parallel Processing**

The code runs async. The `parallelProcessing` flag sets the order of processing of each level. If set to true, all will run together. This will use more RAM (for a certain period of time) but will run quicker in general. There is a chance however, that the FPS will be reduced to an unaccepted level due to many parallel calculations between frames. Setting this flag to false will process one setting after the other. This will use only one single simplification object and will use less RAM. It can, however, take a little longer.

- **Type**

To allow further types of simplification to be implemented (will be explained later, for those who are interested) the type of simplification should be stated. There is only one kind at the moment, BABYLON.SimplificationType.QUADRATIC. This is also the default value, if type is undefined.

- **Success Callback**

Since this is an asynchronous function (which returns immediately), a callback is required in order to run code after the simplification process is over.

This function will be called after the Auto-LOD process is successfully done.

- **Usage Example**

```javascript
BABYLON.SceneLoader.ImportMesh("", "./", "DanceMoves.babylon", scene, (newMeshes, particleSystems, skeletons) => {
 newMeshes[1].simplify(
 [
 { quality: 0.9, distance: 25 },
 { quality: 0.3, distance: 50 },
 ],
 false,
 BABYLON.SimplificationType.QUADRATIC,
 function () {
 alert("LOD finisehd, let's have a beer!");
 },
 );
});
```

Once the simplification is finished, you can also access the simplified mesh by utilizing the [getLODLevelAtDistance](/typedoc/classes/babylon.mesh#getlodlevelatdistance) and [getLODLevels](/typedoc/classes/babylon.mesh#getlodlevels) functions of the mesh class. You can use this to clone the simplified mesh and use it indepedently of the main mesh.
<Playground id="#1ED15P#38" title="Clone simplified mesh" description="Access a simplified mesh and clone it."/>

## Demos 

Zoom in and out to see the effect, watch the number of active vertices closely.

Simplifying spheres. Materials of the spheres will be set after simplification ended completely.

 <Playground id="#1ED15P#1" title="Simplifying Spheres" description="Simple example of to use Auto-LOD to simplify spheres."/>

Simplifying a color-based complex mesh. An alert window will pop when simplification is over. This mesh will also take time to load and requires optimization.

With global mesh optimization -
<Playground id="#2JBSNA#3" title="Simplifying Complex Meshes" description="Simple example of to use Auto-LOD to simplify complex meshes with global optimization."/>

With optimization during simplification -
<Playground id="#2JBSNA#4" title="Simplifying Complex Meshes" description="Simple example of to use Auto-LOD to simplify complex meshes with optimization during simplification."/>

## Rules, Quirks and things to pay attention to

Not all meshes can be simplified. Better said - all meshes can be simplified, some however, should not be.

An object like a Box (if built in an optimal way, like the BABYLON.MeshBuilder.CreateBox function) has no "extra faces" that can be removed. removing one single face will cause it to... not be a box.

### A few "rules" to follow

(and never forget, rules are meant to be broken!)

1. Try simplifying meshes with more than 500 faces. Less than that will make no sense, probably.
2. Best meshes to simplify are complex objects.
3. Meshes like a plane will probably lose their shape after simplification.
4. The lower the quality of the mesh, the further the distance should be. This should not be linear - a complex mesh that was simplified to 90% will probably still look almost the same, but at 30%, it is very obvious that the mesh was simplified. Lower quality simplification should have a large distance defined.
5. Try simplifying meshes that represent a single object. A mesh containing many distant objects in one will simplify rather poorly. LOD will work poorly on such meshes as well, since the position of the mesh is not actually the position of all mesh-parts.
6. Set the mesh's material before starting the decimation. The LOD Mesh uses them when initialized. If they will not be set, expect the material to disappear when the given distance is reached.

### Quirks

- Quadratic simplification can be calculated using many factors. Position, normals, colors, UV coordinates, etc... The more factors, the slower it will run (more calculations). The decision was made to stay with position only - this means that after simplification, the UV coordinates will sometimes be a bit off. It is usually unnoticeable if you follow rule 4 above.
- Meshes might change their shape. Very noticeable with a small plane.
- Meshes might suddenly have "holes" in them. This can be avoided using the mesh optimization (starting 2.1, described further down)
- Submeshes are supported starting with Babylon.js 2.1. Meshes with submeshes would not be decimated 100% correctly due to the lack of border detection (see next point). Give it a try and see if it fits your needs.
- Some triangles on the borders will be "deleted". The reason is usually the (lack of) border detection, which is a part of the original paper. The feature was not included in the implementation due to the amount of time needed to calculate that correctly.
- Objects that are initialized using an image (best example is a Height Map-based ground) will only decimate after the image is fully loaded. For that, take advantage of the `onReady` callbacks they have:

```javascript
const ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("ground", "textures/heightmap.png", {width: 20, height: 20, subdivisions: 100, onReady: (readyMesh) => {
 //Simplify mesh here
 readyMesh.simplify([{quality: 0.1, distance: 10}]);
 ...
}}, scene);
```

<Playground id="#P2J3R8" title="Simplify ground mesh" description="Create ground mesh from heightmap and simplify it."/>

## Mesh optimization (Starting with Babylon.js 2.1)

Due to the nature of Babylon's file format, it is possible that many vertices will have the same positions, normals, but different color/uv information. This presents a problem to the decimation process, which relies on having all triangles with the same position altered.

If you try simplifying a mesh, and it suddenly lacks a few triangles, this will be the reason - your mesh is not "optimized" for simplification.

There are two types of optimization available:

1. Global altering function, which is a part of BABYLON.Mesh:

```javascript
mesh.optimizeIndices(function () {
 //do whatever you want here
});
```

This option alters(!) the mesh's indices order. It is faster, but might change the UV coordinates of vertices of the mesh. If that is the case, use:

2. Optimization during simplification - The Simplification Settings now includes a new variable: optimizeMesh, which is a boolean that defaults to false. If set to true, a non-altering mesh optimization will run during the mesh's preparation for decimation. The simplification will run on a temporary array of vertices and will correlate the new vertices' positions with the old uv/color information. This is the better option, but also the slower option (will be noticeable with very large meshes like the demo skull) <Playground id="#2JBSNA#4" title="Optimization During Simplification Example" description="Simple example of optimizing while simplifying."/>

Check which one of the methods works best for you. Both have their up and down sides, for better results use the 2nd option (set optimizeMesh to true in the settings).

## Developing further simplification algorithms

If you want to add a new simplification algorithm, there are a few steps that are required:

1. Create a class that implements the BABYLON.ISimplifier interface (and of course implement the function! :-) )
2. Add the type of simplification to the SimplificationType enum
3. Add the class init in the mesh.simplify function (the inner function "getSimplifier" should contain your type).
4. We'd love to see a PR with your new simplification!

## Accessing the simplification class directly

You can access the quadratic error decimation directly and play with its features. You can do that by creating an object of the class QuadraticErrorSimplification

```javascript
const decimator = new QuadraticErrorSimplification(meshToDecimate);
```

Afterwards you can play with the following object variables:

1. decimationIterations - max number of iterations of the decimation process. The simplification will (usually) stop before the max number of iterations, but it actually all depends on the next variable. Default: 100.
2. aggressiveness - The threshold that decides if a triangle is up for a deletion is decided using this variable. Setting it to a low value (2, for example) will cause the decimation to be a little slower, but more percise in selecting the triangles. Setting it to a high value (15 for example) will probably cause the decimation to end in 1 or 2 iterations, since a lot of triangles will be chosen for deletion. Anyhow, once the quality is reached, the process stops. The question - did it choose the better triangles to decimate! Default: 7.
3. syncIterations - the number of synchronous iterations inside the async iterations. Rather hard to explain, but a lower number will hurt the performance less but will make the process take a bit more time. If you need explanations look at the AsyncLoop class in babylon.tools.js or contact @raananw at the forum.
 After setting the variables, you can run the simplify function that will start the entire process:

```javascript
simplify(settings, successCallback);
```

See the explanation above to understand what each variable is.

## How To Use TrailMesh

`TrailMesh` creates a new `Mesh` that trails another.

```javascript
const newTrail = new BABYLON.TrailMesh(name, generator, scene, diameter, length, autoStart);

newTrail.start(); //Starts the trailing mesh.
newTrail.stop(); //Stops the trailing mesh.
```

| variable | description |
| -------------------- | ------------------------------------------------------- |
| name | The value used by scene.getMeshByName() to do a lookup. |
| generator | The mesh to generate a trail. |
| scene | The scene to add this mesh to. |
| diameter (optional) | Diameter of trailing mesh. Default is 1. |
| length (optional) | Length of trailing mesh. Default is 60. |
| autoStart (optional) | Automatically start trailing mesh. Default true. |

TrailMesh will be affected by all modifications to the generator mesh. Using `bakeCurrentTransformIntoVertices` on the generator after scaling (and before a position shift) will prevent the TrailMesh from scaling.

## Example Usage

```javascript
let alpha = Math.PI;
// Create a mesh for the trail to follow.
const cube = BABYLON.MeshBuilder.CreateBox("cube", {}, scene);
cube.scaling.y = 2;
cube.bakeCurrentTransformIntoVertices();
cube.position.x = Math.sin(alpha) * 10;
cube.position.z = Math.cos(alpha) * 10;
cube.computeWorldMatrix(true);

const trail = new BABYLON.TrailMesh("new", cube, scene, 0.5, 60, true);

const sourceMat = new BABYLON.StandardMaterial("sourceMat", scene);
sourceMat.emissiveColor = sourceMat.diffuseColor = new BABYLON.Color3.Red();
sourceMat.specularColor = new BABYLON.Color3.Black();

trail.material = sourceMat;

const observer = scene.onBeforeRenderObservable.add(animate);
function animate() {
 alpha += Math.PI / 120;
 cube.position.x = Math.sin(alpha) * 10;
 cube.position.z = Math.cos(alpha) * 10;
 cube.rotation.x = (Math.PI * alpha) / 2;
 cube.rotation.y = alpha;
}
```

## Examples

- <Playground id="#1F4UET#33" title="Glowing orbs with trail" description="Simple example of using trailmesh in your scene."/>


## Transformations
Transformations are the actions that change an object's position, rotation and scale. Although this section largely covers transformations applied to meshes some can also apply to other Babylon.js objects.

Applying transformations can seem straightforward and in many cases they are, such as changing position. Others aspects may appear easy but in practice can be difficult either in concept, execution or both. In 3D something as simple as a rotation can prove tricky, once you have rotated a mesh about x and y then its z axis may not be where you think it should be since a mesh's local frame of reference rotates with it.

Frames of reference, in 3D, are formed by an origin and three mutually perpendicular axes through the origin. When created in Babylon.js objects are placed using a frame of reference in **World Space** where there are two horizontal axes, x and z, and a vertical y axis in a left handed system.

Each mesh also has its own **Local Space**.  Meshes built within Babylon.js are created with their local space origin at the world space origin and with their local space axes x, y and z aligned with the x, y and z axes of the world space. The local origin acts as the center of transformation unless pivots or parents are added to the mesh. Both of these cases will be described.

Meshes created in other packages and imported may use different frames of reference.




## UtilityLayerRenderer

The UtilityLayerRenderer class overlays objects in a scene without modifying the existing scene. It can be used to enable custom overlays or [Gizmos](/features/featuresDeepDive/mesh/gizmo).

Default utilityLayerRenderers are available with the following

```javascript
UtilityLayerRenderer.DefaultUtilityLayer; // for overlays like position/scale gizmos
UtilityLayerRenderer.DefaultKeepDepthUtilityLayer; // for occluded gizmos like bounding box)
```

but utility layers can be created manually with the following

```javascript
const utilLayer = new BABYLON.UtilityLayerRenderer(scene);
```

The UtilityLayerRenderer contains references to both the utility layer's scene as well as the original scene.

```javascript
utilLayer.originalScene;
utilLayer.utilityLayerScene;
```

Once created meshes can be added to the utility layer's scene

```javascript
// Create an overlay box
const overlayBox = BABYLON.MeshBuilder.CreateBox("box", { size: 1 }, utilLayer.utilityLayerScene);
overlayBox.position.z = 0.5;
overlayBox.position.y = 3.5;
// Create a different light for the overlay scene
const overlayLight = new BABYLON.HemisphericLight("light1", new BABYLON.Vector3(0, 0, 1), utilLayer.utilityLayerScene);
overlayLight.intensity = 0.7;
```

## Controls

By default, the overlaid scene will be drawn on top of the existing scene ignoring the depth buffer. Of objects in the utility scene are desired to be occluded by the main scene, autoClearDepthAndStencil should be set to false

```javascript
utilLayer.utilityLayerScene.autoClearDepthAndStencil = false;
```

Note: When this is set to false, transparent meshes will always be occluded by objects drawn to the utility layer
By default, the utility layer's scene will be drawn following every draw of the original scene. To disable this behavior, the shouldRender property can be set to false. If set to false, the utility layer can be rendered manually via the render function.

```javascript
utilLayer.shouldRender = false;
utilLayer.render();
```

## Pointer events

Since the utility layer is rendered on top of the existing scene there are a couple options to control how pointer interactions with the scenes work.
By default, the utility layer fires the pointerUp, pointerDown and pointerMove events as usual but pointer down events are only passed to the utility layer's scene if the pointer event contacts it first.

To disable other events if the pointer event does not contact the utility layer first, the following can be used.

```javascript
utilLayer.onlyCheckPointerDownEvents = false;
```

To enable all events beyond up, down and move (eg. mouse wheel). processAllEvents can be set.

```javascript
utilLayer.processAllEvents = true;
```

The UtilityLayerRenderer fires an onPointerOutObservable event when the pointer leaves the utility layer back to the original scene.

```javascript
utilLayer.onPointerOutObservable.add(function (pointerId) {});
```

# Examples

- <Playground id="#DEYAQ5#41" title="Overlay Scene Example" description="Simple example of an overlay,"/>
- <Playground id="#31M2AP#9" title="Gizmo Example" description="Simple example of the gizmo,"/>

## The MeshDebugPluginMaterial
Visualizing certain properties of a mesh can often be tricky.
The MeshDebugPluginMaterial, one of the [material plugins](features/featuresDeepDive/materials/using/materialPlugins) available in the Babylon library, can be used to aid in debugging these properties.

The plugin currently offers 7 modes, which are detailed below.

## Triangles Mode
The `TRIANGLES` visualization of the MeshDebugPluginMaterial allows you to see the underlying mesh's wireframe. 
![TRIANGLES mode](/img/features/meshDebug/mdpmTriangles.png)

### How To Use
Before applying the plugin, first call the static function `PrepareMeshForTrianglesAndVerticesMode` on the mesh. Then create the MeshDebugPluginMaterial with the `mode` option set to `MeshDebugMode.TRIANGLES`

You can customize the wireframe's thickness and color with the options below
* `wireframeTrianglesColor`: _(Color3)_ the color of the wireframe
* `wireframeThickness`: _(number)_ the thickness of the wireframe's edges

#### Example
```javascript
BABYLON.MeshDebugPluginMaterial.PrepareMeshForTrianglesAndVerticesMode(mesh);

new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: BABYLON.MeshDebugMode.TRIANGLES,
 wireframeTrianglesColor: new BABYLON.Color3(0, 0, 0),
 wireframeThickness: 0.7
});
```

**NOTE** _Behind-the-scenes, `PrepareMeshForTrianglesAndVerticesMode` is tripling the number of triangles and vertices in the mesh's vertex buffers. This is necessary for the plugin's shaders to work correctly. You can undo these changes to the mesh via the [rollback function](/typedoc/classes/BABYLON.MeshDebugPluginMaterial#PrepareMeshForTrianglesAndVerticesMode) returned by the method._

Playground example: <Playground id="#KPLZWF" title="Triangles" description="Applying TRIANGLES to a model."/>

## Vertices Mode
The plugin's `VERTICES` mode draws dots over all vertices of the mesh, as shown below.
![VERTICES mode](/img/features/meshDebug/mdpmVertices.png)

### How To Use
This mode works similar to `TRIANGLES`. Call the static function `PrepareMeshForTrianglesAndVerticesMode` on the mesh first, then apply the plugin.

Customization options include
* `vertexColor`: _(Color3)_ the color of the vertex dots
* `vertexRadius`: _(number)_ the radius of the vertex dots

#### Example
```javascript
BABYLON.MeshDebugPluginMaterial.PrepareMeshForTrianglesAndVerticesMode(mesh);

new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: BABYLON.MeshDebugMode.TRIANGLES,
 vertexColor: new BABYLON.Color3(0, 0, 0),
 vertexRadius: 1.2
});
```

## Triangles-Vertices Mode
If you'd like to see both the mesh's wireframe and vertex dots, use the `TRIANGLES_VERTICES` mode of the plugin.
![TRIANGLES_VERTICES mode](/img/features/meshDebug/mdpmTrianglesVertices.png)

### How To Use
Just like both `TRIANGLES` and `VERTICES` modes, use `PrepareMeshForTrianglesAndVerticesMode` on the mesh, then apply the plugin.

The same options available to `TRIANGLES` and `VERTICES` modes also apply to `TRIANGLES_VERTICES`, with one exception. Below, note that `wireframeTrianglesColor` is replaced by `wireframeVerticesColor`. 
* `vertexColor`: _(Color3)_ the color of the vertex dots
* `vertexRadius`: _(number)_ the radius of the vertex dots
* `wireframeVerticesColor`: _(Color3)_ the color of the wireframe
* `wireframeThickness`: _(number)_ the thickness of the wireframe's edges in screen space

#### Example
```javascript
BABYLON.MeshDebugPluginMaterial.PrepareMeshForTrianglesAndVerticesMode(mesh);

new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: BABYLON.MeshDebugMode.TRIANGLES_VERTICES,
 wireframeVerticesColor: new BABYLON.Color3(0.8, 0.8, 0.8),
 wireframeThickness: 0.7,
 vertexColor: new BABYLON.Color3(0, 0, 0),
 vertexRadius: 1.2
});
```

## UV0 and UV1 Modes
These modes can help visualize a mesh's UVs with a basic checkerboard grid.
![UV0 mode](/img/features/meshDebug/mdpmUV0.png)

### How To Use
Simply set the plugin mode to `UV0` or `UV1`, depending on which UV set you'd like to see.

You can customize the primary and secondary color of the checkerboard grid via
* `uvPrimaryColor`: _(Color3)_ the first color used in the checkerboard grid
* `uvSecondaryColor`: _(Color3)_ the second color used in the checkerboard grid
* `uvScale`: _(number)_ the number of squares along one axis of the grid

#### Example
```javascript
new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: BABYLON.MeshDebugMode.UV0,
 uvPrimaryColor: new BABYLON.Color3(1, 1, 1),
 uvSecondaryColor: new BABYLON.Color3(0.5, 0.5, 0.5),
 uvScale: 20
});
```

## Vertex Colors Mode
The `VERTEXCOLORS` mode can be used to better see a mesh's vertex colors.
![VERTEXCOLORS mode](/img/features/meshDebug/mdpmVertexColors.png)

### How To Use
Set the plugin's mode to `VERTEXCOLORS`. For best results, also set the `multiply` option to `false`.

#### Example
```javascript
new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: BABYLON.MeshDebugMode.VERTEXCOLORS,
 multiply: false
});
```

**NOTE** _By default, the plugin multiplies the mode's color against the material's final color underneath. We should disable this behavior here to get the real color of each vertex._
**NOTE** _Under-the-hood, disabling `multiply` when on `VERTEXCOLORS` mode will also disable lighting effects on the model. See [The multiply option](toolsAndResources/utilities/VisualizeMeshData#the-multiply-option) section for more details._

## Material IDs Mode
The `MATERIALIDS` mode provides a visual way of distinguishing different materials from one another.
![MATERIALIDS mode](/img/features/meshDebug/mdpmMaterialIds.png)

### How To Use
Set the plugin's mode to `MATERIALIDS` across all materials. You may also want to toggle off the `multiply` option to better see the ID colors.

The MeshDebugPluginMaterial comes with a default color palette for `MATERIALIDS`. To use a custom color palette, you can directly replace the plugin's [static palette](typedoc/classes/BABYLON.MeshDebugPluginMaterial#MaterialColors) with your own before applying the plugin, like in the following snippet.

#### Example
```javascript
BABYLON.MeshDebugPluginMaterial.Reset();

BABYLON.MeshDebugPluginMaterial.MaterialColors = [
 new BABYLON.Color3(1,0,0),
 new BABYLON.Color3(0,1,0),
 new BABYLON.Color3(0,0,1)
];

new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: BABYLON.MeshDebugMode.MATERIALIDS,
 multiply: false
});
```

**NOTE** _If you'd like ID colors to be consistent across runs, call the static function [`MeshDebugPluginMaterial.Reset()`](/typedoc/classes/BABYLON.MeshDebugPluginMaterial#Reset) before applying the modes. This resets all static variables of the MeshDebugPluginMaterial class, including the counting mechanism for material IDs._

Playground example: <Playground id="#RZPC9Q" title="Material IDs" description="Applying MATERIALIDS to a model."/>

## The Multiply Option
The `MeshDebugPluginMaterial` features an option, `multiply`, that determines if the plugin's visualization colors should be multiplied against the material's final color. This option is set to `true` by default, but what happens if you set it to `false`?

If set to false, the plugin will replace the material's final color with its own, built-in visual (unless the plugin is in `VERTEXCOLORS`). This default shading looks as follows:

![Default Shading](/img/features/meshDebug/mdpmNone.png)

The visual is based off a Phong lighting model and treats the active camera the a light source. 
You can customize the default shading's appearance with a few options.
* `shadedDiffuseColor`: _(Color3)_ the diffuse color of the default shading
* `shadedSpecularColor`: _(Color3)_ the specular color of the default shading
* `shadedSpecularPower`: _(number)_ the strength of the default shading's specularity

### Example
```javascript
new BABYLON.MeshDebugPluginMaterial(mesh.material, {
 mode: // any mode
 multiply: false,
 shadedDiffuseColor: new BABYLON.Color3(1, 1, 1),
 shadedSpecularColor: new BABYLON.Color3(.8, .8, .8),
 shadedSpecularPower: 10
});
```

See the difference: <Playground id="#U9UKR8" title="Default Shading" description="Example showcasing the default shading of the plugin material."/>

## Notes on Usage
The mesh must have a material assigned to it in order for the MeshDebugPluginMaterial to work as expected. You might consider adding logic to your program that assigns new PBRMaterials to meshes without any material.

Also, all material plugins must be added to materials _before_ they are used for rendering. There are a few techniques to do this, including
- Importing the mesh asynchronously, then adding the plugin to the materials of the result
- Using an observable like `scene.onNewMaterialAddedObservable`
- Using an `AssetContainer` to modify the materials before adding them to the scene
- Creating a new material, applying the plugin to the new material, then assigning the new material to the mesh

## API
See the full list of available properties, options, methods, and more [here](/typedoc/classes/BABYLON.MeshDebugPluginMaterial).


## Meshes

In the 3D virtual world shapes are built from meshes, lots of triangular facets joined together, each facet made from three vertices.

![A mesh](/img/features/scene/custom1.jpg)

Babylon.js provides for the creation of predefined meshes, of your own custom meshes and for importing meshes created by 3D design software. For all meshes the underlying data structure is exposed and can be updated.


Pretty much every 3D programmer runs into depth buffer issues sooner or later. 
This is especially true when creating outer-space scenes where object distances can be in light years.

In such cases, the linear depth buffer (the default) can generate glitches when distances start reaching big numbers. 
In short, the depth values are proportional to the reciprocal of Z. This gives good precision near the camera, but a little off in the distance.

You can read an interesting analysis by Brano Kemen on this blog: http://www.gamasutra.com/blogs/BranoKemen/20090812/85207/Logarithmic_Depth_Buffer.php

To help with this issue, you may want to use a better Z-value distribution: the logarithmic depth buffer where Z = log(C*z + 1) / log(C*Far + 1) * w

StandardMaterials can enable the logarithmic depth buffer if the browser supports *GL_EXT_frag_depth* extension.

To enable it, just use this code:
```
material.useLogarithmicDepth = true;
```

If the extension is not supported, Babylon.js will revert to linear depth buffering.


Meshes

Meshes

Coming next

Facet Data

Learn all about facet data in Babylon.js.

Gizmos

Learn about gizmos in Babylon.js.

Creating Meshes

Learn about the different processes of creating meshes in Babylon.js.

Mesh Transformations

Learn all about mesh transformations in Babylon.js.

Copies, Clones, and Instancing

Learn all about copies, clones, and instances in Babylon.js.

Interactions

Learn how interactions work in Babylon.js.

Node Geometry

Learn how use the NodeGeometry class

Drawing Bounding Boxes

Learn how to draw bounding boxes in Babylon.js.

BillBoard Mode

Learn how use Mesh BillBoard Mode.

Decals

Learn how use decals in Babylon.js.

Highlighting Meshes

Learn how to highlight meshes in Babylon.js.

Making Meshes Glow

Learn all about the glow layer in Babylon.js.

Merging Meshes

Learn how to merge meshes in Babylon.js.

Drawing Curves

Learn how to draw curves in Babylon.js.

Path3D

Learn how to use Path3D in Babylon.js.

Levels of Detail (LOD)

Learn the integrated LOD system in Babylon.js.

Dynamically Morph A Mesh

Learn how to dynamically morph a mesh in Babylon.js.

Morph Targets

Learn all about morph targets in Babylon.js.

Bones and Skeletons

Learn all about bones and skeletons in Babylon.js.

Rendering Utility Layers

Learn how to render utility layers in Babylon.js.

Simplifying Meshes With Auto-LOD

Learn how to use the Auto-LOD system in Babylon.js.

Rendering Edges

Learn all about the edge renderer in Babylon.js.

Trail Mesh

Learn how to draw a trail mesh in Babylon.js.

Exploding Meshes

Learn how to explode meshes in Babylon.js.

Visualizing Mesh Data

Overview of using the MeshDebugPluginMaterial to visually debug model data.