Quaternion

Implementation of a quaternion. This is used for rotating things without encountering the dreaded gimbal lock issue, amongst other advantages.

Example

var quaternion = new v3d.Quaternion(); quaternion.setFromAxisAngle(new v3d.Vector3(0, 1, 0), Math.PI / 2); var 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

.x : Float

Changing this property will result in onChangeCallback being called.

.y : Float

Changing this property will result in onChangeCallback being called.

.z : Float

Changing this property will result in onChangeCallback being called.

.w : Float

Changing this property will result in onChangeCallback being called.

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

.copy (q : Quaternion) : Quaternion

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) : Quaternion

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.

.inverse () : Quaternion

Inverts this quaternion - calculate the conjugate and then normalizes the result.

.length () : Float

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

.lengthSq () : Float

Computes the 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 () : Quaternion

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) : Quaternion

Multiplies this quaternion by q.

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

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

.onChange (onChangeCallback : Function) : Quaternion

Sets the onChangeCallback() method.

.onChangeCallback () : Quaternion

This function is called whenever any of the following occurs:

By default it is the empty function, however you can change it if needed using onChange(onChangeCallback).

.premultiply (q : Quaternion) : Quaternion

Pre-multiplies this quaternion by q.

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

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) : Quaternion

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) : Quaternion

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

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

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) : Quaternion

Sets this quaternion from the rotation specified by Euler angle.

.setFromRotationMatrix (m : Matrix4) : Quaternion

Sets this quaternion from rotation component of m.
Adapted from the method here.

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

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 (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].

Static Methods

Static methods (as opposed to instance methods) are designed to be called directly from the class, rather than from a specific instance. So to use the static version of, call it like so: v3d.Quaternion.slerp(qStart, qEnd, qTarget, t); By contrast, to call the 'normal' or instanced slerp method, you would do the following: //instantiate a quaternion with default values var q = new v3d.Quaternion(); //call the instanced slerp method q.slerp(qb, t)

.slerp (qStart : Quaternion, qEnd : Quaternion, qTarget : Quaternion, t : Float) : Quaternion

qStart - The starting quaternion (where t is 0)
qEnd - The ending quaternion (where t is 1)
qTarget - The target quaternion that gets set with the result
t - interpolation factor in the closed interval [0, 1].

Unlike the normal method, the static version of slerp sets a target quaternion to the result of the slerp operation. // Code setup var startQuaternion = new v3d.Quaternion().set(0, 0, 0, 1).normalize(); var endQuaternion = new v3d.Quaternion().set(1, 1, 1, 1).normalize(); var t = 0; // Update a mesh's rotation in the loop t = (t + 0.01) % 1; // constant angular momentum v3d.Quaternion.slerp(startQuaternion, endQuaternion, mesh.quaternion, t);

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

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 quatnerion.
srcOffset1 - An offset into the array src1.
t - Normalized interpolation factor (between 0 and 1).

Like the static slerp method above, but operates directly on flat arrays of numbers.

Source

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