
## Tube
A tube is much as you would expect it to be: a surface with a hollow interior along its 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.CreateTube("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."/>
updatable tube: <Playground id="#WW0ALQ#1" title="Create an Updatable Tube" description="Simple example of creating an updatable tube."/>
spiral tube: <Playground id="#WW0ALQ#2" title="Create a Spiral Tube" description="Simple example of creating a spiral tube."/>

When using the radiusFunction, it must return a number. Its parameters 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."/>
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."/>
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."/>

## 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
```



## 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 this local origin that runs along the path during the extrusion.

When you need the appearance of a solid shape, 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 there are profile shapes for which the caps will not fit correctly. In this case, you can use 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).

Because the extrusion converts the path points to a Path3D, there are two anomalies that can occur for a given set of path points. The first is that the orientation of the normal to the path is undefined when the path is a straight line. The Path3D constructor will pick a first normal, which may not be the one needed. Use the firstNormal option to set the path normal at the first point. The second anomaly occurs when the path reverses itself from one point to the next; this causes the tangent at that point to become undefined. To apply a heuristic fix for this, use the adjustFrame option and set it to true.

## 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
closeShape|_(boolean)_ closes the shape, no need to push shape[0] to shape array|false
closePath|_(boolean)_ closes the path, no need to push path[0] to path array|false
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
firstNormal|_(Vector3)_ path normal of first point of path|null
adjustFrame|_(boolean)_ apply heuristic to adjust tangents of paths that reverse direction|false

### Examples
 <Playground id="#MR8LEL#2" title="Close Shape by Push" description="Closed shape extrusion."/>  

 closed using shape.push(shape[0])  

<Playground id="#MR8LEL#738" title="CloseShape is True" description="Closed shape extrusion."/>  

closed using closeShape: true  

<Playground id="#MR8LEL#739" title="Updatable Extrusion" description="Updatable extrusion." isMain={true} category="Mesh"/>  

update of extrusion including, shape, path, scale and rotation  
  
<Playground id="#MR8LEL#4" title="Extrusion With Open Shape" description="Open shape extrusion."/>  

extrusion with open shape  
  
<Playground id="#MR8LEL#5" title="Spiral Extrusion" description="Simple example of spiral extrusion."/>  

spiral extrusion with straight path and rotation set:    

<Playground id="#MR8LEL#740" title="Capped Extrusion" description="Capped extrusion."/>  

capped extrusion   

 <Playground id="#MR8LEL#741" title="Incorrectly Capped Extrusion" description="Incorrectly capped extrusion."/>  

 shape profile that does not cap correctly  
 
  <Playground id="#5ICT41#8" title="Extrusion firstNormal" description="How setting firstNormal affects extrusion."/>
  
 setting first normal to control orientation

 <Playground id="#5ICT41#6" title="Extrusion path reverses direction" description="Correcting reversing extrusion path"/>
 
 extrusion path reverses causing artifacts

## 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
```



## Surfaces, Mathematics and Ribbons
Mathematics is very useful for drawing surfaces in 3D space. Surfaces are often described by the equation type *y = f(x, z)*, that is, the height of a 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 changes linearly, it is easy to write a direct equation, such as *y = x²*, and use Babylon.js to draw its path for a range of x values. 

```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 like 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))
}
```

This becomes useful when the change in x is not linear. Consider a circle of radius 5, for example. The direct equation is *x² + y² = 25*. How do you code that? Using the angle, a, as a 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."/>

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."/>

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."/>

## 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."/>  
parabolas scaled: <Playground id="#F6JW5W#21" title="Math-Based Scaled Ribbon Parabolas" description="Simple example of creating scaled ribbon parabolas with math."/>  
parabolas with some trigonometry: <Playground id="#F6JW5W#23" title="Trigonometry-Based Ribbon Parabolas 1" description="Simple example of creating ribbon parabolas with trigonometry."/>  
parabolas and more trigonometry: <Playground id="#F6JW5W#24" title="Trigonometry-Based Ribbon Parabolas 2" description="Simple example of creating ribbon parabolas with trigonometry."/>  
cuboids with soft edges <Playground id="#PCWRFE#2" title="Cuboids with soft edges" description="Example of using a parameterized function to create various cuboid shapes"/>  
cuboids with soft edges and recalculated UVs <Playground id="#PCWRFE#15" title="Cuboids with soft edges and recalculated UVs" description="Example of using a parameterized function to create various cuboid shapes and then recalculate UV coordinates for texture projection."/>  

## Paths to Try
You could choose a known math curve from sources like the sites below, among others. When you feel more comfortable, create your own. 

http://en.wikipedia.org/wiki/List_of_curves
http://www.mathcurve.com/courbes2d/courbes2d.shtml

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

Creating Tubes

Tube

MeshBuilder

Examples

Mesh