
## Transformations
## Introduction to Coordinate Transformation

The first step in understanding coordinate transformation in Babylon.js is to understand how the data describing a mesh is stored. The positions of each vertex are kept in an array of coordinates in the local space of the mesh. Each transformation applied to the mesh is stored in a matrix called the *World Matrix*. For each rendered frame, the current *World Matrix* is used on the local space vertex data to obtain the world data for the mesh. Except in exceptional circumstances, such as *baking a transformation* or a user updating it, the mesh vertex data remains unchanged. 


When you want one mesh, mesh_C, to be located in the frame of reference of another mesh, mesh_P, you can use coordinate transformation. Use the _transformCoordinates_ function to apply the *World Matrix* of mesh_P to the required position.

For example, take mesh_P to be a box, a cube of size 1. In the local space of the box, the center of the top face is at (0, 0.5, 0). Move and rotate this box to a new position. We want mesh_C, a sphere, to be located at the center of the top face of the box in this new position. To do this, use

```javascript
const matrix = mesh_P.computeWorldMatrix(true); //true forces a recalculation rather than using cache version
const local_position = new BABYLON.Vector3(0, 0.5, ,0); //Required position of C in the local space of P
const global_position = BABYLON.Vector3.TransformCoordinates(local_position, matrix); //Obtain the required position of C in World Space
mesh_C.position = global_position;
```

Position sphere using TransformCoordinates: <Playground id="#TRAIXW" title="Position a Sphere Using Transform Coordinates" description="Simple example of positioning a sphere using transform coordinates."/>

To translate the sphere by the direction vector (1, 1, 1), for example, you can add this to the current local position vector:

```javascript
const matrix = mesh_P.computeWorldMatrix(true);
const local_position = new BABYLON.Vector3(0, 0.5, 0);
local_position.addInPlace(new BABYLON.Vector3(1, 1, 1));
const global_position = BABYLON.Vector3.TransformCoordinates(local_position, matrix);
mesh_C.position = global_position;
```

Translate sphere using TransformCoordinates: <Playground id="#TRAIXW#1" title="Translate a Sphere Using Transform Coordinates" description="Simple example of translating a sphere using transform coordinates."/>

More extensive examples follow.



## Examples of Coordinate Transformation

## Satellite

Take a box that is rotating and translating, from whose top a smaller box emerges and travels in a direction that is always perpendicular to the top face of the box. 

In the local coordinate system of the box the up direction is (0, 1, 0) and so locally the position of anything travelling in that direction will be (0, y, 0).

Knowing the world matrix of the box for any frame, you can apply it to the smaller box's local position vector (0, y, 0) to determine the smaller box's world position for that frame.

Obtaining the world matrix for the box inside a _registerAfterRender_ loop means that the world matrix has already been computed for the box, so you can get it directly.

To match the orientation of the smaller box to the larger box, whatever rotation has been applied to the box must also be applied to the smaller box. The easiest way to do this is to reuse the same rotation methods applied to the box for the smaller box.

The following code gives the animation.

```javascript
    scene.registerAfterRender(function () {
        box.rotate(BABYLON.Axis.Y, Math.PI / 150, BABYLON.Space.LOCAL);
        box.rotate(BABYLON.Axis.X, Math.PI / 200, BABYLON.Space.LOCAL);
        box.translate(new BABYLON.Vector3(-1, -1, -1).normalize(), 0.001, BABYLON.Space.WORLD)
        small.rotationQuaternion = box.rotationQuaternion;
        matrix = box.getWorldMatrix();
        y += 0.001;
        local_pos = new BABYLON.Vector3(0, y, 0);
        small.position = BABYLON.Vector3.TransformCoordinates(local_pos, matrix);

    })
```

Small box travels from Large Box: <Playground id="#TRAIXW#2" title="Small Box Travels From Large Box" description="Simple example of a small box traveling from a large box."/>

