Class Quaternion

This class holds a quaternion rotation. It includes routines for using the quaternion to rotate points and vectors. It includes routines for constructing many common rotations and inverting the rotation as well as accessing the underlying x,y,z,w components of the quaterion.

Most of the functions in the class are defined both as member functions that can be called on a specific instance of Quaternion and as static functions. The static functions return a new result, leaving the original inputs unchanged, whereas, in general, member functions save the result in the quaternion itself and return void:

const Q1 = Quaternion.makeRotationX(Math.PI);
const Q2 = Quaternion.makeRotationY(Math.PI);

// save the result in Q3, leaving Q1 and Q2 unchanged
const Q3 = Quaternion.multiply(Q1, Q2);

// each call to multiply overwrites the previous contents of Q4 with the result of the multiplication
const Q4 = Quaternion.makeRotationZ(Math.PI);
Q4.multiply(Q1);
Q4.multiply(Q2);

Index

Constructors

constructor

new Quaternion(x?: number, y?: number, z?: number, w?: number): Quaternion
Creates a new Quaternion object with zero rotation (i.e., the identity quaternion)
Parameters
- x: number = 0
  The x component of the Quaternion
- y: number = 0
  The y component of the Quaternion
- z: number = 0
  The z component of the Quaternion
- w: number = 1
  The w component of the Quaternion
Returns Quaternion
- Defined in math/Quaternion.ts:307

Properties

w

w: number

x

x: number

y

y: number

z

z: number

`Static` `Readonly`IDENTITY

IDENTITY: Quaternion = ...

A static property to provide quick access to the identity quaternion (0, 0, 0, 1). (Note: Be careful not to change the value of this field! It is marked readonly, but typescipt do not completely enforce this!)

// Good use of IDENTITY:
const q = Quaternion();
if (q.equals(Quaternion.IDENTITY)) {
  console.log("q equals the identity quaternion")
}

// Dangerous use of IDENTITY!!!!
const q = Quaternion.IDENTITY;  // makes q a reference to Quaternion.IDENTITY
q.makeRotationZ(Math.PI); // changes Quaternion.IDENTITY!

