Quaternion

Implementation of a quaternion.

Quaternions are used in Verge3D 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 v3d.Quaternion();
    quaternion.setFromAxisAngle(new v3d.Vector3(0, 1, 0), Math.PI / 2);

    const vector = new v3d.Vector3(1, 0, 0);
    vector.applyQuaternion(quaternion);

Constructor

Quaternion(x : Float, y : Float, z : Float, w : Float)

x — x coordinate.
y — y coordinate.
z — z coordinate.
w — w coordinate.

Properties

# .isQuaternion : Boolean

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

Methods

# .angleTo(q : Quaternion) → Float

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

# .clone() → Quaternion

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

# .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(q : Quaternion) → this

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

# .equals(v : Quaternion) → Boolean

v — Quaternion that this quaternion will be compared to.

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

# .dot(v : Quaternion) → Float

Calculates the dot product of quaternions v and this one.

# .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() → this

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

# .invert() → this

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

# .length() → Float

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

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() → this

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

# .multiply(q : Quaternion) → this

Multiplies this quaternion by q.

# .multiplyQuaternions(a : Quaternion, b : Quaternion) → this

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

# .premultiply(q : Quaternion) → this

Pre-multiplies this quaternion by q.

# .random() → this

Sets this quaternion to a uniformly random, normalized quaternion.

# .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(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(qa : Quaternion, qb : Quaternion, t : Float) → this

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

# .set(x : Float, y : Float, z : Float, w : Float) → this

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

# .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(euler : Euler) → this

Sets this quaternion from the rotation specified by Euler angle.

# .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(vFrom : Vector3, vTo : Vector3) → this

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

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

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

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

Static Methods

# .slerpFlat(dst : Array, dstOffset : Integer, src0 : Array, srcOffset0 : Integer, src1 : Array, srcOffset1 : Integer, t : Float)

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(dst : Array, dstOffset : Integer, src0 : Array, srcOffset0 : Integer, src1 : Array, srcOffset1 : Integer) → Array

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

Source

For more info on how to obtain the source code of this module see this page.