
## Custom Extruded Shapes
A custom extruded shape replaces the _rotation_ and _scale_ options with _rotationFunction_ or _scaleFunction_. These allow you to vary the rotation and scale of the mesh as it extrudes by defining them in terms of a path index or a distance along the path. Since the custom extrusion is based on the Babylon.js ribbon there are two options, *ribbonClosePath* which closes the profile shape and *ribbonCloseArray*, which closes the extrusion path array.

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 = {
    shape: myPoints, //vec3 array with z = 0,
    path: myPath, //vec3 array
    rotationFunction: rotFn,
    scaleFunction: scaleFn,
    updatable: true
}

let extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", options, scene);  //scene is optional and defaults to the current scene

// Update
options.shape = newShape;
options.path = newPath;
options.instance = extruded;
options.rotationFunction = newRotFn;
options.scaleFunction = newScaleFn;
extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", options); //No scene parameter when using instance
```

option|value|default value
--------|-----|-------------
shape|_(Vector3[])_  array of Vector3, the shape you want to extrude **REQUIRED**|
path|_(Vector3[])_  array of Vector3, the extrusion axis **REQUIRED** |
scaleFunction|_( function(i, distance) )_  a function returning a scale value from _(i, distance)_ parameters|{return 1;}
rotationFunction|_( function(i, distance) )_  a function returning a rotation value from _(i, distance)_ parameters|{return 0;}
ribbonClosePath|_(boolean)_ the underlying ribbon _closePath_ parameter value|false
ribbonCloseArray|_(boolean)_ the underlying ribbon _closeArray_ parameter value|false
cap|_(number)_ extrusion cap : NO_CAP, CAP_START, CAP_END, CAP_ALL|NO_CAP
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 an extruded shape to be updated|null
invertUV|_(boolean)_ to swap the U and V coordinates at geometry construction time (texture rotation of 90°)|false

  
You must set at least the _shape_ and _path_ options. On update, you must set the _shape_, _path_ and _instance_ options and you can set the _rotationFunction_ or _scaleFunction_ options.

 The _scaleFunction_  and _rotationFunction_ are called on each path point and require two parameters, _index_ and _distance_.  

* index refers to the path point position in the path array 
* distance is the current point distance from the beginning of the path. 


### Examples
non updatable extrusion: <Playground id="#ZMKN5T#1" title="Non Updatable Extrusion" description="Simple example of non updatable extrusion." image=""/>
update of extrusion scaleFunction and rotation Function: <Playground id="#ZMKN5T#2" title="Updatable Extrusion" description="Simple example of updatable extrusion." image=""/>
offset open profile shape path defined by trigonometry: <Playground id="#ZMKN5T#3" title="Offset Open Profile Shape Path Defined By Trigonometry" description="Simple example of offset open profile shape path defined by trigonometry." image=""/> 
sine wave by alternately scaling positive/negative: <Playground id="#ZMKN5T#4" title="Sine Wave By Alternately Scaling Positive/Negative" description="Simple example of sine wave by alternately scaling positive/negative." image=""/>
example of constant scale and rotation evolving with the distance: <Playground id="#ZMKN5T#5" title="Example Of Constant Scale And Rotation Evolving With The Distance" description="Simple example of example of constant scale and rotation evolving with the distance." image=""/> 
non-linear rotation function: <Playground id="#ZMKN5T#6" title="Non-Linear Rotation Function" description="Simple example of non-linear rotation function." image=""/> 

offset open profile shape: <Playground id="#RF9W9#20" title="Offset Open Profile Shape" description="Simple example of offset open profile shape." image=""/>   
open extrusion path: <Playground id="#RF9W9#21" title="Open Extrusion path" description="Simple example of open extrusion path." image=""/> 
Extrusion with constant scale 1 and no rotation: <Playground id="#RF9W9#43" title="Extrusion With Constant Scale" description="Simple example of extrusion with constant scale 1 and no rotation." image=""/>
 _ribbonCloseArray_ to true: <Playground id="#RF9W9#44" title="Custom Extrusion With ribbonCloseArray" description="Simple example of custom extrusion with ribbonCloseArray set to true." image=""/>
 _ribbonClosePath_ to true instead: <Playground id="#RF9W9#45" title="Custom Extrusion With ribbonClosePath" description="Simple example of custom extrusion with ribbonClosePath set to true." image=""/> 
Both true: <Playground id="#RF9W9#46" title="Custom Extrusion With ribbonClosePath and ribbonCloseArray" description="Simple example of custom extrusion with ribbonClosePath and ribbonCloseArray set to true." image=""/>
  
generate strange shapes: <Playground id="#RF9W9#47" title="Strange Shapes With Custom Extrusion" description="Simple example of generating some strange shapes with custom extrusion." image=""/>

## Mesh
Usage: 
```javascript
let extrusion = BABYLON.Mesh.ExtrudeShapeCustom("extrusion", shape, path, scaleFunction, rotateFunction, ribbonCloseArray, ribbonClosePath, cap, scene);
let extrusion = BABYLON.Mesh.ExtrudeShapeCustom("extrusion", shape, path, scaleFunction, rotateFunction, ribbonCloseArray, ribbonClosePath, cap, scene, updatable, sideOrientation, instance); //optional parameters after scene

