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
mat33()
mat44()
quatern()
vec3()
Link to this section Functions
add(lhs, rhs)
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 }.
conjugate(quat)
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(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}
.
dot(lhs, rhs)
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.
equal(a, b)
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.
equal(a, b, eps)
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.
equal_elements(a, b)
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.
equal_elements(a, b, eps)
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.
from_axis_angle(theta, arg)
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}
.
from_list(list)
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
.
from_rotation_matrix(mat)
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)
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)
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)
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.
identity()
identity() :: quatern()
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}
.
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
.
inverse(quat)
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.
multiply(lhs, rhs)
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)
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(q)
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.
normalize_strict(q)
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.
scale(quat, scalar)
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}.
slerp(lhs, rhs, t)
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.
subtract(lhs, rhs)
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 }.
to_rotation_matrix_33(quat)
to_rotation_matrix_33(quat)
creates a mat33
from a quatern.
quat
is the quatern
It returns a mat33
representing a rotation.
to_rotation_matrix_44(quat)
to_rotation_matrix_44(quat)
creates a mat44
from a quatern.
quat
is the quatern
It returns a mat44
representing a rotation.
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
.
zero()
zero() :: quatern()
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.