Quat - Vircadia API Docs

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.