Developer Guide

API Reference

@math.gl/core

@math.gl/culling

@math.gl/polygon

@math.gl/proj4

@math.gl/sun

@math.gl/web-mercator

math.gl allows you to create mathematical objects and then apply transformations on those objects. Objects are typically vectors but can also be more complex object such as spheres, planes, boxes etc, and transformations are typically represented by matrices and quaternions.

Transformations can be represented in many different notations but for computational purposes it is efficient to express them as matrices, or in some cases as quaternions.

The most general transform is a 4x4 matrix. See the article on homogeneous coordinates for some advantages in using 4x4 matrices to represent transformations.

Most math.gl classes offer a `transform`

method that accepts matrices and quaternions.

```
// prettier-ignore
const transformedVector1 = new Vector4(1, 0, 0, 1).transform([
1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1
]);
// or
const transformedVector2 = new Vector4(1, 0, 0, 1).transform(
new Matrix4([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1])
);
```

The various vector classes also offer methods to transform with smaller matrices

```
const transformedVector1 = new Vector4(1, 0, 0, 1).transformByMatrix3([1, 0, 0, 0, 1, 0, 0, 0, 1]);
// or
const transformedVector2 = new Vector3(1, 0, 0).transformByMatrix2(new Matrix2([1, 0, 0, 1]));
```

Quaternion transformations are also supported on some objects

```
const transformedVector1 = new Vector4(1, 0, 0).transformByQuaternion([0, 0, 0, 1]);
// or
const transformedVector2 = new Vector3(1, 0, 0).transformByQuaternion(new Quaternion([1, 0, 0, 1]));
```

Note that `<object>.transform()`

operations modify the object being transformed (and also return the modified object to enable "chaining" of calls).

Alternatively, transformations can also be performed via the matrix and quaternion classes. In this case, the transformation is stored in the result parameters (a new array is allocated if it `result`

is not supplied.)

```
const transformedVector1 = new Vector4(1, 0, 0).transformByQuaternion([0, 0, 0, 1]);
// or
const result = new Vector3();
const transformedVector2 = new Quaternion([1, 0, 0, 1]).transformByQuaternion([1, 0, 0], result);
```

The basic transformations are rotations, scalings, and translations.

One of the most powerful aspects of using matrices to manage transformations is that matrices can be multiplied together using linear algebra.

This allows us to build up a complex transformation by multiplying together component parts.

`Matrix4`

provides a number of transformation methods ('scale', 'rotate', 'translate', ...) that allow us to build transformation matrices. These can be applied to an identity matrix (e.g. a newly created `Matrix4`

) or to a matrix that already contains other transformations.

When composing (i.e. multiplying) matrices it is critical to consider the order in which they are being applied, as changing the order of component will in most cases change the resulting composite transformation. It is not hard to verify that this is consistent with geometric intuition by composing a few operations on paper.

Because of this the `Matrix4`

class provides two matrix multiplication methods: `multiplyLeft`

and `multiplyRight`

that force you to make explicit what you intend when multiplying two matrices.

All `Matrix4`

transformation methods ('scale', 'rotate', 'translate', ...) conceptually correspond to multiplying in a new transformation matrix from the right (although these methods internally are more efficient in that they don't create any temporary objects and they only do the minimal amount of changes to the matrix required for that specific transformation).

In the end, the point or vector to be transformed will be multiplied in from the right, which means that a typical composed transformation needs to be read in reverse order. I.e. in the example below, the vector will first be rotated, then transformed by the `partialTransform`

, then scaled.

```
// Illustrates that transformations are applied in reverse order
const partialTransform = new Matrix4(...);
const fullTransform = new Matrix4()
.scale([1, -1, 1])
.multiplyRight(partialTransform)
.rotateX({radians: Math.PI});
const v = fullTransform.transformVector(new Vector4(...));
```

For more in-depth background about rotations, see the separate article on rotations.

If you have a vector with 3 elements you can rotate it around an axis and a point like so:

`const v = new Vector3([1, 2, 3]).rotateZ({radians: ..., origin: [1, 1, 0]});`

The ability to compose transformations naturally leads to the possibility of *decomposing* a composite transformations into its constituent parts. This is possible, with certain caveats (not all matrices are directly decomposable into rotation, translation and scale. Shear is currently not handled).

Sepcifically, the math.gl `Matrix4`

object exposes the `getScale`

, `getTranslation`

and `getRotation`

(or `getRotationMatrix3`

) methods are provided for this purpose:

```
const transform = new Matrix4()
.translate([10, 10, 0])
.rotateX(Math.PI / 4)
.scale(5);
transform.getScale(); // [5, 5, 5]
transform.getTranslation(); // [ 10, 10, 0]
```