Rotation ¶

Rotation(mat, *, copy=True)

Bases: ItemsArray

Rotation represented as 3×3 matrices.

This class wraps batches of rotation matrices and provides methods for applying, composing and inverting them.

All rotations must have shape (..., 3, 3) and be valid rotation matrices.

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 two rotations.

Parameters:

Name	Type	Description	Default
`other`	`Rotation`	The other rotation(s) to compare with.	required
`degrees`	`bool`	If True, return angle in degrees instead of radians.	`False`

Returns:

Type	Description
`ndarray`	Angle(s) of shape `(...)`, same batch shape as self and other (broadcasted), representing the rotation needed to go from `self` to `other`.

Raises:

Type	Description
`TypeError`	If `other` is not a Rotation.

apply ¶

apply(vectors)

Apply the rotation to a set of 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.

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 rotation matrix to an axis–angle pair.

Parameters:

Name	Type	Description	Default
`tol`	`float`	Numerical tolerance to treat very small angles as zero.	`1e-6`
`degrees`	`bool`	If True, the returned angles are in degrees instead of radians.	`False`

Returns:

Name	Type	Description
`axis`	`ndarray(..., 3)`	Unit vectors representing the rotation axes.
`angle`	`ndarray(...)`	Rotation angles (same batch shape as `axis` without the last dimension).

Notes

• Uses the xyzw quaternion sign convention internally (but does not return quaternions).
• When the angle is below tol, the axis is arbitrarily set to [1, 0, 0]. • The function is batch‑compatible and produces a separate array for the angles so that both outputs can be used independently:

axis, theta = R.as_axis_angle()

as_euler ¶

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

Convert each rotation matrix to Euler angles (XYZ intrinsic order).

as_matrix ¶

as_matrix()

Return the underlying rotation matrices (view, no copy).

as_quaternion ¶

as_quaternion()

Convert each rotation matrix to a quaternion (xyzw convention).

Returns:

Type	Description
`Quaternion`	Quaternions of shape (..., 4), in (x, y, z, w) order.

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 rotation with another Rotation instance.

The resulting rotation applies self first, then other, i.e.:

composed = self ∘ other  ⇔  composed @ v == other @ (self @ v)

Parameters:

Name	Type	Description	Default
`other`	`Rotation`	The second rotation to compose. Must be a Rotation instance.	required

Returns:

Type	Description
`Rotation`	The composed rotation. A new object is always returned.

Raises:

Type	Description
`TypeError`	If `other` is not a Rotation instance.

Notes

• Fully supports broadcasting over batch dimensions. • This method is functionally equivalent to: self @ other.

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 rotation from an axis–angle pair.

Parameters:

Name	Type	Description	Default
`axis`	`array_like(..., 3)`	Rotation axis. Does not need to be unit length if `normalize_axis=True`.	required
`angle`	`array_like(...)`	Rotation angle, broadcastable to the batch shape of `axis`.	required
`normalize_axis`	`bool`	Normalise the axis to unit length before constructing the matrix.	`True`
`degrees`	`bool`	If True, `angle` is interpreted in degrees instead of radians.	`False`

Returns:

Type	Description
`Rotation`	Rotation instance representing the axis–angle pair.

Notes

• Uses the right‑hand rule.
• Supports arbitrary batch shapes; axis and angle are broadcast together.

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, *, validate=True, tol=1e-05)

Construct a Rotation from raw 3×3 matrices.

Parameters:

Name	Type	Description	Default
`mat`	`array_like(..., 3, 3)`	One or more candidate rotation matrices.	required
`validate`	`bool`	If True, checks that matrices are orthogonal and have determinant close to 1.	`True`
`tol`	`float`	Tolerance used for validation.	`1e-5`

Returns:

Type	Description
`Rotation`	New instance wrapping the validated (or unvalidated) matrices.

Raises:

Type	Description
`ValueError`	If validation is enabled and any matrix is not a proper rotation.

from_quaternion `classmethod` ¶

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

Construct a Rotation from unit quaternions (x, y, z, w 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.

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=(), dtype=None)

Create an identity rotation for the given batch shape.

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 rotation (i.e., transpose of the matrix).

Returns:

Type	Description
`Rotation`	Inverse of each rotation in the batch.

is_identity ¶

is_identity(tol=1e-06)

Test whether each rotation in the batch is (numerically) the identity.

Parameters:

Name	Type	Description	Default
`tol`	`float`	Maximum absolute deviation allowed from the exact identity matrix.	`1e-6`

Returns:

Type	Description
`bool or ndarray`	• If the rotation is scalar (batch shape == ()), returns a single bool. • Otherwise, returns a boolean array with the same batch shape, where each element indicates whether the corresponding matrix is close to identity within `tol`.

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).

Rotation ¶

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_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 ¶

shape `property` ¶

size `property` ¶

invert ¶

matmul ¶

from_axis_angle `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` ¶