Quaternion Class Reference¶

quatham.Quaternion.Quaternion ¶

Quaternion(value: NDArray | list | tuple | None = None)

Quaternion Class for handling quaternions and their transformations and translations.

Parameters:

Name	Type	Description	Default
`value`	`NDArray or list or tuple or None`	Quaternion data in scalar-first format [w, x, y, z]. Can be a single quaternion (shape (4,)) or multiple quaternions (shape (N, 4)). If None, creates an empty quaternion object.	`None`

Attributes:

Name	Type	Description
`scalar`	`NDArray`	The real (scalar) component w of the quaternion(s).
`vector`	`NDArray`	The imaginary (vector) component [x, y, z] of the quaternion(s).
`w`	`NDArray`	Alias for scalar component.
`x`	`NDArray`	x component of the vector part.
`y`	`NDArray`	y component of the vector part.
`z`	`NDArray`	z component of the vector part.
`num_quaternions`	`int or None`	Number of quaternions stored, or None if empty.
`conjugate`	`Quaternion`	The conjugate quaternion (scalar negated vector part).
`magnitude`	`NDArray`	Magnitude (norm) of each quaternion.

Examples:

Create a quaternion from a list::

q = Quaternion([1.0, 0.0, 0.0, 0.0])

Create from Euler angles::

q = Quaternion.from_euler([0.0, 0.0, np.pi/2], seq='z', degrees=False)

Get rotation matrix::

rot_mat = q.get_rotation_matrix()

scalar `property` ¶

scalar: NDArray

Return the real or scalar component of the quaternion object.

Returns:

Type	Description
`NDArray`	The scalar (w) component of the quaternion(s).

vector `property` ¶

vector: NDArray

Return the imaginary or vector component of the quaternion object.

Returns:

Type	Description
`NDArray`	A numpy array of shape (N, 3) containing [x, y, z] components. NOT guaranteed to be a unit vector.

w `instance-attribute` ¶

w = self.scalar

x `instance-attribute` ¶

x = self.ndarray[:, 1]

y `instance-attribute` ¶

y = self.ndarray[:, 2]

z `instance-attribute` ¶

z = self.ndarray[:, 3]

conjugate `property` ¶

conjugate: Self

Conjugate of quaternion.

The conjugate negates the vector part while keeping the scalar part unchanged.

Returns:

Type	Description
`Quaternion`	A new Quaternion object representing the conjugate.

magnitude `property` ¶

magnitude: NDArray

Magnitude (Euclidean norm) of the quaternion(s).

Returns:

Type	Description
`NDArray`	Array of magnitudes for each quaternion, or a scalar if single quaternion.

from_euler `classmethod` ¶

from_euler(
    angles: NDArray,
    seq: str = "xyz",
    degrees: bool = False,
    intrinsic: bool = False,
) -> Self

Create a quaternion from Euler angles.

Parameters:

Name	Type	Description	Default
`angles`	`NDArray`	Array of Euler angles.	required
`seq`	`str`	Sequence of axes for rotations (e.g., 'xyz', 'zxz', etc.).	`'xyz'`
`degrees`	`bool`	If True, angles are in degrees; otherwise radians.	`False`
`intrinsic`	`bool`	If True, rotations are intrinsic (local axes); otherwise extrinsic (fixed axes).	`False`

Returns:

Type	Description
`Quaternion`	A new Quaternion object.

from_axisangle `classmethod` ¶

from_axisangle(
    v: NDArray | list | tuple,
    theta: float | NDArray | list | tuple,
    degrees: bool = False,
) -> Self

Create a quaternion from an axis-angle representation.

Parameters:

Name	Type	Description	Default
`v`	`NDArray or list or tuple`	Rotation axis as a 3-element vector or array of shape (N, 3).	required
`theta`	`float or NDArray or list or tuple`	Rotation angle(s) around the axis.	required
`degrees`	`bool`	If True, theta is interpreted as degrees; otherwise radians.	`False`

Returns:

Type	Description
`Quaternion`	A new Quaternion object.

from_spherical `classmethod` ¶

from_spherical(
    theta: float, phi: float, degrees: bool = False
) -> Self

Create a quaternion from spherical coordinates.

Parameters:

Name	Type	Description	Default
`theta`	`float`	Polar angle (angle from z-axis).	required
`phi`	`float`	Azimuthal angle (angle in x-y plane from x-axis).	required
`degrees`	`bool`	If True, angles are in degrees; otherwise radians.	`False`

Returns:

Type	Description
`Quaternion`	A new Quaternion object.

normalise ¶

normalise() -> Self

Return a normalised (unit) quaternion.

Returns:

Type	Description
`Quaternion`	A new Quaternion object normalized to unit length.

normalize ¶

normalize() -> Self

Return a normalised (unit) quaternion (alias for normalise).

Returns:

Type	Description
`Quaternion`	A new Quaternion object normalized to unit length.

to_rotation_matrix ¶

to_rotation_matrix() -> NDArray

Convert quaternion to a 3x3 rotation matrix.

