vectrix/quaternions

• Description & Usage
• Functions

• slerp

• invert

• quatToString

• normalize

• create

• identity

• fromEulerAngles

• fromAxisAngle

Description

The quaternions module focuses on quaternion operations that are useful for performing 3-dimensional rotations. Quaternions inherit from vectrix.vectors#vec4, which in turn inherit from vectrix.matrices, so most of the operations supported by vec4 and generic matrices are supported by quats (TODO: remove the ones that don't make sense for quaternions)

Note that in the examples quaternions outputs are displayed as they would be by quaternion.toString(), which rounds to the nearest 2 decimal points for brevity. Actual values will be accurate to at least 1.0e-7 (the minimum accuracy required by the unit tests).

Vectrix quaternions store their scalar component in the last place, so all quaternion functions that accept an array as a parameter expect it as [x,y,z,w] rather than [w,x,y,z]. This for consistency with the vectors module.

const quaternions = require("vectrix.quaternions");
let q = quaternion.create([0.4, 1.0, 2.1, 1.0]); // quaternion(0.40, 1.00, 2.10, 1.0);

Quaternion values are aliased to x, y, z, and w, and can be accessed in any combination as with GLSL:

q.xy; // [0.4, 1.0]
q.zyx; // [2.1, 1.0, 0.4]
q.zw; // [2.1, 1.0]
// etc

#Functions

---

slerp

slerp(origin, destination, t) ⇨ quaternion

Performs a spherical linear interpolation between a and b.

Example:

let q1 = quaternions.create([0.3,-0.6,-0.4,0.2]);
let q2 = quaternions.create([0.6,0.8,0.5,0.7]);
slerp(q1, q2, 0.4); // quaternion(0.75, 0.01, -0.02, 0.72);

Parameters

name	type	description
origin	`quaternion	array(4)`
destination	`quaternion	array(4)`
t	float	interval [0...1]

Returns: quaternion

---

invert

invert(a, normalize) ⇨ quaternion

Finds the inverse of a quaternion by normalizing then inverting the quat. Normalization can be skipped by setting normalize = false if the quat is known to be normal already. Be careful, since floating point errors will often de-normalize your quats!

Example:

// functional
quaternions.invert([4.0,7.0,5.0,1.0]); // quaternion(-0.36, -0.89, -0.27, 0.09)
// OO
quaternions.create([4.0,7.0,5.0,1.0]).invert(); // quaternion(-0.36, -0.89, -0.27, 0.09)

Parameters

name	type	description
a	`quaternion	array(4)`
normalize	bool	(default true)

Returns: quaternion

---

quatToString

quatToString(a) ⇨ string

Create a string representation of a quaternion.

Example:

// functional style
quaternions.quatToString(quaternions.create()); // quaternion(0.00, 0.00, 0.00, 1.00)
// OO style
quaternions.create().toString(); // quaternion(0.00, 0.00, 0.00, 1.00)

Parameters

name	type	description
a	quaternion	quaternion to stringify

Returns: string

---

normalize

normalize(a) ⇨ quaternion

Normalize a quaternion.

Example:

// functional style
quaternions.normalize([4.0, 10.0, 3.0, 1.0]).toString(); // quaternion(0.36, 0.89, 0.27, 0.09);
// OO style
quaternions.create([4.0, 10.0, 3.0, 1.0]).normalize(); // quaternion(0.36, 0.89, 0.27, 0.09);

Parameters

name	type	description
a	`quaternion	array(4)`

Returns: quaternion

---

create

create(vals, buffer, offset) ⇨ quaternion

Factory for creating quaternions. Quaternions are represented as 4 member arrays of (x,y,z,w) where x,y,z are the vector component and w is the scalar component.

Example:

quaternions.create([0.4, 32.1, 9.0, 1.0]); // quaternion(0.40, 32.10, 9.00, 1.00)

Parameters

name	type	description
vals	array(4)	[x,y,z,w] (default [0,0,0,1] = identity quaternion)
buffer	ArrayBuffer	(optional) an array buffer to create the vector on
offset	offset	(optional) offset for the buffer, ignored if buffer is not supplied

Returns: quaternion

---

identity

identity() ⇨ quaternion

Creates an identity quaternion [0,0,0,1].

Example:

quaternions.create.identity(); // quaternion(0.00, 0.00, 0.00, 0.01)

Returns: quaternion

---

fromEulerAngles

fromEulerAngles(a) ⇨ quaternion

Creates a quaternion from Euler angles (in radians).

Example:

quaternions.create.fromEulerAngles([75*Math.PI/180, 65*Math.PI/180, 15*Math.PI/180]); // quaternion(0.412, 0.56, 0.36, 0.62)

Parameters

name	type	description
a	array(3)	[yaw,pitch,roll] in radians

Returns: quaternion

---

fromAxisAngle

fromAxisAngle(axis, angle) ⇨ quaternion

Creates a quaternion from an axis-angle rotation.

Example:

quaternions.create.fromAxisAngle([1,0,0],90*Math.PI/180); // quaternion(0.70, 0.00, 0.00, 0.70)

Parameters

name	type	description
axis	array(3)	of rotation
angle	float	of rotation as radian

Returns: quaternion