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.

.x : Float

.y : Float

.z : Float

.w : Float

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.

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

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.

Source

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