Quaternion
¶
Quaternions represent rotation around an axis, defined by quaternion components x, y, z and w. Quaternions are compact, do not suffer from gimbal lock and can be easily interpolated. Kanzi Engine uses quaternions internally to represent all rotations. Quaternions are based on complex numbers and are not easy to understand intuitively. You almost never access or modify the individual components. In most cases you take existing rotations and use them to construct new rotations (e.g. to smoothly interpolate between two rotations). You can use the Quaternion operator * to rotate one rotation by another, or to rotate a vector by a rotation.
Functions which can be used to create new instances of Quaternion.
| Quaternion() | Default constructor, initializes the quaternion components to identity, representing no rotation (x=0, y=0, z=0, w=1) |
| Quaternion() | Constructor, initializes the quaternion components to x, y, z and w |
Default constructor, initializes the quaternion components to identity, representing no rotation (x=0, y=0, z=0, w=1).
local quaternion = Quaternion()
Constructor, initializes the quaternion components to x, y, z and w.
local quaternion = Quaternion(x, y, z, w)
| x | (float) | x component of the quaternion. |
| y | (float) | y component of the quaternion. |
| z | (float) | z component of the quaternion. |
| w | (float) | w component of the quaternion. |
Methods of Quaternion class.
| Quaternion.createFromVector() | Creates quaternion from axis and angle |
| Quaternion.createFromEulerAngles() | Creates a quaternion from Euler angles |
| Quaternion.createFromEulerAngles() | Creates a quaternion from Euler angles |
| Quaternion:normalized() | Get normalized copy of this quaternion |
| Quaternion:conjugated() | Get conjugated copy of this quaternion |
| Quaternion:getX() | Get the x component of the quaternion |
| Quaternion:getY() | Get the y component of the quaternion |
| Quaternion:getZ() | Get the z component of the quaternion |
| Quaternion:getW() | Get the w component of the quaternion |
| Quaternion:setX() | Sets the x component of the quaternion |
| Quaternion:setY() | Sets the y component of the quaternion |
| Quaternion:setZ() | Sets the z component of the quaternion |
| Quaternion:setW() | Sets the w component of the quaternion |
Creates quaternion from axis and angle. Use this to create a quaternion from axis of rotation and angle in radians.
| axis | (Vector3) | Axis components in Vector3(x, y, z). |
| angleInRadians | (float) | Angle in radians. |
| (Quaternion) | Rotated quaternion. |
Creates a quaternion from Euler angles. Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.
| anglesInRadians | (Vector3) | Euler angles in radians. |
| (Quaternion) | Rotated quaternion. |
Creates a quaternion from Euler angles. Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.
| rotationX | (float) | Rotation angle around the x axis in radians. |
| rotationY | (float) | Rotation angle around the y axis in radians. |
| rotationZ | (float) | Rotation angle around the z axis in radians. |
| (Quaternion) | Rotated quaternion. |
Get normalized copy of this quaternion. Normalized quaternion is called an unit quaternion. Calculates the magnitude from the dot product of the quaternion components, and divides all the quaternion components with the magnitude. Use this when rotating or transforming a vector with a quaternion, and when generating a rotation or transformation matrix from quaternion. Using unnormalized quaternion in calculations can lead to floating point rounding errors. The errors that result from using an unnormalized quaternion in calculations are proportional to the square of the quaternion's magnitude.
| (Quaternion) | Normalized quaternion. |
Get conjugated copy of this quaternion. Conjugation inverses the quaternion axis components x, y and z. Use this to get the inverse rotation of a quaternion.
| (Quaternion) | Conjugated quaternion. |
Get the x component of the quaternion.
| (float) | The x component. |
Get the y component of the quaternion.
| (float) | The y component. |
Get the z component of the quaternion.
| (float) | The z component. |
Get the w component of the quaternion.
| (float) | The w component. |
Sets the x component of the quaternion.
| x | (float) | The new value of the x component. |
Sets the y component of the quaternion.
| y | (float) | The new value of the y component. |
Sets the z component of the quaternion.
| z | (float) | The new value of the z component. |
Sets the w component of the quaternion.
| w | (float) | The new value of the w component. |
Quaternion specific standalone functions, which are not a part of the Quaternion class.
| componentWiseMultiply() | Multiplies quaternion components component-wise and returns the resulting quaternion |
| dotProduct() | Calculates the dot product of two quaternions |
| inverse() | Returns an inverse quaternion for a quaternion |
| rotateVector() | Applies quaternion rotation to a vector |
| quaternionToMatrix4x4() | Converts a quaternion rotation to a 4x4 rotation matrix |
| matrix4x4ToQuaternion() | Creates a quaternion from Matrix4x4 |
| calculateEulerAngles() | Calculates Euler angles from a quaternion |
| quaternionSlerp() | Applies spherical linear interpolation (slerp) to two quaternions using the shortest path |
| quaternionSlerpLongerPath() | Applies spherical linear interpolation (slerp) to two quaternion using the longer path |
Multiplies quaternion components component-wise and returns the resulting quaternion.
| q1 | (Quaternion) | The first quaternion. |
| q2 | (Quaternion) | The second quaternion. |
| (Quaternion) | The result quaternion. |
Calculates the dot product of two quaternions.
| q1 | (Quaternion) | The first quaternion. |
| q2 | (Quaternion) | The second quaternion. |
| (float) | The dot product of the quaternions. |
Returns an inverse quaternion for a quaternion.
| q | (Quaternion) | Quaternion to invert. |
| (Quaternion) | Inverse quaternion. |
Applies quaternion rotation to a vector. Calculates q * v * q.conjugated(), for a quaternion q and a vector v.
| quaternion | (Quaternion) | Quaternion rotation. |
| vector | (Vector3) | Vector that you want to rotate. |
| (Vector3) | The rotated vector. |
Converts a quaternion rotation to a 4x4 rotation matrix.
| quaternion | (Quaternion) | Quaternion rotation. |
| (Matrix4x4) | Matrix4x4 with rotation values extracted from quaternion. |
Creates a quaternion from Matrix4x4. Extracts and calculates the quaternion components from passed in Matrix4x4. Use this when you already have the rotation stored in a 4x4 matrix and want to extract the rotation angles to a quaternion.
| matrix | (Matrix4x4) | Matrix4x4 from which to extract and calculate the quaternion components. |
| (Quaternion) | Rotated and normalized quaternion. |
Calculates Euler angles from a quaternion. Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y, and z.
| (Vector3) | Euler angles in radians. |
Applies spherical linear interpolation (slerp) to two quaternions using the shortest path. Use this to evaluate interpolation between two rotations at given interpolation time. Takes the shortest path of interpolation between two degrees, which amounts to maximum of 180 degrees of rotation in any direction.
| q1 | (Quaternion) | First quaternion. |
| q2 | (Quaternion) | Second quaternion. |
| interpolationTime | (float) | Interpolation parameter in range [0 .. 1]. |
| (Quaternion) | Interpolated rotated quaternion. |
Applies spherical linear interpolation (slerp) to two quaternion using the longer path. Use this to evaluate interpolation between two rotations at given interpolation time. Takes the longer path to the result. Interpolates the whole angle difference between the two quaternion rotations. For example, from 0 to 270 rotates the whole 270 degrees.
| q1 | (Quaternion) | First quaternion. |
| q2 | (Quaternion) | Second quaternion. |
| interpolationTime | (float) | Interpolation parameter in range [0 .. 1]. |
| (Quaternion) | Interpolated rotated quaternion. |