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
- the updatable option is set to true;
- 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 contiguous 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 |
| useVertexAlpha | (boolean) false if the alpha blending is not required (faster) | true |
Lines are colored with a color property
lines.color = new BABYLON.Color3(1, 0, 0);
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 |
| 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 |
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);
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 |
| useVertexAlpha | (boolean) false if the alpha blending is not required (faster) | true |
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);
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) 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 |
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) 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 |
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) 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 |
- Playground Example of an Extrusion in Z direction -
Playground Update of the Extrusion Changing Scale and Rotation -
- Playground Update of the Extrusion Changing Scale and Rotation -
When you need sharp mitred corners there is a utility function available Extruded Shape with Mitred Corners
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) 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 |
- 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) 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 |
Non Regular Polygon
Please note that CreatePolygon uses Earcut, so, in non playground projects, you will have to add a reference to their cdn or download their npm package
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) 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 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
Please note that ExtrudePolygon uses Earcut, so, in non playground projects, you will have to add a reference to their cdn or download their npm package
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 |
| 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 XoZ plane, ie of the form BABYLON.Vector3(x, 0, z) and in counter clockwise order;
- Playground Example of Extruded Polygon -
- Playground Example of Extruded Polygons using faceUV one with wrap one without -
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
Tiled Planes and Boxes
Decals