Quaternion ¶

Quaternion(mat, *, copy=True)

Bases: Rotation

Quaternion representation of rotations (unit, xyzw convention).

This subclass of Rotation stores each rotation as a 4D unit quaternion, and implements all core operations (compose, inverse, apply) via matrix conversion when needed.

Internal shape: (..., 4)

Initialize an ItemsArray from any array-like input.

The input must be broadcastable to the expected item shape defined by the subclass via _item_shape. Typical examples include arrays of vectors, matrices, or quaternions.

Parameters:

Name	Type	Description	Default
`mat`	`array_like`	Input data to be wrapped. Must be broadcastable to shape (..., *_item_shape). For example, if `_item_shape = (3,)`, acceptable inputs include: - [1, 2, 3] → broadcasted to shape (1, 3) - [[1, 2, 3], [4, 5, 6]] → shape (2, 3) - np.ones((10, 1, 3)) → shape (10, 1, 3)	required
`copy`	`bool`	If True, the input is copied. If False, a view is kept (when safe), which avoids unnecessary allocations.	`True`

Raises:

Type	Description
`ValueError`	If the input is not broadcastable to the required item shape.

shape `property` ¶

shape

Batch shape (everything except the final item_shape).

size `property` ¶

size

Number of individual items.

invert ¶

__invert__()

Operator overload: return the inverse of the rotation (~R).

Equivalent to R.inverse(). Subclasses can override inverse() to customize this behavior.

matmul ¶

__matmul__(other)

Overload @ for rotations.

R @ S where both are Rotation → composition (apply R, puis S).
R @ v where v has shape (..., 3) → applique la rotation.

Parameters:

Name	Type	Description	Default
`other`	`Rotation or array_like(..., 3)`		required

Returns:

Type	Description
`Rotation or ndarray`

angle_to ¶

angle_to(other, degrees=False)

Compute the angular distance between this quaternion and another rotation.

Parameters:

Name	Type	Description	Default
`other`	`Rotation`	Another rotation (can be any subclass of Rotation).	required
`degrees`	`bool`	If True, returns the angle in degrees.	`False`

Returns:

Type	Description
`ndarray`	Rotation angle(s) needed to go from self to other, shape (...,).

apply ¶

apply(vectors)

Apply the quaternion rotation to 3D vectors.

Parameters:

Name	Type	Description	Default
`vectors`	`array_like(..., 3)`	Vectors to rotate. Must be broadcastable with the rotation batch shape.	required

Returns:

Type	Description
`ndarray`	Rotated vectors, same shape as input.

Notes

Uses the formula:
v_rot = q ⋅ v ⋅ q⁻¹
where v is a pure quaternion with w=0.

Broadcasting is supported across batch dimensions.

as_array ¶

as_array(dtype=None)

View on the internal array (no copy).

as_axis_angle ¶

as_axis_angle(tol=1e-06, degrees=False)

Convert each quaternion to an axis–angle pair.

Parameters:

Name	Type	Description	Default
`tol`	`float`	Numerical tolerance: angles below this are treated as zero.	`1e-6`
`degrees`	`bool`	If True, angles are returned in degrees instead of radians.	`False`

Returns:

Name	Type	Description
`axis`	`ndarray(..., 3)`	Unit rotation axes.
`angle`	`ndarray(...)`	Rotation angles.

Notes

Quaternions must be normalized.
For angles close to zero, axis is set arbitrarily to [1, 0, 0].

as_euler ¶

as_euler(order='XYZ', degrees=False)

Convert each quaternion to Euler/Tait–Bryan angles.

Parameters:

Name	Type	Description	Default
`order`	`(XYZ, XZY, YXZ, YZX, ZXY, ZYX)`	Axis order used for the decomposition (uppercase = intrinsic/body-fixed).	`'XYZ'`
`degrees`	`bool`	If True, angles are returned in degrees instead of radians.	`False`

Returns:

Type	Description
`ndarray`	Euler angles of shape (..., 3), in the specified order.

as_matrix ¶

as_matrix()

Convert each quaternion to a 3×3 rotation matrix.

as_quaternion ¶

as_quaternion()

Return the raw quaternion array (xyzw, shape (..., 4)).

broadcast_to ¶

broadcast_to(shape)

Broadcast the array to a new batch shape.

