Path3D is a math object.
Given an array of successive Vector3, it allows you to construct a path in space by computing on each point a triplet of vectors, the tangent, the normal and the binormal to keep direction and consistency (reduction of rotations).
Here is the model inspired from : http://www.cs.cmu.edu/afs/andrew/scs/cs/15-462/web/old/asst2camera.html
Each triplet can then be used as a local system coordinate. You could set for example a camera on each normal sliding along a curve.
Here is a simple example of the visualisation of the triplets on a sinus curve : https://www.babylonjs-playground.com/#2DLXYB -
Another example to show how the triplets slightly rotate when the curve goes more into depth : https://www.babylonjs-playground.com/#2DLXYB#1 -
Path3D creation :
var points = [v1, v2, ..., vn]; // array of Vector3
var path3d = new BABYLON.Path3D(points);
You can then get the triplets. Each following methods return an array of Vector3 which are respectively on each curve point the tangent, normal and binormal vectors :
var tangents = path3D.getTangents();
var normals = path3D.getNormals();
var binormals = path3D.getBinormals();
There are also two other methods : one returning the curve which is actually a copy of the initial Vector3 array given to create the path3D object and the other one returning the distance of each points from the first curve point (distance = zero) as a simple array of numeric values (the distances).
var curve = path3d.getCurve();
var distances = path3d.getDistances();
In order to avoid memory re-allocation (in the render loop for instance) 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
path3D.update(points2);
Tangents, normals and bi-normals are thus recomputed for this new path.
If you need to give a fixed orientation to the normal on the first path point, you can pass an extra Vector3 as parameter on creation or 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 first normal will then be the projection of your parameter vector onto the plane orthogonal to the first tangent at the first point position. In a simplest way, this is a mean to have a "vertical" (or quite vertical, depending on the path) first normal for instance.