// Do this instead:
const q = Quaternion.makeIdentity(); // create a new identity matrix M
q.makeRotationZ(Math.PI

Methods

clone

clone(): Quaternion
Creates a new quaternion with the same values as this one

Returns Quaternion
A new quaternion with the same values as this one
- Defined in math/Quaternion.ts:534

copy

copy(q: Quaternion): void
Copies the x,y,z,w components of another quaternion into this one
Parameters
- q: Quaternion
  The quaternion to copy
Returns void
- Defined in math/Quaternion.ts:521

getMatrix

getMatrix(): Matrix4
Converts this quaternion into an equivalent 4x4 rotation matrix and returns the result.

Returns Matrix4
A 4x4 rotation matrix representation of this Quaternion
- Defined in math/Quaternion.ts:606

inverse

inverse(): Quaternion
Computes the inverse of this quaternion and returns the result in a new quaternion.

Returns Quaternion
The inverse of this Quaternion
- Defined in math/Quaternion.ts:596

invert

invert(): void
Inverts the quaternion and save the result in this quaternion.

Returns void
- Defined in math/Quaternion.ts:580

lookAt

lookAt(eyePoint: Vector3, targetPoint: Vector3, upVector?: Vector3): void
Sets this quaternion to a rotation like that used to orient a camera. The quaternion will rotate the -Z direction (typically, the "forward" direction for objects and the default "look" direction for cameras) to point in the new "look" direction defined by the vector (targetPoint - eyePoint). The up vector is used to further constrain the rotation. The original Y direction will rotate to point, as much as possible, toward the upVector.
Parameters
- eyePoint: Vector3
  The position of the camera or other object being oriented
- targetPoint: Vector3
  The point to look at
- upVector: Vector3 = Vector3.UP
  The direction that the original +Y direction should rotate into (as closely as possible).
Returns void
- Defined in math/Quaternion.ts:652

makeIdentity

makeIdentity(): Quaternion
Creates a new identity Quaternion object

Returns Quaternion
A new Quaternion object representing the identity Quaternion (0, 0, 0, 1)
- Defined in math/Quaternion.ts:133

multiply

multiply(q: Quaternion): void
Multiply this quaternion with the input quaternion and save the result in this quaternion. i.e., this = this * q Quaternion multiplication is not commutative, so order matters. See premultiply() to do the multiplication in the opposite order.
Parameters
- q: Quaternion
  The quaternion to multiply with
Returns void
- Defined in math/Quaternion.ts:546

normalize

normalize(): void
Normalize this quaternion and save the result in this quaternion.

Returns void
- Defined in math/Quaternion.ts:566

premultiply

premultiply(q: Quaternion): void
Premultiply this quaternion with the input quaternion and save the result in this quaternion. i.e., this = q * this. This operation is not commutative, so order matters; See multiply() to do the multiplication in the opposite order.
Parameters
- q: Quaternion
  The quaternion to premultiply with
Returns void
- Defined in math/Quaternion.ts:558

rotate

rotate(v: Vector3): Vector3
Rotates a 3D point or 3D vector by this quaternion and returns the result in a new Vector3
Parameters
- v: Vector3
  The original 3D point or 3D vector
Returns Vector3
A new 3D point or 3D vector
- Defined in math/Quaternion.ts:746

set

set(x: number, y: number, z: number, w: number): void
Sets the x,y,z,w components of the quaternion to the given x, y, z, and w values
Parameters
- x: number
  The x value
- y: number
  The y value
- z: number
  The z value
- w: number
  The w value
Returns void
- Defined in math/Quaternion.ts:323

setAxisAngle

setAxisAngle(axis: Vector3, angle: number): void
Sets the quaternion to a rotation around axis by angle radians. Note, the axis parameter must be a unit vector.
Parameters
- axis: Vector3
  A unit vector that describes the axis of rotation
- angle: number
  The angle of rotation in radians
Returns void
- Defined in math/Quaternion.ts:388

setEulerAngles

setEulerAngles(x: number, y: number, z: number, order?: string): void
Sets the quaternion to the rotation specified by the provied Euler angles and order of rotation
Parameters
- x: number
  The x-axis rotation angle in radians
- y: number
  The y-axis rotation angle in radians
- z: number
  The z-axis rotation angle in radians
- order: string = 'YZX'
  The order in which the rotation angles are applied (defaults to 'YZX')
Returns void
- Defined in math/Quaternion.ts:409

setIdentity

setIdentity(): void
Sets the quaternion to the identity quaternion

Returns void
- Defined in math/Quaternion.ts:335

setMatrix

setMatrix(matrix: Matrix4): void
Sets the quaternion to a rotation equal to the one in the provided 4x4 rotation matrix
Parameters
- matrix: Matrix4
  A 4x4 rotation matrix
Returns void
- Defined in math/Quaternion.ts:475

setRotationX

setRotationX(angle: number): void
Sets the quaternion to a rotation around the x axis
Parameters
- angle: number
  The angle of rotation in radians
Returns void
- Defined in math/Quaternion.ts:348

setRotationY

setRotationY(angle: number): void
Sets the quaternion to a rotation around the y axis
Parameters
- angle: number
  The angle of rotation in radians
Returns void
- Defined in math/Quaternion.ts:361

setRotationZ

setRotationZ(angle: number): void
Sets the quaternion to a rotation around the z axis
Parameters
- angle: number
  The angle of rotation in radians
Returns void
- Defined in math/Quaternion.ts:374

slerp

slerp(q1: Quaternion, q2: Quaternion, alpha: number): void
Sets this quaternion to an interpolation between two quaternions, q1 and q2, based on the given alpha value
Parameters
- q1: Quaternion
  The starting quaternion
- q2: Quaternion
  The ending quaternion
- alpha: number
  The interpolation value (0-1)
Returns void
- Defined in math/Quaternion.ts:680

`Static`clone

clone(q: Quaternion): Quaternion
Creates a new quaternion and copies the x,y,z,w values of the input into it.
Parameters
- q: Quaternion
  The Quaternion object to copy
Returns Quaternion
A new Quaternion object with the same values as q
- Defined in math/Quaternion.ts:55

`Static`inverse

inverse(q: Quaternion): Quaternion
Returns a new quaternion that is the inverse (opposite rotation) of the input quaternion.
Parameters
- q: Quaternion
  The Quaternion object to invert
Returns Quaternion
A new Quaternion object representing the inverse of q
- Defined in math/Quaternion.ts:121

`Static`lookAt

lookAt(eyePoint: Vector3, targetPoint: Vector3, upVector?: Vector3): Quaternion
Creates a new quaternion with a rotation like that used to orient a camera. The quaternion will rotate the -Z direction (typically, the "forward" direction for objects and the default "look" direction for cameras) to point in the new "look" direction defined by the vector (targetPoint - eyePoint). The up vector is used to further constrain the rotation. The original Y direction will rotate to point, as much as possible, toward the upVector.
Parameters
- eyePoint: Vector3
  The position of the camera or other object being oriented
- targetPoint: Vector3
  The point to look at
- upVector: Vector3 = Vector3.UP
Returns Quaternion
A new Quaternion that performs the specified rotation
- Defined in math/Quaternion.ts:219

`Static`makeAxisAngle

makeAxisAngle(axis: Vector3, angle: number): Quaternion
Creates a new quaternion to represent a rotation of angle radians around axis.
Parameters
- axis: Vector3
  The axis to rotate around
- angle: number
  The angle of rotation
Returns Quaternion
A new Quaternion
- Defined in math/Quaternion.ts:184

`Static`makeEulerAngles

makeEulerAngles(x: number, y: number, z: number, order?: string): Quaternion
Creates a new quaternion from given Euler angles
Parameters
- x: number
  The x-axis rotation angle
- y: number
  The y-axis rotation angle
- z: number
  The z-axis rotation angle
- order: string = 'YZX'
  The order of the rotations (defaults to 'YZX')
Returns Quaternion
A new Quaternion
- Defined in math/Quaternion.ts:200

`Static`makeMatrix

makeMatrix(matrix: Matrix4): Quaternion
Creates a new quaternion with the same rotation as in the provided 4x4 transformation matrix.
Parameters
- matrix: Matrix4
  A 4x4 transformation matrix that includes a rotation.
Returns Quaternion
A new Quaternion that specifies the same rotation
- Defined in math/Quaternion.ts:246

`Static`makeRotationX

makeRotationX(angle: number): Quaternion
Creates a new Quaternion object representing a rotation around the x-axis
Parameters
- angle: number
  The angle to rotate by around the x-axis (in radians)
Returns Quaternion
A new Quaternion object representing a rotation around the x-axis
- Defined in math/Quaternion.ts:144

`Static`makeRotationY

makeRotationY(angle: number): Quaternion
Creates a new Quaternion object representing a rotation around the y-axis
Parameters
- angle: number
  The angle to rotate by around the y-axis (in radians)
Returns Quaternion
A new Quaternion object representing a rotation around the y-axis
- Defined in math/Quaternion.ts:157

`Static`makeRotationZ

makeRotationZ(angle: number): Quaternion
Creates a new Quaternion object representing a rotation around the z-axis
Parameters
- angle: number
  The angle to rotate by around the z-axis (in radians)
Returns Quaternion
A new Quaternion object representing a rotation around the z-axis
- Defined in math/Quaternion.ts:170

`Static`multiply

multiply(q1: Quaternion, q2: Quaternion): Quaternion
Multiplies two Quaternion objects together and returns a new quaternion = q1 * q2 Note: multiplication of quaternions is not commutative, so order matters. See premultiply() to do the opposite order, or just switch the order of the arguments.
Parameters
- q1: Quaternion
  The first Quaternion object
- q2: Quaternion
  The second Quaternion object
Returns Quaternion
A new Quaternion object representing the product of q1 and q2
- Defined in math/Quaternion.ts:69

`Static`normalize

normalize(q: Quaternion): Quaternion
Returns a new quaternion that is a normalized version of the input quaternion.
Parameters
- q: Quaternion
  The Quaternion object to normalize
Returns Quaternion
A new Quaternion object with normalized values
- Defined in math/Quaternion.ts:108

`Static`premultiply

premultiply(q1: Quaternion, q2: Quaternion): Quaternion
Premultiplies two Quaternion objects and returns a new quaternion = q2 * q1 Note: multiplication of quaternions is not commutative, so order matters. See multiply() to do the opposite order, or just switch the order of the arguments.
Parameters
- q1: Quaternion
  The first Quaternion object
- q2: Quaternion
  The second Quaternion object
Returns Quaternion
A new Quaternion object which is the result of the premultiplication of the two input Quaternion objects
- Defined in math/Quaternion.ts:90

`Static`rotate

rotate(v: Vector3, q: Quaternion): Vector3
Rotates a 3D point or 3D vector by the specified quaternion and returns the result in a new Vector3
Parameters
- v: Vector3
  The original 3D point or 3D vector
- q: Quaternion
  The rotation to apply
Returns Vector3
A new 3D point or 3D vector
- Defined in math/Quaternion.ts:275

`Static`slerp

slerp(q1: Quaternion, q2: Quaternion, alpha: number): Quaternion
Returns a Quaternion from two input Quaternions using spherical linear interpolation.
Parameters
- q1: Quaternion
  The first Quaternion
- q2: Quaternion
  The second Quaternion
- alpha: number
  The interpolation factor
Returns Quaternion
A new Quaternion representing the slerp between q1 and q2
- Defined in math/Quaternion.ts:261

Class Quaternion

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Quaternion

Properties

w

x

y

z

Static ReadonlyIDENTITY

Methods

clone

Returns Quaternion

copy

Parameters

Returns void

getMatrix

Returns Matrix4

inverse

Returns Quaternion

invert

Returns void

lookAt

Parameters

Returns void

makeIdentity

Returns Quaternion

multiply

Parameters

Returns void

normalize

Returns void

premultiply

Parameters

Returns void

rotate

Parameters

Returns Vector3

set

Parameters

Returns void

setAxisAngle

Parameters

Returns void

setEulerAngles

Parameters

Returns void

setIdentity

Returns void

setMatrix

Parameters

Returns void

setRotationX

Parameters

Returns void

setRotationY

Parameters

Returns void

setRotationZ

Parameters

Returns void

slerp

Parameters

Returns void

Staticclone

Parameters

Returns Quaternion

Staticinverse

Parameters

Returns Quaternion

StaticlookAt

Parameters

Returns Quaternion

StaticmakeAxisAngle

Parameters

`Static` `Readonly`IDENTITY

`Static`clone

`Static`inverse

`Static`lookAt

`Static`makeAxisAngle

`Static`makeEulerAngles

`Static`makeMatrix

`Static`makeRotationX

`Static`makeRotationY

`Static`makeRotationZ

`Static`multiply

`Static`normalize

`Static`premultiply

`Static`rotate

`Static`slerp