Rotation

A Rotation is a transformation that can be applied to an Object, a Number3 or another Rotation.

It can be created from euler angles, an axis-angle, or from vectors, and can be used as a safe way to store, manipulate, and apply rotations in your scene.

A table of three numbers can be used in place of an expected Rotation argument in all of its functions and most operations.

Internally, a quaternion is used to represent a Rotation. All of its functions as well as the * operator use this form. It allows rotations to be applied in a scene of any complexity.
However, the + and - operators are performed on the euler angles form, which may be used on simpler use-cases.

You can access the euler representation at any time using Rotation.X, Rotation.Y and Rotation.Z.
Note that the euler angles may change despite representing the same rotation, that is because there are several sequences of X, Y, Z rotations leading to the same transformation. This can also be due to euler angles being snapped back into the range 0 to 2PI.

⚠️ If you are having issues with rotations in your scene, try to avoid performing calculations using euler angles and instead,
- to safely combine rotations, use the * operator instead of the + / - euler operators,
- rotA + rotB can be replaced by rotB * rotA
- rotA - rotB can be replaced by -rotB * rotA
- leverage the built-in Rotation alternate set functions,
rotation:SetAxisAngle
rotation:SetLookRotation
rotation:SetFromToRotation
- leverage the built-in Object rotate functions,
object:RotateLocal
object:RotateWorld
object:RotationLocalToWorld
object:RotationWorldToLocal
- leverage the built-in Number3 rotate function,
number3:Rotate

Constructors

Rotation ( )

Rotation ( Number3 eulerAnglesXYZ )

Rotation ( number eulerAngleX, number eulerAngleY, number eulerAngleZ )

Rotation ( Number3 axis, number angle )

A rotation can be created,
- without parameter, rotation will be identity
- with euler angles
- with axis-angle

Either way, a quaternion is created and used internally to safely represent that rotation.

Functions

number Angle ( Rotation otherRot )

Returns the angle in radians between this rotation and another rotation.

Rotation Copy ( )

Returns a new Rotation as a copy of this rotation.

nil Inverse ( )

Inverse the rotation. This is safer than negating euler angles.

Note that negating a Rotation by writing -myRot is performing the inverse and returning it.

nil Lerp ( Rotation from, Rotation to, number ratio )

Sets this Rotation to the linear interpolation between two given rotations at a given ratio.

This is faster than Slerp, but may not always be appropriate. Use Slerp instead if Lerp doesn't give satisfactory results.

nil Set ( Number3 eulerAnglesXYZ )

nil Set ( number eulerAngleX, number eulerAngleY, number eulerAngleZ )

Sets this Rotation from euler angles.

nil SetAxisAngle ( Number3 axis, number angle )

Sets this Rotation from axis-angle.

nil SetFromToRotation ( Number3 fromVector, Number3 toVector )

Sets this Rotation from two vectors. It will be set to the rotation going from the first vector to the second vector.

nil SetLookRotation ( Number3 vector )

Sets this Rotation from a direction vector. It will be set to the rotation between identity and the given vector.

nil Slerp ( Rotation from, Rotation to, number ratio )

Sets this Rotation to the spherical interpolation between two given rotations at a given ratio.