Quaternion

Contents

• Functions

Modules

• quaternion

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 (non-zero) 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 (non-zero) 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.

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 x-component...
• vy number ...y-component...
• vz number ...and z-component.

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 x-axis...
• y number ...around the y-axis...
• z number ...and around the z-axis.
• 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 (non-zero) 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.

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 (non-zero) quaternion.

Parameters:

• qout Quaternion q scaled to length 1.
• q Quaternion Non-zero quaternion.

Returns:

Quaternion qout.

See also:

Length

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.