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(*args)

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

__getstate__()

Helper for pickle.

__mul__(value, /)

Multiply by a vector to rotate the vector

Args:

  • other (npt.ArrayLike[np.float64])

    3-element array representing vector to rotate or Nx3 array of vectors to rotate

Returns:

  • npt.ArrayLike[np.float64]

    3-element array representing rotated vector or Nx3 array of rotated vectors

Example

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

Return repr(self).

__rmul__(value, /)

Return value*self.

__str__()

Return str(self).

angle

Return the angle in radians of the rotation

Returns:

  • float

    Angle in radians of the rotation

as_euler()

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

Returns:

  • tuple[float, float, float]

    Tuple with 3 elements representing the rotation angles in radians

as_rotation_matrix()

Return 3x3 rotation matrix representing equivalent rotation

Returns:

  • npt.ArrayLike[np.float64]

    3x3 rotation matrix representing equivalent rotation

axis

Return the axis of rotation as a unit vector

Returns:

  • npt.ArrayLike[np.float64]

    3-element array representing the axis of rotation as a unit vector

conj

Return conjugate or inverse of the rotation

Returns:

  • satkit.quaternion

    Conjugate or inverse of the rotation

conjugate

Return conjugate or inverse of the rotation

Returns:

  • satkit.quaternion

    Conjugate or inverse of the rotation

static from_axis_angle(axis, angle)

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

Args:

  • axis (npt.ArrayLike[np.float64])

    3-element array representing axis of rotation

  • angle (float)

    angle of rotation in radians

Returns:

  • satkit.quaternion

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

static from_rotation_matrix(dcm)

Return quaternion representing identical rotation to input 3x3 rotation matrix

Args:

  • mat (npt.ArrayLike[np.float64])

    3x3 rotation matrix

Returns:

  • satkit.quaternion

    Quaternion representing identical rotation to input 3x3 rotation matrix

static rotation_between(v1, v2)

Quaternion representation rotation between two input vectors

Args:

  • v1 (npt.ArrayLike[np.float64])

    vector rotating from

  • v2 (npt.ArrayLike[np.float64])

    vector rotating to

Returns:

  • satkit.quaternion

    Quaternion that rotates from v1 to v2

static rotx(theta_rad)

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

Args:

  • theta (float)

    angle of rotation in radians

Returns:

  • satkit.quaternion

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

Notes

Equivalent rotation matrix: | 1 0 0| | 0 cos(theta) -sin(theta)| | 0 sin(theta) cos(theta)|

static roty(theta_rad)

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

Args:

  • theta (float)

    angle of rotation in radians

Returns:

  • satkit.quaternion

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

Notes

Equivalent rotation matrix: | cos(theta) 0 sin(theta)| | 0 1 0| | -sin(theta) 0 cos(theta)|

static rotz(theta_rad)

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

Args:

  • theta (float)

    angle of rotation in radians

Returns:

  • satkit.quaternion

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

Notes

Equivalent rotation matrix: | cos(theta) -sin(theta) 0| | sin(theta) cos(theta) 0| | 0 0 1|

slerp(other, frac, epsilon=1e-06)

Spherical linear interpolation between self and other

Args:

  • 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

    Quaternion representing interpolation between self and other