Quat API
Contents
- 1 Overview
- 2 Quat.angle()
- 3 Quat.angleAxis()
- 4 Quat.axis()
- 5 Quat.conjugate()
- 6 Quat.dot()
- 7 Quat.equal()
- 8 Quat.fromPitchYawRollDegrees()
- 9 Quat.fromPitchYawRollRadians()
- 10 Quat.fromVec3Degrees()
- 11 Quat.fromVec3Radians()
- 12 Quat.getForward()
- 13 Quat.getFront()
- 14 Quat.getRight()
- 15 Quat.getUp()
- 16 Quat.inverse()
- 17 Quat.lookAt()
- 18 Quat.lookAtSimple()
- 19 Quat.mix()
- 20 Quat.multiply()
- 21 Quat.normalize()
- 22 Quat.print()
- 23 Quat.rotationBetween()
- 24 Quat.safeEulerAngles()
- 25 Quat.slerp()
- 26 Quat.squad()
Overview
//TODO
| Properties | Type | Description |
|---|---|---|
| Quat.objectName | string |
Quat.angle()
Compute the angle of rotation.
Function
Quat.angle(q)
Arguments
q: quat: the rotation.
Returns
angle: float: The angle of the rotation q in radians.
Examples
<code>var angle = Quat.angle(rotation);</code>
Quat.angleAxis()
Compute the quaternion that corresponds to a rotation of an angle (radians) about some normalized axis.
Function
Quat.angleAxis(angle, axis)
Arguments
angle: float: the angle of rotation (degrees).
axis: vec3: the normalized axis of rotation.
Returns
q: quat: The rotation obtained when rotating by angle radians about normalized axis.
Examples
<code>var angle = 90; // quarter turn
var axis = { x: 1, y: 0, z: 0};
var rotation = Quat.angleAxis(angle, axis);</code>
Quat.axis()
Compute the normalized axis of rotation.
Function
Quat.axis(q)
Arguments
q: quat: the rotation.
Returns
axis: vec3: The normalized axis of the rotation q.
Examples
<code>var axis = Quat.axis(rotation);</code>
Quat.conjugate()
Compute the conjugate (inverse) quaternion.
Function
Quat.conjugate(q)
Arguments
q: quat: the rotation to conjugate.
Returns
conjugateQ: quat: The conjugate (inverse) rotation corresponding to q such that q * conjugateQ = identity.
Examples
<code>var inverseRotation = Quat.conjugate(rotation);</code>
Quat.dot()
Compute the dot product between two quaternions. This is a measure of how "close" two rotations are to each other.
Note: a zero dot product value means the rotations are completely orthogonal to each other. The closer they are to each other the more non-zero the value is (either positive or negative). Identical rotations will have a dot product of +/- 1.
Function
dot(q1, q2)
Arguments
q1: quat: the first quaternion.
q2: quat: the second quaternion.
Returns
d: float: The inner product between two rotations.
Examples
<code>var d = Quat.dot(q1, q2);
if (Math.abs(d) > 0.999999) {
// the rotations are close enough to be considered identical
}</code>
Quat.equal()
Compare equality of two quaternions.
Note: this method is of dubious usefulness since it only returns true for exactly equal quaternions, not for nearly equal rotations and sometimes not even for exactly equal rotations (because the negative quaternion corresponds to the exact same rotation). A more useful way to compare two rotations is to use Quat.dot().
Function
Quat.equal(q1, q2)
Arguments
q1: quat: the first quaternion
q2: quat: the second quaternion
Returns
b: Bool: true if the quaternions are exactly equal.
Examples
<code>var same = Quat.equals(q1, q2);</code>
Should print:
rotation = 0 , 0.707107 , 0 , 0.707107
Quat.fromPitchYawRollDegrees()
Compute a rotation using three angles: pitch, yaw, roll.
Function
Quat.fromPitchYawRollDegrees(pitch, yaw, roll)
Arguments
pitch: float: angle of rotation about local xAxis (left) followed by…
yaw: float: angle of rotation about local yAxis (up) followed by…
roll: float: angle of rotation about local zAxis (forward).
Note: the units of angle are degrees.
Returns
q: quat: The rotation produced by rotating successively by pitch (about local xAxis), yaw (about subsequent local yAxis), and roll (about subsequent local zAxis).
Examples
<code>var rotation = Quat.fromPitchYawRollDegrees(pitch, yaw, roll);</code>
Quat.fromPitchYawRollRadians()
Compute a rotation using three angles: pitch, yaw, roll.
Function
Quat.fromPitchYawRollRadians(pitch, yaw, roll)
Arguments
pitch: float: angle of rotation about local xAxis (left) followed by…
yaw: float: angle of rotation about local yAxis (up) followed by…
roll: float: angle of rotation about local zAxis (forward).
Note: the units of angle are radians.
Returns
q: quat: The rotation produced by rotating successively by pitch (about local xAxis), yaw (about subsequent local yAxis), and roll (about subsequent local zAxis).
Examples
<code>var rotation = Quat.fromPitchYawRollDegrees(pitch, yaw, roll);</code>
Quat.fromVec3Degrees()
Compute a rotation using three angles (pitch, yaw, roll) packed into a single Vec3 argument.
Function
Quat.fromVec3Degrees(angles)
Arguments
angles: vec3: three angles (x: pitch, y: yaw, z: roll) stored in the components of a vec3.
Note: the angles units are in degrees.
Returns
q: quat: The rotation produced by rotating successively by pitch (about local xAxis), yaw (about subsequent local yAxis), and roll (about subsequent local zAxis).
Examples
<code>var angles = {x: pitch, y: yaw, z: roll};
var rotation = Quat.fromVec3Degrees(angles);</code>
Quat.fromVec3Radians()
Compute a rotation using three angles (pitch, yaw, roll) packed into a single Vec3 argument.
Function
Quat.fromVec3Radians()
Arguments
angles: vec3: three angles (x: pitch, y: yaw, z: roll) stored in the components of a vec3.
Note: the units of angle are radians.
Returns
q: quat: The rotation produced by rotating successively by pitch (about local xAxis), yaw (about subsequent local yAxis), and roll (about subsequent local zAxis).
Examples
<code>\\var angles = {x: pitch, y: yaw, z: roll};
var rotation = Quat.fromVec3Radians(angles);</code>
Quat.getForward()
Compute the rotated forward direction (zAxis).
Function
Quat.getForward(q)
Arguments
q: quat: the rotation.
Returns
forward: vec3: The local forward direction (zAxis) after being rotated.
Examples
<code>var forward = Quat.getForward(rotation);</code>
Quat.getFront()
Compute the rotated forward direction (zAxis). This method calls Quat.getForward().
Function
Quat.getFront(q)
Arguments
q: quat: the rotation.
Returns
forward: vec3: The local forward direction (zAxis) after being rotated.
Examples
<code>var forward = Quat.getFront(rotation);</code>
Quat.getRight()
Compute the rotated right direction (negative xAxis).
Function
Quat.getRight(q)
Arguments
q: quat: the rotation.
Returns
right: vec3: The local right direction (negative xAxis) after being rotated.
Examples
<code>var right = Quat.getRight(rotation);</code>
Quat.getUp()
Compute the rotated up direction (yAxis).
Function
Quat.getUp(q)
Arguments
q: quat: the rotation.
Returns
up: vec3: The local up direction (yAxis) after being rotated.
Examples
<code>var up = Quat.getUp(rotation);</code>
Quat.inverse()
Compute the inverse (conjugate) quaternion.
Function
Quat.inverse(q)
Arguments
q: quat: the rotation to invert.
Returns
inverseQ: quat: The inverse (conjugate) rotation corresponding to q such that q * inverseQ = identity.
Examples
<code>var inverseRotation = Quat.inverse(rotation);</code>
Quat.lookAt()
Compute the rotation that will orient a camera at a known location to look straight at another point.
Note: the camera's local forward direction is assumed to be the zAxis, and its local up direction is the yAxis. The orientation will be computed such that there is zero roll about its forward direction.
Function
lookAt(eye, center, up)
Arguments
eye: vec3: the location of the camera
center: vec3: the point where the camera is looking
up: vec3: the vertical direction
Returns
q: quat: The rotation of the camera.
Examples
If we know where we are, the location of the thing we're looking at, and the world's up direction then lookAt() will compute our orientation for us.
<code>// suppose we have a laser turret that we want to point at a // known target location var eye = laser.position; var center = target.position; var up = zAxis; // world-frame's up // Quat.lookAt() will compute the orientation we want var orientation = Quat.lookAt(eye, center, up);</code>
Quat.lookAtSimple()
Compute the rotation that will orient a camera at a known location to look straight at another point, assuming that the world'd up direction is the yAxis.
Note: the camera's local forward direction is assumed to be its zAxis, and its local up direction is its yAxis. The orientation will be computed such that there is zero roll about its forward direction.
Function
Quat.lookAt(eye, center, up)
Arguments
eye: vec3: the location of the camera
center: vec3: the point where the camera is looking
Returns
q: quat: The rotation of the camera.
Examples
If we know where we are and the location of the thing we're looking at then lookAtSimple() will compute our orientation for us.
<code>// suppose we have a laser turret that we want to point at a // known target location var eye = laser.position; var center = target.position; // Quat.lookAtSimple() will compute the orientation we want: var orientation = Quat.lookAtSimple(eye, center);</code>
Quat.mix()
Compute the interpolation (slerp) between two rotations. Uses spherical linear interpolation (slerp) if the rotations are far enough apart, otherwise uses linear interpolation (lerp).
Function
Quat.mix(q1, q2, factor)
Arguments
q1: quat: the beginning rotation.
q2: quat: the ending rotation.
factor: float: the mixture coefficient in the range [0, 1]
Returns
q3: quat: The spherically interpolated rotation between beginning and ending rotations, unless the two rotations are very close to each other in which case it uses linear interpolation (lerp). A factor value of 0 gives q1 and a value of 1 gives q2.
Examples
This example shows how to use Quat.mix() to animate a rotation between one rotation and another.
<code>// to animate between one rotation and another:
var dt = amountOfTimeThatHasPassed;
var mixFactor = amountOfTimeThatHasPassed / TIME_TO_COMPLETE;
if (mixFactor) > 1) {
mixFactor = 1;
}
var newRotation = Quat.mix(startRotation, endRotation, mixFactor);</code>
Quat.multiply()
Multiply two rotations together to get their unnormalized product.
Function
Quat.multiply(q2, q1)
Arguments
q2: quat: second rotation from the left
q1: quat: first rotation from the left
Returns
q3: quat: The unnormalized product of the two rotations q2 * q1
Examples
Two rotations can be combined by multiplying them together.
<code>// create two quarter turn rotations about distinct axes
// then multiply them together to get a third rotation
// equivalent to applying first one and then the other
var angle = 0.5 * Math.PI; // radians equivalent to 90 degrees
var xAxis = { x: 1, y: 0, z: 0 };
var yAxis = { x: 0, y: 1, z: 0 };
// first rotation is a positive right-angle turn about xAxis
var turnAboutX = Quat::angleAxis(angle, xAxis);
// second rotation is a positive right-angle turn about yAxis
var turnAboutY = Quat::angleAxis(angle, yAxis);
var firstAboutXThenY = Quat.multiply(turnAboutY, turnAboutX);</code>
Quat.normalize()
Compute the normalized quaternion.
Function
Quat.normalize(q)
Arguments
q: quat: the quaternion to normalize
Returns
normalizedQuat: quat: The quaternion q normalized such that its length is equal to 1.
Examples
This example shows a loop that increments a rotation around one full turn. Since the rotation is used to compute its next value each iteration it must be normalized, otherwise numerical error may be compounded.
<code>var rotation = {x: 0, y: 0, z: 0, w: 1}; // identity rotation
// increment rotation one full turn
var numLoops = 100;
var smallAngle = 2 * Math.pi / numLoops;
var axis = {x: 1, y: 2, z: 3};
var smallRotation = Quat.angleAxis(smallAngle, axis);
for (var i = 0; i < numLoops; ++i) {
rotation = Quat.multiply(smallRotation, rotation);
rotation = Quat.normalize(rotation);
}
// we expect some numerical error after one full turn
// but it should be small when rotation is re-normalized
var testVector = {x: 2, y: -3, z: -1};
var rotatedVector = Vec3.multiplyQbyV(rotation, testVector);
var error = Vec3.sub(testVector, rotatedVector);
Vec3.print(error, \"error = \");</code>
Quat.print()
Print the component values of a quaternion.
Function
Quat.print(message, q)
Arguments
message: String: preceding message string.
q: quat: the rotation.
Returns
No return value.
Examples
<code>var angle = 90; // axisAngle takes DEGREES!
var axis = {x: 0, y: 1, z: 0};
var rotation = Quat.axisAngle(angle, axis);
Quat.print(rotation, \"rotation =\");</code>
Should print:
rotation = 0 , 0.707107 , 0 , 0.707107
Quat.rotationBetween()
Compute the shortest rotation that would swing one vector to align with another.
Function
rotationBetween(v1, v2)
Arguments
v1: vec3: the first vector
v2: vec3: the second vector
Note: the arguments do not need to be normalized, however the return value may be nonsense if either of the arguments has zero length.
Returns
q: quat: The shortest rotation that would swing v1 to align with v2
Examples
Sometimes we know where something is pointing and where we want it to point, but we don't know the incremental rotation that would get it there. rotationBetween() is a utility that makes this easy.
<code>// suppose we know an object's rotation and non-zero velocity
var rotation = properties.rotation;
var velocity = properties.velocity;
// and suppose the object's local forward direction points
// parallel to its local yAxis and that we want to rotate the
// object to align its forward axis to be parallel to its
// velocity...
// we can compute its forward axis in the world-frame like so
var yAxis = {x: 0, y: 1, z: 0};
var forward = Vec3.multiplyQbyV(rotation, yAxis);
// we use angleBetween() to compute the delta rotation that brings
// the forward direction parallel to the velocity
var deltaRotation = Quat.angleBetween(forward, velocity);
// we can now compute the final rotation of the object
var finalRotation = Quat.multiply(deltaRotation, rotation);</code>
Quat.safeEulerAngles()
Compute the pitch, yaw, and roll angles (in radians) that correspond to a rotation.
The safe in the name signifies that the angle results will not be garbage even when the rotation is particularly difficult to decompose.
Function
Quat.safeEulerAngles(q)
Arguments
q: quat: the rotation to decompose into pitch, yaw, and roll.
Returns
angles: vec3: The pitch, yaw, and roll angles (in radians) stored in a Vec3 that correspond to the rotation.
Examples
<code>var angles = Quat.safeEulerAngles(rotation); var pitch = angles.x; var yaw = angles.y; var roll = angles.z;</code>
Quat.slerp()
Compute the normalized spherical linear interpolation (slerp) between two rotations.
Function
Quat.slerp(q1, q2, factor)
Arguments
q1: quat: the beginning rotation.
q2: quat: the ending rotation.
factor: float: the mixture coefficient in the range [0, 1]
Returns
q3: quat: The spherically interpolated rotation between beginning and ending rotations. A factor value of 0 gives q1 and a value of 1 gives q2.
Examples
This example shows how to use Quat.slerp() to animate a rotation between one rotation and another.
<code>// to animate between one rotation and another:
var dt = amountOfTimeThatHasPassed;
var mixFactor = amountOfTimeThatHasPassed / TIME_TO_COMPLETE;
if (mixFactor) > 1) {
mixFactor = 1;
}
var newRotation = Quat.slerp(startRotation, endRotation, mixFactor);</code>
Quat.squad()
Compute a B-spline smoothed normalized spherical linear interpolation (slerp) between two rotations. Useful for animating through a series of rotation waypoints.
Function
Quat.squad(q1, q2, q3, q4, factor)
Arguments
q1: quat: the rotation previous to beginning rotation.
q2: quat: the beginning rotation.
q3: quat: the ending rotation.
q4: quat: the rotation after ending rotation.
factor: float: the mixture coefficient in the range [0, 1]
Returns
q5: quat: The smoothed spherically interpolated rotation between beginning and ending rotations. A factor value of 0 gives q2 and a value of 1 gives q3. # Examples
<code>// TODO: write this example</code>