This is equivalent to np.broadcast_to(...), preserving the item shape. No copy is made.

Parameters:

Name	Type	Description	Default
`shape`	`tuple of int`	New shape for the batch dimensions.	required

Returns:

Type	Description
`ItemsArray`	A new view with broadcasted shape.

compose ¶

compose(other)

Compose this quaternion with another rotation (self ∘ other).

Internally performs a Hamilton product: self @ other.as_quaternion()

Parameters:

Name	Type	Description	Default
`other`	`Rotation`	The second rotation to apply (any type: matrix, quaternion, ...).	required

Returns:

Type	Description
`Quaternion`	Composed rotation, of the same type as `self`.

filter ¶

filter(mask, in_place=False)

Filter transformations using a boolean mask.

Parameters:

Name	Type	Description	Default
`mask`	`array_like(...)`	Boolean mask matching the shape of the batch.	required
`in_place`	`bool`	If True, modifies the current instance. Otherwise, returns a new one.	`False`

Returns:

Type	Description
`ItemsArray`	Filtered array (or self if in_place is True).

from_axis_angle `classmethod` ¶

from_axis_angle(axis, angle, *, normalize_axis=True, degrees=False)

Construct a Quaternion from an axis–angle pair.

Parameters:

Name	Type	Description	Default
`axis`	`array_like(..., 3)`	Rotation axis (x, y, z). Does not need to be unit length if `normalize_axis=True`.	required
`angle`	`array_like(...)`	Rotation angle (radians by default), broadcastable with `axis`.	required
`normalize_axis`	`bool`	Normalise the axis to unit length before conversion.	`True`
`degrees`	`bool`	Interpret `angle` in degrees instead of radians.	`False`

Returns:

Type	Description
`Quaternion`	Quaternion representing the given axis–angle rotation.

from_euler `classmethod` ¶

from_euler(euler, *, order='XYZ', degrees=False)

Construct a Quaternion from Euler angles.

Parameters:

Name	Type	Description	Default
`euler`	`array_like(..., 3)`	Angles for the three axes, in the order specified by `order`.	required
`order`	`(XYZ, XZY, YXZ, YZX, ZXY, ZYX)`	Axis order (uppercase = intrinsic / body‑fixed convention).	`'XYZ'`
`degrees`	`bool`	If True, `euler` is interpreted in degrees instead of radians.	`False`

Returns:

Type	Description
`Quaternion`	Quaternion representing the composed rotation.

from_euler_OLD `classmethod` ¶

from_euler_OLD(euler, *, order='XYZ', degrees=False)

Construct a rotation from Euler/Tait‑Bryan angles.

Parameters:

Name	Type	Description	Default
`euler`	`array_like(..., 3)`	Angles for the three axes, in the order specified by `order`.	required
`order`	`(XYZ, XZY, YXZ, YZX, ZXY, ZYX)`	Axis order (uppercase = intrinsic / body‑fixed convention).	`'XYZ'`
`degrees`	`bool`	Interpret `euler` in degrees instead of radians.	`False`

Returns:

Type	Description
`Rotation`	Rotation instance representing the Euler angles.

Raises:

Type	Description
`ValueError`	If `order` is not one of the supported axis permutations.

Notes

• Uses the right‑hand rule for each elemental rotation.
• Broadcasting works: euler can have any leading batch shape.

from_euler_OLD2 `classmethod` ¶

from_euler_OLD2(euler, *, order='XYZ', degrees=False)

Construct a rotation from Euler angles using intrinsic XYZ order.

from_matrix `classmethod` ¶

from_matrix(mat, *, normalize=True)

Construct a Quaternion from rotation matrices.

Parameters:

Name	Type	Description	Default
`mat`	`array_like(..., 3, 3)`	Input rotation matrices.	required
`normalize`	`bool`	If True, output quaternions are normalized.	`True`

Returns:

Type	Description
`Quaternion`

from_quaternion `classmethod` ¶

from_quaternion(quat, *, normalize=True, tol=1e-05)

Construct a Quaternion from raw (x y z w) values.

Parameters:

Name	Type	Description	Default
`quat`	`array_like(..., 4)`	Input quaternions in (x, y, z, w) order. Must be broadcastable.	required
`normalize`	`bool`	If True, the input is renormalised to unit length.	`True`
`tol`	`float`	Tolerance for the norm check when `normalize=False`.	`1e-5`

