Library: Math: Quat

» Overview

Quaternions are a mathematical construct that extends the concept of complex numbers into four dimensions, comprising one real component and three imaginary components. Renowned for their ability to represent rotations in three-dimensional space with remarkable precision, quaternions offer several advantages over traditional representations such as Euler angles and rotation matrices.

A key benefit is their inherent resistance to gimbal lock — a phenomenon where the orientation becomes indeterminate due to the constraints of traditional rotational systems. In addition to their application in computer graphics, robotics, and aerospace, quaternions also serve as versatile tools in various branches of mathematics, enabling efficient computations and transformations across multiple domains. Their unique properties make quaternions an essential element in developing sophisticated algorithms for 3D modelling, animation, and simulation.

» Importing

It's already imported by default whenever you import assetify. You need to declare the below globally only once:

loadstring(exports.assetify_library:import())()

» Operations

• Addition

  local cQuat1, cQuat2 = math.quat(1, 1, 1, 1), math.quat(2, 2, 2, 2)
  local resultant = cQuat1 + cQuat2

• Subtraction

  local cQuat1, cQuat2 = math.quat(1, 1, 1, 1), math.quat(2, 2, 2, 2)
  local resultant = cQuat1 - cQuat2

• Multiplication

  --Note: Quaternion multiplications aren't commutative!
  local cQuat1, cQuat2 = math.quat(1, 1, 1, 1), math.quat(2, 2, 2, 2)
  local resultant = cQuat1 * cQuat2

• Division

  local cQuat1, cQuat2 = math.quat(1, 1, 1, 1), math.quat(2, 2, 2, 2)
  local resultant = cQuat1 / cQuat2

» APIs

• math.quat:getType() - shared

  ✨ Retrieve's instance's type.

  local string: type = self:getType()

• math.quat() - shared

  ✨ Creates a quaternion instance.

  local quat: cQuat = math.quat(
     float: x,
     float: y,
     float: z,
     float: w
  )

• math.quat:destroy() - shared

  ✨ Destroys an existing quat.

  local bool: result = self:destroy()

• math.quat:scale() - shared

  ✨ Scales quat w/ specified scale.

  local quat: self = self:scale(
     float: scale
  )

• math.quat:setAxisAngle() - shared

  ✨ Sets quat's axis angles.

  local quat: self = self:setAxisAngle(
     float: x,
     float: y,
     float: z,
     float: angle
  )

• math.quat:fromAxisAngle() - shared

  ✨ Creates a quat w/ specified axis angles.

  local quat: cQuat = math.quat:fromAxisAngle(
     float: x,
     float: y,
     float: z,
     float: angle
  )

• math.quat:toEuler() - shared

  ✨ Retrieves euler angles from quat.

  local float: x, float: y, float: z = self:toEuler()

• math.quat:fromEuler() - shared

  ✨ Creates a quat w/ specified euler angles.

  local quat: cQuat = math.quat:fromEuler(
     float: x,
     float: y,
     float: z
  )