Module quaternion
Some operations on quaternions.
A Quaternion is a table (or object with __index and __newindex metamethods) with x, y, z, and w components, each being a number.
All functions are able to take any combination of their Quaternion arguments. Namely, the same Quaternion may be passed multiple times without incident. Any routine that produces a Quaternion will place it in its qout argument (which is also returned, to allow for easy composition). An argument may be both a pure input and qout; qout is only written once the necessary values have been read.
To use the plugin, add the following in build.settings
:
plugins = {
["plugin.quaternion"] = { publisherId = "com.xibalbastudios" }
}
Sample code is available here.
Functions
Add (qout, q1, q2)  Adds quaternions q1 and q2. 
Add_Scaled (qout, q1, q2, k)  Adds quaternions q1 and a scaled q2. 
AngleBetween (q1, q2)  Gives the angle between two quaternions. 
Conjugate (qout, q)  Computes the conjugate of q. 
Difference (qout, q1, q2)  Computes the quaternion diff such that q1 * diff = q2. 
Dot (q1, q2)  Dot product of q1 and q2. 
Exp (qout, q)  Computes the exponential of q. 
FromAxisAngle (qout, angle, vx, vy, vz)  Builds a quaternion representing a rotation around an axis. 
FromEulerAngles (qout, x, y, z[, method="xyz"])  Builds a quaternion representation of a sequence of rotations around the unit axes. 
Inverse (qout, q)  Computes the inverse of a (nonzero) quaternion, i.e. 
Length (q)  Length of quaternion q. 
Log (qout, q)  Computes the logarithm of q. 
Multiply (qout, q1, q2)  Multiplies quaternions q1 and q2. 
Negate (qout, q)  Negates quaternion q. 
Normalize (qout, q)  Normalizes a (nonzero) quaternion. 
Scale (qout, q, k)  Scales quaternion q. 
Slerp (qout, q1, q2, t)  Performs spherical linear interpolation from q1 to q2. 
Squad (qout, q1, q2, q3, q4, t)  Performs spherical quadrangle interpolation between four quaternions. 
Sub (qout, q1, q2)  Subtracts quaternion q2 from q1. 
Functions
 Add (qout, q1, q2)

Adds quaternions q1 and q2.
Parameters:
 qout Quaternion q1 + q2.
 q1 Quaternion Addend #1...
 q2 Quaternion ...and #2.
Returns:

Quaternion
qout.
 Add_Scaled (qout, q1, q2, k)

Adds quaternions q1 and a scaled q2.
Parameters:
 qout Quaternion q1 + q2 * k.
 q1 Quaternion Addend #1...
 q2 Quaternion ...and #2.
 k number Scale factor.
Returns:

Quaternion
qout.
 AngleBetween (q1, q2)

Gives the angle between two quaternions.
Parameters:
 q1 Quaternion Quaternion #1...
 q2 Quaternion ...and #2.
Returns:

number
Shorter angle between q1 and q2.
 Conjugate (qout, q)

Computes the conjugate of q.
Parameters:
 qout Quaternion Conjugate.
 q Quaternion
Returns:

Quaternion
qout.
 Difference (qout, q1, q2)

Computes the quaternion diff such that q1 * diff = q2.
Parameters:
 qout Quaternion Difference.
 q1 Quaternion Initial quaternion.
 q2 Quaternion Final quaternion.
Returns:

Quaternion
qout.
 Dot (q1, q2)

Dot product of q1 and q2.
Parameters:
 q1 Quaternion Quaternion #1...
 q2 Quaternion ...and #2.
Returns:

number
Dot product.
 Exp (qout, q)

Computes the exponential of q.
Given q = [w, theta * v] (with v a unit vector), the exponential is defined as [cos(theta), sin(theta) * v] * e^{w}.
Parameters:
 qout
Quaternion
exp(q)
.  q Quaternion
Returns:

Quaternion
qout.
 qout
Quaternion
 FromAxisAngle (qout, angle, vx, vy, vz)

