Utilities Reference¶

Low-level Numba-accelerated quaternion functions.

quatham.utilities.normalise ¶

normalise(quat: NDArray) -> NDArray

Normalise a 4-element numpy array for use as a quaternion.

Handles both 1D (single quaternion) and 2D (multiple quaternions) arrays.

Parameters:

Name	Type	Description	Default
`quat`	`NDArray`	Array of shape (4,) or (N, 4) containing quaternion data.	required

Returns:

Type	Description
`NDArray`	Normalised quaternion array of the same shape as input.

quatham.utilities._axis_angle_to_quat ¶

_axis_angle_to_quat(
    vec: NDArray | list | tuple,
    theta: float | NDArray | list | tuple,
    degrees: bool = False,
) -> NDArray

Convert axis-angle representation to a quaternion.

Supports both single axis/angle inputs and batched arrays, including broadcasting.

Parameters:

Name	Type	Description	Default
`vec`	`NDArray or list or tuple`	Rotation axis as a 3-element vector or array of shape (N, 3). Will be normalised internally.	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
`NDArray`	Quaternion array of shape (4,) for single inputs or (N, 4) for batched inputs in scalar-first format [w, x, y, z].

quatham.utilities._quat_to_axis_angle ¶

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

Convert quaternion(s) to axis-angle representation.

Supports both single quaternion (shape (4,)) and batched quaternions (shape (N, 4)).

Parameters:

Name	Type	Description	Default
`q`	`NDArray or list or tuple`	Quaternion data of shape (4,) or (N, 4) in scalar-first format [w, x, y, z].	required
`degrees`	`bool`	If True, angles are returned in degrees; otherwise radians.	`False`

Returns:

Type	Description
`tuple`	(axis, theta) where axis is the normalized rotation axis (shape (3,) or (N, 3)) and theta is the rotation angle (float for single quaternion or shape (N,) for batched).

quatham.utilities._calc_rotation_mat ¶

_calc_rotation_mat(qarr: NDArray) -> NDArray

Compute (N, 3, 3) rotation matrices from (N, 4) quaternions [w, x, y, z].

Numba-jitted for best performance.

Parameters:

Name	Type	Description	Default
`qarr`	`NDArray(N, 9)`	Array of quaternions (scalar, x, y, z parts).	required

Returns:

Type	Description
`NDArray`	Array of shape (N, 9) containing rotation matrices in flat row-major order.

quatham.utilities._calc_euler_angles ¶

_calc_euler_angles(qarr: NDArray, seq: str) -> NDArray

Compute Euler angles from quaternion components (Numba-jitted).

Supports proper Euler angle sequences: xzx, xyx, yxy, yzy, zxz, zyz.

Parameters:

Name	Type	Description	Default
`qarr`	`NDArray`	Array of quaternions of shape (N, 4) in scalar-first format [w, x, y, z].	required
`seq`	`str`	Euler angle sequence (one of 'xzx', 'xyx', 'yxy', 'yzy', 'zxz', 'zyz').	required

Returns:

Type	Description
`NDArray`	Euler angles of shape (N, 3) containing [alpha, beta, gamma]. Returns NaN for invalid sequences.

quatham.utilities._calc_tait_bryan_angles ¶

_calc_tait_bryan_angles(
    qarr: NDArray, seq: str, intrinsic: bool = True
) -> NDArray

Compute Tait-Bryan angles from (N, 4) quaternions [w, x, y, z].

Numba-jitted for performance.

quatham.utilities._compose_quaternion_rotation ¶

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

Compose a quaternion from a sequence of rotations (Euler/Tait-Bryan angles).

Parameters:

Name	Type	Description	Default
`angles`	`NDArray`	Array of rotation angles of shape (N, len(seq)) or (len(seq),).	required
`seq`	`str`	Sequence of rotation axes.	`'xyz'`
`degrees`	`bool`	If True, input angles are in degrees; otherwise radians.	`False`
`intrinsic`	`bool`	If True, rotations are intrinsic (local axes); otherwise extrinsic (fixed axes).	`False`

Returns:

Type	Description
`NDArray`	Quaternion array of shape (N, 4) in scalar-first format.

quatham.utilities._quat_mult ¶

_quat_mult(p: ndarray, q: ndarray) -> ndarray

quatham.utilities._quat_div ¶

_quat_div(p: ndarray, q: ndarray) -> ndarray

quatham.utilities._spherical_coords_to_quat ¶

_spherical_coords_to_quat(
    theta: float | NDArray,
    phi: float | NDArray,
    degrees: bool = False,
) -> NDArray

Convert spherical coordinates to a quaternion.

Parameters:

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

Returns:

Type	Description
`NDArray`	Quaternion of shape (1, 4) in scalar-first format [w, x, y, z].