// fixed unit scale and zero rotation
let extrusion = BABYLON.Mesh.ExtrudeShapeCustom("extrusion", shape, path, () => {return 1}, () => {return 0}, ribbonCloseArray, ribbonClosePath, cap, scene);
```


## Dashed Lines
Creates a contiguous series of dashed line segments from a list of points. You must set at least the _points_ option. On update, you must set the _points_ and _instance_ options properties and you should not change . Any other option will not be changed.
## MeshBuilder
Usage:
```javascript
const options = {
    points: myPoints, //vec3 array,
    updatable: true
}

let dashedlines = BABYLON.MeshBuilder.CreateDashedLines("dashedlines", options, scene);  //scene is optional and defaults to the current scene

// Update
options.points[0].x +=6; 
options.instance = lines;
lines = BABYLON.MeshBuilder.CreateDashedLines("dashedlines", options); //No scene parameter when using instance
```

option|value|default value
--------|-----|-------------
points|_(Vector3[])_  array of Vector3, the path of the line **REQUIRED** |
dashSize|_(number)_  size of the dashes|3
gapSize|_(number)_  size of the gaps|1
dashNb|_(number)_  intended number of dashes|200
updatable|_(boolean)_ true if the mesh is updatable|false
instance|_(LineMesh)_ an instance of a line mesh to be updated|null

The actual length of the dashes and gaps is determined by how many are set by the *dashNb* and then the ratio, of *dashSize* and * gapSize* rather than the actual size 
All of the following will produce equal sized dashes and gaps.
```javascript
dashSize = 1;
gapSize = 1;

dashSize = 1000;
gapSize = 1000;

dashSize = 876;
gapSize = dashSize;
```
### Examples
non updatable default dashed lines: <Playground id="#TYF5GH#1" title="Create Non Updatable Default Dashed Lines" description="Simple example of creating non updatable default dashed lines." image=""/> 
non updatable dashed lines set options: <Playground id="#TYF5GH#2" title="Create Non Updatable Dashed Lines With Options" description="Simple example of creating non updatable dashed lines with options." image=""/>
non updatable 'closed' dashed lines: <Playground id="#TYF5GH#3" title="Create Non Updatable Closed Dashed Lines" description="Simple example of creating non updatable closed dashed lines." image=""/>
updatable example: <Playground id="#TYF5GH#4" title="Create Updatable Closed Dashed Lines" description="Simple example of creating updatable closed dashed lines." image=""/>

Dashed lines are colored with a color property rather than a material.

```javascript
dashedlines.color = new BABYLON.Color3(1, 0, 0);
```

Colored Dashed Lines: <Playground id="#TYF5GH#5" title="Create Colored Dashed Lines" description="Simple example of creating colored dashed lines." image=""/>

## Mesh
Usage:
```javascript
const dashedlines = BABYLON.Mesh.CreateDashedLines("dashedLines", vector3 array, dashSize, gapSize, dashNb, scene);
const dashedlines = BABYLON.Mesh.CreateDashedLines("dashedLines", vector3 array, dashSize, gapSize, dashNb, scene, updatable, instance); //optional parameters after scene
```


## Extruded Non Regular Polygon
*ExtrudePolygon* adds a *depth* option to *CreatePolygon*. The extrusion is carried out down the vertical y axis from the polygon shape in the horizontal xz plane. Like *CreatePolygon* it requires an Earcut script. Since it can be concave it requires a procedure to fill the polygon with triangles and an Earcut method is used. Whilst an Earcut script is pre-loaded in the Playground you will have to add a reference to such a script in your own projects. One is available at [cdn](https://unpkg.com/earcut@2.1.1/dist/earcut.min.js) or via a [npm package](https://github.com/mapbox/earcut#install).

On creation the local origin of the extruded polygon is coincident with the world origin. It is not possible to give a position relative to the extruded polygon as this depends on the data sets used.

*ExtrudePolygon* calls [PolygonMeshBuilder](/divingDeeper/mesh/creation/param/polyMeshBuilder). There is no *instance* option. You must set at least the _shape_ and _depth_ options. 

## MeshBuilder
Usage :
```javascript
const extrudedPolygon = BABYLON.MeshBuilder.ExtrudePolygon("polygon", options, scene); //scene is optional and defaults to the current scene
```

option|value|default value
--------|-----|-------------
shape|_(Vector3[])_  array of Vector3, the shape you want to turn **REQUIRED** |
depth|_(number)_  the depth of the extrusion **REQUIRED** |
faceColors|_(Color4[])_ array of 3 _Color4_, one per box face|Color4(1, 1, 1, 1) for each side
faceUV|_(Vector4[])_ array of 3 _Vector4_, one per box face| UVs(0, 0, 1, 1) for each side
wrap|_(boolean)_ maps texture to sides with faceUV[1] when false texture mapped to each individual side, when true wrapped over all sides |false
holes|_(Vector3[][])_  array of holes, each hole being an array of successive Vector3 | [] 
updatable|_(boolean)_ true if the mesh is updatable|false
sideOrientation|_(number)_ side orientation|DEFAULTSIDE

All vectors for shape and holes are Vector3 and should be in the xz plane, ie of the form BABYLON.Vector3(x, 0, z) and in **counter clockwise** order;

## Examples
Extruded Polygon: <Playground id="#KIEYA6" title="Extruding Irregular Polygons" description="Simple example of extruding irregular polygons." image=""/>
Extruded Polygons using faceUV, one with wrap, one without: <Playground id="#KIEYA6#1" title="Extruding Irregular Polygons Advanced" description="Simple example of extruding irregular polygons." image=""/>


## Mesh
```javascript
let polygon = BABYLON.Mesh.CreatePolygon("polygon", shape, depth, scene);
let polygon = BABYLON.Mesh.CreatePolygon("polygon", shape, depth, scene, holes, updatable, sideOrientation); //optional parameters after scene
```


## Extruded Shape
An extruded shape is created by defining a shape profile using vector3 coordinates in the xy plane and providing a path along which the profile will be extruded. You must set at least the _shape_ and _path_ options. On update, you must set the _shape_, _path_ and _instance_ options and you can set the _scale_ and _rotation_ options.

On creation the local origin of an extrusion 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.

The profile shape's local origin is (0, 0, 0) relative to its defining coordinates and it is the local origin that runs along the path during the extrusion.

When you need the appearance of a solid shape then there is an option to cap the ends. The caps are drawn by creating triangles from the Barycenter of the shape profile to the profile vertices, so that there are profile shapes that cause caps to not correctly fit the profile shape. In this case you can used CreatePolygon for the caps, however you do need to position and rotate these caps in addition to creating them.

When you need sharp mitred corners there is a utility function available [Extruded Shape with Mitred Corners](/toolsAndResources/utilities/Mitred)

## MeshBuilder
Usage :
```javascript
const options = {
    shape: myPoints, //vec3 array with z = 0,
    path: myPath, //vec3 array
    updatable: true
}

let extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", options, scene);  //scene is optional and defaults to the current scene

// Update
options.shape = newShape;
options.path = newPath;
options.instance = extruded;
extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", options); //No scene parameter when using instance
```

option|value|default value
--------|-----|-------------
shape|_(Vector3[])_  array of Vector3, the shape you want to extrude **REQUIRED** |
path|_(Vector3[])_  array of Vector3, the extrusion axis **REQUIRED** |
scale|_(number)_  the value to scale the shape|1
rotation|_(number)_  the value to rotate the shape each step along the path|0
cap|_(number)_ extrusion cap : NO_CAP, CAP_START, CAP_END, CAP_ALL|NO_CAP
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 an extruded shape to be updated|null
invertUV|_(boolean)_ to swap the U and V coordinates at geometry construction time (texture rotation of 90°)|false

### Examples
non updatable extrusion: <Playground id="#MR8LEL#2" title="Non Updatable Extrusion" description="Simple example of non updatable extrusions." image=""/>
update of extrusion including, shape, path, scale and rotation: <Playground id="#MR8LEL#3" title="Updatable Extrusion" description="Simple example of updatable extrusions." image=""/>
extrusion with open shape: <Playground id="#MR8LEL#4" title="Extrusion With Open Shape" description="Simple example of extrusion with open shpaes." image=""/>

spiral extrusion with straight path and rotation set: <Playground id="#MR8LEL#5" title="Spiral Extrusion" description="Simple example of spiral extrusion." image=""/>  

capped extrusion: <Playground id="#MR8LEL#6" title="Capped Extrusion" description="Simple example of capped extrusion." image=""/>
profile that does not cap correctly: <Playground id="#MR8LEL#7" title="Incorrectly Capped Extrusion" description="Simple example of inocrrectly capped extrusion." image=""/>


## Mesh
Usage:
```javascript
let extrusion = BABYLON.Mesh.ExtrudeShape(name, shape, path, scale, rotation, cap, scene);
let extrusion = BABYLON.Mesh.ExtrudeShape(name, shape, path, scale, rotation, cap, scene, updatable, sideOrientation, instance); //optional parameters after scene
```


## Lathe
A lathed shape is created by defining a shape profile using vector3 coordinates in the xy plane. The shape profile will be rotated around the y axis to form the lather shape. It is recommended that all the x values are positive. You must set at least the _shape_ option.

On creation the local origin of a lathed shape 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.

There in no _instance_ option for lathed shapes

## MeshBuilder
Usage :
```javascript
const lathe = BABYLON.MeshBuilder.CreateLathe("lathe", options, scene); //scene is optional and defaults to the current scene
```

option|value|default value
--------|-----|-------------
shape|_(Vector3[])_  array of Vector3, the shape you want to turn **REQUIRED** |
radius|_(number)_  the value to radius of the lathe|1
tessellation|_(number)_  the number of iteration around the lathe|64
arc|_(number)_ ratio of the circumference between 0 and 1|1
cap|_(number)_ tube cap : NO_CAP, CAP_START, CAP_END, CAP_ALL|NO_CAP
closed|_(boolean)_ to open/close the lathe circumference, should be set to `false` when used with `arc`|true
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) 
invertUV|_(boolean)_ to swap the U and V coordinates at geometry construction time (texture rotation of 90°)|false

The radius value is a multiplier for the x values in the profile shape vector3s.

### Examples
Lathed shape: <Playground id="#PQ0GIE" title="Lathed Shape Example" description="Simple example of a lathed shape." image=""/>
Hexagonal nut: <Playground id="#PQ0GIE#1" title="Lathed Hexagonal Nut" description="Simple example of a lathed hexagonal nut." image=""/>  
Arc: <Playground id="#PQ0GIE#2" title="Lathed Arc" description="Simple example of a lathed arc." image=""/>


## Mesh
Usage:
```javascript
let lathe = BABYLON.Mesh.CreateLathe("lathe", shape, radius, tessellation, scene);
let lathe = BABYLON.Mesh.CreateLathe("lathe", shape, radius, tessellation, scene, updatable, sideOrientation); //optional parameters after scene
```
Note the limited parameters for this method


## Line System
MeshBuilder only. A system of non-contiguous lines that are independent of each other and may exist in their own space. You must set at least the _lines_ option. On update, you must set the _lines_ and _instance_ options. You can also update the _colors_ option if previously set at construction time.

## MeshBuilder 
Usage :
```javascript
// creates an instance of a line system
let lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: myArray}, scene);

