
## Ribbon
The ribbon is a very versatile shape. Picture a ribbon in the real world with parallel wires running down its length. You can turn such a ribbon into a wide variety of shapes. By joining one long edge to its opposite, you could form a tube and bend it into different shapes. This and more is possible with a Babylon.js ribbon. Instead of parallel wires, a Babylon.js ribbon is formed from paths defined by an array of vector3s, and how you define the paths determines the final shape. 

On creation, the local origin of a ribbon is coincident with the world origin. It is not possible to give a position relative to the constructed shape, as this depends on the data sets used.

## MeshBuilder
Usage :

```javascript
const options = {
    pathArray: myPaths, //[vector3 array, vector3 array, vector3 array......]
    updatable: true
}

let ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", options, scene); //scene is optional and defaults to the current scene

options.pathArray: myNewPaths; //The length must equal the length of myPaths and myNewPaths[i].length === myPaths[i] for all i
options.instance = true;

// updates the existing instance of ribbon : no need for the parameter scene
ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myNewPath, instance: ribbon});
```

option|value|default value
--------|-----|-------------
pathArray|_(Vector3[][])_  array of array of Vector3, the array of paths **REQUIRED**
closeArray|_(boolean)_  to force the ribbon to join its last and first paths|false
closePath|_(boolean)_  to force each ribbon path to join its last and first points|false
offset|_(number)_  used if the pathArray has one path only|half the path length
updatable|_(boolean)_ true if the mesh is updatable|false
sideOrientation|_(number)_ side orientation|DEFAULTSIDE
frontUVs|_(Vector4)_  **ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option** | Vector4(0,0, 1,1) 
backUVs|_(Vector4)_  **ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option** | Vector4(0,0, 1,1) 
instance|_(LineMesh)_ an instance of a ribbon to be updated|null
invertUV|_(boolean)_ to swap the U and V coordinates at geometry construction time (texture rotation of 90°)|false

### Examples

Update of a ribbon: <Playground id="#F6JW5W#5" title="Updating a Ribbon" description="Simple example of updating a ribbon."/>

double sided ribbon not updatable: <Playground id="#F6JW5W#6" title="Create a Non Updatable Double Sided Ribbon" description="Simple example of creating a non updatable double sided ribbon."/>
double sided ribbon not updatable path lines in red: <Playground id="#F6JW5W#7" title="Create a Non Updatable Double Sided Ribbon With Red Path Lines" description="Simple example of creating a non updatable double sided ribbon with red path lines."/>  
open ribbon: <Playground id="#F6JW5W#8" title="Create An Open Ribbon" description="Simple example of creating an open ribbon."/>
with closePath true: <Playground id="#F6JW5W#9" title="Create a Ribbon with closePath = True" description="Simple example of creating a ribbon with closePath set to true."/> 
with closeArray true: <Playground id="#F6JW5W#10" title="Create a Ribbon with closeArray = True" description="Simple example of creating a ribbon with closeArray set to true."/> 


## Mesh
Usage: 
```javascript
const ribbon = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, closeArray, closePath, offset, scene);
const ribbon = BABYLON.Mesh.CreateRibbon("ribbon", pathArray, closeArray, closePath, offset, scene, updatable, sideOrientation, instance); //optional parameters after scene
```

More about ribbons on the next page.


## Ribbon in Detail

Let's take a closer look at a ribbon.

It is formed using paths. A path is simply an array of a minimum of two vector3 points.

The image below shows the construction of a ribbon using two paths, A and B, each having five points.

![Ribbon](/img/how_to/ribbon/ribbon.webp)

Here's a simple example:

<Playground id="#MZ7QRG#1194" title="Simple Ribbon Example" description="Simple ribbon example."/>

You can have as many paths as you wish, including just one. You can close all the paths and/or close the paths array itself. Imagine a long, narrow ribbon in the real world with wire running down its length. Closing the paths forms a loop of ribbon, while closing the array forms a tube.

## Single Path Ribbon

First construct the single path, for example

```javascript
pathHelix = [];
let v;
for (let i = 0; i <= 60; i++) {
  v = (2.0 * Math.PI * i) / 20;
  pathHelix.push(new BABYLON.Vector3(3 * Math.cos(v), i / 4, 3 * Math.sin(v)));
}
```

Showing the path: <Playground id="#F6JW5W#12" title="Showing Ribbon Path" description="Simple example of showing ribbon path."/>