Returns:

Type	Description
`Quaternion`	Instance storing the (possibly normalised) quaternions.

Raises:

Type	Description
`ValueError`	If shape is wrong or quaternions are not unit (when normalize=False).

from_quaternion_MAUVAISE_CONVENTION `classmethod` ¶

from_quaternion_MAUVAISE_CONVENTION(quat, *, normalize=True, tol=1e-05)

Construct a Rotation from unit quaternions (xyzw convention).

Parameters:

Name	Type	Description	Default
`quat`	`array_like(..., 4)`	Input quaternions in (x, y, z, w) order. Must be broadcastable.	required
`normalize`	`bool`	If True, normalizes the input quaternions to unit norm.	`True`
`tol`	`float`	Tolerance used to check if quaternions are close to unit length (if normalize=False).	`1e-5`

Returns:

Type	Description
`Rotation`	Rotation instance representing the quaternions.

Raises:

Type	Description
`ValueError`	If input shape is invalid or quaternions are not unit (when normalize=False).

from_vectors `staticmethod` ¶

from_vectors(v_src, v_dst, normalized=False)

Constructs a rotation (as a quaternion) that rotates v_src onto v_dst.

Parameters:

Name	Type	Description	Default
`v_src`	`(array_like, shape(..., 3))`	Source vectors.	required
`v_dst`	`(array_like, shape(..., 3))`	Target vectors.	required

Returns:

Type	Description
`Rotation`	Rotation that aligns v_src with v_dst.

identity `classmethod` ¶

identity(shape=())

Return the identity quaternion (no rotation).

interpolate ¶

interpolate(other, t)

Performs spherical linear interpolation (SLERP) between two rotations.

Parameters:

Name	Type	Description	Default
`other`	`Rotation`	The target rotation to interpolate to.	required
`t`	`float or ndarray`	Interpolation parameter(s), where 0 gives self and 1 gives other. Supports broadcasting over batch dimensions.	required

Returns:

Type	Description
`Quaternion`	Interpolated rotations as quaternions.

inverse ¶

inverse()

Return the inverse (conjugate) of the unit quaternion.

is_identity ¶

is_identity(tol=1e-06)

Test whether each quaternion is (numerically) the identity rotation.

Parameters:

Name	Type	Description	Default
`tol`	`float`	Tolerance on the angular deviation from identity.	`1e-6`

Returns:

Type	Description
`bool or ndarray`	• If the quaternion is scalar (no batch), returns a single bool. • Otherwise, returns a boolean array with the same batch shape.

look_at `staticmethod` ¶

look_at(v_src, v_dst, up=None, upward=(0, 0, 1), normalized=False)

Build a Rotation that aligns the local frame (v_src, up) to (v_dst, upward), preserving right-handedness.

If up is None, only the forward direction is used (i.e. v_src → v_dst), and roll is undefined. The returned rotation minimizes the angular difference.

Parameters:

Name	Type	Description	Default
`v_src`	`(array_like, shape(..., 3))`	Source forward vector(s).	required
`v_dst`	`(array_like, shape(..., 3))`	Target forward vector(s).	required
`up`	`(array_like, shape(..., 3))`	Up vector(s) in the source frame. If None, only direction is used.	`None`
`upward`	`(array_like, shape(..., 3))`	Up vector(s) in the destination frame.	`(0, 0, 1)`
`normalized`	`bool`	If True, assume v_src and v_dst are already unit vectors.	`False`

Returns:

Type	Description
`Rotation`	Rotation matrix (3×3 or batch of matrices) aligning v_src to v_dst.

look_at_OLD `staticmethod` ¶

look_at_OLD(v_src, v_dst, up=None, upward=(0, 0, 1), normalized=False)

Build a Rotation that aligns the local frame (v_src, up) to (v_dst, upward), preserving right-handedness.

If up is None, only the forward direction is used (i.e. v_src → v_dst), and roll is undefined. The returned rotation minimizes the angular difference.

Parameters:

Name	Type	Description	Default
`v_src`	`(array_like, shape(..., 3))`	Source forward vector(s).	required
`v_dst`	`(array_like, shape(..., 3))`	Target forward vector(s).	required
`up`	`(array_like, shape(..., 3))`	Up vector(s) in the source frame. If None, only direction is used.	`None`
`upward`	`(array_like, shape(..., 3))`	Up vector(s) in the destination frame.	`(0, 0, 1)`
`normalized`	`bool`	If True, assume v_src and v_dst are already unit vectors.	`False`