## Disc World

Imagine a disc flying through space with buildings on it. In fact, the following example uses a thin cylinder as the disc, since the top circular face is horizontal, whereas the face of a disc in Babylon.js is vertical. (OK, it does not make any real difference, but it is more natural to start with a horizontal ground.)

The building will be an array of boxes. Leaving the boxes as separate meshes would mean applying the _TransformCoordinates_ function to each of them, so instead they will be merged into one mesh. As in the example above, the rotations of the disc and the boxes are matched, and the position of the boxes is transformed.

```javascript
    var phi = 0;
    scene.registerAfterRender(function () {
        matrix = disc.getWorldMatrix();
        disc.rotate(BABYLON.Axis.Y, Math.PI / 150, BABYLON.Space.LOCAL);
        disc.rotate(BABYLON.Axis.Z, Math.PI / 200, BABYLON.Space.LOCAL);
        disc.position = new BABYLON.Vector3(15 * Math.cos(phi), 16 * Math.sin(phi), 5)
        boxes.rotationQuaternion = disc.rotationQuaternion;
        boxes.position = BABYLON.Vector3.TransformCoordinates(boxes_position, matrix);
        phi +=0.01;

    });
```
Disc World: <Playground id="#TRAIXW#5" title="Disc World" description="Simple example of a disc world with coordinate transformation."/>

One final step before considering parents and pivots as a way of changing the center of transformation of a mesh is the more drastic step of changing the vertex data describing the mesh itself by baking a transformation into the mesh.




## Transformations
## Rotation Conventions

There are several methods of achieving rotations within Babylon.js, and each uses a particular convention.


## Euler Angles

In 3D space, Euler angles can produce any possible orientation by providing three angles to rotate about three axes in a given order.  

For the three axes X, Y, and Z, there are 12 different permutations for the order of the angles. Since X, Y, and Z can be in *World Space* or in *Local Space*, this means there are potentially 24 different possibilities. Most, if not all, of these are used in different systems around the world. So you need to be very clear about the convention used by the system you are working in.

Mesh.rotation(alpha, beta, gamma) uses the three Euler angles alpha, beta and gamma which are rotations about the X, Y and Z axes respectively. The convention that Babylon.js uses is based on the yaw, pitch and roll convention and so is carried out around X, Y and Z in local space in the order Y, X, Z.

References to Euler angles within the Babylon.js community can usually be taken to mean the angles to use with the _rotation_ method.

### YXZ *Local Axes* Yaw, Pitch, Roll

![Yaw pitch roll](/img/how_to/Mesh/yawpitchroll.webp)

A pitch is about X, yaw about Y, and roll about Z, applied in the order yaw, pitch, roll using **local** axes.

Applying independent rotations to a newly created mesh (i.e. one that has zero rotations) in the order YXZ using local axes

```javascript
mesh.rotate(BABYLON.Axis.Y, yaw, BABYLON.Space.LOCAL);
mesh.rotate(BABYLON.Axis.X, pitch, BABYLON.Space.LOCAL);
mesh.rotate(BABYLON.Axis.Z, roll, BABYLON.Space.LOCAL);
```

produces the same orientation as 

```javascript
mesh.rotation = new BABYLON.Vector3(pitch, yaw, roll);
```

which will produce this orientation regardless of the mesh's orientation before it is applied. The playground below demonstrates this by randomly generating angles and then applying these two methods to two different boxes, which remain in alignment.

<Playground id="#1ST43U#50" title="YXZ Yaw, Pitch, Roll" description="Simple example of YXZ Yaw, Pitch, Roll."/>

### ZXY *World Axes*

The YXZ convention with local axes has produced a particular orientation and it turns out that taking the same angles (alpha = pitch, beta = yaw and gamma = roll) and applying them in the order ZXY in world space will produce exactly the same orientation.

Applying independent rotations to a newly created mesh (i.e. one that has zero rotations) in the order ZXY

