> 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/quaternion.md).

# Quaternion

### Creating a Quaternion

#### Identity Quaternion

```python
quaternion = sp.Quaternion()
```

The default value is:

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

#### From Components

```python
quaternion = sp.Quaternion(
    0.0,
    0.0,
    0.0,
    1.0
)
```

The component order is:

```
[x, y, z, w]
```

#### From a List

```python
quaternion = sp.Quaternion(
    [0.0, 0.0, 0.0, 1.0]
)
```

#### From Vector and Scalar

```python
quaternion = sp.Quaternion(
    sp.Vector(
        0.0,
        0.0,
        0.0
    ),
    1.0
)
```

### Components

Individual quaternion components can be read through:

```python
quaternion.x
quaternion.y
quaternion.z
quaternion.w
```

The Vector component is available through:

```python
quaternion.vector
```

Returns:

```
sp.Vector
```

The scalar component is available through:

```python
quaternion.scalar
```

Returns:

```
float
```

### `list()`

Returns the Quaternion as:

```
[x, y, z, w]
```

Example:

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

### Euler Conversion

#### `fromEuler()`

Creates a Quaternion from Euler rotation values.

The Euler values use **radians**.

```python
import math

quaternion = sp.Quaternion.fromEuler(
    sp.Vector(
        math.radians(90.0),
        0.0,
        0.0
    )
)
```

Returns:

```
sp.Quaternion
```

#### `toEuler()`

Converts the Quaternion back to Euler rotation.

```python
rotation = quaternion.toEuler()
```

Returns:

```
sp.Vector
```

The returned values are in **radians**.

### Matrix Conversion

#### `toMatrix()`

Converts a Quaternion to a Matrix.

```python
matrix = quaternion.toMatrix()
```

Returns:

```
sp.Matrix
```

#### `fromMatrix()`

Creates a Quaternion from a Matrix.

```python
quaternion = sp.Quaternion.fromMatrix(
    matrix
)
```

Returns:

```
sp.Quaternion
```

### Rotation Vectors

#### `fromRotationVector()`

Creates a Quaternion from a rotation Vector.

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

quaternion = sp.Quaternion.fromRotationVector(
    rotation
)
```

Returns:

```
sp.Quaternion
```

#### `toRotationVector()`

Converts the Quaternion to a rotation Vector.

```python
rotation = quaternion.toRotationVector()
```

Returns:

```
sp.Vector
```

The rotation Vector uses radians.

### `length()`

Returns the Quaternion length.

```python
length = quaternion.length()
```

Returns:

```
float
```

### `normalised()`

Returns a normalized Quaternion.

```python
normalised = quaternion.normalised()
```

Returns:

```
sp.Quaternion
```

### `dot()`

Calculates the dot product between two Quaternions.

```python
result = quaternionA.dot(
    quaternionB
)
```

Returns:

```
float
```

### `slerped()`

Performs spherical linear interpolation between two Quaternions.

```python
result = sp.Quaternion.slerped(
    quaternionA,
    quaternionB,
    0.5
)
```

Returns:

```
sp.Quaternion
```

For example, interpolating halfway between rotations of `0°` and `90°` produces a rotation of approximately `45°`.

### `setToSlerp()`

Sets an existing Quaternion to the interpolated result between two Quaternions.

```python
result = sp.Quaternion()

result.setToSlerp(
    quaternionA,
    quaternionB,
    0.5
)
```

`setToSlerp()` returns:

```
None
```

The Quaternion instance itself is updated.

### Quaternion Multiplication

Two Quaternion values can be multiplied:

```python
result = quaternionA * quaternionB
```

Returns:

```
sp.Quaternion
```

{% hint style="info" %}
Multiplication between `sp.Quaternion` and `sp.Vector` is not supported through the `*` operator.
{% endhint %}

### Quick Reference

| API                          | Returns         |
| ---------------------------- | --------------- |
| `sp.Quaternion()`            | `sp.Quaternion` |
| `sp.Quaternion(x, y, z, w)`  | `sp.Quaternion` |
| `sp.Quaternion(list)`        | `sp.Quaternion` |
| `.x`, `.y`, `.z`, `.w`       | `float`         |
| `.vector`                    | `sp.Vector`     |
| `.scalar`                    | `float`         |
| `list()`                     | `list[float]`   |
| `fromEuler(vector)`          | `sp.Quaternion` |
| `toEuler()`                  | `sp.Vector`     |
| `fromMatrix(matrix)`         | `sp.Quaternion` |
| `toMatrix()`                 | `sp.Matrix`     |
| `fromRotationVector(vector)` | `sp.Quaternion` |
| `toRotationVector()`         | `sp.Vector`     |
| `length()`                   | `float`         |
| `normalised()`               | `sp.Quaternion` |
| `dot(quaternion)`            | `float`         |
| `slerped(a, b, amount)`      | `sp.Quaternion` |
| `setToSlerp(a, b, amount)`   | `None`          |
| `quaternion * quaternion`    | `sp.Quaternion` |

{% hint style="warning" %}
Euler and rotation Vector conversions use radians.
{% endhint %}