The ribbon is formed by joining each point on the path to a later point where one exists. The _offset_ property governs how many points ahead the current point will be joined to. The triangular facets for the mesh are formed from the current point, the next point, and the offset point.

For point _p_ and offset _f_, the triangle is _p_, _p + 1_, _p + f_, provided, of course, that _p + f &lt; number of points in the path array_.

Create the ribbon with a variety of offsets and show in wireframe  
default offset, half the path length (60 / 2 = 30): <Playground id="#F6JW5W#13" title="Create a Ribbon Example 1" description="Simple example of creating a ribbon with varying properties."/>
offset 10: <Playground id="#F6JW5W#14" title="Create a Ribbon Example 2" description="Simple example of creating a ribbon with varying properties."/>
offset 5: <Playground id="#F6JW5W#15" title="Create a Ribbon Example 3" description="Simple example of creating a ribbon with varying properties."/>
offset 20: <Playground id="#F6JW5W#16" title="Create a Ribbon Example 4" description="Simple example of creating a ribbon with varying properties."/>

So playing with _offset_, _closeArray_, or other parameters, you can easily get volumes, even with a single path: <Playground id="#F6JW5W#17" title="Create a Ribbon Example 5" description="Simple example of creating a ribbon with varying properties."/>

## Length of Paths

It's not mandatory that all the ribbon paths have the same length, but it is not recommended.  
The best way to emulate different lengths for some parts of your mesh is simply to use many ribbons.

In this example: <Playground id="#88AZQ#16" title="Create a Ribbon With Path Lengths" description="Simple example of creating a ribbon using path lengths."/>
_path2_ and _path3_ are longer than _path1_ and _path4_.

As you can see, the final ribbon adjusts to different lengths. The rule is that they all start from the first path points, and each intermediate ribbon then stops at the first end reached by either of its two constituent paths. However, while you can add color using a material, as done here: <Playground id="#88AZQ#17" title="Create a Colored Ribbon" description="Simple example of creating a colored ribbon."/>

There is no effect on light reflection for a ribbon with different-length paths.
Therefore you **can't add a texture** to a ribbon constructed with different length paths.  
This is due to the fact that the nested ribbon texturing algorithm only knows how to deal with a unique length for all paths.
When applying a texture, the algorithm assumes that the ribbon can be unfolded into a rectangle that can be stretched to fit on top of the image used for the texture.
This is only possible when paths are of equal length.

## Closed shapes : normals or textures ?

The ribbon mesh provides two ways to automatically close an unclosed shape.

- _closeArray_ parameter : this will add an extra unit ribbon between the last path and the first path of your _pathArray_.
- _closePath_ parameter : this will join the last and first points of each _path_ in your _pathArray_.

<Playground id="#3XMWZ#44" title="Start With An Unclosed Ribbon" description="Simple example of creating an unclosed ribbon."/>

```javascript
var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", { pathArray: paths }, scene);
```

<Playground id="#3XMWZ#45" title="Ribbon With CloseArray" description="Simple example of creating a ribbon With CloseArray set to true."/>

```javascript
var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", { pathArray: paths, closeArray: true }, scene);
```

<Playground id="#3XMWZ#49" title="Textured Ribbon" description="Simple example of creating a textured ribbon."/>

Notice that the texture isn't stretched on the surface added by the automatic closing but applied independently.
The reason for this behavior is that, with ribbon _closeXXX_ parameters, priority is given to the normals (the tools that compute light reflection) over textures.
If you don't care about continuous light reflection but you do want your texture to be stretched along the whole surface,
you just have to forget automatic closing and close the ribbon yourself. A simple way to do this is to push the first _path_ again at the end of the _pathArray_.

<Playground id="#3XMWZ#50" title="Closed Textured Ribbon" description="Simple example of creating a closed textured ribbon."/>

```javascript
paths.push(paths[0]);
var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", { pathArray: paths }, scene);
```

The same rules and workarounds apply to the _closePath_ parameter.

<Playground id="#3XMWZ#52" title="Ribbon With ClosePath" description="Simple example of creating a ribbon with closePath set to true."/>

<Playground id="#3XMWZ#51" title="Textured Ribbon With ClosePath" description="Simple example of creating a textured ribbon with closePath set to true."/>



## GreasedLineRibbon