// updates the existing instance of lineSystem : no need for the parameter scene here
lineSystem = BABYLON.MeshBuilder.CreateLineSystem("lineSystem", {lines: myArray, instance: lineSystem});
```

option|value|default value
--------|-----|-------------
lines|_(Vector3[][])_  array of lines, each line being an array of successive Vector3 **REQUIRED**
updatable|_(boolean)_ true if the mesh is updatable|false
instance|_(LineMesh)_ an instance of a line system mesh to be updated|null
colors|_(Color4[])_ array of Color4, each point color|null
useVertexAlpha|_(boolean)_ false if the alpha blending is not required (faster)|true

### Examples
Example of a Linesystem: <Playground id="#Y7CS4N" title="Line System Example" description="Simple example of a line system." image=""/>
Update of the Linesystem: <Playground id="#Y7CS4N#1" title="Updating Line System Example" description="Simple example of updating a line system." image=""/>

Unlike a mesh Lines are colored after creation with a color property rather than a material.
```javascript
linesystem.color = new BABYLON.Color3(1, 0, 0);
```
Colored Line System: <Playground id="#Y7CS4N#2" title="Colored Line System Example 1" description="Simple example of a colored line system." image=""/>

You can produce multi-colored lines by setting the colors for each point of each line before creation

<Playground id="#Y7CS4N#3" title="Colored Line System Example 2" description="Simple example of a colored line system." image=""/>


## Lines
Lines are created as a contiguous series of attached line segments from a list of points. You must set at least the _points_ option. On update, you must set the _points_ and _instance_ options. You can also update the _colors_ option if previously set at construction time.

## MeshBuilder
Usage:
```javascript
const options = {
    points: myPoints, //vec3 array,
    updatable: true
}

let lines = BABYLON.MeshBuilder.CreateLines("lines", options, scene);  //scene is optional and defaults to the current scene

