vectrix.quaternions - nphyx/vectrix GitHub Wiki
vectrix/quaternions
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
quaternion
slerp(origin, destination, t) ⇨ 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
quaternion
invert(a, normalize) ⇨ 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
string
quatToString(a) ⇨ 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
quaternion
normalize(a) ⇨ 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
quaternion
create(vals, buffer, offset) ⇨ 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
quaternion
identity() ⇨ Creates an identity quaternion [0,0,0,1].
Example:
quaternions.create.identity(); // quaternion(0.00, 0.00, 0.00, 0.01)
Returns: quaternion
fromEulerAngles
quaternion
fromEulerAngles(a) ⇨ 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
quaternion
fromAxisAngle(axis, angle) ⇨ 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