Quat
A quaternion.
Summary
Static Properties
IDENTITY | A constant quaternion set to [0, 0, 0, 1] (the identity).[read only] |
ZERO | A constant quaternion set to [0, 0, 0, 0].[read only] |
Properties
w | The w component of the quaternion. |
x | The x component of the quaternion. |
y | The y component of the quaternion. |
z | The z component of the quaternion. |
Methods
clone | Returns an identical copy of the specified quaternion. |
copy | Copies the contents of a source quaternion to a destination quaternion. |
equals | Reports whether two quaternions are equal. |
equalsApprox | Reports whether two quaternions are equal using an absolute error tolerance. |
getAxisAngle | Gets the rotation axis and angle for a given quaternion. |
getEulerAngles | Converts the supplied quaternion to Euler angles. |
invert | Generates the inverse of the specified quaternion. |
length | Returns the magnitude of the specified quaternion. |
lengthSq | Returns the magnitude squared of the specified quaternion. |
mul | Returns the result of multiplying the specified quaternions together. |
mul2 | Returns the result of multiplying the specified quaternions together. |
normalize | Returns the specified quaternion converted in place to a unit quaternion. |
set | Sets the specified quaternion to the supplied numerical values. |
setFromAxisAngle | Sets a quaternion from an angular rotation around an axis. |
setFromDirections | Set the quaternion that represents the shortest rotation from one direction to another. |
setFromEulerAngles | Sets a quaternion from Euler angles specified in XYZ order. |
setFromMat4 | Converts the specified 4x4 matrix to a quaternion. |
slerp | Performs a spherical interpolation between two quaternions. |
toString | Converts the quaternion to string form. |
transformVector | Transforms a 3-dimensional vector by the specified quaternion. |
Details
Static Properties
IDENTITY | A constant quaternion set to [0, 0, 0, 1] (the identity). [read only] |
ZERO | A constant quaternion set to [0, 0, 0, 0]. [read only] |
Constructor
Quat([x], [y], [z], [w])
Create a new Quat instance.
Parameters
x | number, number[] | The quaternion's x component. Defaults to 0. If x is an array of length 4, the array will be used to populate all components. |
y | number | The quaternion's y component. Defaults to 0. |
z | number | The quaternion's z component. Defaults to 0. |
w | number | The quaternion's w component. Defaults to 1. |
Properties
Methods
clone()
Returns an identical copy of the specified quaternion.
const q = new pc.Quat(-0.11, -0.15, -0.46, 0.87);
const qclone = q.clone();
console.log("The result of the cloning is: " + q.toString());
Returns
thisA quaternion containing the result of the cloning.
copy(rhs)
Copies the contents of a source quaternion to a destination quaternion.
const src = new pc.Quat();
const dst = new pc.Quat();
dst.copy(src, src);
console.log("The two quaternions are " + (src.equals(dst) ? "equal" : "different"));
Parameters
rhs | Quat | The quaternion to be copied. |
Returns
QuatSelf for chaining.
equals(rhs)
Reports whether two quaternions are equal.
const a = new pc.Quat();
const b = new pc.Quat();
console.log("The two quaternions are " + (a.equals(b) ? "equal" : "different"));
Parameters
rhs | Quat | The quaternion to be compared against. |
Returns
booleanTrue if the quaternions are equal and false otherwise.
equalsApprox(rhs, [epsilon])
Reports whether two quaternions are equal using an absolute error tolerance.
const a = new pc.Quat();
const b = new pc.Quat();
console.log("The two quaternions are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
Parameters
rhs | Quat | The quaternion to be compared against. |
epsilon | number | The maximum difference between each component of the two quaternions. Defaults to 1e-6. |
Returns
booleanTrue if the quaternions are equal and false otherwise.
getAxisAngle(axis)
Gets the rotation axis and angle for a given quaternion. If a quaternion is created with
setFromAxisAngle
, this method will return the same values as provided in the original
parameter list OR functionally equivalent values.
const q = new pc.Quat();
q.setFromAxisAngle(new pc.Vec3(0, 1, 0), 90);
const v = new pc.Vec3();
const angle = q.getAxisAngle(v);
// Outputs 90
console.log(angle);
// Outputs [0, 1, 0]
console.log(v.toString());
Parameters
axis | Vec3 | The 3-dimensional vector to receive the axis of rotation. |
Returns
numberAngle, in degrees, of the rotation.
getEulerAngles([eulers])
Converts the supplied quaternion to Euler angles.
Parameters
eulers | Vec3 | The 3-dimensional vector to receive the Euler angles. |
Returns
Vec3The 3-dimensional vector holding the Euler angles that correspond to the supplied quaternion.
invert()
Generates the inverse of the specified quaternion.
// Create a quaternion rotated 180 degrees around the y-axis
const rot = new pc.Quat().setFromEulerAngles(0, 180, 0);
// Invert in place
rot.invert();
Returns
QuatSelf for chaining.
length()
Returns the magnitude of the specified quaternion.
const q = new pc.Quat(0, 0, 0, 5);
const len = q.length();
// Outputs 5
console.log("The length of the quaternion is: " + len);
Returns
numberThe magnitude of the specified quaternion.
lengthSq()
Returns the magnitude squared of the specified quaternion.
const q = new pc.Quat(3, 4, 0);
const lenSq = q.lengthSq();
// Outputs 25
console.log("The length squared of the quaternion is: " + lenSq);
Returns
numberThe magnitude of the specified quaternion.
mul(rhs)
Returns the result of multiplying the specified quaternions together.
const a = new pc.Quat().setFromEulerAngles(0, 30, 0);
const b = new pc.Quat().setFromEulerAngles(0, 60, 0);
// a becomes a 90 degree rotation around the Y axis
// In other words, a = a * b
a.mul(b);
console.log("The result of the multiplication is: " + a.toString());
Parameters
rhs | Quat | The quaternion used as the second multiplicand of the operation. |
Returns
QuatSelf for chaining.
mul2(lhs, rhs)
Returns the result of multiplying the specified quaternions together.
const a = new pc.Quat().setFromEulerAngles(0, 30, 0);
const b = new pc.Quat().setFromEulerAngles(0, 60, 0);
const r = new pc.Quat();
// r is set to a 90 degree rotation around the Y axis
// In other words, r = a * b
r.mul2(a, b);
console.log("The result of the multiplication is: " + r.toString());
Parameters
lhs | Quat | The quaternion used as the first multiplicand of the operation. |
rhs | Quat | The quaternion used as the second multiplicand of the operation. |
Returns
QuatSelf for chaining.
normalize()
Returns the specified quaternion converted in place to a unit quaternion.
const v = new pc.Quat(0, 0, 0, 5);
v.normalize();
// Outputs 0, 0, 0, 1
console.log("The result of the vector normalization is: " + v.toString());
Returns
QuatThe result of the normalization.
set(x, y, z, w)
Sets the specified quaternion to the supplied numerical values.
const q = new pc.Quat();
q.set(1, 0, 0, 0);
// Outputs 1, 0, 0, 0
console.log("The result of the vector set is: " + q.toString());
Parameters
x | number | The x component of the quaternion. |
y | number | The y component of the quaternion. |
z | number | The z component of the quaternion. |
w | number | The w component of the quaternion. |
Returns
QuatSelf for chaining.
setFromAxisAngle(axis, angle)
Sets a quaternion from an angular rotation around an axis.
const q = new pc.Quat();
q.setFromAxisAngle(pc.Vec3.UP, 90);
Parameters
axis | Vec3 | World space axis around which to rotate. |
angle | number | Angle to rotate around the given axis in degrees. |
Returns
QuatSelf for chaining.
setFromDirections(from, to)
Set the quaternion that represents the shortest rotation from one direction to another.
Parameters
from | Vec3 | The direction to rotate from. It should be normalized. |
to | Vec3 | The direction to rotate to. It should be normalized. |
Returns
QuatSelf for chaining.
setFromEulerAngles(ex, [ey], [ez])
Sets a quaternion from Euler angles specified in XYZ order.
// Create a quaternion from 3 euler angles
const q = new pc.Quat();
q.setFromEulerAngles(45, 90, 180);
// Create the same quaternion from a vector containing the same 3 euler angles
const v = new pc.Vec3(45, 90, 180);
const r = new pc.Quat();
r.setFromEulerAngles(v);
Parameters
ex | number, Vec3 | Angle to rotate around X axis in degrees. If ex is a Vec3, the three angles will be read from it instead. |
ey | number | Angle to rotate around Y axis in degrees. |
ez | number | Angle to rotate around Z axis in degrees. |
Returns
QuatSelf for chaining.
setFromMat4(m)
Converts the specified 4x4 matrix to a quaternion. Note that since a quaternion is purely a representation for orientation, only the translational part of the matrix is lost.
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
const rot = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);
// Convert to a quaternion
const q = new pc.Quat().setFromMat4(rot);
Parameters
m | Mat4 | The 4x4 matrix to convert. |
Returns
QuatSelf for chaining.
slerp(lhs, rhs, alpha)
Performs a spherical interpolation between two quaternions. The result of the interpolation is written to the quaternion calling the function.
const q1 = new pc.Quat(-0.11, -0.15, -0.46, 0.87);
const q2 = new pc.Quat(-0.21, -0.21, -0.67, 0.68);
const result;
result = new pc.Quat().slerp(q1, q2, 0); // Return q1
result = new pc.Quat().slerp(q1, q2, 0.5); // Return the midpoint interpolant
result = new pc.Quat().slerp(q1, q2, 1); // Return q2
Parameters
lhs | Quat | The quaternion to interpolate from. |
rhs | Quat | The quaternion to interpolate to. |
alpha | number | The value controlling the interpolation in relation to the two input quaternions. The value is in the range 0 to 1, 0 generating q1, 1 generating q2 and anything in between generating a spherical interpolation between the two. |
Returns
QuatSelf for chaining.
toString()
Converts the quaternion to string form.
const v = new pc.Quat(0, 0, 0, 1);
// Outputs [0, 0, 0, 1]
console.log(v.toString());
Returns
stringThe quaternion in string form.
transformVector(vec, [res])
Transforms a 3-dimensional vector by the specified quaternion.
// Create a 3-dimensional vector
const v = new pc.Vec3(1, 2, 3);
// Create a 4x4 rotation matrix
const q = new pc.Quat().setFromEulerAngles(10, 20, 30);
const tv = q.transformVector(v);
Parameters
vec | Vec3 | The 3-dimensional vector to be transformed. |
res | Vec3 | An optional 3-dimensional vector to receive the result of the transformation. |
Returns
Vec3The input vector v transformed by the current instance.