Oolite JavaScript Reference: Quaternion

Prototype: `Object`
Subtypes: none

The `Quaternion` class represents a quaternion, a four-dimensional number, which is used to express rotations. Explaining quaternion mathematics is way beyond the scope of this document, but a quick overview is provided below.

Quaternions for Rotations

This is a very quick, pragmatic discussion of quaternions as they apply to rotating things in Oolite. If you’re interested in the theory, see:

Consider a ship at point h oriented to face a station at point t. This can be expressed as the vector from the ship to the station, v = th. However, if the ship rolls, it is still heading along the same vector v, so additional information is required: a twist angle, α. A rotation quaternion is a tuple Q = (w, x, y, z), such that

Qw = cos α/2
Qx = vx sin α/2
Qy = vy sin α/2
Qz = vz sin α/2

Additionally, a rotation quaternion must be normalized; that is, it must fulfill the normal invariant Qw² + Qx² + Qy² + Qz² = 1. Unlike with property list scripting and specifications, quaternions will not be automatically normalized for you except where specified, but a `normalize()` method is provided.

An identity rotation – that is, one which, when applied, has no effect – is represented by the identity quaternion (1, 0, 0, 0). Often you will want to start with this identity quaternion before applying the methods rotate, rotateX, rotateY or rotateZ.

The `Quaternion` class provides several methods to make construction of rotations easier: `rotate()`, `rotateX()`, `rotateY()`, `rotateZ()`.

Rotations can be combined by quaternion multiplication (see the `multiply()` method). Note that quaternion multiplication is not commutative; that is, PQ is not the same as QP. If this seems strange, take a box or book and assign it x, y and z axes. Rotate it about the x axis and then the y axis. Then, rotate it about the y axis followed by the x axis. If the results of the two rotations are the same, you’re doing it wrong.

The Quaternion calculator is a very useful spreadsheet to get quaternions from rotation angles.

Quaternion Expressions

All Oolite-provided functions which take a quaternion as an argument may instead be passed an array of four numbers, or an Entity (in which case the entity’s `orientation` is used). In specifications, this is represented by arguments typed `quaternionExpression`.

Properties

`w`

```w : Number (read/write)
```

The w component of the quaternion.

`x`

```x : Number (read/write)
```

The x component of the quaternion.

`y`

```y : Number (read/write)
```

The y component of the quaternion.

`z`

```z : Number (read/write)
```

The z component of the quaternion.

Methods

Constructor

```new Quaternion([value : quaternionExpression])
```

Create a new quaternion with the specified value. If no value is provided, the quaternion is initialized to the identity quaternion (1, 0, 0, 0).

Note: in version 1.77 or earlier, the quaternion is incorrectly initialised to the zero quaternion (0, 0, 0, 0) if no value is provided. For portability you should therefore provide a value to the constructor.

`conjugate`

This method was added in Oolite test release 1.77.

```function conjugate() : Quaternion
```

Return the conjugate of the quaternion (i.e. the quaternion which when multiplied by the original quaternion returns the identity quaternion). The input quaternion must be normalized.

`dot`

```function dot(q : quaternionExpression) : Number
```

Returns the quaternion dot product (inner product) of the target and `q`. (For two normalized quaternions, this will be 1 if they’re equal, -1 if they’re opposite and 0 if they’re perpendicular.)

`multiply`

```function multiply(q : quaternionExpression) : Quaternion
```

Returns the standard quaternion product (Grassmann product) of the target and `q`. This is used to concatenate rotations together.

`normalize`

```function normalize() : Quaternion
```

Returns the quaternion adjusted to fulfill the normal invariant. Specifically, this divides each component by the square root of (w² + x² + y² + z²).

`rotate`

```function rotate(a : vectorExpression, angle : Number) : Quaternion
```

Returns a quaternion rotated `angle` radians about the axis of `a`. The vector `a` must be a normalized vector. A positive angle is anti-clockwise if the vector is pointing towards you.

`rotateX`

```function rotateX(angle : Number) : Quaternion
```

Returns a quaternion rotated `angle` radians about the x axis. A positive angle is anti-clockwise if the x axis is pointing towards you.

`q.rotateX(angle)` is equivalent to `q.rotate([1, 0, 0], angle)`.

`rotateY`

```function rotateY(angle : Number) : Quaternion
```

Returns a quaternion rotated `angle` radians about the y axis. A positive angle is anti-clockwise if the y axis is pointing towards you.

`q.rotateY(angle)` is equivalent to `q.rotate([0, 1, 0], angle)`.

`rotateZ`

```function rotateZ(angle : Number) : Quaternion
```

Returns a quaternion rotated `angle` radians about the z axis. A positive angle is anti-clockwise if the z axis is pointing towards you.

`q.rotateZ(angle)` is equivalent to `q.rotate([0, 0, 1], angle)`.

`toArray`

```function toArray() : Array
```

Returns an array of the quaternion’s components, in the order `[w, x, y, z]`. `q.toArray()` is equivalent to `[q.w, q.x, q.y, q.z]`.

`vectorForward`

```function vectorForward() : Vector
```

Returns the forward vector from the quaternion.

To understand this, consider an entity which is aligned with the world co-ordinate system – that is, its `orientation` is the identity quaternion (1, 0, 0, 0), and thus its x axis is aligned with the world x axis, its y axis is aligned with the world y axis and its z axis is aligned with the world z axis. If it is rotated by a quaternion Q, `Q.vectorForward()` is the forward (z) axis after rotation. Similarly, `Q.vectorUp()` is the up (y) axis after rotation, and `Q.vectorRight()` is the right (x) axis after rotation.

`vectorRight`

```function vectorRight() : Vector
```

Returns the right vector from the quaternion. See `vectorForward()` for a definition.

`vectorUp`

```function vectorUp() : Vector
```

Returns the up vector from the quaternion. See `vectorForward()` for a definition.

Static Methods

`random`

```function random() : Quaternion
```

Returns a random normalized quaternion.