Description
Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts
TheQuat
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 |
|
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 |
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 |
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 |
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 |
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 |
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: |
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
ExampleGet the rotation angle of a quaternion.
|
(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
ExampleCalculate a rotation of 90 degrees about the direction your camera is looking.
|
(static) axis( q ) → {Vec3}
Returns: The normalized rotation axis for q .
|
||||||
---|---|---|---|---|---|---|
Gets the rotation axis for a quaternion. Parameters
ExampleGet the rotation axis of a quaternion.
|
(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
ExampleTwo ways of calculating a camera orientation that points in the direction of a given quaternion but keeps the camera's horizontal axis level.
|
(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
ExampleTwo ways of calculating a camera orientation in the x-z plane with a yaw pointing in the direction of a given quaternion.
|
(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
ExampleA unit quaternion multiplied by its conjugate is a zero rotation.
|
(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
ExampleTesting unit quaternions for equality.
|
(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 Parameters
ExampleTesting unit quaternions for equality.
|
(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
ExampleCreate a rotation of 180 degrees about the y axis.
|
(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
ExampleCreate a rotation of 180 degrees about the y axis.
|
(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
ExampleZero out pitch and roll from an orientation.
|
(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
ExampleCreate a rotation of 180 degrees about the y axis.
|
(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 Parameters
ExampleDemonstrate that the "forward" vector is for the negative z-axis.
|
(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 Parameters
|
(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 Parameters
|
(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 Parameters
|
(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
ExampleA quaternion multiplied by its inverse is a zero rotation.
|
(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
ExampleRotate your view in independent mode to look at the world origin upside down.
|
(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
ExampleRotate your view in independent mode to look at the world origin.
|
(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
ExampleAnimate between one rotation and another.
|
(static) multiply( q1, q2 ) → {Quat}
Returns: q1 multiplied with q2 .
|
|||||||||
---|---|---|---|---|---|---|---|---|---|
Multiplies two quaternions. Parameters
ExampleCalculate the orientation of your avatar's right hand in world coordinates.
|
(static) normalize( q ) → {Quat}
Returns: q normalized to have unit length.
|
||||||
---|---|---|---|---|---|---|
Normalizes a quaternion. Parameters
ExampleNormalize a repeated delta rotation so that maths rounding errors don't accumulate.
|
(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
ExampleTwo ways of printing a label plus a quaternion's Euler angles.
|
(static) rotationBetween( v1, v2 ) → {Quat}
Returns: The rotation from v1 onto v2 .
|
|||||||||
---|---|---|---|---|---|---|---|---|---|
Calculates the shortest rotation from a first vector onto a second. Parameters
ExampleApply a change in velocity to an entity and rotate it to face the direction it's travelling.
|
(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
ExampleReport the camera yaw.
|
(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
|
(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: Parameters
|