Transformation

Transformation(mat, *, copy=True)

Bases: ItemsArray

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.

position property writable

position

Access the translation component (view, not copy).

rotation property writable

rotation

Return the pure rotation part of the matrix.

scale property writable

scale

Extract scale from transformation matrix (per axis).

shape property

shape

Batch shape (everything except the final item_shape).

size property

size

Number of individual items.

__invert__

__invert__()

Overload the ~ operator to return the inverse transformation.

__matmul__

__matmul__(other)

Overload the @ operator.

• Transformation @ Transformation → composition (self ∘ other) where the right operand is applied first, then self (column‑major convention).
• Transformation @ vectors → alias for :py:meth:transform.

apply

apply(vectors)

Apply the transformation(s) to 3D or 4D vectors.

Parameters:

Name	Type	Description	Default
vectors	array_like(..., 3) or (..., 4)	Input vectors. If shape[-1] == 3, a 1 is appended to enable homogeneous transformation. If already 4D, used as-is.	required

Returns:

Name	Type	Description
transformed	ndarray(..., 3 or 4)	Transformed vectors. Shape is the broadcast of self.shape and vectors.shape[:-1].

as_array

as_array(dtype=None)

View on the internal array (no copy).

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 classmethod

compose(*transforms)

Compose multiple transformations together (right to left).

Parameters:

Name	Type	Description	Default
*transforms	Transformation	Any number of Transformation objects to compose. Composition is performed as T1 @ T2 @ T3, meaning T3 is applied first.	()

Returns:

Type	Description
Transformation	The composed transformation.

decompose

decompose()

Return rotation, scale, translation from each 4x4 transform.

Returns:

Name	Type	Description
rot	Rotation	Rotation (orthonormal, no scale)
scale	ndarray(..., 3)	Scale vector along each axis
trans	ndarray(..., 3)	Translation vector

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_components classmethod

from_components(translation=None, rotation=None, scale=None)

Build a Transformation from translation, rotation, and scale.

Parameters:

Name	Type	Description	Default
translation	array_like(..., 3)	Translation vector(s). Default is [0, 0, 0].	None
rotation	None or array_like(..., 3, 3) or Rotation	Rotation matrix/matrices. If None, uses the identity.	None
scale	array_like(..., 3)	Per‑axis scale vector(s). Default is [1, 1, 1].	None

Notes

All three inputs are broadcasted together. The returned batch shape is the broadcasted shape of translation[...,0], scale[...,0], and rotation[...,0,0].

interpolate

interpolate(other, t)

Interpolate between two transformations A and B using factor t.

Parameters:

Name	Type	Description	Default
other	Transformation	The other transformation to interpolate with.	required
t	float or array_like(...)	Interpolation weight(s) in [0, 1]. Shape must be broadcastable.	required

Returns:

Type	Description
Transformation	Interpolated transformation(s).

inverse

inverse()

Return the inverse of the transformation(s).

Returns:

Type	Description
Transformation	A new Transformation representing the inverse.

is_identity

is_identity(eps=1e-05)

Return a boolean array indicating which matrices are identity.

Parameters:

Name	Type	Description	Default
eps	float	Tolerance for element-wise comparison. Default is global ZERO.	1e-05

Returns:

Name	Type	Description
mask	ndarray of bool, shape == self.shape	True where transformation is (approximately) the identity.

normalize_rotation

normalize_rotation(in_place=False)

Orthonormalize the rotation part of each matrix via SVD.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, modifies the current instance. Otherwise, returns a new one.	False

Returns:

Type	Description
Transformation	A Transformation with orthonormal rotation matrices.

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