Quat

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar 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.

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 }

Properties

Name Type Summary
IDENTITY Quat

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

Methods

Name Return Value Summary
angle number

Gets the rotation angle for a quaternion.

angleAxis Quat

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

axis Vec3

Gets 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

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

dot number

Calculates 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

Tests 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

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

fromPitchYawRollRadians Quat

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

fromVec3Degrees Quat

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

fromVec3Radians Quat

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

getForward Vec3

Gets 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 Vircadia camera has axes x = right, y = up, -z = forward.

getFront Vec3

Gets 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 Vircadia camera has axes x = right, y = up, -z = forward.

getRight Vec3

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

getUp Vec3

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

inverse Quat

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

lookAt Quat

Calculates a camera orientation given an 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

Calculates a camera orientation given an 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

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

multiply Quat

Multiplies two quaternions.

normalize Quat

Normalizes a quaternion.

print None

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

rotationBetween Quat

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

safeEulerAngles Vec3

Calculates 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

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

squad Quat

Computes 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.

Gets 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.

Generates 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.

Gets 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.

Calculates 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.

Calculates 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.

Tests 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.

Generates 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.fromPitchYawRollDegrees(0, 180, 0 );
(static) fromPitchYawRollRadians( pitch, yaw, roll ) → {Quat}
Returns: A quaternion created from the pitch, yaw, and roll Euler angles.

Generates 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.

Generates 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.

Generates 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.

Gets 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 Vircadia 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.

Gets 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 Vircadia 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.

Gets the "right" direction that the camera would have if its orientation was set to the quaternion value. The Vircadia 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.

Gets the "up" direction that the camera would have if its orientation was set to the quaternion value. The Vircadia 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.

Calculates 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.

Calculates a camera orientation given an 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.

Calculates a camera orientation given an 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.

Computes 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.

Multiplies 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 )

Prints 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.

Calculates 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.

Calculates 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.

Computes 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.

Computes 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.