Quat

Description

The Quat API provides facilities for generating and manipulating quaternions. Quaternions should be used in preference to Euler angles wherever possible because quaternions don't suffer from the problem of gimbal lock.

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

Properties

Name Type Summary
IDENTITY Quat { x: 0, y: 0, z: 0, w: 1 } : The identity rotation, i.e., no rotation. Read-only.

Example

Print the IDENTITY value.

print(JSON.stringify(Quat.IDENTITY)); // { x: 0, y: 0, z: 0, w: 1 }
print(JSON.stringify(Quat.safeEulerAngles(Quat.IDENTITY))); // { x: 0, y: 0, z: 0 }

Methods

Name Return Value Summary
angle number Get the rotation angle for a quaternion.
angleAxis Quat Generate a quaternion given an angle to rotate through and an axis to rotate about.
axis Vec3 Get the rotation axis for a quaternion.
cancelOutRoll Quat Cancels out the roll component of a quaternion so that its horizontal axis is level.
cancelOutRollAndPitch Quat Cancels out the roll and pitch component of a quaternion so that its completely horizontal with a yaw pointing in the given quaternion's direction.
conjugate Quat Calculate the conjugate of a quaternion. For a unit quaternion, its conjugate is the same as its Quat.inverse.
dot number Calculate the dot product of two quaternions. The closer the quaternions are to each other the more non-zero the value is (either positive or negative). Identical unit rotations have a dot product of +/- 1.
equal boolean Test whether two quaternions are equal. Note: The quaternions must be exactly equal in order for true to be returned; it is often better to use Quat.dot and test for closeness to +/-1.
fromPitchYawRollDegrees Quat Generate a quaternion from pitch, yaw, and roll values in degrees.
fromPitchYawRollRadians Quat Generate a quaternion from pitch, yaw, and roll values in radians.
fromVec3Degrees Quat Generate a quaternion from a Vec3 of Euler angles in degrees.
fromVec3Radians Quat Generate a quaternion from a Vec3 of Euler angles in radians.
getForward Vec3 Get the "forward" direction that the camera would face if its orientation was set to the quaternion value. This is a synonym for Quat.getFront. The High Fidelity camera has axes x = right, y = up, -z = forward.
getFront Vec3 Get the "front" direction that the camera would face if its orientation was set to the quaternion value. This is a synonym for Quat.getForward. The High Fidelity camera has axes x = right, y = up, -z = forward.
getRight Vec3 Get the "right" direction that the camera would have if its orientation was set to the quaternion value. The High Fidelity camera has axes x = right, y = up, -z = forward.
getUp Vec3 Get the "up" direction that the camera would have if its orientation was set to the quaternion value. The High Fidelity camera has axes x = right, y = up, -z = forward.
inverse Quat Calculate the inverse of a quaternion. For a unit quaternion, its inverse is the same as its Quat.conjugate.
lookAt Quat Calculate a camera orientation given eye position, point of interest, and "up" direction. The camera's negative z-axis is the forward direction. The result has zero roll about its forward direction with respect to the given "up" direction.
lookAtSimple Quat Calculate a camera orientation given eye position and point of interest. The camera's negative z-axis is the forward direction. The result has zero roll about its forward direction.
mix Quat Compute a spherical linear interpolation between two rotations, safely handling two rotations that are very similar. See also, Quat.slerp.
multiply Quat Multiply two quaternions.
normalize Quat Normalizes a quaternion.
print None Print to the program log a text label followed by a quaternion's pitch, yaw, and roll Euler angles.
rotationBetween Quat Calculate the shortest rotation from a first vector onto a second.
safeEulerAngles Vec3 Calculate the Euler angles for the quaternion, in degrees. (The "safe" in the name signifies that the angle results will not be garbage even when the rotation is particularly difficult to decompose with pitches around +/-90 degrees.)
slerp Quat Compute a spherical linear interpolation between two rotations, for rotations that are not very similar. See also, Quat.mix.
squad Quat Compute a spherical quadrangle interpolation between two rotations along a path oriented toward two other rotations. Equivalent to: Quat.slerp(Quat.slerp(q1, q2, alpha), Quat.slerp(s1, s2, alpha), 2 * alpha * (1.0 - alpha)).