Returns:

Type	Description
`NDArray`	A 3x3 rotation matrix. For multiple quaternions, returns shape (N, 3, 3). Currently, returns a single 3x3 matrix for the first quaternion.

get_rotation_matrix_flat ¶

get_rotation_matrix_flat() -> NDArray

Convert quaternion to a flat 9-element rotation matrix array.

Returns:

Type	Description
`NDArray`	A flat array of shape (N, 9) containing rotation matrix elements. For a single quaternion, returns shape (9,).

to_axis_angle ¶

to_axis_angle(
    degrees: bool = False,
) -> tuple[NDArray, NDArray | float]

Convert quaternion to axis-angle representation.

Parameters:

Name	Type	Description	Default
`degrees`	`bool`	If True, returns angle(s) in degrees; otherwise radians.	`False`

Returns:

Type	Description
`tuple of (NDArray, NDArray or float)`	(axis, theta) where axis is the normalized rotation axis vector(s) of shape (3,) or (N, 3), and theta is the rotation angle(s) as a float or array of shape (N,).

get_rotation_vector ¶

get_rotation_vector() -> NDArray

Convert quaternion to rotation vector (axis * angle).

Returns:

Type	Description
`NDArray`	Rotation vector of shape (3,) for a single quaternion or (N, 3) for multiple quaternions, where each row is axis * angle.

to_euler ¶

to_euler(
    seq: str = "zxz",
    degrees: bool = False,
    intrinsic: bool = True,
) -> NDArray

Calculate Euler rotation angles from the quaternion.

Euler angles refer to sequences of rotations about 2 distinct axes. The supported sequences are: x-y-x, x-z-x, y-x-y, y-z-y, z-y-z, z-x-z.

Intrinsic refers to rotations about the local coordinate system, while extrinsic rotations are about the fixed global axes.

Parameters:

Name	Type	Description	Default
`seq`	`str`	The Euler angle sequence (one of 'xzx', 'xyx', 'yxy', 'yzy', 'zxz', 'zyz').	`'zxz'`
`degrees`	`bool`	If True, returns angles in degrees; otherwise radians.	`False`
`intrinsic`	`bool`	If True, uses intrinsic rotations; otherwise extrinsic.	`True`

Returns:

Type	Description
`NDArray`	Array of shape (N, 3) containing [alpha, beta, gamma] Euler angles.

Raises:

Type	Description
`ValueError`	If `seq` is not one of the supported sequences.

to_tait_bryan ¶

to_tait_bryan(
    seq: str = "xyz",
    degrees: bool = False,
    intrinsic: bool = True,
) -> NDArray

Calculate Tait-Bryan rotation angles from the quaternion.

Tait-Bryan angles (also called Cardan angles, nautical angles, or yaw-pitch-roll) refer to sequences of rotations about 3 distinct axes. The supported sequences are: x-y-z, y-z-x, z-x-y, x-z-y, z-y-x, y-x-z.

Intrinsic refers to rotations about the local coordinate system, while extrinsic rotations are about the fixed global axes.

Parameters:

Name	Type	Description	Default
`seq`	`str`	The Tait-Bryan angle sequence (one of 'xyz', 'yzx', 'zxy', 'xzy', 'zyx', 'yxz').	`'xyz'`
`degrees`	`bool`	If True, returns angles in degrees; otherwise radians.	`False`
`intrinsic`	`bool`	If True, uses intrinsic rotations; otherwise extrinsic.	`True`

Returns:

Type	Description
`NDArray`	Array of shape (N, 3) containing [alpha, beta, gamma] Tait-Bryan angles.

Raises:

Type	Description
`ValueError`	If `seq` is not one of the supported sequences.

to_yaw_pitch_roll ¶

to_yaw_pitch_roll(degrees: bool = False) -> NDArray

Get the intrinsic Tait-Bryan angles following the z-y-x convention (yaw-pitch-roll).

Parameters:

Name	Type	Description	Default
`degrees`	`bool`	If True, returns angles in degrees; otherwise radians.	`False`

Returns:

Type	Description
`NDArray`	Array of shape (N, 3) containing [yaw, pitch, roll] angles.

vector_norm ¶

vector_norm() -> NDArray | float

L2 norm of the vector component of the quaternion.

Returns:

Type	Description
`NDArray or float`	The norm of the vector (imaginary) part of each quaternion.

tolist ¶

tolist() -> list

Convert quaternion data to a Python list.

Returns:

Type	Description
`list`	List representation of the quaternion array.

add ¶

__add__(other: Self | NDArray | list | tuple) -> Self

Add another quaternion or array to this quaternion.

Parameters:

Name	Type	Description	Default
`other`	`Quaternion or array - like`	Quaternion or array of components to add.	required

Returns:

Type	Description
`Quaternion`	Sum of the quaternions.

radd ¶

__radd__(other: Self | NDArray | list | tuple) -> Self

Right addition for quaternion.

Parameters:

Name	Type	Description	Default
`other`	`Quaternion or array - like`	Quaternion or array of components to add.	required

