# 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.

## Contents

### 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:

- Wikipedia: Quaternions and spatial rotation
- Wikipedia: Quaternion
- MathWorld: Quaternion

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* = *t* − *h*. 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

*Q*= cos_{w}*α*/2*Q*=_{x}*v*sin_{x}*α*/2*Q*=_{y}*v*sin_{y}*α*/2*Q*=_{z}*v*sin_{z}*α*/2

Additionally, a rotation quaternion must be normalized; that is, it must fulfill the **normal invariant** *Q _{w}*² +

*Q*² +

_{x}*Q*² +

_{y}*Q*² = 1. Unlike with property list scripting and specifications, quaternions will not be automatically normalized for you except where specified, but a

_{z}`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**.

functionconjugate() : 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`

functiondot(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`

functionmultiply(q : quaternionExpression) : Quaternion

Returns the standard quaternion product (Grassmann product) of the target and `q`

. This is used to concatenate rotations together.

`normalize`

functionnormalize() : 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`

functionrotate(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`

functionrotateX(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`

functionrotateY(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`

functionrotateZ(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`

functiontoArray() : 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`

functionvectorForward() : 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`

functionvectorRight() : Vector

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

for a definition.

`vectorUp`

functionvectorUp() : Vector

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

for a definition.

## Static Methods

`random`

functionrandom() : Quaternion

Returns a random normalized quaternion.