Method Details

(static) angle( q ) → {number}
Returns: The rotation angle for q, in radians. WARNING: This value is in radians whereas the value used by Quat.angleAxis is in degrees.

Get the rotation angle for a quaternion.

Parameters

Name Type Description
q Quat The quaternion.
Example

Get the rotation angle of a quaternion.

var forward = Quat.getForward(Camera.orientation);
var rotation = Quat.angleAxis(90, forward);
var angle = Quat.angle(rotation);
print("Angle: " + angle * 180 / Math.PI);  // 90 degrees.
(static) angleAxis( angle, axis ) → {Quat}
Returns: A quaternion that is a rotation through angle degrees about the axis. WARNING: This value is in degrees whereas the value returned by Quat.angle is in radians.

Generate a quaternion given an angle to rotate through and an axis to rotate about.

Parameters

Name Type Description
angle number The angle to rotate through, in degrees.
axis Vec3 The unit axis to rotate about.
Example

Calculate a rotation of 90 degrees about the direction your camera is looking.

var rotation = Quat.angleAxis(90, Quat.getForward(Camera.orientation));
(static) axis( q ) → {Vec3}
Returns: The normalized rotation axis for q.

Get the rotation axis for a quaternion.

Parameters

Name Type Description
q Quat The quaternion.
Example

Get the rotation axis of a quaternion.

var forward = Quat.getForward(Camera.orientation);
var rotation = Quat.angleAxis(90, forward);
var axis = Quat.axis(rotation);
print("Forward: " + JSON.stringify(forward));
print("Axis: " + JSON.stringify(axis)); // Same value as forward.
(static) cancelOutRoll( orientation ) → {Quat}
Returns: orientation with its roll canceled out.

Cancels out the roll component of a quaternion so that its horizontal axis is level.

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
Example

Two ways of calculating a camera orientation that points in the direction of a given quaternion but keeps the camera's horizontal axis level.

var quaternion = Quat.fromPitchYawRollDegrees(10, 20, 30);

var noRoll = Quat.cancelOutRoll(quaternion);
Quat.print("", noRoll, true); // dvec3(-1.033004, 22.245996, -0.000000)

var front = Quat.getFront(quaternion);
var lookAt = Quat.lookAtSimple(Vec3.ZERO, front);
Quat.print("", lookAt, true); // dvec3(-1.033004, 22.245996, -0.000000)
    
(static) cancelOutRollAndPitch( orientation ) → {Quat}
Returns: orientation with its roll and pitch canceled out.

Cancels out the roll and pitch component of a quaternion so that its completely horizontal with a yaw pointing in the given quaternion's direction.

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
Example

Two ways of calculating a camera orientation in the x-z plane with a yaw pointing in the direction of a given quaternion.

var quaternion = Quat.fromPitchYawRollDegrees(10, 20, 30);

var noRollOrPitch = Quat.cancelOutRollAndPitch(quaternion);
Quat.print("", noRollOrPitch, true); // dvec3(0.000000, 22.245995, 0.000000)

var front = Quat.getFront(quaternion);
var lookAt = Quat.lookAtSimple(Vec3.ZERO, { x: front.x, y: 0, z: front.z });
Quat.print("", lookAt, true); // dvec3(0.000000, 22.245996, 0.000000)
(static) conjugate( q ) → {Quat}
Returns: The conjugate of q.

Calculate the conjugate of a quaternion. For a unit quaternion, its conjugate is the same as its Quat.inverse.

Parameters

Name Type Description
q Quat The quaternion to conjugate.
Example

A unit quaternion multiplied by its conjugate is a zero rotation.

var quaternion = Quat.fromPitchYawRollDegrees(10, 20, 30);
Quat.print("quaternion", quaternion, true); // dvec3(10.000000, 20.000004, 30.000004)
var conjugate = Quat.conjugate(quaternion);
Quat.print("conjugate", conjugate, true); // dvec3(1.116056, -22.242186, -28.451778)
var identity = Quat.multiply(conjugate, quaternion);
Quat.print("identity", identity, true); // dvec3(0.000000, 0.000000, 0.000000)
(static) dot( q1, q2 ) → {number}
Returns: The dot product of q1 and q2.

