Skip to content

niQuaternion⚓︎

A rotation in quaternion representation.

Properties⚓︎

w⚓︎

The W component of the quaternion.

Returns:

  • result (number)

x⚓︎

The X component of the quaternion.

Returns:

  • result (number)

y⚓︎

The Y component of the quaternion.

Returns:

  • result (number)

z⚓︎

The Z component of the quaternion.

Returns:

  • result (number)

Methods⚓︎

copy⚓︎

Creates a copy of the quaternion.

local result = myObject:copy()

Returns:

dot⚓︎

Calculates the dot product between this quaternion and another.

local result = myObject:dot(other)

Parameters:

Returns:

  • result (number): The dot product result.

exp⚓︎

Calculates the exponential e^q.

local result = myObject:exp()

Returns:

  • result (number): The result.

fromAngleAxis⚓︎

Fill the quaternion by converting an angle-axis rotation. The angle must be within the interval [0, PI] and the axis must be unit length.

myObject:fromAngleAxis(angle, axis)

Parameters:

fromRotation⚓︎

Fill the quaternion by converting a rotation matrix.

myObject:fromRotation(matrix)

Parameters:

invert⚓︎

Inverting or conjugating a rotation quaternion has the effect of reversing the axis of rotation, which modifies it to rotate in the opposite direction from the original. That is, if an object is rotated to a new position using a quaternion, then rotating it again by quaternion's inverse will return it to its original location.

local result = myObject:invert()

Returns:

log⚓︎

Calculates the logarithm log(q).

local result = myObject:log()

Returns:

  • result (number): The result.

normalize⚓︎

Normalizes the quaternion to unit length in-place. Returns true if result is unit length, false if the quaternion magnitude is very near to zero and cannot be normalized.

local isNormalized = myObject:normalize()

Returns:

  • isNormalized (boolean): If the quaternion was successfully normalized.

normalized⚓︎

Returns a normalized copy of this quaternion. The quaternion will be all zero if the quaternion magnitude is very near to zero and cannot be normalized.

local result = myObject:normalized()

Returns:

rotateTowards⚓︎

Calculates a spherical linear interpolation between this quaternion and another, limited to a maximum rotation angle. Chooses the shortest path of interpolation between quaternions, which means it minimizes spin but the interpolation arc is limited to pi radians or 180 degrees of interpolation.

local result = myObject:rotateTowards(target, rotationLimit)

Parameters:

  • target (niQuaternion): The quaternion to interpolate towards.
  • rotationLimit (number): The interpolation result will be limited to this maximum angle from the initial quaternion. Angle in radians.

Returns:

slerp⚓︎

Calculates a spherical linear interpolation between this quaternion and another. Chooses the shortest path of interpolation between quaternions, which means it minimizes spin but the interpolation arc is limited to pi radians or 180 degrees of interpolation.

local result = myObject:slerp(target, transition)

Parameters:

  • target (niQuaternion): The quaternion to interpolate towards.
  • transition (number): The interpolation parameter. Must be between 0.0 (closer to this quaternion) and 1.0 (closer to the other quaternion).

Returns:

slerpKeyframe⚓︎

Calculates a spherical linear interpolation between this quaternion and another. Does not choose a direction of interpolation. This means the interpolation arc can be up to 2pi radians or 360 degrees, depending on the signs of the quaternions.

local result = myObject:slerpKeyframe(target, transition)

Parameters:

  • target (niQuaternion): The quaternion to interpolate towards.
  • transition (number): The interpolation parameter. Must be between 0.0 (closer to this quaternion) and 1.0 (closer to the other quaternion).

Returns:

toAngleAxis⚓︎

Convert this quaternion into an angle-axis rotation.

local angle, axis = myObject:toAngleAxis()

Returns:

toRotation⚓︎

Convert this quaternion into a rotation matrix.

local result = myObject:toRotation()

Returns:

Functions⚓︎

new⚓︎

Creates a new niQuaternion object.

local quaternion = niQuaternion.new(w, x, y, z)

Parameters:

  • w (number): Default: 0.
  • x (number): Default: 0.
  • y (number): Default: 0.
  • z (number): Default: 0.

Returns:

Math Operations⚓︎

Multiplication (*)⚓︎

Left operand type Right operand type Result type Description
niQuaternion niQuaternion niQuaternion Multiplies two quaternions. The end effect is that the resulting rotation quaternion is equal to the combined rotation of both quaternions.

Unary minus (-)⚓︎

Result type Description
niQuaternion Unary negation. The resulting quaternion represents the same rotation. It's used to get the closest rotation to another quaternion. if q1:dot(targetQuat) < 0 then the closest path to reach targetQuat is -targetQuat. Used in the slerp method.