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

Summary

add(lhs, rhs)

add(lhs, rhs) add two quaternions

conjugate(quat)

conjugate(quat) returns the conjugate of a quaternion

create()

create() creates a zeroed quatern

create(quatern)

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

create(w, vec)

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

create(w, x, y, z)

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

dot(lhs, rhs)

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

from_rotation_matrix(mat)

from_rotation_matrix(mat) creates a quatern from a rotation matrix

get_pitch(quat)

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

get_roll(quat)

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

get_yaw(quat)

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

inverse(quat)

inverse(quat) returns the inverse of a quaternion

multiply(lhs, rhs)

multiply(lhs, rhs) multiply two quaternions

norm(quat)

norm(quat) Returns the L2 norm of a quaternion

normalize(quat)

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

scale(quat, scalar)

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

subtract(lhs, rhs)

subtract(lhs, rhs) subtract two quaternions

to_rotation_matrix(quat)

to_rotation_matrix(quat) creates a mat33 from a quatern

Types

quatern :: {float, float, float, float}

vec3 :: {float, float, float}

mat33 :: {float, float, float, float, float, float, float, float, float}

Functions

add(lhs, rhs)

Specs:

add(lhs, rhs) add two quaternions.

lhs is the first quatern

rhs is the second quatern

It returns a quatern of the form

{ lhs<sub>w</sub> + rhs<sub>w</sub>, lhs<sub>x</sub> + rhs<sub>x</sub>, lhs<sub>y</sub> + rhs<sub>y</sub>, lhs<sub>z</sub> + rhs<sub>z</sub> }.
conjugate(quat)

Specs:

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.

create()

Specs:

create() creates a zeroed quatern.

It takes no arguments.

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

create(quatern)

Specs:

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.

create(w, vec)

Specs:

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

w is the angle in radians.

vec is the axis, a tuple {x,y,z}

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

create(w, x, y, z)

Specs:

  • 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}.

dot(lhs, rhs)

Specs:

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.

from_rotation_matrix(mat)

Specs:

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}.

get_pitch(quat)

Specs:

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.

get_roll(quat)

Specs:

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.

get_yaw(quat)

Specs:

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.

inverse(quat)

Specs:

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.

multiply(lhs, rhs)

Specs:

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.

norm(quat)

Specs:

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.

normalize(quat)

Specs:

`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.

scale(quat, scalar)

Specs:

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}.
subtract(lhs, rhs)

Specs:

subtract(lhs, rhs) subtract two quaternions.

lhs is the first quatern

rhs is the second quatern

It returns a quatern of the form

{ lhs<sub>w</sub> - rhs<sub>w</sub>, lhs<sub>x</sub> - rhs<sub>x</sub>, lhs<sub>y</sub> - rhs<sub>y</sub>, lhs<sub>z</sub> - rhs<sub>z</sub> }.
to_rotation_matrix(quat)

Specs:

to_rotation_matrix(quat) creates a mat33 from a quatern.

quat is the quatern

It returns a mat33 representing a rotation.