Quaternions¶

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.

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.

For an excellent description of quaternions, see here.

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

`conj` `property` ¶

Return conjugate or inverse of the rotation

Returns:

Type	Description
`quaternion`	satkit.quaternion: Conjugate or inverse of the rotation

`conjugate` `property` ¶

Return conjugate or inverse of the rotation

Returns:

Type	Description
`quaternion`	satkit.quaternion: Conjugate or inverse of the rotation

`x` `property` ¶

X component of the quaternion

Returns:

Name	Type	Description
`float`	`float`	X component of the quaternion

`y` `property` ¶

Y component of the quaternion

Returns:

Name	Type	Description
`float`	`float`	Y component of the quaternion

`z` `property` ¶

Z component of the quaternion

Returns:

Name	Type	Description
`float`	`float`	Z component of the quaternion

`w` `property` ¶

Scalar component of the quaternion

Returns:

Name	Type	Description
`float`	`float`	Scalar component of the quaternion

`init(w=1.0, x=0.0, y=0.0, z=0.0)` ¶

Return quaternion with input (w,x,y,z) values

Parameters:

Name	Type	Description	Default
`w`	`float`	Scalar component of the quaternion	`1.0`

Example

# Identity quaternion (no rotation)
q = satkit.quaternion()

# 90 degree rotation about z-axis
import math
q = satkit.quaternion.rotz(math.radians(90))

x: X component of the quaternion y: Y component of the quaternion z: Z component of the quaternion

`from_axis_angle(axis, angle)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`axis`	`ArrayLike[float64]`	3-element array representing axis of rotation	required
`angle`	`float`	angle of rotation in radians	required

Returns:

Type	Description
`quaternion`	satkit.quaternion: Quaternion representing rotation by "angle" degrees about the given axis

`from_rotation_matrix(mat)` `staticmethod` ¶

Return quaternion representing identical rotation to input 3x3 rotation matrix

Parameters:

Name	Type	Description	Default
`mat`	`ArrayLike[float64]`	3x3 rotation matrix	required

Returns:

Type	Description
`quaternion`	satkit.quaternion: Quaternion representing identical rotation to input 3x3 rotation matrix

`rotx(theta)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`theta`	`float`	angle of rotation in radians	required

Returns:

Type	Description
`quaternion`	satkit.quaternion: Quaternion representing right-handed rotation of vector by "theta" radians about the xhat unit vector

Notes

`roty(theta)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`theta`	`float`	angle of rotation in radians	required

Returns:

Type	Description
`quaternion`	satkit.quaternion: Quaternion representing right-handed rotation of vector by "theta" radians about the yhat unit vector

Notes

`rotz(theta)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`theta`	`float`	angle of rotation in radians	required

Returns:

Type	Description
`quaternion`	satkit.quaternion: Quaternion representing right-handed rotation of vector by "theta" radians about the zhat unit vector

Notes

`rotation_between(v1, v2)` `staticmethod` ¶

Quaternion representation rotation between two input vectors

Parameters:

Name	Type	Description	Default
`v1`	`ArrayLike[float64]`	vector rotating from	required
`v2`	`ArrayLike[float64]`	vector rotating to	required

Returns:

Type	Description
`quaternion`	satkit.quaternion: Quaternion that rotates from v1 to v2

Example

import numpy as np
v1 = np.array([1, 0, 0])
v2 = np.array([0, 1, 0])
q = satkit.quaternion.rotation_between(v1, v2)
print(q * v1)
# [0, 1, 0]

`as_rotation_matrix()` ¶

Return 3x3 rotation matrix representing equivalent rotation

Returns:

Type	Description
`NDArray[float64]`	npt.ArrayLike[np.float64]: 3x3 rotation matrix representing equivalent rotation

`as_euler()` ¶

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

Returns:

Type	Description
`tuple[float, float, float]`	tuple[float, float, float]: Tuple with 3 elements representing the rotation angles in radians

`angle()` ¶

Return the angle in radians of the rotation

Returns:

Name	Type	Description
`float`	`float`	Angle in radians of the rotation

`axis()` ¶

Return the axis of rotation as a unit vector

Returns:

Type	Description
`NDArray[float64]`	npt.ArrayLike[np.float64]: 3-element array representing the axis of rotation as a unit vector

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

Spherical linear interpolation between self and other

Parameters:

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

Returns:

Name	Type	Description
`quaternion`	`quaternion`	Quaternion representing interpolation between self and other

Example

import math
q1 = satkit.quaternion.rotz(math.radians(0))
q2 = satkit.quaternion.rotz(math.radians(90))
q_mid = q1.slerp(q2, 0.5)
print(f"Mid-rotation angle: {math.degrees(q_mid.angle()):.1f} deg")
# Mid-rotation angle: 45.0 deg

Quaternions¶

quaternion ¶

conj property ¶

conjugate property ¶

x property ¶

y property ¶

z property ¶

w property ¶

__init__(w=1.0, x=0.0, y=0.0, z=0.0) ¶

from_axis_angle(axis, angle) staticmethod ¶

from_rotation_matrix(mat) staticmethod ¶

rotx(theta) staticmethod ¶

roty(theta) staticmethod ¶

rotz(theta) staticmethod ¶

rotation_between(v1, v2) staticmethod ¶

as_rotation_matrix() ¶

as_euler() ¶

angle() ¶

axis() ¶

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

`quaternion` ¶

`conj` `property` ¶

`conjugate` `property` ¶

`x` `property` ¶

`y` `property` ¶

`z` `property` ¶

`w` `property` ¶

`init(w=1.0, x=0.0, y=0.0, z=0.0)` ¶

`from_axis_angle(axis, angle)` `staticmethod` ¶

`from_rotation_matrix(mat)` `staticmethod` ¶

`rotx(theta)` `staticmethod` ¶

`roty(theta)` `staticmethod` ¶

`rotz(theta)` `staticmethod` ¶

`rotation_between(v1, v2)` `staticmethod` ¶

`as_rotation_matrix()` ¶

`as_euler()` ¶

`angle()` ¶

`axis()` ¶

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