[name]
Implementation of a [link:http://en.wikipedia.org/wiki/Quaternion quaternion].
This is used for [link:https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation rotating things]
without encountering the dreaded
[link:http://en.wikipedia.org/wiki/Gimbal_lock 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
[name]( [param:Float x], [param:Float y], [param:Float z], [param:Float w] )
[page:Float x] - x coordinate
[page:Float y] - y coordinate
[page:Float z] - z coordinate
[page:Float w] - w coordinate
Properties
[property:Float x]
Changing this property will result in [page:.onChangeCallback onChangeCallback] being called.
[property:Float y]
Changing this property will result in [page:.onChangeCallback onChangeCallback] being called.
[property:Float z]
Changing this property will result in [page:.onChangeCallback onChangeCallback] being called.
[property:Float w]
Changing this property will result in [page:.onChangeCallback onChangeCallback] being called.
Methods
[method:Quaternion clone]()
Creates a new Quaternion with identical [page:.x x], [page:.y y],
[page:.z z] and [page:.w w] properties to this one.
[method:Quaternion conjugate]()
Returns the rotational conjugate of this quaternion. The conjugate of a quaternion
represents the same rotation in the opposite direction about the rotational axis.
[method:Quaternion copy]( [param:Quaternion q] )
Copies the [page:.x x], [page:.y y], [page:.z z] and [page:.w w] properties
of [page:Quaternion q] into this quaternion.
[method:Boolean equals]( [param:Quaternion v] )
[page:Quaternion v] - Quaternion that this quaternion will be compared to.
Compares the [page:.x x], [page:.y y], [page:.z z] and [page:.w w] properties of
[page:Quaternion v] to the equivalent properties of this quaternion to determine if they
represent the same rotation.
[method:Float dot]( [param:Quaternion v] )
Calculates the [link:https://en.wikipedia.org/wiki/Dot_product dot product] of
quaternions [page:Quaternion v] and this one.
[method:Quaternion fromArray]( [param:Array array], [param:Integer offset] )
[page:Array array] - array of format (x, y, z, w) used to construct the quaternion.
[page:Integer offset] - (optional) an offset into the array.
Sets this quaternion's [page:.x x], [page:.y y], [page:.z z] and [page:.w w] properties
from an array.
[method:Quaternion inverse]()
Inverts this quaternion - calculate the [page:.conjugate conjugate] and then
[page:.normalize normalizes] the result.
[method:Float length]()
Computes the [link:https://en.wikipedia.org/wiki/Euclidean_distance Euclidean length]
(straight-line length) of this quaternion, considered as a 4 dimensional vector.
[method:Float lengthSq]()
Computes the [link:https://en.wikipedia.org/wiki/Euclidean_distance 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 [page:.length length]().
[method:Quaternion normalize]()
[link:https://en.wikipedia.org/wiki/Normalized_vector Normalizes] this quaternion - that is,
calculated the quaternion that performs the same rotation as this one, but has [page:.length length]
equal to *1*.
[method:Quaternion multiply]( [param:Quaternion q] )
Multiplies this quaternion by [page:Quaternion q].
[method:Quaternion multiplyQuaternions]( [param:Quaternion a], [param:Quaternion b] )
Sets this quaternion to [page:Quaternion a] x [page:Quaternion b].
Adapted from the method outlined [link:http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/code/index.htm here].
[method:Quaternion onChange]( [param:Function onChangeCallback] )
Sets the [page:.onChangeCallback onChangeCallback]() method.
[method:Quaternion onChangeCallback]( )
This function is called whenever any of the following occurs:
-
The [page:.x x], [page:.y y], [page:.z z] or
[page:.w w] properties are changed.
-
The [page:.set set](), [page:.copy copy](), [page:.clone clone](),
[page:.setFromAxisAngle setFromAxisAngle](), [page:.setFromRotationMatrix setFromRotationMatrix](),
[page:.conjugate conjugate](), [page:.normalize normalize](),
[page:.multiplyQuaternions multiplyQuaternions](), [page:.slerp slerp]() or [page:.fromArray fromArray]()
functions are called.
-
[page:.setFromEuler 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 [page:.onChange onChange]( [page:Function onChangeCallback] ).
[method:Quaternion premultiply]( [param:Quaternion q] )
Pre-multiplies this quaternion by [page:Quaternion q].
[method:Quaternion slerp]( [param:Quaternion qb], [param:float t] )
[page:Quaternion qb] - The other quaternion rotation
[page:float t] - interpolation factor in the closed interval [0, 1].
Handles the spherical linear interpolation between quaternions. [page:float t] represents the
amount of rotation between this quaternion (where [page:float t] is 0) and [page:Quaternion qb] (where
[page:float 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 );
[method:Quaternion set]( [param:Float x], [param:Float y], [param:Float z], [param:Float w] )
Sets [page:.x x], [page:.y y], [page:.z z], [page:.w w] properties of this quaternion.
[method:Quaternion setFromAxisAngle]( [param:Vector3 axis], [param:Float angle] )
Sets this quaternion from rotation specified by [page:Vector3 axis] and [page:Float angle].
Adapted from the method [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/angleToQuaternion/index.htm here].
*Axis* is assumed to be normalized, *angle* is in radians.
[method:Quaternion setFromEuler]( [param:Euler euler] )
Sets this quaternion from the rotation specified by [page:Euler] angle.
[method:Quaternion setFromRotationMatrix]( [param:Matrix4 m] )
Sets this quaternion from rotation component of [page:Matrix4 m].
Adapted from the method [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm here].
[method:Quaternion setFromUnitVectors]( [param:Vector3 vFrom], [param:Vector3 vTo] )
Sets this quaternion to the rotation required to rotate direction vector [page:Vector3 vFrom] to
direction vector [page:Vector3 vTo].
Adapted from the method [link:http://lolengine.net/blog/2013/09/18/beautiful-maths-quaternion-from-vectors here].
[page:Vector3 vFrom] and [page:Vector3 vTo] are assumed to be normalized.
[method:Array toArray]( [param:Array array], [param:Integer offset] )
[page:Array array] - An optional array to store the quaternion. If not specified, a new array will be created.
[page:Integer offset] - (optional) if specified, the result will be copied
into this [page: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 )
[method:Quaternion slerp]( [param:Quaternion qStart], [param:Quaternion qEnd], [param:Quaternion qTarget], [param:Float t] )
[page:Quaternion qStart] - The starting quaternion (where [page:Float t] is 0)
[page:Quaternion qEnd] - The ending quaternion (where [page:Float t] is 1)
[page:Quaternion qTarget] - The target quaternion that gets set with the result
[page:float 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 );
[method:null slerpFlat](
[page:Array dst],
[page:Integer dstOffset],
[page:Array src0],
[page:Integer srcOffset0],
[page:Array src1],
[page:Integer srcOffset1],
[page:Float t]
)
[page:Array dst] - The output array.
[page:Integer dstOffset] - An offset into the output array.
[page:Array src0] - The source array of the starting quaternion.
[page:Integer srcOffset0] - An offset into the array *src0*.
[page:Array src1] - The source array of the target quatnerion.
[page:Integer srcOffset1] - An offset into the array *src1*.
[page:float t] - Normalized interpolation factor (between 0 and 1).
Like the static *slerp* method above, but operates directly on flat arrays of numbers.
Source
[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]