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
