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> | Quaternion <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 Quaternion

Start quaternion.

endQuat Quaternion

End quaternion.

changeAmount number

Interpolation factor between 0.0 and 1.0.

workQuat Quaternion

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 Quaternion

source Quaternion to copy

dot(q) → {number}

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

Parameters:
Name Type Description
q Quaternion

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 Vector3

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 Vector3

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

Psi angle in radians (roll).

theta number

Theta angle in radians (yaw).

phi number

Phi angle in radians (pitch).

fromRotationMatrix(matrix) → {Quaternion}

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

Parameters:
Name Type Description
matrix Matrix3

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 Vector3

The source vector.

to Vector3

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

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 | Quaternion

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> | Quaternion <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 Quaternion

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 Vector3

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 Vector3

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 Matrix3 <optional>

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

toString() → {string}