Returns:

Type	Description
`Rotation`	Rotation matrix (3×3 or batch of matrices) aligning v_src to v_dst.

reshape ¶

reshape(*new_shape)

Reshape the batch dimensions of the array, preserving the item shape.

The total number of items must remain unchanged. This is equivalent to np.reshape() on the batch dimensions only, i.e., the trailing _item_shape is preserved.

Parameters:

Name	Type	Description	Default
`*new_shape`	`int`	New shape for the batch. Must satisfy `np.prod(new_shape) == self.size`.	`()`

Returns:

Type	Description
`ItemsArray`	A new reshaped view of the same data (no copy).

Raises:

Type	Description
`ValueError`	If the total number of items does not match.

resize ¶

resize(*new_shape, fill=0.0)

Resize the batch to a new shape, preserving item shape.

If the total number of items remains unchanged, the underlying array is simply reshaped (no allocation). Otherwise, a new array is created and filled with the given value. Existing data is preserved as much as possible (copied in row-major order).

Parameters:

Name	Type	Description	Default
`*new_shape`	`int`	New shape for the batch (excluding the item shape). Can increase or decrease the number of items.	`()`
`fill`	`float`	Value used to initialize new items when the array is enlarged.	`0.0`

Returns:

Type	Description
`ItemsArray`	The current instance (resized in place).

wxyz_to_xyzw `staticmethod` ¶

wxyz_to_xyzw(array, normalize=True)

Convert quaternions from (w, x, y, z) to (x, y, z, w) order.

Parameters:

Name	Type	Description	Default
`array`	`(array_like, shape(..., 4))`	Input array of quaternions in (w, x, y, z) order.	required
`normalize`	`bool`	If True, normalize the quaternion(s) to unit length.	`True`

Returns:

Type	Description
`(ndarray, shape(..., 4))`	Array of quaternions in (x, y, z, w) order.
> *Caution:* This does not construct a `Quaternion` object,
`it only reorders the array.`

xyzw_to_wxyz `staticmethod` ¶

xyzw_to_wxyz(array)

Convert quaternions from (x, y, z, w) to (w, x, y, z) order.

Parameters:

Name	Type	Description	Default
`array`	`(array_like, shape(..., 4))`	Input array of quaternions in (x, y, z, w) order.	required

Returns:

Type	Description
`(ndarray, shape(..., 4))`	Array of quaternions in (w, x, y, z) order.
`> *Note:* This does not normalize the quaternion(s).`

Quaternion ¶

shape property ¶

size property ¶

__invert__ ¶

__matmul__ ¶

angle_to ¶

apply ¶

as_array ¶

as_axis_angle ¶

as_euler ¶

as_matrix ¶

as_quaternion ¶

broadcast_to ¶

compose ¶

filter ¶

from_axis_angle classmethod ¶

from_euler classmethod ¶

from_euler_OLD classmethod ¶

from_euler_OLD2 classmethod ¶

from_matrix classmethod ¶

from_quaternion classmethod ¶

from_quaternion_MAUVAISE_CONVENTION classmethod ¶

from_vectors staticmethod ¶

identity classmethod ¶

interpolate ¶

inverse ¶

is_identity ¶

look_at staticmethod ¶

look_at_OLD staticmethod ¶

reshape ¶

resize ¶

wxyz_to_xyzw staticmethod ¶

xyzw_to_wxyz staticmethod ¶

shape `property` ¶

size `property` ¶

invert ¶

matmul ¶

from_axis_angle `classmethod` ¶

from_euler `classmethod` ¶

from_euler_OLD `classmethod` ¶

from_euler_OLD2 `classmethod` ¶

from_matrix `classmethod` ¶

from_quaternion `classmethod` ¶

from_quaternion_MAUVAISE_CONVENTION `classmethod` ¶

from_vectors `staticmethod` ¶

identity `classmethod` ¶

look_at `staticmethod` ¶

look_at_OLD `staticmethod` ¶

wxyz_to_xyzw `staticmethod` ¶

xyzw_to_wxyz `staticmethod` ¶