Calculate the dot product of two quaternions. The closer the quaternions are to each other the more non-zero the value is (either positive or negative). Identical unit rotations have a dot product of +/- 1.

Parameters

Name Type Description
q1 Quat The first quaternion.
q2 Quat The second quaternion.
Example

Testing unit quaternions for equality.

var q1 = Quat.fromPitchYawRollDegrees(0, 0, 0);
var q2 = Quat.fromPitchYawRollDegrees(0, 0, 0);
print(Quat.equal(q1, q2)); // true
var q3 = Quat.fromPitchYawRollDegrees(0, 0, 359.95);
print(Quat.equal(q1, q3)); // false

var dot = Quat.dot(q1, q3);
print(dot); // -0.9999999403953552
var equal = Math.abs(1 - Math.abs(dot)) < 0.000001;
print(equal); // true
(static) equal( q1, q2 ) → {boolean}
Returns: true if the quaternions are equal, otherwise false.

Test whether two quaternions are equal. Note: The quaternions must be exactly equal in order for true to be returned; it is often better to use Quat.dot and test for closeness to +/-1.

Parameters

Name Type Description
q1 Quat The first quaternion.
q2 Quat The second quaternion.
Example

Testing unit quaternions for equality.

var q1 = Quat.fromPitchYawRollDegrees(0, 0, 0);
var q2 = Quat.fromPitchYawRollDegrees(0, 0, 0);
print(Quat.equal(q1, q2)); // true
var q3 = Quat.fromPitchYawRollDegrees(0, 0, 359.95);
print(Quat.equal(q1, q3)); // false

var dot = Quat.dot(q1, q3);
print(dot); // -0.9999999403953552
var equal = Math.abs(1 - Math.abs(dot)) < 0.000001;
print(equal); // true
(static) fromPitchYawRollDegrees( pitch, yaw, roll ) → {Quat}
Returns: A quaternion created using the pitch, yaw, and roll Euler angles.

Generate a quaternion from pitch, yaw, and roll values in degrees.

Parameters

Name Type Description
pitch number The pitch angle in degrees.
yaw number The yaw angle in degrees.
roll number The roll angle in degrees.
Example

Create a rotation of 180 degrees about the y axis.

var rotation = Quat.fromPitchYawRollDgrees(0, 180, 0 );
(static) fromPitchYawRollRadians( pitch, yaw, roll ) → {Quat}
Returns: A quaternion created from the pitch, yaw, and roll Euler angles.

Generate a quaternion from pitch, yaw, and roll values in radians.

Parameters

Name Type Description
pitch number The pitch angle in radians.
yaw number The yaw angle in radians.
roll number The roll angle in radians.
Example

Create a rotation of 180 degrees about the y axis.

var rotation = Quat.fromPitchYawRollRadians(0, Math.PI, 0);
(static) fromVec3Degrees( vector ) → {Quat}
Returns: A quaternion created from the Euler angles in vector.

Generate a quaternion from a Vec3 of Euler angles in degrees.

Parameters

Name Type Description
vector Vec3 A vector of three Euler angles in degrees, the angles being the rotations about the x, y, and z axes.
Example

Zero out pitch and roll from an orientation.

var eulerAngles = Quat.safeEulerAngles(orientation);
eulerAngles.x = 0;
eulerAngles.z = 0;
var newOrientation = Quat.fromVec3Degrees(eulerAngles);
(static) fromVec3Radians( vector ) → {Quat}
Returns: A quaternion created using the Euler angles in vector.

Generate a quaternion from a Vec3 of Euler angles in radians.

Parameters

Name Type Description
vector Vec3 A vector of three Euler angles in radians, the angles being the rotations about the x, y, and z axes.
Example

Create a rotation of 180 degrees about the y axis.

var rotation = Quat.fromVec3Radians({ x: 0, y: Math.PI, z: 0 });
(static) getForward( orientation ) → {Vec3}
Returns: The negative z-axis rotated by orientation.

