# Path3D

> Learn how to use Path3D in Babylon.js.

Source: https://doc.babylonjs.com/features/featuresDeepDive/mesh/path3D

## How To Use Path3D

A `Path3D` is a mathematical object created from a sequence of position vectors of points on a curve. Once created, a `Path3D` can be used to determine the triplet of tangent, normal, and binormal vectors of the curve for each of those points. Each triplet can then be used as a local coordinate system. You could, for example, set the camera direction to the normal as it follows the curve.

A `Path3D` object is simple to construct, as follows:

```javascript
const points = [v1, v2, ..., vn];          // array of Vector3
const path3d = new BABYLON.Path3D(points);
```

You can then get the arrays of tangents, normals, and binormals as follows:

```javascript
const tangents = path3D.getTangents();
const normals = path3D.getNormals();
const binormals = path3D.getBinormals();
```

Each element of the arrays is a `Vector3`.

- [Playground: Tangents, Normals, and Binormals](https://playground.babylonjs.com/#2DLXYB#0) - Simple example of exploring tangents, normals, and binormals.

Please zoom in and rotate: tangents are in red, normals in blue, and the binormal in green.

Notice, in the next example, how the triplets slightly rotate when the curve goes more into depth.  
- [Playground: Tangents, Normals, and Binormals - Color Coded](https://playground.babylonjs.com/#2DLXYB#1) - Simple example of exploring color coded tangents, normals, and binormals.

While there is only one tangent at any point on the curve, 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](https://doc.babylonjs.com/features/featuresDeepDive/mesh/path3D#set-the-normal).

## Path3D Methods

As well as `getTangents`, `getNormals`, and `getBinormals`, `Path3D` provides some other methods.

### Get Curve Points

The `getCurve` method returns a copy of the initial `Vector3` array given to create the `Path3D` object.

```javascript
const 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, 0, 0), (5, 0, 0), (5, 1, 0)] the array of distances is [0, 4, 5].

```javascript
const distances = path3d.getDistances();
```

### Interpolation

You can get information about any virtual point from 0.0 to 1.0 along the path by using functions that interpolate between the path points. These are the following:

`getPointAt`, `getTangentAt`, `getNormalAt`, `getBinormalAt`, `getDistanceAt`, `getPreviousPointIndexAt`, `getSubPositionAt`

### Copying (part of) the path

The `slice` method returns a new Path3D that is a subpath, or slice, of the original path. It takes a _start_ and _end_ position from 0.0 to 1.0, or negative values, which wrap back around from 1.0.

### Update

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.

```javascript
const points1 = [v1, v2, ..., vn];          // array of Vector3
const path3d = new BABYLON.Path3D(points1);
const points2 = [u1, u2, ..., un];          // another array of Vector3
path3D.update(points2);
```

Tangents, normals, and binormals are then recomputed for this new path.

- [Playground: Update Path3D](https://playground.babylonjs.com/#2DLXYB#253) - Update a Path3D object and observe its results.

### Getting the closest position to a point

The `getClosestPositionTo` function returns the position, from 0.0 to 1.0, of the closest virtual point along the path to an arbitrary Vector3.

## Set The Normal

For any vector there are an infinite number of vectors at right angles to it.

![Multiple Normals](https://doc.babylonjs.com/img/how_to/Mesh/tangentnormals.webp)

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.

```javascript
const initialVector = new BABYLON.Vector3(0, 1, 0);
const otherVector = new BABYLON.Vector3(0, 0, 1);
const points = [v1, v2, ..., vn];          // array of Vector3
const 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 seen in the diagram below, when the parameter is a vertical vector (black), this is projected onto the plane orthogonal to the tangent vector (red) to form the normal (green).

![Curve Normal](https://doc.babylonjs.com/img/how_to/Mesh/planenormal.webp)

The playground example shows what happens as the vector setting the normal direction is rotated.

- [Playground: Path3D with Rotating Normals](https://playground.babylonjs.com/#8ICWNU) - Simple example of Path3D with rotating normals.

## Normalization and tangent alignment

Apart from the first normal, there are two more parameters:

`raw`, boolean, **false** by default. If true, the tangents, normals, and binormals are not normalized. This is useful for depicting path acceleration or speed.

`alignTangentsWithPath`, boolean, **false** by default. If true, the tangents are aligned with the path.

## Objects Following A Path

As mentioned in the beginning section, the position of points along the curve, together with the tangent, normal, and binormal vectors, can be used to guide the position and orientation of an object, creating interesting yet effortless animations.

- [Playground: Camera Following a Path](https://playground.babylonjs.com/#SGVUBC#86) - Example of a Camera animated to follow the positions and orientations along a Path3D object.

The playground above illustrates this technique. The Path3D is constructed as the combination of a few cubic Bèzier curves (but manually defining the points would work just fine). On each point of the path, its tangent and binormal vectors are passed as [arguments](https://doc.babylonjs.com/typedoc/classes/babylon.quaternion#fromlookdirectionrh) to the `FromLookDirectionRH()` method of the [Quaternion class](https://doc.babylonjs.com/features/featuresDeepDive/mesh/transforms/center_origin/rotation_quaternions), orienting the camera such that it looks down the tangent direction, and points up towards the binormal. We then set the sequences of positions and orientations as [animation keys](https://doc.babylonjs.com/features/featuresDeepDive/animation/animation_design), and play it. This idea isn't limited to Cameras, as it could also be used to define paths along which characters would walk in a game, for example.

## Further reading

- [Path3D API](https://doc.babylonjs.com/typedoc/classes/babylon.path3d)
- [Align Object With Path3D](https://doc.babylonjs.com/features/featuresDeepDive/mesh/transforms/center_origin/target_align)
- [How To Draw Curves](https://doc.babylonjs.com/features/featuresDeepDive/mesh/drawCurves)
- [How to Create a Track with Custom Alignments](https://doc.babylonjs.com/guidedLearning/workshop/Track)
