# Quaternion

## Quaternion

Quaternions provide a convenient mathematical notation for
representing orientations and rotations of objects in three dimensions.
Compared to Euler angles, Quaternions are simpler to compose and can help avoid the problem of gimbal lock.
Compared to rotation matrices, Quaternions are more numerically stable and the representation (4 numbers) is more compact.
Quaternions are non-commutative and provide a convenient way to interpolate between rotations (using the slerp function).

## Constructor

#### new Quaternion(…args)

##### Parameters:
Name Type Attributes Description
`args` number | Array.<Number> | <repeatable>

Initial values for the quaternion components.

### Members

#### mul

Deprecated:
• Deprecated as of 0.23.x Sets the quaternion's values from another quaternion's values; an alias for .mult

### Methods

#### (static) slerp(startQuat, endQuat, changeAmount, workQuat) → {Quaternion}

Computes the spherical linear interpolation between startQuat and endQuat.

##### Parameters:
Name Type Description
`startQuat`

Start quaternion.

`endQuat`

End quaternion.

`changeAmount` number

Interpolation factor between 0.0 and 1.0.

`workQuat`

Work quaternion.

#### clone() → {Quaternion}

Clones the quaternion

#### conjugate() → {Quaternion}

Conjugates this quaternion

#### copy(rhs) → {Quaternion}

copies the quaternion from the given one

##### Parameters:
Name Type Description
`rhs`

source Quaternion to copy

#### dot(q) → {number}

Calculates the dot product between the current quaternion and another quaternion.

##### Parameters:
Name Type Description
`q`

Quaternion on the right-hand side.

#### fromAngleAxis(angle, axis) → {Quaternion}

Sets the values of this quaternion to the values represented by a given angle and axis of rotation.
Note that this method creates an object, so use fromAngleNormalAxis if your axis is already normalized.
If axis == (0, 0, 0) the quaternion is set to Quaternion.IDENTITY.

##### Parameters:
Name Type Description
`angle` number

The angle to rotate (in radians).

`axis`

The axis of rotation.

#### fromAngleNormalAxis(angle, axis) → {Quaternion}

Sets the values of this quaternion to the values represented by a given angle and unit length axis of rotation.
If axis == (0, 0, 0) the quaternion is set to Quaternion.IDENTITY.

##### Parameters:
Name Type Description
`angle` number

The angle to rotate (in radians).

`axis`

The axis of rotation (already normalized - unit length).

#### fromAngles(psi, theta, phi)

Convert from euler angles to quaternion
NOTE: only support YZX euler angle order
Based on https://github.com/mrdoob/three.js/src/math/Quaternion.js
and https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19770024290.pdf

##### Parameters:
Name Type Description
`psi` number

`theta` number

`phi` number

#### fromRotationMatrix(matrix) → {Quaternion}

Sets the value of this quaternion to the rotation described by the given matrix values.

##### Parameters:
Name Type Description
`matrix`

Rotation matrix.

#### fromVectorToVector(from, to) → {Quaternion}

Sets this quaternion to the one that will rotate vector "from" into vector "to". Vectors do not have to be the same length.

##### Parameters:
Name Type Description
`from`

The source vector.

`to`

The destination vector into which to rotate the source vector.

#### invert() → {Quaternion}

Inverts this quaternion

#### mult(rhs) → {Quaternion}

Performs a multiplication between the current quaternion and another and stores the result locally.
The result is a quaternion product.

##### Parameters:
Name Type Description
`rhs`

Quaternion on the right-hand side.

#### negate() → {Quaternion}

Multiplies this quaternion's values by -1.

#### set(rhs) → {Quaternion}

sets the quaternion from the given arg(s)

##### Parameters:
Name Type Description
`rhs` number |

source to set the Quaternion

#### setAny(…args) → {Quaternion}

Sets a Quaternion given 4 numbers, an array, an {x, y, z, w} object or another Quaternion.
If no arguments are provided, the quaternion is set to Quaternion.IDENTITY.

##### Parameters:
Name Type Attributes Description
`args` number | Array.<Number> | <repeatable>

Values for the vector components.

#### setArray(array) → {Quaternion}

Set the quaternion components from an array (ordered x, y, z, w).

##### Parameters:
Name Type Description
`array` Array

#### setDirect(x, y, z, w) → {Quaternion}

Sets the vector's values from 4 numeric arguments

##### Parameters:
Name Type Description
`x` number
`y` number
`z` number
`w` number
##### Example
``````var q = new Quaternion(); // q == (0, 0, 0, 0)
q.setDirect(2, 4, 6, 8); // q == (2, 4, 6, 8)``````

#### slerp(endQuat, changeAmount) → {Quaternion}

Computes the spherical linear interpolation from the current quaternion towards endQuat.

##### Parameters:
Name Type Description
`endQuat`

End quaternion.

`changeAmount` number

Interpolation factor between 0.0 and 1.0.

#### toAngleAxis(axisStore) → {number}

Returns the rotation angle represented by this quaternion. If a non-null vector is provided, the axis of rotation is stored in
that vector as well.

##### Parameters:
Name Type Description
`axisStore`

The object to store the computed axis in. If null, no computations are done to determine axis.

#### toAngles(store) → {Quaternion}

Convert from quaternion to euler angles
NOTE: only support YZX euler angle order
Based on https://github.com/mrdoob/three.js/src/math/Quaternion.js
and https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19770024290.pdf

##### Parameters:
Name Type Description
`store`

Stores for the output angles in radians

#### toArray() → {Array.<number>}

Returns the components of the quaternion in array (length 4) form

#### toRotationMatrix(storeopt) → {Matrix3}

Return a rotation matrix representing the current quaternion.

##### Parameters:
Name Type Attributes Description
`store` <optional>

The matrix to store our result in. If null, a new matrix is created.