How To

Use Path3D

How To Use Path3D

A Path3D is a mathematical object created from a sequence of position vectors of points on a curve. Once obtained a Path3D can be used to determine the triplet of vectors tangent, normal and binormal of the curve for each of those points. Each triplet can then be used as a local system coordinate. You could set, for example, the camera direction to the normal as it follows the curve.

A Path3D object is simple to construct as follows

var points = [v1, v2, ..., vn];          // array of Vector3
var path3d = new BABYLON.Path3D(points);

You can then get the array of tangents, normals and binormals as follows

var tangents = path3D.getTangents();
var normals = path3D.getNormals();
var binormals = path3D.getBinormals();

each element of the arrays is a Vector3 .

Please zoom in and rotate : tangents in red, normals in blue, binormal in green.

Notice, in the next exxample, how the the triplets slightly rotate when the curve goes more into depth.

Whilst at any point on the curve there is only one tangent there can be an infinite number of normals and hence binormals. If the default one does not suit you it is possible to set the normal direction

Path3D Methods

As well as getTangents, getNormals and getBinormals there are three other methods of Path3D.

Get Curve Points

The getCurve method returns a copy of the initial Vector3 array given to create the path3D object.

var curvePoints = path3d.getCurve();

Get Distances

The getDistances method returns an array of distances from one curve point to the next in order of points and with 0 being the first distance.

For the array of points [(1, 2, 1), (4, 8, 3)] the array of distances is [0, 7].

var distances = path3d.getDistances();


In order to avoid memory re-allocation (when in the render loop for example) since the given points array is internally copied, you can update an existing Path3D object with its update() method.

var points1 = [v1, v2, ..., vn];          // array of Vector3
var path3d = new BABYLON.Path3D(points1);
var points2 = [u1, u2, ..., un];          // another array of Vector3

Tangents, normals and bi-normals are thus recomputed for this new path.

Set The Normal

For any vector there are an infinite number of vectors at right angles to it.

Multiple Normals

In creating a Path3D object Babylon.js assigns a default direction for the normal. If you want to set the direction of the normal yourself, you need to pass a vector for a second parameter to Path3D on creation or on update.

var initialVector = new BABYLON.Vector3(0, 1, 0);
var otherVector = new BABYLON.Vector3(0, 0, 1);
var points = [v1, v2, ..., vn];          // array of Vector3
var path3d = new BABYLON.Path3D(points, initialVector);
// do stuff ...
path3d.update(points, otherVector);

The normal will be the projection of your parameter vector onto the plane orthogonal to the tangent at the point position.

As can been in the diagram below, when the parameter is a vertical vector (black), this is projected onto the plane orthoganal to the tangent vector (red) to form the normal (green).

Curve Normal

The playground example shows what happens as the vector setting the normal direction is rotated.

Further Reading

Basic - Level 1

How To Create Parametric Shapes

More Advanced - Level 3

How To Draw Curves