Skip to main content

Quaternion

Implementation of a quaternion.
Quaternions are used in three.js to represent rotations.

Iterating through a Quaternion instance will yield its components (x, y, z, w) in the corresponding order.

Code Example​

const quaternion = new THREE.Quaternion(); quaternion.setFromAxisAngle( new
THREE.Vector3( 0, 1, 0 ), Math.PI / 2 ); const vector = new THREE.Vector3( 1,
0, 0 ); vector.applyQuaternion( quaternion );

Constructor​

Quaternion​

function Quaternion( x: Float, y: Float, z: Float, w: Float ): void;

x - x coordinate
y - y coordinate
z - z coordinate
w - w coordinate

Properties​

isQuaternion​

isQuaternion: Boolean;

Read-only flag to check if a given object is of type Quaternion.

x​

x: Float;

y​

y: Float;

z​

z: Float;

w​

w: Float;

Methods​

angleTo​

function angleTo( q: Quaternion ): Float;

Returns the angle between this quaternion and quaternion q in radians.

clone​

function clone( ): Quaternion;

Creates a new Quaternion with identical .x, .y, .z and .w properties to this one.

conjugate​

function conjugate( ): this;

Returns the rotational conjugate of this quaternion. The conjugate of a quaternion represents the same rotation in the opposite direction about the rotational axis.

copy​

function copy( q: Quaternion ): this;

Copies the .x, .y, .z and .w properties of .uaternion into this quaternion.

equals​

function equals( v: Quaternion ): Boolean;

v - Quaternion that this quaternion will be compared to.

Compares the .x, .y, .z and .w properties of .uaternion to the equivalent properties of this quaternion to determine if they represent the same rotation.

dot​

function dot( v: Quaternion ): Float;

Calculates the dot product of quaternions v and this one.

fromArray​

function fromArray( array: Array, offset: Integer ): this;

array - array of format (x, y, z, w) used to construct the quaternion.
offset - (optional) an offset into the array.

Sets this quaternion's .x, .y, .z and .w properties from an array.

identity​

function identity( ): this;

Sets this quaternion to the identity quaternion; that is, to the quaternion that represents "no rotation".

invert​

function invert( ): this;

Inverts this quaternion - calculates the .conjugate. The quaternion is assumed to have unit length.

length​

function length( ): Float;

Computes the Euclidean length (straight-line length) of this quaternion, considered as a 4 dimensional vector.

lengthSq​

function lengthSq( ): Float;

Computes the squared Euclidean length (straight-line length) of this quaternion, considered as a 4 dimensional vector. This can be useful if you are comparing the lengths of two quaternions, as this is a slightly more efficient calculation than .length().

normalize​

function normalize( ): this;

Normalizes this quaternion - that is, calculated the quaternion that performs the same rotation as this one, but has .length equal to 1.

multiply​

function multiply( q: Quaternion ): this;

Multiplies this quaternion by q.

multiplyQuaternions​

function multiplyQuaternions( a: Quaternion, b: Quaternion ): this;

Sets this quaternion to a x b.
Adapted from the method outlined here.

premultiply​

function premultiply( q: Quaternion ): this;

Pre-multiplies this quaternion by q.

random​

function random( ): this;

Sets this quaternion to a uniformly random, normalized quaternion.

rotateTowards​

function rotateTowards( q: Quaternion, step: Float ): this;

q - The target quaternion.
step - The angular step in radians.

Rotates this quaternion by a given angular step to the defined quaternion q. The method ensures that the final quaternion will not overshoot q.

slerp​

function slerp( qb: Quaternion, t: Float ): this;

qb - The other quaternion rotation
t - interpolation factor in the closed interval [0, 1].

Handles the spherical linear interpolation between quaternions. t represents the amount of rotation between this quaternion (where t is 0) and qb (where t is 1). This quaternion is set to the result. Also see the static version of the slerp below.

// rotate a mesh towards a target quaternion mesh.quaternion.slerp(
endQuaternion, 0.01 );

slerpQuaternions​

function slerpQuaternions( qa: Quaternion, qb: Quaternion, t: Float ): this;

Performs a spherical linear interpolation between the given quaternions and stores the result in this quaternion.

set​

function set( x: Float, y: Float, z: Float, w: Float ): this;

Sets .x, .y, .z, .w properties of this quaternion.

setFromAxisAngle​

function setFromAxisAngle( axis: Vector3, angle: Float ): this;

Sets this quaternion from rotation specified by axis and angle.
Adapted from the method here.
Axis is assumed to be normalized, angle is in radians.

setFromEuler​

function setFromEuler( euler: Euler ): this;

Sets this quaternion from the rotation specified by Euler angle.

setFromRotationMatrix​

function setFromRotationMatrix( m: Matrix4 ): this;

m - a Matrix4 of which the upper 3x3 of matrix is a pure rotation matrix (i.e. unscaled).
Sets this quaternion from rotation component of m.
Adapted from the method here.

setFromUnitVectors​

function setFromUnitVectors( vFrom: Vector3, vTo: Vector3 ): this;

Sets this quaternion to the rotation required to rotate direction vector vFrom to direction vector vTo.
Adapted from the method here.
vFrom and vTo are assumed to be normalized.

toArray​

function toArray( array: Array, offset: Integer ): Array;

array - An optional array to store the quaternion. If not specified, a new array will be created.
offset - (optional) if specified, the result will be copied into this Array.

Returns the numerical elements of this quaternion in an array of format [x, y, z, w].

toJSON​

function toJSON( ): Array;

This methods defines the serialization result of Quaternion. Returns the numerical elements of this quaternion in an array of format [x, y, z, w].

fromBufferAttribute​

function fromBufferAttribute( attribute: BufferAttribute, index: Integer ):
this;

attribute - the source attribute.
index - index in the attribute.

Sets .x, .y, .z, .w properties of this quaternion from the .ufferAttribute.

Static Methods​

slerpFlat​

function slerpFlat( dst: Array, dstOffset: Integer, src0: Array, srcOffset0:
Integer, src1: Array, srcOffset1: Integer, t: Float ): undefined;

dst - The output array.
dstOffset - An offset into the output array.
src0 - The source array of the starting quaternion.
srcOffset0 - An offset into the array src0.
src1 - The source array of the target quaternion.
srcOffset1 - An offset into the array src1.
t - Normalized interpolation factor (between 0 and 1).

This SLERP implementation assumes the quaternion data are managed in flat arrays.

multiplyQuaternionsFlat​

function multiplyQuaternionsFlat( dst: Array, dstOffset: Integer, src0: Array,
srcOffset0: Integer, src1: Array, srcOffset1: Integer ): Array;

dst - The output array.
dstOffset - An offset into the output array.
src0 - The source array of the starting quaternion.
srcOffset0 - An offset into the array src0.
src1 - The source array of the target quaternion.
srcOffset1 - An offset into the array src1.

This multiplication implementation assumes the quaternion data are managed in flat arrays.

Note: Do not add non-static methods to the bottom of this page. Put them above the

Static Methods

Source​

src/math/Quaternion.js