// Update
options.points[0].x +=6; 
options.instance = lines;
lines = BABYLON.MeshBuilder.CreateLines("lines", options); //No scene parameter when using instance
```

option|value|default value
--------|-----|-------------
points|_(Vector3[])_  array of Vector3, the path of the line **REQUIRED**
updatable|_(boolean)_ true if the mesh is updatable|false
instance|_(LineMesh)_ an instance of a line mesh to be updated|null
colors|_(Color4[])_ array of Color4, each point color|null
useVertexAlpha|_(boolean)_ false if the alpha blending is not required (faster)|true

Unlike a mesh Lines are colored after creation with a color property rather than a material.
```javascript
lines.color = new BABYLON.Color3(1, 0, 0);
```

### Examples
non updatable lines: <Playground id="#MZ7QRG#6" title="Create Non Updatable Lines" description="Simple example of creating non updatable lines." image=""/>
non updatable closed lines: <Playground id="#MZ7QRG#8" title="Create Non Updatable Closed Lines" description="Simple example of creating non updatable closed lines." image=""/> 
updatable example: <Playground id="#MZ7QRG#9" title="Create Updatable Closed Lines" description="Simple example of creating updatable closed lines." image=""/> 
updatable spriral: <Playground id="#MZ7QRG#10" title="Create Updatable Spiral Lines" description="Simple example of creating updatable spiral lines." image=""/>

multi colored lines have to be set on creation. <Playground id="#MZ7QRG#11" title="Create Multi Colored Lines" description="Simple example of creating multi colored lines." image=""/>

## Mesh
usage:
```javascript
let lines = BABYLON.Mesh.CreateLines("lines", points, scene);
let lines = BABYLON.Mesh.CreateLines("lines", points, scene, updatable, instance);
```  


## Polygon Mesh Builder
*CreatePolygon* and *ExtrudePolygon* which follow the same form as other mesh creations call *PolygonMeshBuilder* which can be used directly. It has some advantages but cannot be used with *faceUVs*. The data used in describing the polygon is given in 2D vectors, (x, y) rather than (x 0, z). Additionally, an array of vector2s as well as the polygon data can be passed as Path2 object. The advantage of using Path2 is that curves can be described using simple methods rather than your own functions. The data used to describe the polygon shape must be in counter clockwise order.

The way *PolygonMeshBuilder* works is to construct and return the triangulation of the polygon and then create the mesh from this triangulation using its *build* method. The triangulation requires an Earcut script. Whilst an Earcut script is pre-loaded in the Playground you will have to add a reference to such a script in your own projects. One is available at [cdn](https://unpkg.com/earcut@2.1.1/dist/earcut.min.js) or via a [npm package](https://github.com/mapbox/earcut#install).

The build function takes two optional parameters: the first is a Boolean and is true if the mesh is to be updatable and the seconds is the depth of the extrusion when required.


## Constraints
The polygon and any holes inside it must be [simple](https://en.wikipedia.org/wiki/Simple_polygon), that is no overlapping sides. Holes should be wholly inside the polygon and should not be too close to the sides of the polygon or to each other otherwise the mesh will be malformed. This [algorithm](http://geomalgorithms.com/a09-_intersect-3.html#Simple-Polygons) is one you can use to check if a polygon is simple.

![Safe Construction](/img/how_to/PolyMeshBuild/pmberr1.jpg)

![Unsafe Construction](/img/how_to/PolyMeshBuild/pmberr2.jpg)

![Unsafe Construction](/img/how_to/PolyMeshBuild/pmberr3.jpg)

## Usage
```javascript
const polygon_triangulation = new BABYLON.PolygonMeshBuilder("name", vector2 array, scene);
const polygon = polygon_triangulation.build();
```


```javascript
var polygon_triangulation = new BABYLON.PolygonMeshBuilder("name", Path2, scene);
var polygon = polygon_triangulation.build(false, 3);
```

### Holes
A hole can only be given as an array of vector2, representing the corners of the hole in consecutive counter clockwise order around the hole.

Holes are added to the polygon triangulation using the addHole function.

```javascript
polygon_triangulation.addHole(hole1);
polygon_triangulation.addHole(hole2);
polygon_triangulation.addHole(hole3);
var polygon = polygon_triangulation.build(true, 1.4);
```
## Examples
Each example contains polygons described with vector2s and with Path2
Simple Polygons: <Playground id="#2NJYI5" title="Simple Polygons" description="Example of creating simple polygons with Mesh Builder." image=""/> 
Simple Extruded Polygons: <Playground id="#2NJYI5#1" title="Simple Extruded Polygons" description="Example of simple extruded polygons with Mesh Builder." image=""/>
Polygons with holes: <Playground id="#2NJYI5#2" title="Polygons With Holes" description="Example of creating polygons with holes." image=""/>
Extruded Polygons with holes: <Playground id="#2NJYI5#3" title="Extruded Polygons With Holes" description="Example of extruding polygons with holes." image=""/>



## Non Regular Polygon
A polygon of any type, regular or irregular, convex or concave, is created in the horizontal xz plane. Since it can be concave it requires a procedure to fill the polygon with triangles and an Earcut method is needed. Whilst an Earcut script is pre-loaded in the Playground you will have to add a reference to such a script in your own projects. One is available at [cdn](https://unpkg.com/earcut@2.1.1/dist/earcut.min.js) or via a [npm package](https://github.com/mapbox/earcut#install).

On creation the local origin of the polygon is coincident with the world origin. It is not possible to give a position relative to the polygon as this depends on the data sets used.

*CreatePolygon* calls [PolygonMeshBuilder](/divingDeeper/mesh/creation/param/polyMeshBuilder). There is no *instance* option. You must set at least the _shape_ option. 

## MeshBuilder
Usage :
```javascript
const polygon = BABYLON.MeshBuilder.CreatePolygon("polygon", options, scene); //scene is optional and defaults to the current scene
```

option|value|default value
--------|-----|-------------
shape|_(Vector3[])_  array of Vector3, the shape you want to build **REQUIRED** |
holes|_(Vector3[][])_  array of holes, each hole being an array of successive Vector3 | []
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) 

All vectors for shape and holes are Vector3 and should be in the xz plane, ie of the form BABYLON.Vector3(x, 0, z) and in **counter clockwise** order. You just list all the vertices of the polygon and *CreatePolygon* closes the shape.

### Example
polygon with holes: <Playground id="#ZD60FU" title="Create a Polygon With Holes" description="Simple example of creating a polygon with holes." image=""/>


## Mesh
```javascript
let polygon = BABYLON.Mesh.CreatePolygon("polygon", shape, scene);
let polygon = BABYLON.Mesh.CreatePolygon("polygon", shape, scene, holes, updatable, sideOrientation); //optional parameters after scene
```


## 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. Joining one long edge to its opposite you could form a tube and bend that 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." image=""/>

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." image=""/>
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." image=""/>  
open ribbon: <Playground id="#F6JW5W#8" title="Create An Open Ribbon" description="Simple example of creating an open ribbon." image=""/>
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." image=""/> 
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." image=""/> 


## 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
Lets 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.  

Below shows the construction of a ribbon using two paths A and B each having five points. 

![Ribbon](/img/how_to/ribbon/ribbon.png)

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 ribbon of narrow width in the real world with wire running down its length. Closing the paths forms a loop of ribbon while closing the array would form 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." image=""/>

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 with 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." image=""/> 
offset 10: <Playground id="#F6JW5W#14" title="Create a Ribbon Example 2" description="Simple example of creating a ribbon with varying properties." image=""/> 
offset 5: <Playground id="#F6JW5W#15" title="Create a Ribbon Example 3" description="Simple example of creating a ribbon with varying properties." image=""/> 
offset 20: <Playground id="#F6JW5W#16" title="Create a Ribbon Example 4" description="Simple example of creating a ribbon with varying properties." image=""/>


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." image=""/>

## 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 then to simply 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." image=""/>
_path2_ and _path3_ are longer than _path1_ and _path4_.

As you can see, the final ribbon adjusts to different lengths. The rule is they all start from first path points and each intermediate ribbon then stops at first of its both constituting paths end. 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 colred ribbon." image=""/>

There is no incidence on light reflection for 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 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 unlcosed ribbon." image=""/>

```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." image=""/>

