Quaternions

Introduction

Quaternions are a mathematical concept that extends the idea of complex numbers to four dimensions. They are used in many fields, including computer graphics, robotics, and physics. In the context of this toolkit, they represent rotations in 3D space and are operationally equivalent to rotation matrices.

They have several advantages over rotation matrices, including:

They are more compact, requiring only four numbers to represent a rotation instead of nine.
They are more numerically stable, avoiding the gimbal lock problem.
They are easier to interpolate between, making them useful for animations.

This toolkit provides a Class for working with quaternions, including methods for creating, manipulating, and converting them.

Warning

Quaternions in this module perform a right-handed rotation of the \(vector\). You will occasionally see (especially in attitude control texts) a quaternion convention that does a right-handed rotation of the coordinate system, which is a left-handed rotation of the vector. This abomination serves only to add confusion and must be struck down wherever it is seen.

For an excellent description of quaternions, see here

Class Reference

class satkit.quaternion

Quaternion representing rotation of 3D Cartesian axes

Quaternions perform right-handed rotation of a vector, e.g. rotation of +xhat 90 degrees by +zhat give +yhat

This is different than the convention used in Vallado, but it is the way it is commonly used in mathematics and it is the way it should be done.

For the uninitiated: quaternions are a more-compact and computationally efficient way of representing 3D rotations. They can also be multipled together and easily renormalized to avoid problems with floating-point precision eventually causing changes in the rotated vecdtor norm.

For details, see:

https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation

Notes

Under the hood, this is using the “UnitQuaternion” object in the rust “nalgebra” crate.

__init__()

Return unit quaternion (no rotation)

Returns:: Quaternion representing no rotation
Return type:: satkit.quaternion

__mul__(other: quaternion) → quaternion

Multiply by a vector to rotate the vector

Parameters:: other (npt.ArrayLike[np.float64]) – 3-element array representing vector to rotate or Nx3 array of vectors to rotate
Returns:: 3-element array representing rotated vector or Nx3 array of rotated vectors
Return type:: npt.ArrayLike[np.float64]

Example

>>> xhat = np.array([1,0,0])
>>> q = satkit.quaternion.rotz(np.pi/2)
>>> print(q * xhat)
[0, 1, 0]

angle() → float

Return the angle in radians of the rotation

Returns:: Angle in radians of the rotation
Return type:: float

as_euler() → tuple[float, float, float]

Return equivalent rotation angle represented as rotation angles: (“roll”, “pitch”, “yaw”) in radians:

Returns:: Tuple with 3 elements representing the rotation angles in radians
Return type:: tuple[float, float, float]

as_rotation_matrix() → numpy.typing.NDArray[numpy.float64]

Return 3x3 rotation matrix representing equivalent rotation

Returns:: 3x3 rotation matrix representing equivalent rotation
Return type:: npt.ArrayLike[np.float64]

axis() → numpy.typing.NDArray[numpy.float64]

Return the axis of rotation as a unit vector

Returns:: 3-element array representing the axis of rotation as a unit vector
Return type:: npt.ArrayLike[np.float64]

property conj: quaternion

Return conjugate or inverse of the rotation

Returns:: Conjugate or inverse of the rotation
Return type:: satkit.quaternion

property conjugate: quaternion

Return conjugate or inverse of the rotation

Returns:: Conjugate or inverse of the rotation
Return type:: satkit.quaternion

static from_axis_angle(axis: numpy.typing.NDArray[numpy.float64], angle: float) → quaternion

Quaternion representing right-handed rotation of vector by “angle” degrees about the given axis

Parameters:

axis (npt.ArrayLike[np.float64]) – 3-element array representing axis of rotation
angle (float) – angle of rotation in radians

Returns:

Quaternion representing rotation by “angle” degrees about the given axis

Return type:

satkit.quaternion

static from_rotation_matrix(mat: numpy.typing.NDArray[numpy.float64]) → quaternion

Return quaternion representing identical rotation to input 3x3 rotation matrix

Parameters:: mat (npt.ArrayLike[np.float64]) – 3x3 rotation matrix
Returns:: Quaternion representing identical rotation to input 3x3 rotation matrix
Return type:: satkit.quaternion

static rotation_between(v1: numpy.typing.NDArray[numpy.float64], v2: numpy.typing.NDArray[numpy.float64]) → quaternion

Quaternion represention rotation between two input vectors

Parameters:

v1 (npt.ArrayLike[np.float64]) – vector rotating from
v2 (npt.ArrayLike[np.float64]) – vector rotating to

Returns:

Quaternion that rotates from v1 to v2

Return type:

satkit.quaternion

static rotx(theta) → quaternion

Quaternion representing right-handed rotation of vector by “theta” radians about the xhat unit vector

Parameters:: theta (float) – angle of rotation in radians
Returns:: Quaternion representing right-handed rotation of vector by “theta” radians about the xhat unit vector
Return type:: satkit.quaternion

Notes

static roty(theta) → quaternion

Quaternion representing right-handed rotation of vector by “theta” radians about the yhat unit vector

Parameters:: theta (float) – angle of rotation in radians
Returns:: Quaternion representing right-handed rotation of vector by “theta” radians about the yhat unit vector
Return type:: satkit.quaternion

Notes

static rotz(theta) → quaternion

Quaternion representing right-handed rotation of vector by “theta” radians about the zhat unit vector

Parameters:: theta (float) – angle of rotation in radians
Returns:: Quaternion representing right-handed rotation of vector by “theta” radians about the zhat unit vector
Return type:: satkit.quaternion

Notes

slerp(other: quaternion, frac: float, epsilon: float = 1e-06) → quaternion

Spherical linear interpolation between self and other

Parameters:

other (quaternion) – Quaternion to perform interpolation to
frac (float) – fractional amount of interpolation, in range [0,1]
epsilon (float, optional) – Value below which the sin of the angle separating both quaternions must be to return an error. Default is 1.0e-6

Returns:

Quaternion representing interpolation between self and other

Return type:

quaternion