Quaternion API

Quaternion API

This API was added on version 0.3.0 and comes with a multitude of functions for creating and manipulating Quaternions!

Unlike Ship API and Extended Ship API, this is a purely Lua API and as such includes multiple Lua-specific features like operator overrides (metamethods) and the ability to create new instances of given objects!

Functions

new

new( vector, number ) -> quaternion

This method constructs a new quaternion from a vector (imaginary) and a real value. This quaternion is not guarenteed to be normalized!

local imaginary = vector.new()
local q = quaternion.new(imaginary, 1)

---

fromAxisAngle

fromAxisAngle( vector, number ) -> quaternion

This method constructs a new quaternion from the provided axis - angle parameters. The quaternion is normalized!

local axis = vector.new(1, 0, 0)
local angle = math.pi
local q = quaternion.fromAxisAngle(axis, angle)

---

fromEuler

fromEuler( number, number, number ) -> quaternion

This method constructs a quaternion from the provided pitch, yaw, and roll using YXZ reference frame!

local pitch = math.pi / 2
local yaw = math.pi
local roll = 0
local q = quaternion.fromEuler(pitch, yaw, roll)

---

fromComponents

fromComponents( number, number, number, number ) -> quaternion

This method constructs a quaternion using the four components (x, y, z, w). This will not be normalized!

local q = quaternion.fromComponents(0, 0, 0, 1)

---

fromShip

fromShip() -> quaternion

This method constructs a quaternion directly from ship.getQuaternion(). It will error if the Ship API doesn't exist!

local q = quaternion.fromShip()

---

identity

identity() -> quaternion

This method constructs a new identity quaternion, representing an empty rotation!

local q = quaternion.identity()

---

---

Metatable Funnctions

add

add( quaternion, quaternion ) -> quaternion

This method adds two quaternions together. The resulting quaternion will not be normalized! If you want to add rotations together, use the mul function instead.

local q1 = quaternion.new()
local q2 = quaternion.new()
local q3 = q1:add(q2)
-- local q3 = q1 + q2 also works

---

sub

sub( quaternion, quaternion ) -> quaternion

This method subtracts two quaternions from each other. The resulting quaternion will not be normalized!

local q1 = quaternion.new()
local q2 = quaternion.new()
local q3 = q1:sub(q2)
-- local q3 = q1 - q2 also works

---

mul

mul( quaternion, number ) -> quaternion

mul( quaternion, quaternion ) -> quaternion

mul( quaternion, vector ) -> vector

This method multiplies a quaternion by a scalar value, another quaternion, or a vector!

• If the input is a number, it acts as a scalar value and scales the resulting quaternion
• If the input is another quaternion, it adds the two rotations
• If the input is a vector, it will rotate the vector by the quaternion

local scalar = 2
local q1 = quaternion.new()
local q2 = q1:mul(scalar)
-- local q2 = q1 * scalar also works

---

div

div( quaternion, number ) -> quaternion div( quaternion, quaternion ) -> quaternion

This method divides a quaternion by either a scalar value or another quaternion!

• If the input is a number, it acts as a scalar value. The resulting quaternion will not be normalized

local q1 = quaternion.new()
local q2 = quaternion.new()
local q3 = q1:div(q2)
-- local q3 = q1 / q2 also works

---

unm

unm( quaternion ) -> quaternion

This method negates a quaternion!

local q1 = quaternion.new()
local q2 = q1:unm()
-- local q2 = -q1 also works

---

tostring

tostring( quaternion ) -> string

This method stringifies a quaternion to the format of "w+xi+yj+zk"!

local q = quaternion.new()
print(q:tostring())

---

equals

equals( quaternion, quaternion ) -> boolean

This method compares two quaternions!

local q1 = quaternion.new()
local q2 = quaternion.new()
if q1:equals(q2) then
-- q1 == q2 also works
    print("They are equal!")
end

---

conjugate

conjugate( quaternion ) -> quaternion

This method finds the conjugate of the quaternion!

local q1 = quaternion.new()
local q2 = q1:conjugate()

---

normalize

normalize( quaternion ) -> quaternion

This method normalizes the quaternion!

local q1 = quaternion.new()
local q2 = q1:normalize()

---

inverse

inverse( quaternion ) -> quaternion

This method computes the inverse of the quaternion!

local q1 = quaternion.new()
local q2 = q1:inverse()

---

slerp

slerp( quaternion, quaternion, number ) -> quaternion

This method performs Spherical Linear Interpolation (SLerp) between the two given quaternions and alpha value (lerp ratio, 0..1 range)!

local q1 = quaternion.new()
local q2 = quaternion.new()
local q3 = q1:slerp(q2, 0.5)

---

getAngle

getAngle( quaternion ) -> number

This method gets the angle of the rotation defined by the given quaternion!

local q = quaternion.new()
local angle = q:getAngle()

---

getAxis

getAxis( quaternion ) -> vector

This method gets the normalized axis of rotation corresponding to the rotation defined by the quaternion!

local q = quaternion.new()
local axis = q:getAxis()

---

toEuler

toEuler( quaternion ) -> number, number, number

This method gets the pitch, yaw, and roll Euler angles in radians from the quaternion using YXZ reference frame!

local q = quaternion.new()
local pitch, yaw, roll = q:toEuler()

---

length

length( quaternion ) -> number

This method computes the length of the quaternion!

local q = quaternion.new()
local l = q:length()
-- local l = #q also works

---

isNan

isNan( quaternion ) -> boolean

This method checks if any component of the quaternion is NaN!

local q = quaternion.new()
if q:isNan() then
    print("The quaternion is NaN!")
end

***

#### isInf
`isInf( quaternion ) -> boolean`

_This method checks if any component of the quaternion is infinite!_
```lua
local q = quaternion.new()
if q:isInf() then
    print("The quaternion is infinite!")
end

---

copy

copy( quaternion ) -> quaternion

This method copies the quaternion!

local q1 = quaternion.new()
local q2 = q1:copy()