
## Transformations
## Introduction to Coordinate Transformation

The first step in understanding coordinate transformation Babylon.js is to understand how the data describing a mesh is stored. The positions of each vertex is 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 for exceptional circumstance such as *baking a transformation* or a user updating it, the mesh vertex data remains unchanged. 


When you want one mesh, mesh_C, to locate in the frame of reference of another mesh, mesh_P, using coordinate transformation you use the 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 at this 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 the top of which emerges a smaller box and travels in a direction 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, it can then be applied to the vector (0, y, 0) position of the smaller box to determine the world position of the smaller box for that frame.

Obtaining the world matrix for the box inside a _registerAfterRender_ loop means that the world matrix will already have been obtained for the box and you can get it directly.

To match the orientation of the smaller box to the box whatever rotation has been applied to the box has to be re-applied to the smaller box. The easiest way to do this is to re-use the _rotate_methods applied to the box to the small 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 around space with building on it. In fact the following example uses a thin cylinder as the disc since the top circular face is horizontal whilst the face of a disc in Babylon.js is vertical. (OK it does make any real difference but it 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 rotation of the disc and the boxes are matched and the coordinate position of the boxes 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 using patents 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 a mesh.



## Transformations
## Rotation Conventions

There are several methods of achieving rotations within Babylon.js all of which use a particular convention.


## Euler Angles

In 3D space Euler angles can produce any possible orientation by providing three angles to rotate about each of three axes in a given order.  

For 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 is a potential of 24 different possibilities. Most, if not all,of these are in use in different systems around the world. So you need to be very careful that you know very clearly the convention that the system you are working in uses.

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.jpg)

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 (ie 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 whatever the orientation of the mesh prior to its application. 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 (ie 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 whatever the orientation of the mesh prior to its application. 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.jpg)

As a reminder this convention is directly used in the _rotation_ method in Babylon.js in the form

```javascript
mesh.rotation = new BABYLON.Vector3(pitch, yaw, roll);
```

In this convention to take the three angles, yaw, pitch and roll and rotate 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 (ie 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 (ie 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 the world space of Babylon.js. 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 on the transformation of a mesh and its coordinates.

Introduction To Coordinate Transformation

Transformations

Introduction to Coordinate Transformation