Returns:

Type	Description
`Quaternion`	Sum of the quaternions.

sub ¶

__sub__(other: Self | NDArray | list | tuple) -> Self

Subtract another quaternion or array from this quaternion.

Parameters:

Name	Type	Description	Default
`other`	`Quaternion or array - like`	Quaternion or array of components to subtract.	required

Returns:

Type	Description
`Quaternion`	Difference of the quaternions.

rsub ¶

__rsub__(other: Self | NDArray | list | tuple) -> Self

Right subtraction for quaternion.

Parameters:

Name	Type	Description	Default
`other`	`Quaternion or array - like`	Quaternion or array of components to subtract from.	required

Returns:

Type	Description
`Quaternion`	Difference of the quaternions.

mul ¶

__mul__(
    other: Self | NDArray | list | tuple | float | int,
) -> Self | NDArray

Multiply quaternion by another quaternion, scalar, or rotate a vector.

Parameters:

Name	Type	Description	Default
`other`	`Quaternion or NDArray or list or tuple or float or int`	If Quaternion, performs quaternion multiplication. If float or int, performs scalar multiplication. If array-like of length 3, rotates the vector by this quaternion.	required

Returns:

Type	Description
`Quaternion or NDArray`	Result quaternion, scaled quaternion, or rotated vector.

Raises:

Type	Description
`TypeError or ValueError`	If other is an unknown type or vector has invalid length.

rmul ¶

__rmul__(other: float | int | number | NDArray) -> Self

Multiply a scalar by this quaternion (scalar * q).

Parameters:

Name	Type	Description	Default
`other`	`float or int or number or NDArray`	Scalar multiplier.	required

Returns:

Type	Description
`Quaternion`	Scaled quaternion.

truediv ¶

__truediv__(
    other: Self | float | int | number | NDArray,
) -> Self

Divide this quaternion by another quaternion or scalar.

Parameters:

Name	Type	Description	Default
`other`	`Quaternion or float or int or number or NDArray`	The divisor quaternion or scalar.	required

Returns:

Type	Description
`Quaternion`	Result of quaternion division.

Raises:

Type	Description
`TypeError or ValueError`	If other is not a Quaternion, scalar, or 4-element array.

rtruediv ¶

__rtruediv__(other: float | int | number) -> Self

Divide a scalar by this quaternion (scalar / q = scalar * q^-1).

Parameters:

Name	Type	Description	Default
`other`	`float or int or number`	Scalar numerator.	required

Returns:

Type	Description
`Quaternion`	Result of scalar division by quaternion.

neg ¶

__neg__() -> Self

Negate all components of the quaternion(s).

Returns:

Type	Description
`Quaternion`	Negated quaternion.

getitem ¶

__getitem__(item: int | slice) -> NDArray

Get item(s) from the quaternion array by index or slice.

Parameters:

Name	Type	Description	Default
`item`	`int or slice`	Index or slice to apply to the underlying quaternion array.	required

Returns:

Type	Description
`NDArray`	The selected quaternion data.

array ¶

__array__() -> NDArray

Convert the quaternion to a numpy array.

Returns:

Type	Description
`NDArray`	The quaternion data as a numpy array of shape (N, 4).

str ¶

__str__()

Return a string representation of the quaternion(s).

Returns:

Type	Description
`str`	Formatted string showing angle and axis for each quaternion.

repr ¶

__repr__()

Return a developer-friendly string representation.

Returns:

Type	Description
`str`	Array representation of the quaternion data.

Quaternion Class Reference¶

quatham.Quaternion.Quaternion ¶

scalar property ¶

vector property ¶

w instance-attribute ¶

x instance-attribute ¶

y instance-attribute ¶

z instance-attribute ¶

conjugate property ¶

magnitude property ¶

from_euler classmethod ¶

from_axisangle classmethod ¶

from_spherical classmethod ¶

normalise ¶

normalize ¶

to_rotation_matrix ¶

get_rotation_matrix_flat ¶

to_axis_angle ¶

get_rotation_vector ¶

to_euler ¶

to_tait_bryan ¶

to_yaw_pitch_roll ¶

vector_norm ¶

tolist ¶

__add__ ¶

__radd__ ¶

__sub__ ¶

__rsub__ ¶

__mul__ ¶

__rmul__ ¶

__truediv__ ¶

__rtruediv__ ¶

__neg__ ¶

__getitem__ ¶

__array__ ¶

__str__ ¶

__repr__ ¶

scalar `property` ¶

vector `property` ¶

w `instance-attribute` ¶

x `instance-attribute` ¶

y `instance-attribute` ¶

z `instance-attribute` ¶

conjugate `property` ¶

magnitude `property` ¶

from_euler `classmethod` ¶

from_axisangle `classmethod` ¶

from_spherical `classmethod` ¶

add ¶

radd ¶

sub ¶

rsub ¶

mul ¶

rmul ¶

truediv ¶

rtruediv ¶

neg ¶

getitem ¶

array ¶

str ¶

repr ¶