mdi-backburger

# 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 Overte 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 Overte 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 Overte 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 Overte 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 Overte 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 Overte 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 Overte 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 Overte 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.