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

Used to check whether this or derived classes are Quaternions. Default is true.

You should not change this, as it is used internally for optimisation.

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

• The x, y, z or w properties are changed.
• The set(), copy(), clone(), setFromAxisAngle(), setFromRotationMatrix(), conjugate(), normalize(), multiplyQuaternions(), slerp() or fromArray() functions are called.
• setFromEuler() function is called with its update argument set to true.

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: THREE.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 THREE.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 THREE.Quaternion().set( 0, 0, 0, 1 ).normalize(); var endQuaternion = new THREE.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 THREE.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

src/math/Quaternion.js