Quaternion - Verge3D User Manual - Soft8Soft
Description: Learn how to use Quaternion in your interactive 3D apps made with Verge3D

# Quaternion

Implementation of quaternion 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);`

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

### # .slerpQuaternions(qa : Quaternion, qb : Quaternion, t : Float) → this

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

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