View Source Graphmath.Quatern (graphmath v2.6.0)
This is the 3D mathematics.
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) }.
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.
Types
Functions
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) 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) 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) 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) 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) 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) 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.
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}.
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) creates a quatern from a rotation matrix.
mat is the matrix
It returns a quatern of the form {w,x,y,z}.
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.
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.
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.
@spec 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) 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) 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 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) 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) 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) 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.
@spec random() :: quatern()
Genrate a random quatenrion (rotation on SO3), using the algorithm given here.
It returns an orientation 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}.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 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_33(quat) creates a mat33 from a quatern.
quat is the quatern
It returns a mat33 representing a rotation.
to_rotation_matrix_44(quat) creates a mat44 from a quatern.
quat is the quatern
It returns a mat44 representing a rotation.
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.
@spec 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.