Get the "forward" direction that the camera would face if its orientation was set to the quaternion value. This is a synonym for Quat.getFront. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
Example

Demonstrate that the "forward" vector is for the negative z-axis.

var forward = Quat.getForward(Quat.IDENTITY);
print(JSON.stringify(forward)); // {"x":0,"y":0,"z":-1}
(static) getFront( orientation ) → {Vec3}
Returns: The negative z-axis rotated by orientation.

Get the "front" direction that the camera would face if its orientation was set to the quaternion value. This is a synonym for Quat.getForward. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
(static) getRight( orientation ) → {Vec3}
Returns: The x-axis rotated by orientation.

Get the "right" direction that the camera would have if its orientation was set to the quaternion value. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
(static) getUp( orientation ) → {Vec3}
Returns: The y-axis rotated by orientation.

Get the "up" direction that the camera would have if its orientation was set to the quaternion value. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
(static) inverse( q ) → {Quat}
Returns: The inverse of q.

Calculate the inverse of a quaternion. For a unit quaternion, its inverse is the same as its Quat.conjugate.

Parameters

Name Type Description
q Quat The quaternion.
Example

A quaternion multiplied by its inverse is a zero rotation.

var quaternion = Quat.fromPitchYawRollDegrees(10, 20, 30);
Quat.print("quaternion", quaternion, true); // dvec3(10.000000, 20.000004, 30.000004)
var inverse = Quat.invserse(quaternion);
Quat.print("inverse", inverse, true); // dvec3(1.116056, -22.242186, -28.451778)
var identity = Quat.multiply(inverse, quaternion);
Quat.print("identity", identity, true); // dvec3(0.000000, 0.000000, 0.000000)
(static) lookAt( eye, target, up ) → {Quat}
Returns: A quaternion that orients the negative z-axis to point along the eye-to-target vector and the x-axis to be the cross product of the eye-to-target and up vectors.

Calculate a camera orientation given eye position, point of interest, and "up" direction. The camera's negative z-axis is the forward direction. The result has zero roll about its forward direction with respect to the given "up" direction.

Parameters

Name Type Description
eye Vec3 The eye position.
target Vec3 The point to look at.
up Vec3 The "up" direction.
Example

Rotate your view in independent mode to look at the world origin upside down.

Camera.mode = "independent";
Camera.orientation = Quat.lookAt(Camera.position, Vec3.ZERO, Vec3.UNIT_NEG_Y);
(static) lookAtSimple( eye, target ) → {Quat}
Returns: A quaternion that orients the negative z-axis to point along the eye-to-target vector and the x-axis to be the cross product of the eye-to-target and an "up" vector. The "up" vector is the y-axis unless the eye-to-target vector is nearly aligned with it (i.e., looking near vertically up or down), in which case the x-axis is used as the "up" vector.

Calculate a camera orientation given eye position and point of interest. The camera's negative z-axis is the forward direction. The result has zero roll about its forward direction.

Parameters

Name Type Description
eye Vec3 The eye position.
target Vec3 The point to look at.
Example

Rotate your view in independent mode to look at the world origin.

Camera.mode = "independent";
Camera.orientation = Quat.lookAtSimple(Camera.position, Vec3.ZERO);
(static) mix( q1, q2, alpha ) → {Quat}
Returns: A spherical linear interpolation between rotations q1 and q2.

Compute a spherical linear interpolation between two rotations, safely handling two rotations that are very similar. See also, Quat.slerp.

Parameters

Name Type Description
q1 Quat The beginning rotation.
q2 Quat The ending rotation.
alpha number The mixture coefficient between 0.0 and 1.0. Specifies the proportion of q2's value to return in favor of q1's value. A value of 0.0 returns q1's value; 1.0 returns q2s's value.
Example

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);
(static) multiply( q1, q2 ) → {Quat}
Returns: q1 multiplied with q2.

Multiply two quaternions.

Parameters

Name Type Description
q1 Quat The first quaternion.
q2 Quat The second quaternion.
Example

Calculate the orientation of your avatar's right hand in world coordinates.

