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);

Hierarchy

Quaternion

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 src/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
A new quaternion with the same values as this one

Returns Quaternion
- Defined in src/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 src/math/Quaternion.ts:521

getMatrix

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

Returns
A 4x4 rotation matrix representation of this Quaternion

Returns Matrix4
- Defined in src/math/Quaternion.ts:606

inverse

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

Returns
The inverse of this Quaternion

Returns Quaternion
- Defined in src/math/Quaternion.ts:596

invert

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

Returns void
- Defined in src/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 src/math/Quaternion.ts:652

makeIdentity

makeIdentity(): Quaternion
Creates a new identity Quaternion object

Returns
A new Quaternion object representing the identity Quaternion (0, 0, 0, 1)

Returns Quaternion
- Defined in src/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 src/math/Quaternion.ts:546

normalize

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

Returns void
- Defined in src/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 src/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

Returns
A new 3D point or 3D vector
Parameters
- v: Vector3
  
  The original 3D point or 3D vector
Returns Vector3
- Defined in src/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 src/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 src/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 src/math/Quaternion.ts:409

setIdentity

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

Returns void
- Defined in src/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 src/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 src/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 src/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 src/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 src/math/Quaternion.ts:680

`Static` copy

copy(q: Quaternion): Quaternion
Creates a new quaternion and copies the x,y,z,w values of the input into it.

Returns
A new Quaternion object with the same values as q
Parameters
- q: Quaternion
  
  The Quaternion object to copy
Returns Quaternion
- Defined in src/math/Quaternion.ts:55

`Static` inverse

inverse(q: Quaternion): Quaternion
Returns a new quaternion that is the inverse (opposite rotation) of the input quaternion.

Returns
A new Quaternion object representing the inverse of q
Parameters
- q: Quaternion
  
  The Quaternion object to invert
Returns Quaternion
- Defined in src/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.

Returns
A new Quaternion that performs the specified rotation
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
- Defined in src/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.

Returns
A new Quaternion
Parameters
- axis: Vector3
  
  The axis to rotate around
- angle: number
  
  The angle of rotation
Returns Quaternion
- Defined in src/math/Quaternion.ts:184

`Static` makeEulerAngles

makeEulerAngles(x: number, y: number, z: number, order?: string): Quaternion
Creates a new quaternion from given Euler angles

Returns
A new Quaternion
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
- Defined in src/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.

Returns
A new Quaternion that specifies the same rotation
Parameters
- matrix: Matrix4
  
  A 4x4 transformation matrix that includes a rotation.
Returns Quaternion
- Defined in src/math/Quaternion.ts:246

`Static` makeRotationX

makeRotationX(angle: number): Quaternion
Creates a new Quaternion object representing a rotation around the x-axis

Returns
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
- Defined in src/math/Quaternion.ts:144

`Static` makeRotationY

makeRotationY(angle: number): Quaternion
Creates a new Quaternion object representing a rotation around the y-axis

Returns
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
- Defined in src/math/Quaternion.ts:157

`Static` makeRotationZ

makeRotationZ(angle: number): Quaternion
Creates a new Quaternion object representing a rotation around the z-axis

Returns
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
- Defined in src/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.

Returns
A new Quaternion object representing the product of q1 and q2
Parameters
- q1: Quaternion
  
  The first Quaternion object
- q2: Quaternion
  
  The second Quaternion object
Returns Quaternion
- Defined in src/math/Quaternion.ts:69

`Static` normalize

normalize(q: Quaternion): Quaternion
Returns a new quaternion that is a normalized version of the input quaternion.

Returns
A new Quaternion object with normalized values
Parameters
- q: Quaternion
  
  The Quaternion object to normalize
Returns Quaternion
- Defined in src/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.

Returns
A new Quaternion object which is the result of the premultiplication of the two input Quaternion objects
Parameters
- q1: Quaternion
  
  The first Quaternion object
- q2: Quaternion
  
  The second Quaternion object
Returns Quaternion
- Defined in src/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

Returns
A new 3D point or 3D vector
Parameters
- v: Vector3
  
  The original 3D point or 3D vector
- q: Quaternion
  
  The rotation to apply
Returns Vector3
- Defined in src/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.

Returns
A new Quaternion representing the slerp between q1 and q2
Parameters
- q1: Quaternion
  
  The first Quaternion
- q2: Quaternion
  
  The second Quaternion
- alpha: number
  
  The interpolation factor
Returns Quaternion
- Defined in src/math/Quaternion.ts:261

Class Quaternion

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

x: number = 0

y: number = 0

z: number = 0

w: number = 1

Returns Quaternion

Properties

w

x

y

z

Static Readonly IDENTITY

Methods

clone

Returns

Returns Quaternion

copy

Parameters

q: Quaternion

Returns void

getMatrix

Returns

Returns Matrix4

inverse

Returns

Returns Quaternion

invert

Returns void

lookAt

Parameters

eyePoint: Vector3

targetPoint: Vector3

upVector: Vector3 = Vector3.UP

Returns void

makeIdentity

Returns

Returns Quaternion

multiply

Parameters

q: Quaternion

Returns void

normalize

Returns void

premultiply

Parameters

q: Quaternion

Returns void

rotate

Returns

Parameters

v: Vector3

Returns Vector3

set

Parameters

x: number

y: number

z: number

w: number

Returns void

setAxisAngle

Parameters

axis: Vector3

angle: number

Returns void

setEulerAngles

Parameters

x: number

y: number

z: number

order: string = 'YZX'

Returns void

setIdentity

`Static` `Readonly` IDENTITY

`Static` copy

`Static` inverse

`Static` lookAt

`Static` makeAxisAngle

`Static` makeEulerAngles

`Static` makeMatrix

`Static` makeRotationX

`Static` makeRotationY

`Static` makeRotationZ