```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." image=""/>

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 by yourself. A simple way to do this is just to re-push the first _path_ at the end of the _pathArray_

<Playground id="#3XMWZ#50" title="Closed Textured Ribbon" description="Simple example of creating a closed textured ribbon." image=""/>

```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." image=""/>

<Playground id="#3XMWZ#51" title="Textured Ribbon With ClosePath" description="Simple example of creating a textured ribbon with closePath set to true." image=""/>


## Surfaces, Mathematics and Ribbons
Mathematics is very useful for drawing surfaces in 3D space. Surfaces are often described by the following equation type *y = f(x, z)*, that is height of point on the surface is determined by the ground coordinate position below the point

For the moment take z as fixed, say *z = 6*. That means for that value of z *y = g(x)* for some function g. 

When x is changing in a linear way it is easy to write a direct equation, such as *y = x²* and to use Babylon.js to draw it path for a range of values of x. 

```javascript
const path = [];
for (let x = -5; x <= 5; x++) {
    let y = x * x
    path.push(new BABYLON.Vector3(x, y, 6))
}
```

Another way would be to use a separate parameter t, for example, and write *x = t*, and *y = t²*. This might seem a waste of time and extra work.
```javascript
const path = [];
for (let t = -5; t <= 5; t++) {
    let x = t;
    let y = t * t
    path.push(new BABYLON.Vector3(x, y, 6))
}
```

Where it is useful is when the change in x is not linear. Consider a circle or radius 5 for example. The direct equation is *x² + y² = 25*. How do you code that? Using the angle, a, as parameter gives

```javascript
const path = [];
for (let a = 0; a < 2 * Math.PI; a += Math.PI / 8) {
    let x = 5 * Math.cos(a);
    let y = 5 * Math.sin(a);
    path.push(new BABYLON.Vector3(x, y, 6))
}
path.push(path[0]); // close circle
```

When it is possible to write the equations using parameters *x = f(t)* and *y = g(t)* it makes coding easier. Assuming the functions f(t) and g(t) have already been coded.

```javascript
const path = [];
for (let t = -5; t <= 5; t++) {
    let x = f(t);
    let y = g(t);
    path.push(new BABYLON.Vector3(x, y, 6))
}
```

Having constructed one path to draw a circle at *z = 6* do the same across a range of *z* values and use the many paths to create a ribbon.

```javascript
const paths = [];
for (let z = -6; z <= 6; z++) {
    const path = [];
    for (let a = 0; a < 2 * Math.PI; a += Math.PI / 8) {
      let x = 5 * Math.cos(a);
      let y = 5 * Math.sin(a);
      path.push(new BABYLON.Vector3(x, y, z))
    }
    path.push(path[0]); // close circle
    paths.push(path)
}
```

