graphmath v1.0.7 Graphmath.Quatern

This is the 3D mathematics library for graphmath.

This submodule handles Quaternion using tuples of floats. i.e. a rotation around an axis.

Consider the quatern format: { w, x, y, z } where w is the angle in Radians, and x y z are the axis coordinates

Link to this section Summary

Functions

add(lhs, rhs) add two quaternions

conjugate(quat) returns the conjugate of a quaternion

create() creates a zeroed quatern

create(quatern) creates a quatern from a list of 4 or more floats

create(w, vec) creates a quatern from an angle and an axis

create(w,x,y,z) creates a quatern of value (w,x,y,z)

dot(lhs, rhs) returns a float resultant of the dot product bectween two quaterns

from_rotation_matrix(mat) creates a quatern from a rotation matrix

pitch(quat) Calculate the local pitch element of a quaternion

roll(quat) Calculate the local roll element of a quaternion

yaw(quat) Calculate the local yaw element of a quaternion

inverse(quat) returns the inverse of a quaternion

multiply(lhs, rhs) multiply two quaternions

norm(quat) Returns the L2 norm of a quaternion

normalize(q) returns a normalized verison of a quaternion

scale(quat, scalar) multiply a quatern for a scalar

slerp(lhs, rhs, t) Performs Spherical linear interpolation between two quaternions, and returns the result

subtract(lhs, rhs) subtract two quaternions

to_rotation_matrix(quat) creates a mat33 from a quatern

Link to this section Types

Link to this type

mat33()
mat33() ::
  {float(), float(), float(), float(), float(), float(), float(), float(),
   float()}

Link to this type

quatern()
quatern() :: {float(), float(), float(), float()}

Link to this type

vec3()
vec3() :: {float(), float(), float()}

Link to this section Functions

Link to this function

add(lhs, rhs)
add(quatern(), quatern()) :: quatern()

add(lhs, rhs) add two quaternions.

lhs is the first quatern

rhs is the second quatern

It returns a quatern of the form { lhsw + rhsw, lhsx + rhsx, lhsy + rhsy, lhsz + rhsz }.

Link to this function

conjugate(quat)
conjugate(quatern()) :: quatern()

conjugate(quat) returns the conjugate of a quaternion.

quat is the quaternion to get the conjugate of.

It returns a quatern representing the inverse of the unit quatern.

Note that the conjugate of a unit quaternion is its inverse.

Link to this function

create()
create() :: quatern()

create() creates a zeroed quatern.

It takes no arguments.

It returns a quatern of the form { 0.0, 0.0, 0.0, 0.0 }.

Link to this function

create(quatern)
create([float()]) :: quatern()

create(quatern) creates a quatern from a list of 4 or more floats.

quatern is a list of 4 or more floats.

It returns a quatern of the form {w,x,y,z}, where w, x, y, and z are the first four elements in quatern.

Link to this function

create(w, vec)
create(float(), vec3()) :: quatern()

create(w, vec) creates a quatern from an angle and an axis.

w is the angle in radians.

vec is the axis vec3 of the form {x,y,z}.

It returns a quatern of the form {w,x,y,z}.

Link to this function

create(w, x, y, z)
create(float(), float(), float(), float()) :: quatern()

create(w,x,y,z) creates a quatern of value (w,x,y,z).

w is the rotation arround the axis in Radians.

x is the first element of the vec3 representing the axis to be created.

y is the second element of the vec3 representing the axis to be created.

z is the third element of the vec3 representing the axis to be created.

It returns a quatern of the form {w,x,y,z}.

Link to this function

dot(lhs, rhs)
dot(quatern(), quatern()) :: float()

dot(lhs, rhs) returns a float resultant of the dot product bectween two quaterns.

lhs is a quatern

rhs is a quatern

It returns a float representing the dot product.

Link to this function

from_rotation_matrix(mat)
from_rotation_matrix(mat33()) :: quatern()

from_rotation_matrix(mat) creates a quatern from a rotation matrix.

mat is the matrix

It returns a quatern of the form {w,x,y,z}.

Link to this function

get_pitch(quat)
get_pitch(quatern()) :: float()

pitch(quat) Calculate the local pitch element of a quaternion.

quat is the quatern

It returns a float representing the pitch of the quaternion in Radians.

Link to this function

get_roll(quat)
get_roll(quatern()) :: float()

roll(quat) Calculate the local roll element of a quaternion.

quat is the quatern

It returns a float representing the roll of the quaternion in Radians.

Link to this function

get_yaw(quat)
get_yaw(quatern()) :: float()

yaw(quat) Calculate the local yaw element of a quaternion.

quat is the quatern

It returns a float representing the yaw of the quaternion in Radians.

Link to this function

inverse(quat)
inverse(quatern()) :: quatern()

inverse(quat) returns the inverse of a quaternion.

quat is the quaternion

It returns a quatern representing the inverse of the parameter quaternion.

If the quatis less than zero, the quaternion returned is a zero quaternion.

Link to this function

multiply(lhs, rhs)
multiply(quatern(), quatern()) :: quatern()

multiply(lhs, rhs) multiply two quaternions.

lhs is the first quatern

rhs is the second quatern

It returns a quatern resultant of the multiplication NOTE: Multiplication is not generally commutative, so in most cases pq != qp.

Link to this function

norm(quat)
norm(quatern()) :: float()

norm(quat) Returns the L2 norm of a quaternion.

quat is a quatern to find the norm of.

It returns a float representing the L2 norm.

Link to this function

normalize(q)
normalize(quatern()) :: quatern()

normalize(q) returns a normalized verison of a quaternion.

q is the quatern to be normalized.

This returns a quatern of unit length in the same direction as q.

Link to this function

scale(quat, scalar)
scale(quatern(), float()) :: quatern()

scale(quat, scalar) multiply a quatern for a scalar.

quat is the quatern

scalar is the scalar

It returns a quatern of the form

{ a<sub>w</sub> * scalar, a<sub>x</sub> * scalar, a<sub>y</sub> * scalar, a<sub>z</sub> * scalar}.
Link to this function

slerp(lhs, rhs, t)
slerp(quatern(), quatern(), float()) :: quatern()

slerp(lhs, rhs, t) Performs Spherical linear interpolation between two quaternions, and returns the result.

lhs is the first quatern

rhs is the second quatern

t is the interpolation parameter that will interpolate to lhs when t = 0 and to rhs when t = 1.

It returns a quatern representing the normalized interpolation point.

Note: slerp has the proprieties of performing the interpolation at constant velocity However, it's NOT commutative, which means slerp( A, B, 0.75 ) != slerp( B, A, 0.25 ) therefore be careful if your code relies in the order of the operands. This is specially important in IK animation.

Link to this function

subtract(lhs, rhs)
subtract(quatern(), quatern()) :: quatern()

subtract(lhs, rhs) subtract two quaternions.

lhs is the first quatern

rhs is the second quatern

It returns a quatern of the form { lhsw - rhsw, lhsx - rhsx, lhsy - rhsy, lhsz - rhsz }.

Link to this function

to_rotation_matrix(quat)
to_rotation_matrix(quatern()) :: mat33()

to_rotation_matrix(quat) creates a mat33 from a quatern.

quat is the quatern

It returns a mat33 representing a rotation.