View Source Graphmath.Quatern (graphmath v3.0.0)
Quaternion arithmetic and 3D rotations using {w, x, y, z} tuples of floats.
w is the scalar component; {x, y, z} is the vector (imaginary) part.
For a unit quaternion representing a rotation by theta radians about the
unit axis {nx, ny, nz}, the components are:
w = cos(theta / 2)
x = nx * sin(theta / 2)
y = ny * sin(theta / 2)
z = nz * sin(theta / 2)The angle is encoded through its half-angle sine and cosine. The vector part
carries the axis direction, scaled by sin(theta / 2).
create/4 and from_list/1 store the components you supply. Use
from_axis_angle/2 to convert an angle and unit axis into those components.
For example, a positive 90-degree rotation about Z is approximately
{0.7071, 0.0, 0.0, 0.7071}:
Graphmath.Quatern.from_axis_angle(:math.pi() / 2, {0.0, 0.0, 1.0})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
from_axis_angle(theta, axis) creates a rotation quaternion from an angle and a unit axis.
from_list(quatern) creates a quatern from a list of 4 or more numbers, converting them to 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 angular velocity over a timestep with initial 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) interpolates between two quaternion orientations along the shortest arc.
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 scalar component.
x is the first imaginary component.
y is the second imaginary component.
z is the third imaginary component.
It returns a quatern of the form {w,x,y,z}.
The supplied values are stored as floats without normalization or angle-axis
conversion. To construct a rotation from an angle and a unit axis, use
from_axis_angle/2.
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 bounds 1 - abs(dot(a, b)),
including the boundary; it is not an angular tolerance in radians.
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.
from_axis_angle(theta, axis) creates a rotation quaternion from an angle and a unit axis.
theta is the angle in radians.
axis is a unit vec3 of the form {nx, ny, nz}.
It returns {cos(theta / 2), nx * sin(theta / 2), ny * sin(theta / 2), nz * sin(theta / 2)}.
The returned scalar component w is cos(theta / 2).
from_list(quatern) creates a quatern from a list of 4 or more numbers, converting them to 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 a 3x3 rotation matrix using the row-vector convention of
Graphmath.Mat33.make_rotate/1 and Graphmath.Mat33.apply_left/2.
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 angular velocity over a timestep with initial orientation q.
q is an orientation quaternion to use as the initial orientation.
omega is a world-space vec3 whose direction is the axis of rotation and
whose magnitude is angular velocity in radians per unit time. The incremental
rotation left-multiplies q, so it acts after the initial orientation.
dt is the timestep over which to apply the angular velocity.
The result is normalized, including for zero timestep or zero angular velocity. Small increments use a Taylor approximation; the zero quaternion remains zero.
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 quat has zero magnitude, this returns the 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.
Raises ArithmeticError if the magnitude of the quaternion is zero.
@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) interpolates between two quaternion orientations along the shortest arc.
lhs is the first quatern
rhs is the second quatern
t is the interpolation parameter on [0,1]. The endpoint orientations are
lhs when t = 0 and rhs when t = 1.
It returns a quatern representing the normalized interpolation point.
Use unit inputs for interpolation at constant angular velocity. Nearly identical orientations use normalized linear interpolation for stability.
Quaternions q and -q represent the same orientation. The sign of rhs
may be reversed to choose the shortest arc, including at t = 1.
Swapping the inputs and replacing t with 1 - t gives the same
orientation, possibly with the opposite quaternion sign.
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 a unit quaternion.
It returns a mat33 representing the same rotation, using row vectors.
Apply it to a 3D vector with Graphmath.Mat33.apply_left/2 or
Graphmath.Mat33.apply_transpose/2. A rotation about Z can also be used
with the Mat33 2D point/vector transforms.
to_rotation_matrix_44(quat) creates a mat44 from a quatern.
quat is a unit quaternion.
It returns a mat44 representing the same rotation, compatible with
Graphmath.Mat44.transform_point/2 and Graphmath.Mat44.transform_vector/2.
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.