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.
If you are interested in using CCSharp, here is the compatible Quaternion.cs file.
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()