API Docs

Class: QuaternionArray

PD. QuaternionArray

new QuaternionArray()

A helper class for performing vector math using [x,y,z,w] array-based quaternions.

Quaternions are a compact representation of the rotation of an object in three dimensions. Quaternions have some advantages over rotation matrices as they are smaller and do not suffer from potential gimbal lock.

Any Float32Array with at least four items in the same [x,y,z.w] format can also be used entirely interchangeably as both output or input in all quaternion array methods.

Author:
  • drajmarsh

Methods

clone(out) <static>

Creates a copy of the given quaternion array.

This method simply returns out.slice() but is included for API compatibility.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to clone.
Returns:

Returns a new copied quaternion array.

Type
number

copy(out, q) <static>

Copies the first four components of q to out.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to receive the result.
q Array.<number>

The [x,y,z,w] quaternion array to copy from.
Returns:

Returns the modified out [x,y,z,w] vector array.

Type
Array.<number>

create( [x] [, y] [, z] [, z]) <static>

Creates a new [x,y,z,w] quaternion array with the given components.

Parameters:
Name Type Argument Description
x number <optional>

The X-axis component, or zero if not defined.
y number <optional>

The Y-axis component, or zero if not defined.
z number <optional>

The Z-axis component, or zero if not defined.
z number <optional>

The W component, or zero if not defined.
Returns:

Returns a new [x,y,z,w] quaternion array.

Type
Array.<number>

invert(out [, q]) <static>

Inverts the sign of each component of a quaternion.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v or simply give one argument to change it in-place.

Parameters:
Name Type Argument Description
out Array.<number>

The [x,y,z,w] quaternion array to receive the result.
q Array.<number> <optional>

The [x,y,z,w] quaternion array to negate, defaults to out if not supplied.
Returns:

Returns the modified out quaternion array.

Type
Array.<number>

multiply(out, a, b) <static>

Multiplies two [x,y,z,w] quaternions together and stores the result in out.

NOTE: This method changes values within the out parameter, however it is safe to use the same quaternion as either a or b.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion to receive the result.
a Array.<number>

The first [x,y,z,w] quaternion to multiply.
b Array.<number>

The second [x,y,z,w] quaternion to multiply.
Returns:

Returns the out argument with computed values.

Type
Array.<number>

normalize(out [, q]) <static>

Resizes a quaternion array to unit length (len == 1.0).

NOTE: This method changes values within the out parameter, however it is safe to use the same array as q or simply give one argument to change it in-place.

Parameters:
Name Type Argument Description
out Array.<number>

The [x,y,z,w] quaternion array to receive the result.
q Array.<number> <optional>

The [x,y,z,w] quaternion array to normalise, defaults to out if not supplied.
Returns:

Returns the modified out quaternion array.

Type
Array.<number>

set(out, x, y, z, w) <static>

Sets the [x,y,z,w] quaternion to the given components.

This method offers some flexibility in terms of the arguments it accepts. You can provide 4 separate numeric values or just a single [x,y,z,w] vector array, a 4D point-like {x,y,z,w} object, or even no arguments at all to create a unit quaternion.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to receive the result.
x number | Array.<number>

The X-axis component, or zero if not defined.
y number

The Y-axis component, or zero if not defined.
z number

The Z-axis component, or zero if not defined.
w number

The W component, or zero if not defined.
Returns:

Returns the updates out [x,y,z,w] quaternion array.

Type
Array.<number>

setComponents(out, x, y, z, z) <static>

Sets the [x,y,z,w] quaternion by its individual components.

This method differs from the set() method in that you must provide all 4 components as separate numeric values. It does not perform any type checking, which makes it a bit faster in situations where you can reliably provide the separate component values.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to receive the result.
x number

The X-axis component, or zero if not defined.
y number

The Y-axis component, or zero if not defined.
z number

The Z-axis component, or zero if not defined.
z number

The W component, or zero if not defined.
Returns:

Returns the updates out [x,y,z,w] quaternion array.

Type
Array.<number>

setFromAxisAngle(out, axis, angle) <static>

Computes the [x,y,z,w] quaternion array for rotating around an arbitrary axis.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to set.
axis Array.<number>

The [x,y,z] vector array defining the axis, which must be normalized.
angle number

The axial rotation angle, in decimal radians.
Returns:

Returns the given [x,y,z,w] quaternion array.

Type
Array.<number>

setFromMatrix(out, matrix) <static>

Computes the [x,y,z,w] quaternion array from a 4x4 column-major rotation matrix array.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to set.
matrix Array.<number>

The 4x4 (16 item) column-major rotation matrix.
Returns:

Returns the given [x,y,z,w] quaternion array.

Type
Array.<number>

setFromNormal(out, normal) <static>

Compute the quaternion required to rotate from the XY plane to given plane.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to set.
normal Array.<number>

The normalised [x,y,z] vector array defining the surface normal of a plane.
Returns:

Returns the out argument with computed values.

Type
Array.<number>

setFromThreeAxis(out, xAxis, yAxis, zAxis) <static>

Sets a quaternion based on three axis representing the new coordinate system.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion to set.
xAxis Array.<number>

The normalised [x,y,z] vector array defining the X-axis.
yAxis Array.<number>

The normalised [x,y,z] vector array defining the Y-axis.
zAxis Array.<number>

The normalised [x,y,z] vector array defining the Z-axis.
Returns:

Returns the updated out quaternion.

Type
Array.<number>

setFromUnitVectors(out, v1, v2) <static>

Computes the [x,y,z,w] quaternion array required rotate from 'v1' to 'v2', where both are normalized direction vectors.

NOTE 1: This method changes values within the out parameter.

NOTE 2: Both direction vectors MUST BE normalized.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to set.
v1 Array.<number>

The normalized [x,y,z] vector array defining the reference direction.
v2 Array.<number>

The normalized [x,y,z] vector array defining the destination direction.
Returns:

Returns the given [x,y,z,w] quaternion array.

Type
Array.<number>

setToNormal(out, normal) <static>

Compute the quaternion required to rotate from the given plane to the XY plane.

Parameters:
Name Type Description
out Array.<number>

The [x,y,z,w] quaternion array to set.
normal Array.<number>

The normalised [x,y,z] vector array defining the surface normal of a plane.
Returns:

Returns the out argument with computed values.

Type
Array.<number>