graphmath v2.1.0 Graphmath.Quatern

This is the 3D mathematics library for graphmath.

This submodule handles Quaternion using tuples of floats.

Quaternions represent an angle of theta around a unit axis vector {nx, ny, nz} as { cos(theta/2), nx * sin(theta/2), ny * sin(theta/2), nz * sin(theta/2) }.

Link to this section Summary

Functions

add(lhs, rhs) add two quaternions

conjugate(quat) returns the conjugate of a quaternion

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

equal(a,b) checks to see if two orientation quaternions a and b are equivalent

equal(a,b,eps) checks to see if two orientation quaternions a and b are equivalent up to some epsilon

equal_elements(a,b) checks to see if two quaternions a and b are element-wise equal

equal_elements(a,b, eps) checks to see if two quaternions a and b are element-wise equal to some epsilon

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

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

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

identity() creates the identity quatern

integrate(q, omega, dt) integrates the angular velocty omega over a timestep dt with intial orientation q

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

normalize_strict(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_33(quat) creates a mat33 from a quatern

to_rotation_matrix_44(quat) creates a mat44 from a quatern

transform_vector(q,v) transforms a vector v by an orientation quaternion q

zero() creates a zero 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

mat44()
mat44() ::
  {float(), float(), float(), float(), float(), float(), float(), 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(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 around 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

equal(a, b)
equal(quatern(), quatern()) :: boolean()

equal(a,b) checks to see if two orientation quaternions a and b are equivalent.

a is the first quaternion.

b is the second quaternion.

It returns true if the quaternions represent the same orientation.

This function expects normalized quaternions.

Note that orientation quaternions exist where a == -b...that is, where the axes are equivalent but the angle is opposite in sign.

Link to this function

equal(a, b, eps)
equal(quatern(), quatern(), float()) :: boolean()

equal(a,b,eps) checks to see if two orientation quaternions a and b are equivalent up to some epsilon

a is the first quaternion.

b is the second quaternion.

eps is the epsilon, on the interval [0,1].

It returns true if the quaternions represent the same orientation.

This function expects normalized quaternions.

Note that orientation quaternions exist where a == -b...that is, where the axes are equivalent but the angle is opposite in sign.

Link to this function

equal_elements(a, b)
equal_elements(quatern(), quatern()) :: boolean()

equal_elements(a,b) checks to see if two quaternions a and b are element-wise equal.

a is the first quaternion.

b is the second quaternion.

It returns true if the quaternions have the same elements, false otherwise.

This function does not require normalized quaternions.

Note that orientation quaternions exist where a == -b...that is, where the axes are equivalent but the angle is opposite in sign.

In such cases, prefer the equal/2 function.

Link to this function

equal_elements(a, b, eps)
equal_elements(quatern(), quatern(), float()) :: boolean()

equal_elements(a,b, eps) checks to see if two quaternions a and b are element-wise equal to some epsilon

a is the first quaternion.

b is the second quaternion.

eps is the float of the epsilon for comparison.

It returns true if the quaternions have the same element-wise values up to and including some epsilon.

This function does not require normalized quaternions.

Note that orientation quaternions exist where a == -b...that is, where the axes are equivalent but the angle is opposite in sign.

In such cases, prefer the equal/3 function.

Link to this function

from_axis_angle(theta, arg)
from_axis_angle(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

from_list(list)
from_list([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

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

identity()
identity() :: quatern()

identity() creates the identity quatern.

It takes no arguments.

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

Link to this function

integrate(q, omega, dt)

integrate(q, omega, dt) integrates the angular velocty omega over a timestep dt with intial orientation q.

q is an orientation quaternion to use as the initial orientation.

omega is a vec3 whose direction is the axis of rotation and whose magnitude is the velocity about that axis.

dt is the timestep over which to apply the angular velocity.

It returns an orientation quatern.

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 quat is less than or equal to 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.

If the magnitude of the quaternion is 0, it will return the zero quaternion.

Link to this function

normalize_strict(q)
normalize_strict(quatern()) :: quatern()

normalize_strict(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.

If the magnitude of the quaternion is 0, it will explode.

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_33(quat)
to_rotation_matrix_33(quatern()) :: mat33()

to_rotation_matrix_33(quat) creates a mat33 from a quatern.

quat is the quatern

It returns a mat33 representing a rotation.

Link to this function

to_rotation_matrix_44(quat)
to_rotation_matrix_44(quatern()) :: mat44()

to_rotation_matrix_44(quat) creates a mat44 from a quatern.

quat is the quatern

It returns a mat44 representing a rotation.

Link to this function

transform_vector(arg1, arg2)

transform_vector(q,v) transforms a vector v by an orientation quaternion q.

q is an orientation quaternion.

v is a Vec3 to transform--it need not be normalized.

It returns a Vec3 of v having undergone the rotation represented by q.

Link to this function

zero()
zero() :: quatern()

zero() creates a zero quatern.

It takes no arguments.

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

Note that the zero quaternion is almost definetely not something you ever use.