You can use all the features of `GreasedLine` except `sizeAttenuation`, which does not make sense in non-camera-facing mode. `GreasedLineRibbon` creates ribbon-like geometry for the lines. To create a `GreasedLineRibbon`, add the `ribbonOptions` property to `GreasedLineMeshBuilderOptions` when using the `CreateGreasedLine` builder function, or to `GreasedLineMeshOptions` when creating the `GreasedLineRibbon` manually.

## Create a GreasedLineRibbon

The easiest and recommended way to create a `GreasedLineRibbon` is to use the `CreateGreasedLine` function:

```javascript
function CreateGreasedLine(name: string, options: GreasedLineMeshBuilderOptions, materialOptions?: Nullable<GreasedLineMaterialBuilderOptions>, scene?: Nullable<Scene>)
```

The simplest usage is:

```javascript
const line = BABYLON.CreateGreasedLine("name", { points, ribbonOptions: { } })
```

<Playground id="#P8NDK0#2" title="Basic usage" description="Basic scenarios with GreasedLineRibbon." />

### GreasedLineMeshBuilderOptions.ribbonOptions

If `ribbonOptions` is present, a non-camera-facing ribbon-like mesh will be created. It is an instance of the `GreasedLineRibbon` class. If you do not want to change the default values, it is enough to pass an empty object as shown previously.

```javascript
pointsMode: GreasedLineRibbonPointsMode;
direction: Vector3;
directionsAutoMode?: GreasedLineRibbonAutoDirectionMode;
width: number;
facesMode?: GreasedLineRibbonFacesMode;
closePath?: boolean;
smoothShading?: boolean;
```

The default values are:

```javascript
pointsMode = GreasedLineRibbonPointsMode.POINTS_MODE_POINTS;
direction = Vector3.UpReadOnly;
directionsAutoMode: GreasedLineRibbonAutoDirectionMode.AUTO_DIRECTIONS_NONE;
width = GreasedLineMaterialDefaults.DEFAULT_WIDTH; // 0.1
facesMode = GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED;
closePath = false;
smoothShading = false;
```

*If you are creating the `GreasedLineRibbonMesh` manually, you must set all the values yourself. In addition, you have to set the `cameraFacing` option to `false` in `GreasedLineMaterialOptions` when creating the material manually.*

#### **pointsMode**

There are two point modes available:

```javascript
POINTS_MODE_POINTS = 0,
POINTS_MODE_PATHS = 1,
```

In `GreasedLineRibbonPointsMode.POINTS_MODE_POINTS` every array of points will become the center (backbone) of the ribbon. The ribbon will be expanded by `width / 2` to `+direction` and `-direction` as well.

In `GreasedLineRibbonPointsMode.POINTS_MODE_PATHS` every array of points is one path. These will be used to build one ribbon.

Let's demonstrate both point modes. The gray mesh is the line ribbon itself and the white line is the center (backbone) of it:

<Playground id="#SS1UUI#30" title="Point mode POINTS_MODE_POINTS" description="Shows how POINTS_MODE_POINTS works." />

The gray mesh is the line ribbon itself and the white lines are the paths which the line ribbon is built between:

<Playground id="#SS1UUI#31" title="Point mode POINTS_MODE_PATHS" description="Shows how POINTS_MODE_PATHS works." />

A simple space track created using `POINTS_MODE_PATHS`. The red debug lines show the paths. Track colors are created using a manually created texture. The red lines show the paths that define the edges of the ribbon.

<Playground id="#TN7XWX#35" title="Path mode" description="A simple space track - uses texture." />

The same space track colored by the `colors` property of the `GreasedLineMaterial`:

<Playground id="#TN7XWX#34" title="Path mode" description="A simple space track - uses colors." />

You can have more than two paths to build line ribbons of custom shapes:

<Playground id="#SS1UUI#32" title="Point mode POINTS_MODE_PATHS with more paths" description="Shows how POINTS_MODE_PATHS works with more than 2 paths." />

#### **direction** and **width**

This property is a normalized direction vector for the slope of the line in `POINTS_MODE_POINTS`. The line ribbon will be expanded to `+direction` and `-direction` from the center line defined by `points` by a value of `width / 2`.

You can change the default width by modifying the value of the static property `GreasedLineRibbonMesh.DEFAULT_WIDTH`. This will not affect existing line ribbons.

