> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/api-reference/math-and-transform-types/matrix.md).

# Matrix

### Creating a Matrix

#### Identity Matrix

```python
matrix = sp.Matrix()
```

The default Matrix is an identity matrix.

```python
matrix.list()
```

returns:

```
[
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0
]
```

#### From a List

A Matrix can be created from a list of 16 values:

```python
matrix = sp.Matrix([
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 2.0, 3.0, 1.0
])
```

#### From a Translation

```python
matrix = sp.Matrix(
    sp.Vector(
        1.0,
        2.0,
        3.0
    )
)
```

#### From Axes and Translation

```python
matrix = sp.Matrix(
    sp.Vector(1.0, 0.0, 0.0),
    sp.Vector(0.0, 1.0, 0.0),
    sp.Vector(0.0, 0.0, 1.0),
    sp.Vector(4.0, 5.0, 6.0)
)
```

### `list()`

Returns the Matrix as a list of 16 floating-point values.

```python
values = matrix.list()
```

### Axis Vectors

The Matrix axes are available as `sp.Vector` values:

```python
matrix.xAxis
matrix.yAxis
matrix.zAxis
```

### `getTranslation()`

Returns the Matrix translation.

```python
translation = matrix.getTranslation()
```

Returns:

```
sp.Vector
```

### `getScale()`

Returns the Matrix scale.

```python
scale = matrix.getScale()
```

Returns:

```
sp.Vector
```

### `setTranslation()`

Changes the translation of an existing Matrix.

```python
matrix.setTranslation(
    sp.Vector(
        1.0,
        2.0,
        3.0
    )
)
```

Returns:

```
None
```

### `translation()`

Creates a translation Matrix.

```python
matrix = sp.Matrix.translation(
    sp.Vector(
        1.0,
        2.0,
        3.0
    )
)
```

Returns:

```
sp.Matrix
```

### Rotation Matrices

Matrix rotation functions use **radians**.

For example:

```python
import math

matrix = sp.Matrix.rotationX(
    math.radians(90.0)
)
```

The following single-axis functions are available:

```python
sp.Matrix.rotationX(angleRadians)
sp.Matrix.rotationY(angleRadians)
sp.Matrix.rotationZ(angleRadians)
```

Multi-axis rotation functions accept an `sp.Vector` containing Euler angles in radians:

```python
sp.Matrix.rotationXYZ(rotation)
sp.Matrix.rotationXZY(rotation)
sp.Matrix.rotationYXZ(rotation)
sp.Matrix.rotationYZX(rotation)
sp.Matrix.rotationZXY(rotation)
sp.Matrix.rotationZXZ(rotation)
sp.Matrix.rotationZYX(rotation)
```

For example:

```python
rotation = sp.Vector(
    math.radians(90.0),
    0.0,
    0.0
)

matrix = sp.Matrix.rotationXYZ(
    rotation
)
```

### Reading Rotation

Rotation values returned from a Matrix are also expressed in **radians**.

```python
rotation = matrix.getRotation()
```

Returns:

```
sp.Vector
```

Explicit Euler-order functions are also available:

```python
matrix.getRotationXYZ()
matrix.getRotationXZY()
matrix.getRotationYXZ()
matrix.getRotationYZX()
matrix.getRotationZXY()
matrix.getRotationZYX()
```

Each returns:

```
sp.Vector
```

### `inverse()`

Returns the inverse Matrix.

```python
inverse = matrix.inverse()
```

Returns:

```
sp.Matrix
```

### `transpose()`

Returns the transposed Matrix.

```python
transposed = matrix.transpose()
```

Returns:

```
sp.Matrix
```

### Matrix Multiplication

Two Matrix values can be multiplied:

```python
result = matrixA * matrixB
```

Returns:

```
sp.Matrix
```

A Matrix can also transform an `sp.Vector`:

```python
result = matrix * vector
```

Returns:

```
sp.Vector
```

For example:

```python
matrix = sp.Matrix.translation(
    sp.Vector(
        1.0,
        2.0,
        3.0
    )
)

vector = sp.Vector(
    4.0,
    5.0,
    6.0
)

result = matrix * vector
```

The resulting Vector is:

```
[5.0, 7.0, 9.0]
```

### Quick Reference

| API                             | Returns       |
| ------------------------------- | ------------- |
| `sp.Matrix()`                   | `sp.Matrix`   |
| `sp.Matrix(list)`               | `sp.Matrix`   |
| `sp.Matrix(translation)`        | `sp.Matrix`   |
| `list()`                        | `list[float]` |
| `xAxis`, `yAxis`, `zAxis`       | `sp.Vector`   |
| `getTranslation()`              | `sp.Vector`   |
| `getScale()`                    | `sp.Vector`   |
| `setTranslation(vector)`        | `None`        |
| `sp.Matrix.translation(vector)` | `sp.Matrix`   |
| `sp.Matrix.rotationX/Y/Z(...)`  | `sp.Matrix`   |
| `sp.Matrix.rotationXYZ(...)`    | `sp.Matrix`   |
| `getRotation()`                 | `sp.Vector`   |
| `getRotationXYZ()`              | `sp.Vector`   |
| `inverse()`                     | `sp.Matrix`   |
| `transpose()`                   | `sp.Matrix`   |
| `matrix * matrix`               | `sp.Matrix`   |
| `matrix * vector`               | `sp.Vector`   |

{% hint style="warning" %}
Matrix rotation functions and rotation values use radians.
{% endhint %}