Quaternion Class (Quat)

Quaternion provides a class and functions for manipulating quaternion objects.

The Quat class provides the following:

  • Convenient ways to deal with rotation representations (equatorial coordinates, matrix and quaternion) including initialization and transformation.

  • Methods to multiply and divide quaternions.

Additional convenience functions are provided for performance applications.

Copyright:

Smithsonian Astrophysical Observatory (2010)

Authors:
class Quaternion.Quaternion.Quat(attitude=None, transform=None, q=None, equatorial=None)[source]
property dec

Retrieve Dec term from equatorial system in degrees

dq(q2=None, **kwargs)[source]

Return a delta quaternion dq such that q2 = self * dq.

This works with any argument that instantiates a Quat object.

This method returns the delta quaternion which represents the transformation from the frame of this quaternion (self) to q2.

q = Quat(q1.transform @ q2.transform)

Example usage:

>>> q1 = Quat((20, 30, 0))
>>> q2 = Quat((20, 30.1, 1))
>>> dq = q1.dq(q2)
>>> dq.equatorial
array([  1.79974166e-15,   1.00000000e-01,   1.00000000e+00])
Param:

q2 Quat or array

q2 must have the same shape as self.

Returns:

Quat

Return type:

numpy array

property equatorial

Retrieve [RA, Dec, Roll]

Return type:

numpy array

classmethod from_attitude(att)[source]

Initial Quat from attitude(s)

This allows initialization from several possibilities that are less strict than the normal initializer: - Quat already (returns same) - Input that works with Quat already - Input that initializes a float ndarray which has shape[-1] == 3 or 4 - Input that initializes an object ndarray where each element inits Quat, e.g. a list of Quat

Parameters:
attQuaternion-like

Attitude(s)

Returns:
Quat

Attitude(s) as a Quat

inv()[source]

Invert the quaternion.

Returns:

inverted quaternion

Return type:

Quat

property pitch

Return quaternion pitch (same as -dec)

property q

Retrieve 4-vector of quaternion elements as [x, y, z, w] or N x 4-vector.

Return type:

numpy array

property ra

Retrieve RA term from equatorial system in degrees

property ra0

Return quaternion RA in the range -180 <= roll < 180.

property roll

Retrieve Roll term from equatorial system in degrees

property roll0

Return quaternion roll in the range -180 <= roll < 180.

rotate_about_vec(vec, alpha)[source]

Rotate self about a 3-vector

Parameters:

  • vec – 3-element array-like Single vector to rotate about

  • alpha – float Angle to rotate by in degrees

Returns:

Quat Rotated attitude

classmethod rotate_x_to_vec(vec, method='radec')[source]

Generate quaternion that rotates X-axis into vec.

The method parameter can take one of three values: “shortest”, “keep_z”, or “radec” (default). The “shortest” method takes the shortest path between the two vectors. The “radec” method does the transformation as the corresponding (RA, Dec, Roll=0) attitude. The “keep_z” method does a roll about X-axis (followed by the “shortest” path) such that the transformed Z-axis is in the original X-Z plane. In equations:

T: "shortest" quaternion taking X-axis to vec
Rx(theta): Rotation by theta about X-axis = [[1,0,0], [0,c,s], [0,-s,c]]
Z: Z-axis [0,0,1]
[T * Rx(theta) * Z]_y = 0
T[1,1] * sin(theta) + T[1,2]*cos(theta) = 0
theta = atan2(T[1,2], T[1,1])
Parameters:

  • vec – Input 3-vector

  • method – method for determining path (shortest|keep_z|radec)

Returns:

Quaternion object

property shape

The shape of the multi-quaternion.

For example, if the Quat is: - a single quaternion, then its shape is (). - a multi-quaternion with self.q.shape = (N, 4), then its shape is (N,)

Returns:

self.q.shape[:-1]

Return type:

tuple

property transform

Retrieve the value of the 3x3 rotation/transform matrix

Returns:

3x3 rotation/transform matrix

Return type:

numpy array

property yaw

Return quaternion yaw (same as ra0)

class Quaternion.Quaternion.QuatDescriptor(*, default=None, required=False, cls=None)[source]

Descriptor for an attribute that is a Quat.

Parameters:
defaultQuatLike, optional

Default value for the attribute. If not specified, the default for the attribute is None. If the intent is to default to a particular attitude, this must be a tuple such as (0, 0, 0, 1) or (0, 0, 0) or a Quat object. A list is not allowed.

requiredbool, optional

If True, the attribute is required to be set explicitly when the object is created. If False the default value is used if the attribute is not set.

Examples

>>> from dataclasses import dataclass
>>> from Quaternion import Quat, QuatDescriptor
>>> @dataclass
... class MyClass:
...     att1: Quat = QuatDescriptor(required=True)
...     att2: Quat = QuatDescriptor(default=(10, 20, 30))
...     att3: Quat | None = QuatDescriptor()
...
>>> obj = MyClass(att1=[0, 0, 0, 1])
>>> obj.att1
<Quat q1=0.00000000 q2=0.00000000 q3=0.00000000 q4=1.00000000>
>>> obj.att2.equatorial
array([10., 20., 30.])
>>> obj.att3 is None
True
>>> obj.att3 = [10, 20, 30]
>>> obj.att3.equatorial
array([10., 20., 30.])
cls

alias of Quat

Quaternion.Quaternion.normalize(array)[source]

Normalize a 4 (or Nx4) element list or np.array for use as a quaternion.

This replaces any [0, 0, 0, 0] values with [0, 0, 0, 1].

Parameters:

array – 4 or Nx4 element list/array

Returns:

normalized array

Return type:

numpy array

Quaternion.Quaternion.quat_mult(q1, q2)[source]

Multiply two quaternions q1 * q2.

This is a fast numba-compiled version of the original code in the Quat class which is used for a single quaternion.

Parameters:
q1array-like

4-component quaternion

q2array-like

4-component quaternion

Returns:
q_outarray-like

4-component quaternion

Quaternion.Quaternion.quat_to_equatorial(q)[source]

Compute RA, dec, roll for the quaternion.

This is a fast numba-compiled version of the original code in the Quat class which is used for a single quaternion.

Parameters:
qarray-like

4-component quaternion

Returns:
rafloat

Right ascension in degrees

decfloat

Declination in degrees

rollfloat

Roll in degrees