Mirror Engine API / Quat
Class: Quat
A quaternion representing rotation in 3D space. Quaternions are typically used to represent rotations in 3D applications, offering advantages over Euler angles including no gimbal lock and more efficient interpolation.
Constructors
new Quat()
new Quat(
x?: number | number[],
y?: number,
z?: number,
w?: number): Quat
Create a new Quat instance.
Parameters
x?
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.
number | number[]
y?
number = 0
The quaternion's y component. Defaults to 0.
z?
number = 0
The quaternion's z component. Defaults to 0.
w?
number = 1
The quaternion's w component. Defaults to 1.
Returns
Properties
w
w: number
The w component of the quaternion.
x
x: number
The x component of the quaternion.
y
y: number
The y component of the quaternion.
z
z: number
The z component of the quaternion.
IDENTITY
readonly static IDENTITY: Quat;
A constant quaternion set to [0, 0, 0, 1] (the identity). Represents no rotation.
ZERO
readonly static ZERO: Quat;
A constant quaternion set to [0, 0, 0, 0].
Methods
clone()
clone(): Quat
Returns an identical copy of the specified quaternion.
Returns
A new quaternion identical to this one.
Example
const q = new Quat(-0.11, -0.15, -0.46, 0.87)
const qclone = q.clone()
console.log('The result of the cloning is: ' + qclone.toString())
copy()
copy(rhs: Quat): Quat
Copies the contents of a source quaternion to a destination quaternion.
Parameters
rhs
The quaternion to be copied.
Returns
Self for chaining.
Example
const src = new Quat()
const dst = new Quat()
dst.copy(src)
console.log(
'The two quaternions are ' + (src.equals(dst) ? 'equal' : 'different')
)
equals()
equals(rhs: Quat): boolean
Reports whether two quaternions are equal.
Parameters
rhs
The quaternion to be compared against.
Returns
boolean
True if the quaternions are equal and false otherwise.
Example
const a = new Quat()
const b = new Quat()
console.log('The two quaternions are ' + (a.equals(b) ? 'equal' : 'different'))
equalsApprox()
equalsApprox(rhs: Quat, epsilon?: number): boolean
Reports whether two quaternions are equal using an absolute error tolerance.
Parameters
rhs
The quaternion to be compared against.
epsilon?
number = 1e-6
The maximum difference between each component of the two quaternions. Defaults to 1e-6.
Returns
boolean
True if the quaternions are equal and false otherwise.
Example
const a = new Quat()
const b = new Quat()
console.log(
'The two quaternions are approximately ' +
(a.equalsApprox(b, 1e-9) ? 'equal' : 'different')
)
getAxisAngle()
getAxisAngle(axis: Vec3): number
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.
Parameters
axis
The 3-dimensional vector to receive the axis of rotation.
Returns
number
Angle, in degrees, of the rotation.
Example
const q = new Quat()
q.setFromAxisAngle(new Vec3(0, 1, 0), 90)
const v = new Vec3()
const angle = q.getAxisAngle(v)
// Outputs 90
console.log(angle)
// Outputs [0, 1, 0]
console.log(v.toString())
getEulerAngles()
getEulerAngles(eulers?: Vec3): Vec3
Converts the supplied quaternion to Euler angles.
Parameters
eulers?
Vec3 = ...
The 3-dimensional vector to receive the Euler angles.
Returns
The 3-dimensional vector holding the Euler angles that correspond to the supplied quaternion.
Example
const q = new Quat()
q.setFromAxisAngle(new Vec3(0, 1, 0), 90)
const e = new Vec3()
q.getEulerAngles(e)
// Outputs [0, 90, 0]
console.log(e.toString())
invert()
invert(src?: Quat): Quat
Generates the inverse of the specified quaternion.
Parameters
src?
Quat = ...
The quaternion to invert. If not set, the operation is done in place.
Returns
Self for chaining.
Example
// Create a quaternion rotated 180 degrees around the y-axis
const rot = new Quat().setFromEulerAngles(0, 180, 0)
// Invert in place
rot.invert()
length()
length(): number
Returns the magnitude of the specified quaternion.
Returns
number
The magnitude of the specified quaternion.
Example
const q = new Quat(0, 0, 0, 5)
const len = q.length()
// Outputs 5
console.log('The length of the quaternion is: ' + len)
lengthSq()
lengthSq(): number
Returns the magnitude squared of the specified quaternion.
Returns
number
The magnitude squared of the quaternion.
Example
const q = new Quat(3, 4, 0, 0)
const lenSq = q.lengthSq()
// Outputs 25
console.log('The length squared of the quaternion is: ' + lenSq)
mul()
mul(rhs: Quat): Quat
Returns the result of multiplying the specified quaternions together.
Parameters
rhs
The quaternion used as the second multiplicand of the operation.
Returns
Self for chaining.
Example
const a = new Quat().setFromEulerAngles(0, 30, 0)
const b = new 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())
mul2()
mul2(lhs: Quat, rhs: Quat): Quat
Returns the result of multiplying the specified quaternions together.
Parameters
lhs
The quaternion used as the first multiplicand of the operation.
rhs
The quaternion used as the second multiplicand of the operation.
Returns
Self for chaining.
Example
const a = new Quat().setFromEulerAngles(0, 30, 0)
const b = new Quat().setFromEulerAngles(0, 60, 0)
const r = new Quat()
// r is set to a 90 degree rotation around the Y axis
// In other words, r = a * b
r.mul2(a, b)
mulScalar()
mulScalar(scalar: number, src?: Quat): Quat
Multiplies each element of a quaternion by a number.
Parameters
scalar
number
The number to multiply by.
src?
Quat = ...
The quaternion to scale. If not set, the operation is done in place.
Returns
Self for chaining.
Example
const q = new Quat(1, 2, 3, 4)
q.mulScalar(2)
// q is now [2, 4, 6, 8]
normalize()
normalize(src?: Quat): Quat
Normalizes the specified quaternion.
Parameters
src?
Quat = ...
The quaternion to normalize. If not set, the operation is done in place.
Returns
The result of the normalization.
Example
const v = new Quat(0, 0, 0, 5)
v.normalize()
// Outputs [0, 0, 0, 1]
console.log(v.toString())
set()
set(
x: number,
y: number,
z: number,
w: number): Quat
Sets the specified quaternion to the supplied numerical values.
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
Self for chaining.
Example
const q = new Quat()
q.set(1, 0, 0, 0)
// Outputs 1, 0, 0, 0
console.log('The result of the vector set is: ' + q.toString())
setFromAxisAngle()
setFromAxisAngle(axis: Vec3, angle: number): Quat
Sets a quaternion from an angular rotation around an axis.
Parameters
axis
World space axis around which to rotate. Should be normalized.
angle
number
Angle to rotate around the given axis in degrees.
Returns
Self for chaining.
Example
const q = new Quat()
q.setFromAxisAngle(Vec3.UP, 90)
setFromDirections()
setFromDirections(from: Vec3, to: Vec3): Quat
Set the quaternion that represents the shortest rotation from one direction to another.
Parameters
from
The direction to rotate from. It should be normalized.
to
The direction to rotate to. It should be normalized.
Returns
Self for chaining.
Example
const q = new Quat()
const from = new Vec3(0, 0, 1)
const to = new Vec3(0, 1, 0)
q.setFromDirections(from, to)
setFromEulerAngles()
setFromEulerAngles(
ex: number | Vec3,
ey?: number,
ez?: number): Quat
Sets a quaternion from Euler angles specified in XYZ order.
Parameters
ex
Angle to rotate around X axis in degrees. If ex is a Vec3, the three angles will be read from it instead.
number | Vec3
ey?
number
Angle to rotate around Y axis in degrees.
ez?
number
Angle to rotate around Z axis in degrees.
Returns
Self for chaining.
Example
// Create a quaternion from 3 euler angles
const q = new Quat()
q.setFromEulerAngles(45, 90, 180)
// Create the same quaternion from a vector containing the same 3 euler angles
const v = new Vec3(45, 90, 180)
const r = new Quat()
r.setFromEulerAngles(v)
setFromMat4()
setFromMat4(m: Mat4): Quat
Converts the specified 4x4 matrix to a quaternion. Note that since a quaternion is purely a representation for orientation, only the rotational part of the matrix is used.
Parameters
m
The 4x4 matrix to convert.
Returns
Self for chaining.
Example
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
const rot = new Mat4().setFromAxisAngle(Vec3.UP, 180)
// Convert to a quaternion
const q = new Quat().setFromMat4(rot)
slerp()
slerp(
lhs: Quat,
rhs: Quat,
alpha: number): Quat
Performs a spherical interpolation between two quaternions. The result of the interpolation is written to the quaternion calling the function.
Parameters
lhs
The quaternion to interpolate from.
rhs
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
Self for chaining.
Example
const q1 = new Quat(-0.11, -0.15, -0.46, 0.87)
const q2 = new Quat(-0.21, -0.21, -0.67, 0.68)
const result = new Quat()
result.slerp(q1, q2, 0) // Return q1
result.slerp(q1, q2, 0.5) // Return the midpoint interpolant
result.slerp(q1, q2, 1) // Return q2
toString()
toString(): string
Converts the quaternion to string form.
Returns
string
The quaternion in string form.
Example
const v = new Quat(0, 0, 0, 1)
// Outputs [0, 0, 0, 1]
console.log(v.toString())
transformVector()
transformVector(vec: Vec3, res?: Vec3): Vec3
Transforms a 3-dimensional vector by the specified quaternion.
Parameters
vec
The 3-dimensional vector to be transformed.
res?
Vec3 = ...
An optional 3-dimensional vector to receive the result of the transformation.
Returns
The transformed vector (res if specified, otherwise a new Vec3).
Example
// Create a 3-dimensional vector
const v = new Vec3(1, 2, 3)
// Create a quaternion rotation
const q = new Quat().setFromEulerAngles(10, 20, 30)
const tv = q.transformVector(v)