|
|
@@ -10,12 +10,19 @@
|
|
|
<body>
|
|
|
<h1>[name]</h1>
|
|
|
|
|
|
- <div class="desc">Implementation of a <a href="http://en.wikipedia.org/wiki/Quaternion">quaternion</a>. This is used for rotating things without encountering the dreaded <a href="http://en.wikipedia.org/wiki/Gimbal_lock">gimbal lock</a> issue, amongst other advantages.</div>
|
|
|
+ <div class="desc">
|
|
|
+ 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.
|
|
|
+ </div>
|
|
|
|
|
|
|
|
|
<h2>Example</h2>
|
|
|
|
|
|
- <code>var quaternion = new THREE.Quaternion();
|
|
|
+ <code>
|
|
|
+ var quaternion = new THREE.Quaternion();
|
|
|
quaternion.setFromAxisAngle( new THREE.Vector3( 0, 1, 0 ), Math.PI / 2 );
|
|
|
|
|
|
var vector = new THREE.Vector3( 1, 0, 0 );
|
|
|
@@ -28,190 +35,232 @@
|
|
|
|
|
|
<h3>[name]( [page:Float x], [page:Float y], [page:Float z], [page:Float w] )</h3>
|
|
|
<div>
|
|
|
- x - x coordinate<br />
|
|
|
- y - y coordinate<br />
|
|
|
- z - z coordinate<br />
|
|
|
- w - w coordinate
|
|
|
+ [page:Float x] - x coordinate<br />
|
|
|
+ [page:Float y] - y coordinate<br />
|
|
|
+ [page:Float z] - z coordinate<br />
|
|
|
+ [page:Float w] - w coordinate
|
|
|
</div>
|
|
|
|
|
|
|
|
|
<h2>Properties</h2>
|
|
|
|
|
|
<h3>[property:Float x]</h3>
|
|
|
+ <div>Changing this property will result in </div>
|
|
|
|
|
|
<h3>[property:Float y]</h3>
|
|
|
+ <div>
|
|
|
+
|
|
|
+ </div>
|
|
|
|
|
|
<h3>[property:Float z]</h3>
|
|
|
+ <div>
|
|
|
+
|
|
|
+ </div>
|
|
|
|
|
|
<h3>[property:Float w]</h3>
|
|
|
+ <div>
|
|
|
+
|
|
|
+ </div>
|
|
|
|
|
|
|
|
|
<h2>Methods</h2>
|
|
|
|
|
|
- <h3>[method:Quaternion set]( [page:Float x], [page:Float y], [page:Float z], [page:Float w] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion clone]()</h3>
|
|
|
<div>
|
|
|
- Sets values of this quaternion.
|
|
|
+ Creates a new Quaternion with identical [page:.x x], [page:.y y],
|
|
|
+ [page:.z z] and [page:.w w] properties to this one.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion copy]( [page:Quaternion q] ) [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- Copies values of *q* to this quaternion.
|
|
|
- </div>
|
|
|
|
|
|
- <h3>[method:Quaternion fromArray]( [page:Array array], [page:Integer offset] ) [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- array -- Array of format (x, y, z, w) used to construct the quaternion.<br />
|
|
|
- offset -- An optional offset into the array.
|
|
|
- </div>
|
|
|
+ <h3>[method:Quaternion conjugate]()</h3>
|
|
|
<div>
|
|
|
- Sets this quaternion's component values from an array.
|
|
|
+ Returns the rotational conjugate of this quaternion. The conjugate of a quaternion
|
|
|
+ represents the same rotation in the opposite direction about the rotational axis.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion setFromEuler]( [page:Euler euler] ) [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- Sets this quaternion from rotation specified by Euler angle.
|
|
|
- </div>
|
|
|
+ <h3>[method:Quaternion copy]( [page:Quaternion q] )</h3>
|
|
|
+ <div>Copies the [page:.x x], [page:.y y], [page:.z z] and [page:.w w] properties
|
|
|
+ of [page:Quaternion q] into this quaternion.</div>
|
|
|
|
|
|
- <h3>[method:Quaternion setFromAxisAngle]( [page:Vector3 axis], [page:Float angle] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Boolean equals]( [page:Quaternion v] )</h3>
|
|
|
<div>
|
|
|
- Sets this quaternion from rotation specified by axis and angle.<br />
|
|
|
- Adapted from [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/angleToQuaternion/index.htm].<br />
|
|
|
- *Axis* is asumed to be normalized, *angle* is in radians.
|
|
|
- </div>
|
|
|
+ [page:Quaternion v] - Quaternion that this quaternion will be compared to.<br /><br />
|
|
|
|
|
|
- <h3>[method:Quaternion setFromRotationMatrix]( [page:Matrix4 m] ) [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- Sets this quaternion from rotation component of *m*.<br />
|
|
|
- Adapted from [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm].
|
|
|
+ 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.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion setFromUnitVectors]( [page:Vector3 vFrom], [page:Vector3 vTo] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Float dot]( [page:Quaternion v] )</h3>
|
|
|
<div>
|
|
|
- Sets this quaternion to the rotation required to rotate direction vector *vFrom* to direction vector *vTo*.<br />
|
|
|
- Adapted from [link:http://lolengine.net/blog/2013/09/18/beautiful-maths-quaternion-from-vectors].<br />
|
|
|
- *vFrom* and *vTo* are assumed to be normalized.
|
|
|
+ Calculate the [link:https://en.wikipedia.org/wiki/Dot_product dot product] of
|
|
|
+ quaternions [page:Quaternion v] and this one.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion inverse]() [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion fromArray]( [page:Array array], [page:Integer offset] )</h3>
|
|
|
<div>
|
|
|
- Inverts this quaternion.
|
|
|
- </div>
|
|
|
+ [page:Array array] - array of format (x, y, z, w) used to construct the quaternion.<br />
|
|
|
+ [page:Integer offset] - (optional) an offset into the array.<br /><br />
|
|
|
|
|
|
- <h3>[method:Float length]() [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- Computes length of this quaternion.
|
|
|
+ Sets this quaternion's [page:.x x], [page:.y y], [page:.z z] and [page:.w w] properties
|
|
|
+ from an array.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion normalize]() [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion inverse]()</h3>
|
|
|
<div>
|
|
|
- Normalizes this quaternion.
|
|
|
+ Inverts this quaternion - calculated the [page:.conjugate conjugate] and then
|
|
|
+ [page:.normalize normalizes] the result.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion multiply]( [page:Quaternion q] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Float length]()</h3>
|
|
|
+ <div>Computes the Euclidean length of this quaternion, considered as a 4 dimensional vector.</div>
|
|
|
+
|
|
|
+ <h3>[method:Float lengthSq]()</h3>
|
|
|
<div>
|
|
|
- Multiplies this quaternion by *q*.
|
|
|
+ Computes the Euclidean 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]().
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion premultiply]( [page:Quaternion q] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion normalize]()</h3>
|
|
|
<div>
|
|
|
- Pre-multiplies this quaternion by *q*.
|
|
|
+ [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*.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion multiplyQuaternions]( [page:Quaternion a], [page:Quaternion b] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion multiply]( [page:Quaternion q] )</h3>
|
|
|
+ <div>Multiplies this quaternion by [page:Quaternion q].</div>
|
|
|
+
|
|
|
+ <h3>[method:Quaternion multiplyQuaternions]( [page:Quaternion a], [page:Quaternion b] )</h3>
|
|
|
<div>
|
|
|
- Sets this quaternion to *a x b*<br />
|
|
|
+ Sets this quaternion to [page:Quaternion a] x [page:Quaternion b].<br />
|
|
|
Adapted from [link:http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/code/index.htm].
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion multiplyVector3]( [page:Vector3 vector], [page:Vector3 dest] ) [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- Rotates *vector* by this quaternion into *dest*.<br />
|
|
|
- If *dest* is not specified, result goes to *vec*.
|
|
|
- </div>
|
|
|
+ <h3>[method:Quaternion onChange]( [page:Function onChangeCallback] )</h3>
|
|
|
+ <div>Set the [page:.onChangeCallback onChangeCallback]() method.</div>
|
|
|
|
|
|
- <h3>[method:Float lengthSq]() [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion onChangeCallback]( )</h3>
|
|
|
<div>
|
|
|
- Calculates the squared length of the quaternion.
|
|
|
+ This function is called whenever and of the following occur:
|
|
|
+ <ul>
|
|
|
+ <li>
|
|
|
+ The [page:.x x], [page:.y y], [page:.z z] or
|
|
|
+ [page:.w w] properties are changed.
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ 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.
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ [page:.setFromEuler setFromEuler]() function is called with its *update* argument set to true.
|
|
|
+ </li>
|
|
|
+ </ul>
|
|
|
+ By default it is the empty function, however you can change it if needed using [page:.onChange onChange]( [page:Function onChangeCallback] ).
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion conjugate]() [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- Returns the rotational conjugate of this quaternion. The conjugate of a quaternion
|
|
|
- represents the same rotation in the opposite direction about the rotational axis.
|
|
|
- </div>
|
|
|
|
|
|
- <h3>[method:Quaternion slerp]( [page:Quaternion quaternionB], [page:float t] ) [page:Quaternion this]</h3>
|
|
|
- <div>
|
|
|
- quaternionB -- The other quaternion rotation<br />
|
|
|
- t -- Normalized 0 to 1 interpolation factor
|
|
|
- </div>
|
|
|
- <div>
|
|
|
- Handles the spherical linear interpolation between quaternions. *t* represents the amount of rotation
|
|
|
- between this quaternion (where *t* is 0) and quaternionB (where *t* is 1). This quaternion is set to
|
|
|
- the result. Also see the static version of the *slerp* below.
|
|
|
- </div>
|
|
|
- <code>
|
|
|
- // rotate a mesh towards a target quaternion
|
|
|
- mesh.quaternion.slerp( endQuaternion, 0.01 );
|
|
|
- </code>
|
|
|
+ <h3>[method:Quaternion premultiply]( [page:Quaternion q] )</h3>
|
|
|
+ <div>Pre-multiplies this quaternion by [page:Quaternion q].</div>
|
|
|
|
|
|
- <h3>[method:Boolean equals]( [page:Quaternion v] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion slerp]( [page:Quaternion qb], [page:float t] )</h3>
|
|
|
<div>
|
|
|
- v -- Quaternion that this quaternion will be compared to.
|
|
|
+ [page:Quaternion qb] - The other quaternion rotation<br />
|
|
|
+ [page:float t] - Normalized interpolation factor (between 0 and 1).<br /><br />
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+ <code>
|
|
|
+ // rotate a mesh towards a target quaternion
|
|
|
+ mesh.quaternion.slerp( endQuaternion, 0.01 );
|
|
|
+ </code>
|
|
|
</div>
|
|
|
+
|
|
|
+ <h3>[method:Quaternion set]( [page:Float x], [page:Float y], [page:Float z], [page:Float w] )</h3>
|
|
|
+ <div>Sets [page.x x], [page.y y], [page.z z], [page.w w] properties of this quaternion.</div>
|
|
|
+
|
|
|
+ <h3>[method:Quaternion setFromAxisAngle]( [page:Vector3 axis], [page:Float angle] )</h3>
|
|
|
<div>
|
|
|
- Compares each component of *v* to each component of this quaternion to determine if they
|
|
|
- represent the same rotation.
|
|
|
+ Sets this quaternion from rotation specified by [page:Vector3 axis] and [page:Float angle].<br />
|
|
|
+ Adapted from [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/angleToQuaternion/index.htm].<br />
|
|
|
+ *Axis* is asumed to be normalized, *angle* is in radians.
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Quaternion clone]() [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion setFromEuler]( [page:Euler euler] )</h3>
|
|
|
+ <div>Sets this quaternion from the rotation specified by [page:Euler] angle.</div>
|
|
|
+
|
|
|
+ <h3>[method:Quaternion setFromRotationMatrix]( [page:Matrix4 m] )</h3>
|
|
|
<div>
|
|
|
- Clones this quaternion.
|
|
|
+ Sets this quaternion from rotation component of [page:Matrix4 m].<br />
|
|
|
+ Adapted from [link:http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm].
|
|
|
</div>
|
|
|
|
|
|
- <h3>[method:Array toArray]( [page:Array array], [page:Integer offset] ) [page:Quaternion this]</h3>
|
|
|
+ <h3>[method:Quaternion setFromUnitVectors]( [page:Vector3 vFrom], [page:Vector3 vTo] )</h3>
|
|
|
<div>
|
|
|
- array -- An optional array to store the quaternion.<br/>
|
|
|
- offset -- An optional offset into the output array.
|
|
|
+ Sets this quaternion to the rotation required to rotate direction vector [page:Vector3 vFrom] to
|
|
|
+ direction vector [page:Vector3 vTo].<br />
|
|
|
+ Adapted from [link:http://lolengine.net/blog/2013/09/18/beautiful-maths-quaternion-from-vectors].<br />
|
|
|
+ [page:Vector3 vFrom] and [page:Vector3 vTo] are assumed to be normalized.
|
|
|
</div>
|
|
|
+
|
|
|
+ <h3>[method:Array toArray]( [page:Array array], [page:Integer offset] )</h3>
|
|
|
<div>
|
|
|
- Returns the numerical elements of this quaternion in an array of format (x, y, z, w).
|
|
|
+ [page:Array array] - An optional array to store the quaternion. If not specified a new array will be created.<br/>
|
|
|
+ [page:Integer offset] - optional) if specified, the result will be copied
|
|
|
+ into this [page:Array].<br /><br />
|
|
|
+
|
|
|
+ Returns the numerical elements of this quaternion in an array of format [x, y, z, w].
|
|
|
</div>
|
|
|
|
|
|
<h2>Static Methods</h2>
|
|
|
|
|
|
<h3>[method:Quaternion slerp]( [page:Quaternion qStart], [page:Quaternion qEnd], [page:Quaternion qTarget], [page:Float t] )</h3>
|
|
|
<div>
|
|
|
- qStart -- The starting quaternion (where *t* is 0)<br />
|
|
|
- qEnd -- The ending quaternion (where *t* is 1)<br />
|
|
|
- qTarget -- The target quaternion that gets set with the result<br />
|
|
|
- t -- Normalized 0 to 1 interpolation factor
|
|
|
+ [page:Quaternion qStart] - The starting quaternion (where [page:Float t] is 0)<br />
|
|
|
+ [page:Quaternion qEnd] - The ending quaternion (where [page:Float t] is 1)<br />
|
|
|
+ [page:Quaternion qTarget] - The target quaternion that gets set with the result<br />
|
|
|
+ [page:float t] - Normalized interpolation factor (between 0 and 1).<br /><br />
|
|
|
+
|
|
|
+ Unlike the normal method, the static version of slerp sets a target quaternion to the result of the slerp operation.
|
|
|
+ <code>
|
|
|
+ // 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 );
|
|
|
+ </code>
|
|
|
</div>
|
|
|
- <div>
|
|
|
- Unlike the normal method, the static version of slerp sets a target quaternion to the result of the slerp operation.
|
|
|
- </div>
|
|
|
- <code>
|
|
|
- // 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;
|
|
|
- </code>
|
|
|
- <code>
|
|
|
- // Update a mesh's rotation in the loop
|
|
|
- t = ( t + 0.01 ) % 1; // constant angular momentum
|
|
|
- THREE.Quaternion.slerp( startQuaternion, endQuaternion, mesh.quaternion, t );
|
|
|
- </code>
|
|
|
|
|
|
- <h3>[method:null slerpFlat]( [page:Array dst], [page:Integer dstOffset], [page:Array src0], [page:Integer srcOffset0], [page:Array src1], [page:Integer srcOffset1], [page:Float t] )</h3>
|
|
|
+
|
|
|
+ <h3>
|
|
|
+ [method:null slerpFlat](
|
|
|
+ [page:Array dst],
|
|
|
+ [page:Integer dstOffset],
|
|
|
+ [page:Array src0],
|
|
|
+ [page:Integer srcOffset0],
|
|
|
+ [page:Array src1],
|
|
|
+ [page:Integer srcOffset1],
|
|
|
+ [page:Float t]
|
|
|
+ )
|
|
|
+ </h3>
|
|
|
<div>
|
|
|
- dst -- The output array.<br />
|
|
|
- dstOffset -- An offset into the output array.<br />
|
|
|
- src0 -- The source array of the starting quaternion.<br />
|
|
|
- srcOffset0 -- An offset into the array *src0*.<br />
|
|
|
- src1 -- The source array of the target quatnerion.<br />
|
|
|
- srcOffset1 -- An offset into the array *src1*.<br />
|
|
|
- t -- Interpolation factor 0 at start, 1 at end.
|
|
|
- </div>
|
|
|
+ [page:Array dst] - The output array.<br />
|
|
|
+ [page:Integer dstOffset] - An offset into the output array.<br />
|
|
|
+ [page:Array src0] - The source array of the starting quaternion.<br />
|
|
|
+ [page:Integer srcOffset0] - An offset into the array *src0*.<br />
|
|
|
+ [page:Array src1] - The source array of the target quatnerion.<br />
|
|
|
+ [page:Integer srcOffset1] - An offset into the array *src1*.<br />
|
|
|
+ [page:float t] - Normalized interpolation factor (between 0 and 1).<br /><br />
|
|
|
<div>
|
|
|
Like the static *slerp* method above, but operates directly on flat arrays of numbers.
|
|
|
</div>
|
Lewy Blue