Again we can use a parameter for *z*
```javascript
const paths = [];
for (let t = -6; t <= 6; t++) {
    const path = [];
    for (let a = 0; a < 2 * Math.PI; a += Math.PI / 8) {
        let x = 2 * Math.cos(a);
        let y = 2 * Math.sin(a);
        let z = t;
        path.push(new BABYLON.Vector3(x, y, z))
    }
    path.push(path[0]); // close circle
    paths.push(path)
}
```
Makes a tube: <Playground id="#F6JW5W#18" title="Math-Based Ribbon Tube" description="Simple example of creating ribbon tube with math." image=""/>

We can also use the *z* parameter with *x* and *y*
```javascript
const paths = [];
for (let t = -6; t <= 6; t++) {
    const path = [];
    for (let a = 0; a < 2 * Math.PI; a += Math.PI / 8) {
        let x = 2 * Math.cos(a) + t / 2;
        let y = 2 * Math.sin(a) + t * t / 4;
        let z = t;
        path.push(new BABYLON.Vector3(x, y, z))
    }
    path.push(path[0]); // close circle
    paths.push(path)
}
```

Makes a U tube: <Playground id="#F6JW5W#19" title="Math-Based Ribbon U-Tube" description="Simple example of creating ribbon U-tube with math." image=""/>

and surfaces get more interesting if the change in z is not linear
```javascript
const paths = [];
for (let t = 0; t < Math.PI; t += Math.PI / 32) {
    const path = [];
    for (let a = 0; a < 2 * Math.PI; a += Math.PI / 32) {
        let x = 4 * Math.cos(a) * Math.sin(t);
        let y = 4 * Math.sin(a) * Math.sin(t);
        let z = 4 * Math.cos(t);
        path.push(new BABYLON.Vector3(x, y, z))
    }
    path.push(path[0]); // close circle
    paths.push(path)
}
```

a sphere: <Playground id="#F6JW5W#25" title="Math-Based Ribbon Sphere" description="Simple example of creating ribbon sphere with math." image=""/>

## More examples
It is hard to stop playing  
A ribbon of parabolas: <Playground id="#F6JW5W#22" title="Math-Based Ribbon Parabolas" description="Simple example of creating ribbon parabolas with math." image=""/>  
parabolas scaled: <Playground id="#F6JW5W#21" title="Math-Based Scaled Ribbon Parabolas" description="Simple example of creating scaled ribbon parabolas with math." image=""/>  
parabolas with some trigonometry: <Playground id="#F6JW5W#23" title="Trigonometry-Based Ribbon Parabolas 1" description="Simple example of creating ribbon parabolas with trigonometry." image=""/>
parabolas and more trigonometry: <Playground id="#F6JW5W#24" title="Trigonometry-Based Ribbon Parabolas 2" description="Simple example of creating ribbon parabolas with trigonometry." image=""/> 

## Paths to Try
You could choose a known math curve from these sites
http://en.wikipedia.org/wiki/List_of_curves  
http://www.mathcurve.com/courbes2d/courbes2d.shtml  
or others.  
When you feel more comfortable, create you own.  


  
  


## Tube
A tube is much as you would expect it to be, a surface with  hollow length.  
On creation the local origin of a tube 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 = {
    path: myPath, //vec3 array,
    updatable: true
}

let tube = BABYLON.MeshBuilder.CreateTube("tube", options, scene);  //scene is optional and defaults to the current scene