The `widths` option on `GreasedLineMaterialBuilderOptions` is not supported in `POINTS_MODE_PATHS` because in this mode you define the edges of the ribbon and not the center line.

#### **directionsAutoMode**

`AUTO_DIRECTIONS_FROM_FIRST_SEGMENT` sets the direction (slope) of the ribbon from the direction of the first line segment. It is recommended when all the lines are on the same plane.

`AUTO_DIRECTIONS_FROM_ALL_SEGMENTS` calculates the direction (slope) for each line segment according to the direction vector between each point of the line segments. This is a slow method.

`AUTO_DIRECTIONS_ENHANCED` calculates the direction (slope) for each line segment according to the direction vector between each point of the line segments using a more sophisticated algorithm. This is the slowest method.

`AUTO_DIRECTIONS_FACE_TO` calculates the direction (slope) for each line segment according to the direction vector between each point of the line segments and a direction (face-to) vector specified in `direction`. The resulting line will face the direction of this face-to vector.

`AUTO_DIRECTIONS_NONE` requires you to set the direction (slope) manually. It is recommended when you want full control.

<Playground id="#H1LRZ3#522" title="Shows different direction modes" description="Demonstrates all available direction modes." />

#### **facesMode**

```javascript
FACES_MODE_SINGLE_SIDED = 0,
FACES_MODE_SINGLE_SIDED_NO_BACKFACE_CULLING = 1,
FACES_MODE_DOUBLE_SIDED = 2
```

Controls how the faces are created:
In `GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED`, faces are single-sided with back-face culling. This is the default value.
In `GreasedLineRibbonFacesMode.FACES_MODE_SINGLE_SIDED_NO_BACKFACE_CULLING`, faces are single-sided without back-face culling. This sets `backFaceCulling = false` on the material, so it affects all line ribbons added to the line ribbon instance.
In `GreasedLineRibbonFacesMode.FACES_MODE_DOUBLE_SIDED`, extra back faces are created. This doubles the number of faces in the mesh.

<Playground id="#SS1UUI#82" title="Shows different face modes" description="Shows different face modes." />

#### **closePath**

If true, the line will be closed. Works in both `pathMode`s.

<Playground id="#SS1UUI#38" title="Without closing the line ribbon path" description="Without closing the line ribbon path." />
<Playground id="#SS1UUI#37" title="Automatically closing the line ribbon path" description="Automatically closing the line ribbon path." />

#### **smoothShading**

If true, normals will be computed when creating the vertex buffers. This results in smooth shading of the mesh. It does not work when `closePath = true`. `colorMode` must not be `BABYLON.GreasedLineMeshColorMode.COLOR_MODE_SET`, and a light source must be present, of course.

<Playground id="#SS1UUI#35" title="Without smooth shading" description="Without smooth shading." />
<Playground id="#SS1UUI#36" title="With smooth shading" description="With smooth shading." />

## Example playgrounds

<Playground id="#FJRQ8N#138" title="Simple examples" description="A lot of simple examples in one PG." />
<Playground id="#SS1UUI#51" title="Tie drone" description="Shows how to use different options to build a small Imperial Tie drone." />
<Playground id="#SS1UUI#50" title="Tie drones army" description="Flying tie drones from the previous example" />
<Playground id="#H1LRZ3#407" title="Lazy mode" description="Lazy mode line ribbons." />
<Playground id="#H1LRZ3#415" title="Recycle logo" description="Recycle logo comparison. One created using a GreasedLineMesh and the second using GreasedLineRibbonMesh (non-camera-facing version vs camera-facing versions)." />








option	value	default value
pathArray	(Vector3[][]) array of array of Vector3, the array of paths REQUIRED
closeArray	(boolean) to force the ribbon to join its last and first paths	false
closePath	(boolean) to force each ribbon path to join its last and first points	false
offset	(number) used if the pathArray has one path only	half the path length
updatable	(boolean) true if the mesh is updatable	false
sideOrientation	(number) side orientation	DEFAULTSIDE
frontUVs	(Vector4) ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option	Vector4(0,0, 1,1)
backUVs	(Vector4) ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option	Vector4(0,0, 1,1)
instance	(LineMesh) an instance of a ribbon to be updated	null
invertUV	(boolean) to swap the U and V coordinates at geometry construction time (texture rotation of 90°)	false

Creating Ribbons

Ribbon

MeshBuilder

Examples

Mesh