Quaternions

This module defines the Quaternion class. Objects of this class represent quaternions used to express rotations about an axis. These are a very handy representation for rotational transformations. Methods are provided for converting to and from matrices.

A single precision variant is also available named FloatQuaternion.

The Quaternion Class

This class has the following constant data members:

Quaternion.kNumElements -> constant integer value of 4

Quaternion.kElementSize -> constant integer value of 4

This class has the following construction methods:

Quaternion ()

Constructs a new quaternion with uninitialized values.

Returns the new quaternion.

Quaternion (quat)

quat -> Quaternion

Constructs a new quaternion by copying the given quaternion.

Returns the new quaternion.

Quaternion (x, y, z, r)

x -> double

y -> double

z -> double

r -> double

Constructs a new quaternion with the given values, defining the rotation axis directional vector (x, y, z) and the rotation angle (r) in radians.

Returns the new quaternion.

Quaternion (axis, r)

axis -> Dir3d

r -> double

Constructs a new quaternion with the given values.

Returns the new quaternion.

Quaternion (axis)

axis -> Dir3d

Constructs a new quaternion with the given values.

The missing rotation angle is assumed to be zero.

Returns the new quaternion.

Quaternion (t)

t -> table of four double values, either numerically indexed or indexed by the keys 'x', 'y', 'z' and 'r'

Constructs a new quaternion with the values from the given table.

Returns the new quaternion.

Every instance of this class has the following member values, accessible both by numeric indices and the following keys:

1 | "x" -> the rotation axis directional vector x value

2 | "y" -> the rotation axis directional vector y value

3 | "z" -> the rotation axis directional vector z value

4 | "r" -> the rotation angle in radians

Every instance of this class has the following member methods:

Quaternion:Clone ()

Returns a newly allocated copy of this quaternion.

Quaternion:GetMatrix ()

Returns a Matrix3x3 containing the rotation of this quaternion.

Quaternion:IndexedElement (index)

index -> integer (from 1 to Quaternion.kNumElements)

Returns the indexed element.

This seems a bit redundant now that I think of it, but it's potentially faster than the normal numerical Lua index operation.

Quaternion:Inverse ()

Returns a copy of this quaternion with an inverted rotation.

Quaternion:Invert ()

Invert the existing rotation of this quaternion.

The original quaternion is modified in place.

Returns the newly inverted quaternion.

Quaternion:IsEqual (quat)

quat -> Quaternion

Compare this quaternion with the given quaternion and return true if they are identical.

Quaternion:IsNearEqual (quat)

quat -> Quaternion

Compare this quaternion with the given quaternion and return true if they are equal within a tolerance determined by the precision of the quaternions.

Quaternion:IsNearEqual (quat, tolerance)

quat -> Quaternion

tolerance -> double

Compare this quaternion with the given quaternion and return true if they are equal within the given tolerance.

Quaternion:Multiply (quat)

quat -> Quaternion

Multiply this quaternion with the given quaternion, storing the result back into this quaternion.

The original quaternion is modified in place.

Returns the newly multiplied quaternion.

Quaternion:SetByMatrix (matrix)

Set this quaternion to the rotation encoded in the given matrix.

This conversion may not be exact.

The original quaternion is modified in place.

Returns true if the rotation is greater than zero and less than 180 degrees.

Quaternion:SetByRotationBetweenVectors (from, to)

from -> Dir3d

to -> Dir3d

Set this quaternion to the rotation required to rotate the first directional vector into the second.

The original quaternion is modified in place.

Returns true if the result is a non-zero rotation.

Quaternion:SetByRotationBetweenVectorsIfAcute (from, to)

from -> Dir3d

to -> Dir3d Quaternion:Transform (matrix)

Set this quaternion to the rotation required to rotate the first directional vector into the second.

The original quaternion is modified in place.

Returns an integer encoding three possible results:

-1) the calculation was aborted due to an obtuse angle.

0) the resulting angle is zero.

+1) the resulting angle is non-zero.

Multiply this quaternion by the given matrix and store the result back into this quaternion.

The original quaternion is modified in place.

Returns true if the rotation is greater than zero and less than 180 degrees.