```javascript
mesh.rotate(BABYLON.Axis.Z, gamma, BABYLON.Space.WORLD);
mesh.rotate(BABYLON.Axis.X, alpha, BABYLON.Space.WORLD);
mesh.rotate(BABYLON.Axis.Y, beta, BABYLON.Space.WORLD);
```

produces the same orientation as 

```javascript
mesh.rotation = new BABYLON.Vector3(alpha, beta, gamma);
```

which will produce this orientation regardless of the mesh's orientation before it is applied. The playground below demonstrates this by randomly generating angles and then applying these two methods to two different boxes, which remain in alignment.

<Playground id="#1ST43U#52" title="ZXY Example" description="Simple example of ZXY rotation."/>



## Euler Angles to Quaternions

### YXZ, Local Space, Yaw, Pitch, Roll

![Yaw pitch roll](/img/how_to/Mesh/yawpitchroll.webp)

As a reminder, this convention is used directly in the _rotation_ method in Babylon.js in the form

```javascript
mesh.rotation = new BABYLON.Vector3(pitch, yaw, roll);
```

In this convention, you take the three angles, yaw, pitch, and roll and rotate yaw about Y, then pitch about X, and roll about Z using the **local** axes.

```javascript
mesh.rotate(BABYLON.Axis.Y, yaw, BABYLON.Space.LOCAL);
mesh.rotate(BABYLON.Axis.X, pitch, BABYLON.Space.LOCAL);
mesh.rotate(BABYLON.Axis.Z, roll, BABYLON.Space.LOCAL);
```

which with quaternions is the same as using _RotationYawPitchRoll_

```javascript
const yprQuaternion = BABYLON.Quaternion.RotationYawPitchRoll(yaw, pitch, roll);
``` 
Applying the above _rotate_ sequence to a newly created mesh (i.e. one that has zero rotations) in the order YXZ in **local** space, and applying _RotationAlphaBetaGamma_ to a mesh with any orientation using the same angles, will produce the same orientation. The playground below demonstrates this by randomly generating angles and then applying these two methods to two different boxes, which remain in alignment.

<Playground id="#1ST43U#54" title="Yaw Pitch Roll to Quaternion" description="Simple example of converting yaw, pitch, and roll to quaternion."/>

### ZXZ, World Space, A Standard Convention 

A standard Euler angle convention is to take three given angles alpha, beta, and gamma and rotate alpha about Z, then beta about X, then gamma about Z using the **world** axes. In Babylon.js, this can be achieved by using _rotate_

```javascript
mesh.rotate(BABYLON.Axis.Z, alpha, BABYLON.Space.WORLD);
mesh.rotate(BABYLON.Axis.X, beta, BABYLON.Space.WORLD);
mesh.rotate(BABYLON.Axis.Z, gamma, BABYLON.Space.WORLD);
```

which with quaternions is the same as using  _RotationAlphaBetaGamma_

```javascript
var abcQuaternion = BABYLON.Quaternion.RotationAlphaBetaGamma(alpha, beta, gamma);
```

Applying the above _rotate_ sequence to a newly created mesh (i.e. one that has zero rotations) in the order ZXZ in **world** space, and applying _RotationAlphaBetaGamma_ to a mesh with any orientation using the same angles, will produce the same orientation. The playground below demonstrates this by randomly generating angles and then applying these two methods to two different boxes, which remain in alignment.

<Playground id="#1ST43U#53" title="ZXZ To Quaternion" description="Simple example of converting ZXZ to quaternion."/>


So far, we have considered one mesh operating in its local space and in Babylon.js world space. What if we want one mesh to operate in the frame of reference of another mesh? Before we consider parenting in the next section, we will look at ways this can be done using the data that Babylon.js directly stores for a mesh's transformations and coordinates.

Introduction To Coordinate Transformation

Transformations

Introduction to Coordinate Transformation