Quat

Available in: Interface Scripts Client Entity Scripts Server Entity Scripts Assignment Client Scripts

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.
Methods
dot
mix

Properties:
Name Type Description
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

angle(q) → {number}
Get the rotation angle for a quaternion.
Parameters:
Name Type Description
q Quat The quaternion.
Returns:
The rotation angle for q, in radians. WARNING: This value is in radians whereas the value used by Quat.angleAxis is in degrees.
Type: number
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.
angleAxis(angle, axis) → {Quat}
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.
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.
Type: Quat
Example

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

var rotation = Quat.angleAxis(90, Quat.getForward(Camera.orientation));
axis(q) → {Vec3}
Get the rotation axis for a quaternion.
Parameters:
Name Type Description
q Quat The quaternion.
Returns:
The normalized rotation axis for q.
Type: Vec3
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.
cancelOutRoll(orientation) → {Quat}
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.
Returns:
orientation with its roll canceled out.
Type: Quat
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)
  
cancelOutRollAndPitch(orientation) → {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.
Parameters:
Name Type Description
orientation Quat A quaternion representing an orientation.
Returns:
orientation with its roll and pitch canceled out.
Type: Quat
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)
conjugate(q) → {Quat}
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.
Returns:
The conjugate of q.
Type: Quat
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)
dot(q1, q2) → {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.
Parameters:
Name Type Description
q1 Quat The first quaternion.
q2 Quat The second quaternion.
Returns:
The dot product of q1 and q2.
Type: number
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
equal(q1, q2) → {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.
Parameters:
Name Type Description
q1 Quat The first quaternion.
q2 Quat The second quaternion.
Returns:
true if the quaternions are equal, otherwise false.
Type: boolean
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
fromPitchYawRollDegrees(pitch, yaw, roll) → {Quat}
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.
Returns:
A quaternion created using the pitch, yaw, and roll Euler angles.
Type: Quat
Example

Create a rotation of 180 degrees about the y axis.

var rotation = Quat.fromPitchYawRollDgrees(0, 180, 0 );
fromPitchYawRollRadians(pitch, yaw, roll) → {Quat}
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.
Returns:
A quaternion created from the pitch, yaw, and roll Euler angles.
Type: Quat
Example

Create a rotation of 180 degrees about the y axis.

var rotation = Quat.fromPitchYawRollRadians(0, Math.PI, 0);
fromVec3Degrees(vector) → {Quat}
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.
Returns:
A quaternion created from the Euler angles in vector.
Type: Quat
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);
fromVec3Radians(vector) → {Quat}
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.
Returns:
A quaternion created using the Euler angles in vector.
Type: Quat
Example

Create a rotation of 180 degrees about the y axis.

var rotation = Quat.fromVec3Radians({ x: 0, y: Math.PI, z: 0 });
getForward(orientation) → {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.
Parameters:
Name Type Description
orientation Quat A quaternion representing an orientation.
Returns:
The negative z-axis rotated by orientation.
Type: Vec3
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}
getFront(orientation) → {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.
Parameters:
Name Type Description
orientation Quat A quaternion representing an orientation.
Returns:
The negative z-axis rotated by orientation.
Type: Vec3
getRight(orientation) → {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.
Parameters:
Name Type Description
orientation Quat A quaternion representing an orientation.
Returns:
The x-axis rotated by orientation.
Type: Vec3
getUp(orientation) → {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.
Parameters:
Name Type Description
orientation Quat A quaternion representing an orientation.
Returns:
The y-axis rotated by orientation.
Type: Vec3
inverse(q) → {Quat}
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.
Returns:
The inverse of q.
Type: Quat
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)
lookAt(eye, target, up) → {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.
Parameters:
Name Type Description
eye Vec3 The eye position.
target Vec3 The point to look at.
up Vec3 The "up" direction.
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.
Type: Quat
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);
lookAtSimple(eye, target) → {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.
Parameters:
Name Type Description
eye Vec3 The eye position.
target Vec3 The point to look at.
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.
Type: Quat
Example

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

Camera.mode = "independent";
Camera.orientation = Quat.lookAtSimple(Camera.position, Vec3.ZERO);
mix(q1, q2, alpha) → {Quat}
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.
Returns:
A spherical linear interpolation between rotations q1 and q2.
Type: Quat
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);
multiply(q1, q2) → {Quat}
Multiply two quaternions.
Parameters:
Name Type Description
q1 Quat The first quaternion.
q2 Quat The second quaternion.
Returns:
q1 multiplied with q2.
Type: Quat
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);
}
normalize(q) → {Quat}
Normalizes a quaternion.
Parameters:
Name Type Description
q Quat The quaternion to normalize.
Returns:
q normalized to have unit length.
Type: Quat
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.
}
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 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)));
rotationBetween(v1, v2) → {Quat}
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.
Returns:
The rotation from v1 onto v2.
Type: Quat
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;
safeEulerAngles(orientation) → {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.)
Parameters:
Name Type Description
orientation Quat A quaternion representing an orientation.
Returns:
A Vec3 of Euler angles for the orientation, in degrees, the angles being the rotations about the x, y, and z axes.
Type: Vec3
Example

Report the camera yaw.

var eulerAngles = Quat.safeEulerAngles(Camera.orientation);
print("Camera yaw: " + eulerAngles.y);
slerp(q1, q2, alpha) → {Quat}
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.
Returns:
A spherical linear interpolation between rotations q1 and q2.
Type: Quat
squad(q1, q2, s1, s2, alpha) → {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)).
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.
Returns:
A spherical quadrangle interpolation between rotations q1 and q2 using control points s1 and s2.
Type: Quat