Sandbox: Lua: Math: Quat - ov-studio/Vital.sandbox GitHub Wiki

━ What's the Objective?

Quaternions are simplified representation of complex numbers on 4 dimensions (1 real & 3 imaginary dimensions). Quats widely known for representing rotations precisely have special desirable properties compared to other form of representation such as 'Euler', 'Matrix' where you would end up with bottleneck due to Gimbal locks. Beside rotations quats are also pretty useful for generic math.

If you still have no idea how useful they are or where to apply/utilize them in the right way, then make sure to read: https://math.dartmouth.edu/~jvoight/quat-book.pdf

━ 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)

@Objective: Retrieve's instance's type.

local string: type = self:getType()

---

━ math.quat() (Shared)

@Objective: Creates a quaternion instance.

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

---

━ math.quat:destroy() (Shared)

@Objective: Destroys an existing quat.

local bool: result = self:destroy()

---

━ math.quat:scale() (Shared)

@Objective: Scales quat w/ specified scale.

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

---

━ math.quat:setAxisAngle() (Shared)

@Objective: Sets quat's axis angles.

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

---

━ math.quat:fromAxisAngle() (Shared)

@Objective: 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)

@Objective: Retrieves euler angles from quat.

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

---

━ math.quat:fromEuler() (Shared)

@Objective: Creates a quat w/ specified euler angles.

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