var handController = Controller.Standard.RightHand;
var handPose = Controller.getPoseValue(handController);
if (handPose.valid) {
    var handOrientation = Quat.multiply(MyAvatar.orientation, handPose.rotation);
}
(static) normalize( q ) → {Quat}
Returns: q normalized to have unit length.

Normalizes a quaternion.

Parameters

Name Type Description
q Quat The quaternion to normalize.
Example

Normalize a repeated delta rotation so that maths rounding errors don't accumulate.

var deltaRotation = Quat.fromPitchYawRollDegrees(0, 0.1, 0);
var currentRotation = Quat.ZERO;
while (Quat.safeEulerAngles(currentRotation).y < 180) {
    currentRotation = Quat.multiply(deltaRotation, currentRotation);
    currentRotation = Quat.normalize(currentRotation);
    // Use currentRotatation for something.
}
(static) print( label, q, asDegreesopt )

Print to the program log a text label followed by a quaternion's pitch, yaw, and roll Euler angles.

Parameters

Name Type Attributes Default Value Description
label string The label to print.
q Quat The quaternion to print.
asDegrees boolean <optional>
false If true the angle values are printed in degrees, otherwise they are printed in radians.
Example

Two ways of printing a label plus a quaternion's Euler angles.

var quaternion = Quat.fromPitchYawRollDegrees(0, 45, 0);

// Quaternion: dvec3(0.000000, 45.000004, 0.000000)
Quat.print("Quaternion:", quaternion,  true);

// Quaternion: {"x":0,"y":45.000003814697266,"z":0}
print("Quaternion: " + JSON.stringify(Quat.safeEulerAngles(quaternion)));
(static) rotationBetween( v1, v2 ) → {Quat}
Returns: The rotation from v1 onto v2.

Calculate the shortest rotation from a first vector onto a second.

Parameters

Name Type Description
v1 Vec3 The first vector.
v2 Vec3 The second vector.
Example

Apply a change in velocity to an entity and rotate it to face the direction it's travelling.

var newVelocity = Vec3.sum(entityVelocity, deltaVelocity);
var properties = { velocity: newVelocity };
if (Vec3.length(newVelocity) > 0.001) {
    properties.rotation = Quat.rotationBetween(entityVelocity, newVelocity);
}
Entities.editEntity(entityID, properties);
entityVelocity = newVelocity;
(static) safeEulerAngles( orientation ) → {Vec3}
Returns: A Vec3 of Euler angles for the orientation, in degrees, the angles being the rotations about the x, y, and z axes.

Calculate the Euler angles for the quaternion, in degrees. (The "safe" in the name signifies that the angle results will not be garbage even when the rotation is particularly difficult to decompose with pitches around +/-90 degrees.)

Parameters

Name Type Description
orientation Quat A quaternion representing an orientation.
Example

Report the camera yaw.

var eulerAngles = Quat.safeEulerAngles(Camera.orientation);
print("Camera yaw: " + eulerAngles.y);
(static) slerp( q1, q2, alpha ) → {Quat}
Returns: A spherical linear interpolation between rotations q1 and q2.

Compute a spherical linear interpolation between two rotations, for rotations that are not very similar. See also, Quat.mix.

Parameters

Name Type Description
q1 Quat The beginning rotation.
q2 Quat The ending rotation.
alpha number The mixture coefficient between 0.0 and 1.0. Specifies the proportion of q2's value to return in favor of q1's value. A value of 0.0 returns q1's value; 1.0 returns q2s's value.
(static) squad( q1, q2, s1, s2, alpha ) → {Quat}
Returns: A spherical quadrangle interpolation between rotations q1 and q2 using control points s1 and s2.

Compute a spherical quadrangle interpolation between two rotations along a path oriented toward two other rotations. Equivalent to: Quat.slerp(Quat.slerp(q1, q2, alpha), Quat.slerp(s1, s2, alpha), 2 * alpha * (1.0 - alpha)).

Parameters

Name Type Description
q1 Quat Initial rotation.
q2 Quat Final rotation.
s1 Quat First control point.
s2 Quat Second control point.
alpha number The mixture coefficient between 0.0 and 1.0. A value of 0.0 returns q1's value; 1.0 returns q2s's value.