Builds a quaternion representing a rotation around an axis.
The axis does not need to be normalized.
Parameters:
 qout Quaternion Rotation.
 angle number Rotation angle, in radians.
 vx number Axis xcomponent...
 vy number ...ycomponent...
 vz number ...and zcomponent.
Returns:

Quaternion
qout.
 FromEulerAngles (qout, x, y, z[, method="xyz"])

Builds a quaternion representation of a sequence of rotations around the unit axes.
Parameters:
 qout Quaternion Rotation.
 x number Angle around the xaxis...
 y number ...around the yaxis...
 z number ...and around the zaxis.
 method string One of "xyz", "xzw", "yxz", "yzx", "zxy", or "zyx". Where X, Y, and Z are the rotations around those axes, "xyz" corresponds to X * Y * Z. The other methods follow likewise. (default "xyz")
Returns:

Quaternion
qout.
 Inverse (qout, q)

Computes the inverse of a (nonzero) quaternion, i.e. the quaternion q^{1}
such that q^{1} * q or q * q^{1} gives identity quaternion I
(x = y = z = 0, w = 1).
Given quaternion Q, I * Q or Q * I yield back Q.
Parameters:
 qout Quaternion Inverse.
 q Quaternion
Returns:

Quaternion
qout.
 Length (q)

Length of quaternion q.
Parameters:
 q Quaternion
Returns:

number
Length.
 Log (qout, q)

Computes the logarithm of q.
Given q = [cos(theta), sin(theta) * v] * length(q), the logarithm is defined as [ln(length(q)), theta * v / length(v)].
Parameters:
 qout
Quaternion
log(q)
.  q Quaternion
Returns:

Quaternion
qout.
 qout
Quaternion
 Multiply (qout, q1, q2)

Multiplies quaternions q1 and q2.
Parameters:
 qout Quaternion q1 * q2.
 q1 Quaternion Multiplier.
 q2 Quaternion Multiplicand.
Returns:

Quaternion
qout.
 Negate (qout, q)

Negates quaternion q.
Parameters:
 qout Quaternion q.
 q Quaternion
Returns:

Quaternion
qout.
 Normalize (qout, q)

Normalizes a (nonzero) quaternion.
Parameters:
 qout Quaternion q scaled to length 1.
 q Quaternion Nonzero quaternion.
Returns:

Quaternion
qout.
See also:
 Scale (qout, q, k)

Scales quaternion q.
Parameters:
 qout Quaternion q * k.
 q Quaternion
 k number Scale factor.
Returns:

Quaternion
qout.
 Slerp (qout, q1, q2, t)

Performs spherical linear interpolation from q1 to q2.
Parameters:
 qout Quaternion Interpolated result.
 q1 Quaternion Initial quaternion.
 q2 Quaternion Final quaternion.
 t
number
Interpolation time.
At time t = 0 or t = 1, qout will match q1 or q2 respectively. Times within this range, on the other hand, yield quaternions between q1 and q2.
Returns:

Quaternion
qout.
 Squad (qout, q1, q2, q3, q4, t)

Performs spherical quadrangle interpolation between four quaternions.
Quaternions q1, q2, q3, and q4 are understood to be in order.
Useful results will typically be sought between q2 and q3, with q1 and q4 being used to guide the shape of the path.
Parameters:
 qout Quaternion Interpolated result.
 q1 Quaternion Quaternion #1...
 q2 Quaternion ...quaternion #2...
 q3 Quaternion ...quaternion #3...
 q4 Quaternion ...and #4.
 t
number
Interpolation time.
At time t = 0 or t = 1, qout will match q2 or q3 respectively. Times within this range, on the other hand, yield quaternions between q2 and q3.
Furthermore, t = 0 aligns with t = 1 in the interval (q0, q1, q2, q3). Likewise, t = 1 corresponds to t = 0 in the interval (q2, q3, q4, q5). Owing to this and the interpolation's C² continuity, it is possible to gracefully transition from one interval to another.
Returns:

Quaternion
qout.
 Sub (qout, q1, q2)

Subtracts quaternion q2 from q1.
Parameters:
 qout Quaternion q1  q2.
 q1 Quaternion Minuend.
 q2 Quaternion Subtrahend.
Returns:

Quaternion
qout.