// Update
options.path[0].x +=6; 
options.instance = tube;
tube = BABYLON.MeshBuilder.CreateTubes("tube", options); //No scene parameter when using instance
```

option|value|default value
--------|-----|-------------
path|_(Vector3[])_  array of Vector3, the path of the tube **REQUIRED** |
radius|_(number)_  the radius of the tube|1
tessellation|_(number)_  the number of radial segments|64
radiusFunction|_( function(index, distance) )_  a function returning a radius value from _(index, distance)_ parameters|null
cap|_(number)_ tube cap : NO_CAP, CAP_START, CAP_END, CAP_ALL|NO_CAP
arc|_(number)_ ratio of the tube circumference between 0 and 1|1
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 tube to be updated|null
invertUV|_(boolean)_ to swap the U and V coordinates at geometry construction time (texture rotation of 90°)|false  

You must set at least the _path_ option.
On update, you must set the _path_ and _instance_ options and you may also set the _radius_, _radiusFunction_ or _arc_ options.

### Examples
non updatable tube: <Playground id="#WW0ALQ" title="Create a Non Updatable Tube" description="Simple example of creating non updatable tubes." image=""/>
updatable tube: <Playground id="#WW0ALQ#1" title="Create an Updatable Tube" description="Simple example of creating an updatable tube." image=""/>
spiral tube: <Playground id="#WW0ALQ#2" title="Create a Spiral Tube" description="Simple example of creating a spiral tube." image=""/>

When using the radiusFunction it must return a number. Its parameter refer to a path index or a distance along the path. 

distance example: <Playground id="#WW0ALQ#3" title="Create a Tube With Radius Function 1" description="Simple example of creating a tube using the radiusFunction distance." image=""/>
index example: <Playground id="#WW0ALQ#4" title="Create a Tube With Radius Function 2" description="Simple example of creating a tube using the radiusFunction index." image=""/>
with circular path and changing radius: <Playground id="#WW0ALQ#5" title="Create a Tube With Radius Function 3" description="Simple example of creating a tube with a circular path and changing radius." image=""/>

## Mesh
usage: 
```javascript
let tube = BABYLON.Mesh.CreateTube("tube", path, radius, tesselation, optional radiusFunction, cap, scene);
let tube = BABYLON.Mesh.CreateTube("tube", path, radius, tesselation, optional radiusFunction, cap, scene, updatable, sideOrientation, instance); //optional parameters after scene
```



## Tiled Ground
A tiled ground is created differently to a ground mesh. It still lies in the xz plane. The bottom left corner of of the tiled ground is given by the values for xmin and zmin and the top right corner by xmax and zmax. The tiled ground is be subdivided into tile regions: across into w tiles and up into h tiles. In the same way every tile can be further subdivided into w by h sections. The creation of a tiled ground relies on the use of *MultiMaterials*.

## MeshBuilder
Usage:
```javascript
var tiledGround = BABYLON.MeshBuilder.CreateTiledGround("tiled ground", options, scene);
```

option|value|default value
--------|-----|-------------
xmin|_(number)_ map min x coordinate value|-1
zmin|_(number)_ map min z coordinate value|-1
xmax|_(number)_ map max x coordinate value|1
zmin|_(number)_ map max z coordinate value|1
subdivisions|_object_ _( {w: number, h: number} )_ number of subdivisions (tiles) on the height and the width of the map|{w: 6, h: 6}
precision|_( {w: number, h: number} )_ number of subdivisions on the height and the width of each tile|{w: 2, h: 2}
updatable|_(boolean)_ true if the mesh is updatable|false

### Steps to Create Tiling

* Create Tiled Ground
* Create materials needed for each tile
* Create multi material and push each material onto its subMaterials array
* Set the multi material as the material for the Tiled Ground
* Set the subMeshes property of the Tiled Ground to an empty array
* Create and set values for these variables
```javascript
    const verticesCount = tiledGround.getTotalVertices();
    const tileIndicesLength = tiledGround.getIndices().length / (subdivisions.w * subdivisions.h);
```
* Fill the subMeshes array of the Tiled Ground using
```javascript
    let base = 0;
    for (let row = 0; row < grid.h; row++) {
        for (let col = 0; col < grid.w; col++) {
            tiledGround.subMeshes.push(new BABYLON.SubMesh(
                row % 2 ^ col % 2, 
                0, verticesCount, 
                base , 
                tileIndicesLength, 
                tiledGround));
            base += tileIndicesLength;
        }
    }
```

### Examples

Chess Board: <Playground id="#8VDULN" title="Create a Chess Board" description="Simple example of creating a chess board." image=""/>

Using these two materials

![grass](/img/how_to/Materials/grass.png) ![rock](/img/how_to/Materials/rock.png)  

<Playground id="#8VDULN#1" title="Create a Chess Board With Grass And Rock" description="Simple example of creating a chess board with grass and rock textures." image=""/>

Forming a large scale map using open source map tiles: <Playground id="#1XBLWB#6" title="Create a Large Scale Map" description="Simple example of creating a large scale map using open source map tiles." image=""/>

## Mesh
Usage :
```javascript
const tiledGround = BABYLON.Mesh.CreateTiledGround("Tiled Ground", xmin, zmin, xmax, zmax, subdivisions, precision, scene);
const tiledGround = BABYLON.Mesh.CreateTiledGround("Tiled Ground", xmin, zmin, xmax, zmax, subdivisions, precision, scene, updatable); //one optional parameter after scene
```

Creating Parametric Meshes

Parametric Shapes

Coming next

Creating Lines

Learn how to create lines in Babylon.js.

Creating Dashed Lines

Learn how to create dashed lines in Babylon.js.

Creating A Line System

Learn how to create line systems in Babylon.js.

Creating Ribbons

Learn how to create ribbons in Babylon.js.

Ribbon In Detail

Dive into the details of ribbons in Babylon.js.

Ribbons With Math

Learn how to create ribbons with math in Babylon.js.

Creating Tubes

Learn how to create tubes in Babylon.js.

Extruding Shapes

Learn how to extrude shapes in Babylon.js.

Custom Extrusion

Learn how custom extrusion works in Babylon.js.

Lathe

Learn how to use the lathe operation in Babylon.js.

Irregular Polygons

Learn about creating irregular polygons in Babylon.js.

Irregular Polygon Extrusion

Learn how extrude irregular polygons in Babylon.js.

Polygon Mesh Builder

Learn how to create polygons with Mesh Builder in Babylon.js.