How To

Create Parametric Shapes


Parametric Shapes

Unlike set shapes the form of a parametric shape cannot generally be determined by their name as it depends on the parametric values applied to the shape.

The MeshBuilder method uses a number of options that you can set or just settle for the default values. Whilst some options such as size or diameter have an obvious meaning, some such as instance require an explanation before proceeding. Others such as frontUV require Further Reading.

Paths

Many parametric shapes require an array of vectors to form a path as one of its parameters. As well as obtaining this array of points by hand there are some curves, such as a Bezier curve, that can be generated within Babylon.js and the path vectors extracted.

Instance

When in addition the shape has an instance parameter in its options then its shape can be updated by changing the options' values and then using MeshBuilder with instance set to the name of the shape, provided the following conditions are met

  1. the updatable option is set to true;
  2. the number of elements within any array used for an option remains the same;

In practice all the parametric shapes, except for the Lathe and Polygon (both Create and Extend), can have their shape updated in this way by using the already created instance of the mesh.

Where it is possible two playground examples will be given, the first creating a mesh and the second updating it with the instance option.

How To Create Parametric Shapes

Lines

Creates a continguous series of 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 set the colors option if previously set at construction time.

Example :

//creates lines
var lines = BABYLON.MeshBuilder.CreateLines("lines", {points: myArray}, scene);

// updates the existing instance of lines : no need for the parameter scene here
lines = BABYLON.MeshBuilder.CreateLines("lines", {points: myArray, instance: lines});
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
useVertexColor (boolean) true if the alpha values from the former array must be used false

Playground Example of a Spiral from Lines -


Playground Update of the Spiral from Lines -

Lines are colored with a color property

lines.color = new BABYLON.Color3(1, 0, 0);

Playground Example of Colored Lines -


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. Any other option will not be changed.

Example :

// creates an instance of dashedlines
var dashedLines = BABYLON.MeshBuilder.CreateDashedLines("dl", {points: myArray}, scene);

// updates the existing instance of dashedLines : no need for the parameter scene here
dashedLines = BABYLON.MeshBuilder.CreateDashedLines("dl", {points: myArray, instance: dashedLines});
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
dashBn (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

A Playground Example of Dashed Lines -


A Playground Update of Dashed Lines -

Dashed lines are colored with a color property

lines.color = new BABYLON.Color3(1, 0, 0);

Playground Example of Colored Dashed Lines -


Line System

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 set the colors option if previously set at construction time.

Example :

// creates an instance of a line system
var 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
useVertexColor (boolean) true if the alpha values from the former array must be used false

A Playground Example of a Linesystem -


A Playground Update of the Linesystem -

A line system is colored with a color property

linesystem.color = new BABYLON.Color3(1, 0, 0);

Playground Example of Colored Line System -


Ribbon

You must set at least the pathArray option. On update, you must set the pathArray and instance options.

Example :

// creates an instance
var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myPaths}, scene);

// updates the existing instance of ribbon : no need for the parameter scene
ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", {pathArray: myPaths, 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[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of 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

A Playground Example of a Ribbon -


A Playground Update of the Ribbon -

Tube

You must set at least the path option. On update, you must set the path and instance options and you can set the radius, radiusFunction or arc options.

Example :

// creates a tube
var tube = BABYLON.MeshBuilder.CreateTube("tube", {path: myPath}, scene);

// updates the existing instance of tube : no need for the parameter scene
tube = BABYLON.MeshBuilder.CreateTube("tube", {path: myPath, instance: tube});
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(i, distance) ) a function returning a radius value from (i, 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[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of 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

A Playground Example of a Tube -


A Playground Update of the Tube -

Extruded Shapes

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.

In whatever direction you want to extrude the shape the design of the shape should be based on coordinates in the XOY plane, ie the z component should be 0. Some twisting to this base shape can be applied by leaving the x and y components unchanged but allowing the z component to be non zero but not taking the shape too far from generally lying in th XOY plane. Otherwise results will not be as you might expect.

Example :

// creates an extended shape
var extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", {shape: myShape, path: myPath}, scene);

// updates the existing instance of extruded : no need for the parameter scene
extruded = BABYLON.MeshBuilder.ExtrudeShape("ext", {shape: myShape, path: myPath, scale: newScale, rotation: newRotation instance: extruded});
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[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of 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

Playground Example of an Extrusion in Z direction -


Playground Update of the Extrusion Changing Scale and Rotation -

Playground Example of an Extrusion in Y direction -


Playground Update of the Extrusion Changing Scale and Rotation -

Custom Extruded Shapes

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.

Example :

//creates an instance of a Custom Extruded Shape
var extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", {shape: myShape, path: myPath}, scene);

// updates the existing instance of extruded : no need for the parameter scene
extruded = BABYLON.MeshBuilder.ExtrudeShapeCustom("ext", {shape: myShape, path: myPath, scaleFunction: myScaleF, rotationFunction: myRotF instance: extruded});
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[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of 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

Playground Example of a Custom Extruded Shape -


Playground Update of the Custom Extruded Shape Changing Scale and Rotation Functions -

Lathe

You must set at least the shape option.

Example :

var lathe = BABYLON.MeshBuilder.CreateLathe("lathe", {shape: myShape}, 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[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of 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

Playground Example of a Lathe -


Playground Update of the Lathe -

Non Regular Polygon

You must set at least the shape option.

Example :

var polygon = BABYLON.MeshBuilder.CreatePolygon("polygon", {shape: myShape, sideOrientation: BABYLON.Mesh.DOUBLESIDE, frontUVs: myFrontUVs, backUVs: myBackUVs}, scene);
option value default value
shape (Vector3[]) array of Vector3, the shape you want to turn 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[]) array of Vector4, ONLY WHEN sideOrientation:BABYLON.Mesh.DOUBLESIDE is an option Vector4(0,0, 1,1)
backUVs (Vector4[]) array of 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 XoZ plane, ie of the form BABYLON.Vector3(x, 0, z) and in counter clockwise order;

A Playground Example of a Polygon

Uses PolygonMeshBuilder

Extruded Non Regular Polygon

You must set at least the shape and depth options.

Example :

var polygon = BABYLON.MeshBuilder.ExtrudePolygon("polygon", {shape: myShape, depth: 2, faceUV: myUVs}, 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
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 XoZ plane, ie of the form BABYLON.Vector3(x, 0, z) and in counter clockwise order;

Playground Example of Extruded Polygon

Uses PolygonMeshBuilder

Further Reading

How To Make the Most of Options

Side Orientation
Updatable
Face UV and Face Colors
Front and Back UV

Basic - L1

Mesh Overview
Set Shapes 101
Parametric Shapes 101
Set Shapes
Polyhedra Shapes
Decals

Mid Level - L2

Ribbons In Detail

More Advanced - L3

Maths Makes Ribbons
How To Draw 3D Curves