
# 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.webp)

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);
```

`enableEdgesRendering` can be called with a custom epsilon (the default value is 0.95).

```javascript
box.enableEdgesRendering(0.9999);
```

The dot product is the cosine of the angle between the vectors, so for the default epsilon of 0.95 the angle is acos(.95) ~= 18 degrees. If the angle between two faces is less than that, no line is 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 affect 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.webp)

<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 edge renderers are rendering on top of the front, partially transparent mesh. That happens because edge rendering occurs after all other steps in the scene, even after 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 object's rendering group id to a higher value than the meshes with the edge renderer:

![Solution 1](/img/features/edgesRenderer/edgesRenderer2.webp)

And another is to set `forceDepthWrite = true` on the transparent material:

![Solution 2](/img/features/edgesRenderer/edgesRenderer3.webp)

Note that in this case, the edges renderer won't show up behind the transparent mesh.



## How To Use TrailMesh

`TrailMesh` creates a new `Mesh` that trails another.

```javascript
let options = {
    diameter: 1.5,
    length: 100,
    segments: 10,
    sections: 4,
    doNotTaper: false,
    autoStart: true
};
const trail = new BABYLON.TrailMesh(name, generator, scene, options);

trail.start(); // Starts the trailing mesh.
trail.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.                          |
| options              | The object containing trail parameters.                 |



There are a variety of parameters you can set to create different types of trails to suit your needs. If you do not specify `segments`, it will default to the `length` of the trail; i.e., a trail with a length of 60 will have 60 segments.

| options property     | value                                               | default value |
| -------------------- | --------------------------------------------------- |---------------|
| diameter (optional)  | _(number)_ Diameter of trailing mesh.                 | 1             |
| length (optional)    | _(number)_ Length of trailing mesh.                   | 60            |
| segments (optional)  | _(number)_ Segments of trailing mesh.                 | length        |
| sections (optional)  | _(number)_ Cross-section of trailing mesh. Min 2.     | 4             |
| doNoTaper (optional) | _(boolean)_ Whether the trail should taper.           | false         |
| autoStart (optional) | _(boolean)_ Automatically starts the trailing mesh.   | 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.

## Resetting the TrailMesh

As of 7.21.0, you can now reset the `TrailMesh` via `trail.reset()`. Use this in conjunction with `trail.stop()` and `trail.start()`. This is ideal when the trail appears distorted because of sudden, large changes in the generator position, for example when firing and reloading projectile meshes.

## 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);

// Trail options
let options = {
    diameter: 1.5,
    length: 100,
    segments: 10,
    sections: 4,
    doNotTaper: false,
    autoStart: true
};
const trail = new BABYLON.TrailMesh("new", cube, scene, options);

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."/>

- <Playground id="#1640Q5#1" title="Trailmesh vfx" description="An example of adding vfx using the trailmesh."/>



## 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, reducing the number of displayed faces increases 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 in-browser simplification functionality that works asynchronously while trying not to disturb the rendering process. These LOD levels are automatically added to the scene after the calculation finishes.

## 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 asynchronously. The `parallelProcessing` flag sets the processing order for each level. If set to `true`, all levels run together. This uses more RAM for a period of time, but generally runs faster. There is a chance, however, that FPS will be reduced to an unacceptable level because of many parallel calculations between frames. Setting this flag to `false` processes one setting after another. This uses only a single simplification object and less RAM, but it can take a little longer.

- **Type**

To allow additional types of simplification to be implemented, the type of simplification should be specified. 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 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.ImportMeshAsync("./DanceMoves.babylon", scene).then((result) => {
  result.meshes[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 using 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 independently 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 should be simplified. More precisely, all meshes can be simplified, but some should not be.

An object like a Box, if built in an optimal way such as with `BABYLON.MeshBuilder.CreateBox`, has no "extra faces" that can be removed. Removing a 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, and so on. The more factors, the slower it runs because of the extra calculations. The decision was made to use position only. This means that after simplification, the UV coordinates may 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 index order. It is faster, but it might change the UV coordinates of the mesh vertices. If that is the case, use:

2. Optimization during simplification - The Simplification Settings now include a new variable, `optimizeMesh`, which is a boolean that defaults to `false`. If set to `true`, a non-altering mesh optimization runs during the mesh's preparation for decimation. The simplification runs on a temporary array of vertices and correlates the new vertex positions with the old UV/color information. This is the better option, but also the slower one, which 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 method works best for you. Both have their upsides and downsides. For better results, use the second option by setting `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 initialization 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 quadratic error decimation directly and experiment with its features by creating an object of the `QuadraticErrorSimplification` class.

```javascript
const decimator = new QuadraticErrorSimplification(meshToDecimate);
```

Afterwards you can play with the following object variables:

1. decimationIterations - maximum number of iterations of the decimation process. The simplification usually stops before the maximum number of iterations, but it depends on the next variable. Default: 100.
2. aggressiveness - The threshold that decides whether a triangle is a candidate for deletion is controlled by this variable. Setting it to a low value, such as 2, makes decimation a little slower but more precise in selecting triangles. Setting it to a high value, such as 15, will probably cause decimation to end in 1 or 2 iterations, since many triangles will be chosen for deletion. In any case, once the quality is reached, the process stops. The question is whether it chose the best 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.


Rendering Edges

How to use it

EdgesRenderer and Transparent meshes