archimedes.spatial.Quaternion¶

class archimedes.spatial.Quaternion(array: ndarray)¶

Quaternion representation of a rotation in 3 dimensions.

This class is closely modeled after [scipy.spatial.transform.Rotation]( https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html) with a few differences:

The quaternion is always represented in scalar-first format (i.e. [w, x, y, z]) instead of scalar-last ([x, y, z, w]).
This class is designed for symbolic computation, so some checks (e.g. for valid rotation matrices) are omitted, since these cannot be done symbolically.
The class does not support multiple rotations in a single object
This implementation supports kinematic calculations

The following operations on quaternions are supported:

Application on vectors (rotations of vectors)
Quaternion Composition
Quaternion Inversion
Kinematic time derivative given angular velocity

Parameters:: quat (array_like, shape (4,)) – Quaternion representing the rotation in scalar-first format (w, x, y, z).
Variables:: array (np.ndarray, shape (4,)) – Underlying numpy array representing the quaternion.

Examples

>>> from archimedes.spatial import Quaternion
>>> import numpy as np

Consider a counter-clockwise rotation of 90 degrees about the z-axis. This corresponds to the following quaternion (in scalar-first format):

>>> q = Quaternion([np.cos(np.pi/4), 0, 0, np.sin(np.pi/4)])

The quaternion can be expressed in any of the other formats:

>>> q.as_matrix()
array([[ 2.22044605e-16,  1.00000000e+00,  0.00000000e+00],
   [-1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
   [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> np.rad2deg(q.as_euler('zyx'))
array([90.,  0.,  0.])

The same quaternion can be initialized using a rotation matrix:

>>> q = Quaternion.from_matrix([[0, 1, 0],
...                    [-1, 0, 0],
...                    [0, 0, 1]])

Representation in other formats:

>>> np.rad2deg(q.as_euler('zyx'))
array([90.,  0.,  0.])

The from_euler method is flexible in the range of input formats it supports. Here we initialize a quaternion about a single axis:

>>> q = Quaternion.from_euler(np.deg2rad(90), 'z')

The associated rotation matrix can be used to change coordinate systems. If the quaternion represents the orientation of a frame B relative to a frame A, then the rotation matrix transforms vectors from frame A to frame B:

>>> v_A = np.array([1, 0, 0])  # Vector in frame A
>>> R_BA = q.as_matrix()
>>> R_BA @ v_A  # Vector in frame B
[6.12323e-17, -1, 0]

The kinematics method can be used to compute the time derivative of the quaternion as an attitude representation given the angular velocity in the body frame using quaternion kinematics:

>>> w_B = np.array([0, 0, np.pi/2])  # 90 deg/s about z-axis
>>> q.kinematics(w_B)
array([-0.55536037,  0.        ,  0.        ,  0.55536037])

See also

scipy.spatial.transform.Rotation: Similar class in SciPy
RigidBody: Rigid body dynamics supporting Quaternion attitude representation
euler_to_dcm: Directly calculate rotation matrix from roll-pitch-yaw angles
euler_kinematics: Transform roll-pitch-yaw rates to body-frame angular velocity
quaternion_kinematics: Low-level quaternion kinematics function

Methods

`as_euler`(seq)	Return the Euler angles from the quaternion
`as_matrix`()	Return the quaternion as a rotation matrix.
`as_quat`()	Return the same object - dummy method for API consistency.
`from_euler`(euler[, seq])	Create a Quaternion from Euler angles.
`from_matrix`(matrix)	Create a Quaternion from a rotation matrix.
`from_quat`(quat)	Returns a copy of the Quaternion object - dummy method for API consistency.
`identity`()	Return a quaternion representing the identity rotation.
`inv`()	Return the inverse of the quaternion
`kinematics`(w[, baumgarte])	Return the time derivative of the quaternion given angular velocity w.
`mul`(other[, normalize])	Compose (multiply) this quaternion with another
`normalize`()	Return a normalized version of this quaternion.
`replace`(**updates)	Returns a new object replacing the specified fields with new values.

Attributes

array

classmethod from_euler( euler: EulerAngles | ndarray, seq: str | None = None, ) → Quaternion¶

Create a Quaternion from Euler angles.

Parameters:

euler (EulerAngles or array_like) – Euler angles instance or array of Euler angles in radians.
seq (str, optional) – Sequence of axes for Euler angles (up to length 3). Each character must be one of ‘x’, ‘y’, ‘z’ (extrinsic) or ‘X’, ‘Y’, ‘Z’ (intrinsic). Default is ‘xyz’. Should not be specified if euler is an EulerAngles instance.

Returns:

A new Quaternion instance.

Return type:

Quaternion

See also

euler_to_quaternion: Low-level Euler to quaternion conversion function

classmethod from_matrix( matrix: ndarray, ) → Quaternion¶

Create a Quaternion from a rotation matrix.

Note that for the sake of symbolic computation, this method assumes that the input is a valid rotation matrix (orthogonal and determinant +1).

Parameters:: matrix (array_like, shape (3, 3)) – Quaternion matrix.
Returns:: A new Quaternion instance.
Return type:: Quaternion

See also

dcm_to_quaternion: Low-level direction cosine matrix to quaternion conversion

classmethod from_quat( quat: Quaternion, ) → Quaternion¶

Returns a copy of the Quaternion object - dummy method for API consistency.

Returns:: A copy of the input Quaternion instance.
Return type:: Quaternion

classmethod identity() → Quaternion¶: Return a quaternion representing the identity rotation.

__init__(array: ndarray) → None¶

as_euler(seq: str) → EulerAngles¶

Return the Euler angles from the quaternion

This method uses the same notation and conventions as the SciPy Rotation class. See the SciPy documentation and :py:meth:from_euler for more details.

See also

quaternion_to_euler: Low-level quaternion to Euler conversion function

as_matrix() → ndarray¶

Return the quaternion as a rotation matrix.

If the attitude represents the orientation of a body A relative to a frame B, then this method returns the matrix R_BA that transforms vectors from frame A to frame B. Specifically, for a vector v_A expressed in frame A, the corresponding vector in frame B is given by v_B = R_BA @ v_A.

The inverse transformation can be obtained by transposing this matrix: R_AB = R_BA.T.

Return type:: A 3x3 numpy array representing the DCM.

as_quat() → Quaternion¶

Return the same object - dummy method for API consistency.

Returns:: The same Quaternion instance.
Return type:: Quaternion

inv() → Quaternion¶

Return the inverse of the quaternion

Returns:: A new Quaternion instance representing the inverse rotation.
Return type:: Quaternion

kinematics( w: ndarray, baumgarte: float | None = None, ) → Quaternion¶

Return the time derivative of the quaternion given angular velocity w.

If the quaternion represents the attitude of a body B, then w_B should be the body relative angular velocity ω_B.

The derivative is computed using quaternion kinematics:: dq/dt = 0.5 * q ⊗ [0, ω]

where ⊗ is the quaternion multiplication operator.

The method optionally support Baumgarte stabilization to preserve unit normalization. For a stabilization factor λ, the full time derivative is:

dq/dt = 0.5 * q ⊗ [0, ω] - λ * (||q||² - 1) * q

CAUTION: This method returns the time derivative of the attitude, which is represented with the same data structure for consistency with ODE solving - but this return is not itself a valid rotation representation until integrated in time. Hence, the output of kinematics should never be converted to a different attitude representation or rotation matrix.

Parameters:

w (array_like, shape (3,)) – Angular velocity vector in the body frame.
baumgarte (float, optional) – Baumgarte stabilization factor. If > 0, Baumgarte stabilization is applied to enforce unit norm constraint. Default is 0 (no stabilization).

Returns:

The time derivative represented as a Quaternion instance.

Return type:

Quaternion

mul( other: Quaternion, normalize: bool = False, ) → Quaternion¶: Compose (multiply) this quaternion with another

normalize() → Quaternion¶: Return a normalized version of this quaternion.

replace(**updates) → T¶: Returns a new object replacing the specified fields with new values.