Module quaternion
A basic quaternion type and some common quaternion operations.
This may be useful when working with rotation in regards to physics (such as those from the Ship API provided by CC: VS).
An introduction to quaternions can be found on Wikipedia.
Special thanks to getItemFromBlock and Shlomo for sharing their own quaternion handling code.
Constructors
| new (vec, w) | Constructs a new quaternion from a vector and a w parameter. |
| fromAxisAngle (axis, angle) | Constructs a new quaternion from the provided axis - angle parameters. |
| fromEuler (pitch, yaw, roll) | Constructs a new quaternion using the provided pitch, yaw and roll. |
| fromComponents (x, y, z, w) | Constructs a new quaternion using the four provided components. |
| fromMatrix (m) | Constructs a new quaternion from a 3x3 rotation matrix or 4x4 transformation matrix. |
| identity () | Constructs a new identity quaternion, representing an empty rotation. |
Class Quaternion
| quaternion.v | The imaginary component of the quaternion, stored in a Vector. |
| quaternion.a | The real component of the quaternion. |
| quaternion:add (self, other) | Adds two quaternions together. |
| quaternion:sub (self, other) | Subtracts two quaternions together. |
| quaternion:mul (self, other) | Multiplies a quaternion by a scalar value, another quaternion, or a Vector. |
| quaternion:div (self, other) | Divides a quaternion by a scalar or another quaternion. |
| quaternion:unm (self) | Negates a quaternion. |
| quaternion:tostring (self) | Creates a string representation of the quaternion in the form of w + xi + yj + zk. |
| quaternion:equals (self, other) | Determines if the given quaternions are equal. |
| quaternion:conjugate (self) | Finds the conjugate of the quaternion. |
| quaternion:normalize (self) | Normalizes the quaternion. |
| quaternion:inverse (self) | Computes the inverse of the quaternion. |
| quaternion:slerp (self, other, alpha) | Performs Spherical Linear Interpolation (SLerp) between the two given quaternions and alpha value. |
| quaternion:getAngle (self) | Gets the angle of the rotation defined by the given quaternion. |
| quaternion:getAxis (self) | Gets the normalized axis of rotation corresponding to the rotation defined by the given quaternion. |
| quaternion:toEuler (self) | Gets the pitch, yaw and roll euler angles from the given quaternion. |
| quaternion:length (self) | Computes the length of the quaternion. |
| quaternion:isNan (self) | Checks if any component of the quaternion is NaN. |
| quaternion:isInf (self) | Check if any component of the quaternion is infinite. |
| quaternion:copy (self) | Returns a copy of this quaternion, with the same data. |
Constructors
- new (vec, w)
-
Constructs a new quaternion from a vector and a w parameter. Similarly to fromComponents, this method will not produce a normalized quaternion.
Usage:
q = quaternion.new(vec, w) - fromAxisAngle (axis, angle)
-
Constructs a new quaternion from the provided axis - angle parameters. The resulting quaternion is already normalized.
Usage:
q = quaternion.fromAxisAngle(axis, angle) - fromEuler (pitch, yaw, roll)
-
Constructs a new quaternion using the provided pitch, yaw and roll. Uses the YXZ reference frame
Usage:
q = quaternion.fromEuler(pitch, yaw, roll) - fromComponents (x, y, z, w)
-
Constructs a new quaternion using the four provided components. This will not normalize the quaternion unlike other functions, so use at your own risks.
Usage:
q = quaternion.fromComponents(x, y, z, w) - fromMatrix (m)
-
Constructs a new quaternion from a 3x3 rotation matrix or 4x4 transformation matrix.
See also:
Usage:
q = quaternion.fromMatrix(m) - identity ()
-
Constructs a new identity quaternion, representing an empty rotation.
Usage:
q = quaternion.identity()
Class Quaternion
A quaternion, with imaginary component v and real component a.
This is suitable for representing rotation.
- quaternion.v
- The imaginary component of the quaternion, stored in a Vector.
- quaternion.a
- The real component of the quaternion.
- quaternion:add (self, other)
-
Adds two quaternions together. The resulting quaternion will not be normalized. If you want to add rotations together, use the mul function instead.
Usage:
q1:add(q2)q1 + q2
- quaternion:sub (self, other)
-
Subtracts two quaternions together. The resulting quaternion will not be normalized.
Usage:
q1:sub(q2)q1 - q2
- quaternion:mul (self, other)
-
Multiplies a quaternion by a scalar value, another quaternion, or a Vector.
Usage:
q:mul(3)
q * 3q1:mul(q2)q1 * q2
q:mul(v)q * v
- quaternion:div (self, other)
-
Divides a quaternion by a scalar or another quaternion.
Usage:
q1:div(q2)q1 / q2
q:div(2)
q / 2
- quaternion:unm (self)
-
Negates a quaternion.
Usage:
q:unm()-q
- quaternion:tostring (self)
-
Creates a string representation of the quaternion in the form of w + xi + yj + zk.
Usage:
q:tostring()q .. ""
- quaternion:equals (self, other)
-
Determines if the given quaternions are equal.
Usage:
q1:equals(q2)q1 == q2
- quaternion:conjugate (self)
-
Finds the conjugate of the quaternion.
Usage:
q:conjugate() - quaternion:normalize (self)
-
Normalizes the quaternion.
Usage:
q:normalize() - quaternion:inverse (self)
-
Computes the inverse of the quaternion.
Usage:
q:inverse() - quaternion:slerp (self, other, alpha)
-
Performs Spherical Linear Interpolation (SLerp) between the two given quaternions and alpha value.
Usage:
q1:slerp(q2, alpha) - quaternion:getAngle (self)
-
Gets the angle of the rotation defined by the given quaternion.
Usage:
q:getAngle() - quaternion:getAxis (self)
-
Gets the normalized axis of rotation corresponding to the rotation defined by the given quaternion. Uses Vector type.
Usage:
q:getAxis() - quaternion:toEuler (self)
-
Gets the pitch, yaw and roll euler angles from the given quaternion. Uses the YXZ reference frame
Usage:
q:toEuler() - quaternion:length (self)
-
Computes the length of the quaternion.
Usage:
q:length()#q
- quaternion:isNan (self)
-
Checks if any component of the quaternion is NaN.
Usage:
q:isNan() - quaternion:isInf (self)
-
Check if any component of the quaternion is infinite.
Usage:
q:isInf() - quaternion:copy (self)
-
Returns a copy of this quaternion, with the same data.
Usage:
b = a:copy()