Quaternion

Class for representing a Quaternion. Quaternions are used in three.js to represent rotations.

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

Note that three.js expects Quaternions to be normalized.

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

new Quaternion( x : number, y : number, z : number, w : number )

Constructs a new quaternion.

x

The x value of this quaternion.

Default is 0.
y

The y value of this quaternion.

Default is 0.
z

The z value of this quaternion.

Default is 0.
w

The w value of this quaternion.

Default is 1.

Properties

.isQuaternion : boolean (readonly)

This flag can be used for type testing.

Default is true.

.w : number

The w value of this quaternion.

Default is 1.

.x : number

The x value of this quaternion.

Default is 0.

.y : number

The y value of this quaternion.

Default is 0.

.z : number

The z value of this quaternion.

Default is 0.

Methods

.angleTo( q : Quaternion ) : number

Returns the angle between this quaternion and the given one in radians.

q

The quaternion to compute the angle with.
Returns: The angle in radians.

.clone() : Quaternion

Returns a new quaternion with copied values from this instance.

Returns: A clone of this instance.

.conjugate() : Quaternion

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

Returns: A reference to this quaternion.

.copy( quaternion : Quaternion ) : Quaternion

Copies the values of the given quaternion to this instance.

quaternion

The quaternion to copy.
Returns: A reference to this quaternion.

.dot( v : Quaternion ) : number

Calculates the dot product of this quaternion and the given one.

v

The quaternion to compute the dot product with.
Returns: The result of the dot product.

.equals( quaternion : Quaternion ) : boolean

Returns true if this quaternion is equal with the given one.

quaternion

The quaternion to test for equality.
Returns: Whether this quaternion is equal with the given one.

.fromArray( array : Array.<number>, offset : number ) : Quaternion

Sets this quaternion's components from the given array.

array

An array holding the quaternion component values.
offset

The offset into the array.

Default is 0.
Returns: A reference to this quaternion.

.fromBufferAttribute( attribute : BufferAttribute, index : number ) : Quaternion

Sets the components of this quaternion from the given buffer attribute.

attribute

The buffer attribute holding quaternion data.
index

The index into the attribute.
Returns: A reference to this quaternion.

.identity() : Quaternion

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

Returns: A reference to this quaternion.

.invert() : Quaternion

Inverts this quaternion via Quaternion#conjugate. The quaternion is assumed to have unit length.

Returns: A reference to this quaternion.

.length() : number

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

Returns: The Euclidean length.

.lengthSq() : number

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

Returns: The squared Euclidean length.

.multiply( q : Quaternion ) : Quaternion

Multiplies this quaternion by the given one.

q

The quaternion.
Returns: A reference to this quaternion.

.multiplyQuaternions( a : Quaternion, b : Quaternion ) : Quaternion

Multiplies the given quaternions and stores the result in this instance.

a

The first quaternion.
b

The second quaternion.
Returns: A reference to this quaternion.

.normalize() : Quaternion

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

Returns: A reference to this quaternion.

.premultiply( q : Quaternion ) : Quaternion

Pre-multiplies this quaternion by the given one.

q

The quaternion.
Returns: A reference to this quaternion.

.random() : Quaternion

Sets this quaternion to a uniformly random, normalized quaternion.

Returns: A reference to this quaternion.

.rotateTowards( q : Quaternion, step : number ) : Quaternion

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

q

The target quaternion.
step

The angular step in radians.
Returns: A reference to this quaternion.

.set( x : number, y : number, z : number, w : number ) : Quaternion

Sets the quaternion components.

x

The x value of this quaternion.
y

The y value of this quaternion.
z

The z value of this quaternion.
w

The w value of this quaternion.
Returns: A reference to this quaternion.

.setFromAxisAngle( axis : Vector3, angle : number ) : Quaternion

Sets this quaternion from the given axis and angle.

axis

The normalized axis.
angle

The angle in radians.
Returns: A reference to this quaternion.

.setFromEuler( euler : Euler, update : boolean ) : Quaternion

Sets this quaternion from the rotation specified by the given Euler angles.

euler

The Euler angles.
update

Whether the internal onChange callback should be executed or not.

Default is true.
Returns: A reference to this quaternion.

.setFromRotationMatrix( m : Matrix4 ) : Quaternion

Sets this quaternion from the given rotation matrix.

m

A 4x4 matrix of which the upper 3x3 of matrix is a pure rotation matrix (i.e. unscaled).
Returns: A reference to this quaternion.

.setFromUnitVectors( vFrom : Vector3, vTo : Vector3 ) : Quaternion

Sets this quaternion to the rotation required to rotate the direction vector vFrom to the direction vector vTo.

vFrom

The first (normalized) direction vector.
vTo

The second (normalized) direction vector.
Returns: A reference to this quaternion.

.slerp( qb : Quaternion, t : number ) : Quaternion

Performs a spherical linear interpolation between quaternions.

qb

The target quaternion.
t

The interpolation factor in the closed interval [0, 1].
Returns: A reference to this quaternion.

.slerpQuaternions( qa : Quaternion, qb : Quaternion, t : number ) : Quaternion

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

qa

The source quaternion.
qb

The target quaternion.
t

The interpolation factor in the closed interval [0, 1].
Returns: A reference to this quaternion.

.toArray( array : Array.<number>, offset : number ) : Array.<number>

Writes the components of this quaternion to the given array. If no array is provided, the method returns a new instance.

array

The target array holding the quaternion components.

Default is [].
offset

Index of the first element in the array.

Default is 0.
Returns: The quaternion components.

.toJSON() : Array.<number>

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

Returns: The serialized quaternion.

Static Methods

.multiplyQuaternionsFlat( dst : Array.<number>, dstOffset : number, src0 : Array.<number>, srcOffset0 : number, src1 : Array.<number>, srcOffset1 : number ) : Array.<number>

Multiplies two quaternions. This implementation assumes the quaternion data are managed in flat arrays.

dst

The destination array.
dstOffset

An offset into the destination array.
src0

The source array of the first quaternion.
srcOffset0

An offset into the first source array.
src1

The source array of the second quaternion.
srcOffset1

An offset into the second source array.
See:
Returns: The destination array.

.slerpFlat( dst : Array.<number>, dstOffset : number, src0 : Array.<number>, srcOffset0 : number, src1 : Array.<number>, srcOffset1 : number, t : number )

Interpolates between two quaternions via SLERP. This implementation assumes the quaternion data are managed in flat arrays.

dst

The destination array.
dstOffset

An offset into the destination array.
src0

The source array of the first quaternion.
srcOffset0

An offset into the first source array.
src1

The source array of the second quaternion.
srcOffset1

An offset into the second source array.
t

The interpolation factor in the range [0,1].
See:

Source

src/math/Quaternion.js