Transforms

SE(3) rigid body transformations — 3D → 3D

class BaseTransform abstract

Abstract interface for all spatial transformations.

Constructors

classmethod BaseTransform.from_dict
from_dict(cls, data: dict[str, Any]) -> BaseTransform

Deserialize a transform from a dictionary.

Parameters
data
Dictionary previously created by to_dict().
Returns

BaseTransform: The deserialized transform instance.

Methods

BaseTransform.as_matrix
as_matrix() -> np.ndarray

Returns the 4x4 homogeneous representation of the transform.

Returns

np.ndarray: 4x4 matrix of the transform's dtype.

BaseTransform.inverse
inverse() -> BaseTransform

Returns the mathematical inverse of the transformation.

Returns

BaseTransform: The inverse transformation.

BaseTransform.to_dict
to_dict(self) -> dict[str, Any]

Serialize the transform to a JSON-compatible dictionary.

The dictionary MUST include a "type" key with the class name

to enable proper deserialization.

Returns

Dict[str, Any]: JSON-compatible dictionary representation.

class Transform(BaseTransform)

Standard SE(3) rigid body transformation. Consists of a translation (3x1) and a rotation (quaternion).

Constructors

Transform.__init__
__init__( self, translation: np.ndarray | list | tuple | None = None, rotation: quaternion | np.ndarray | list | tuple | Transform | None = None, dtype: np.dtype = <class 'np.float64'> )
classmethod Transform.from_matrix
from_matrix( cls, matrix: np.ndarray, dtype: np.dtype | None = None ) -> Transform

Creates a Transform from a 4x4 matrix.

classmethod Transform.from_rotation_matrix
from_rotation_matrix( cls, rotation_matrix: np.ndarray, t: np.ndarray | list | tuple | None = None, *, validate: bool = True, dtype: np.dtype = <class 'np.float64'> ) -> Transform

Create a Transform from a 3x3 rotation matrix.

Parameters
rotation_matrix
A 3x3 rotation matrix (must be SO(3) when `validate=True`).
t
Optional 3-element translation vector.
validate
If True (default), verify that `rotation_matrix is a valid SO(3) element (orthogonal with determinant +1). Set to False to skip the check on trusted data. Follows the same pattern as scipy.spatial.transform.Rotation.from_matrix with assume_valid`.
dtype
NumPy dtype for the resulting transform.
Returns

Transform: The constructed SE(3) transform.

Raises
Example

>>> R = np.eye(3) >>> tf.Transform.from_rotation_matrix(R, t=[1, 2, 3])

classmethod Transform.from_quaternion
from_quaternion( cls, q: quaternion | np.ndarray | list | tuple, t: np.ndarray | list | tuple | None = None, *, convention: str = 'wxyz', dtype: np.dtype = <class 'np.float64'> ) -> Transform

Create a Transform from a quaternion.

The quaternion is auto-normalized to unit length.

Parameters
q
Quaternion — either a `quaternion.quaternion object or a 4-element array. The element order is determined by convention`.
t
Optional 3-element translation vector.
convention
Element ordering of array input: `"wxyz" (default, numpy-quaternion / Hamilton) or "xyzw" (scipy / ROS). Ignored when q is a quaternion.quaternion` object.
dtype
NumPy dtype for the resulting transform.
Returns

Transform: The constructed SE(3) transform.

Raises
Example

>>> tf.Transform.from_quaternion([1, 0, 0, 0]) # wxyz identity >>> tf.Transform.from_quaternion([0, 0, 0, 1], convention="xyzw")

classmethod Transform.from_axis_angle
from_axis_angle( cls, axis: np.ndarray | list | tuple, angle: float, t: np.ndarray | list | tuple | None = None, *, dtype: np.dtype = <class 'np.float64'> ) -> Transform

Create a Transform from an axis-angle representation.

The axis is auto-normalized to unit length.

Parameters
axis
3-element rotation axis (will be normalized).
angle
Rotation angle in radians.
t
Optional 3-element translation vector.
dtype
NumPy dtype for the resulting transform.
Returns

Transform: The constructed SE(3) transform.

Raises
Example

>>> tf.Transform.from_axis_angle([0, 0, 1], np.pi / 2)

classmethod Transform.from_dict
from_dict(cls, data: dict[str, Any]) -> Transform

Deserialize transform from a dictionary.

Methods

Transform.as_matrix
as_matrix(self) -> np.ndarray

Return the 4x4 homogeneous transformation matrix [R|t; 0 1].

Transform.inverse
inverse(self) -> Transform

Return the inverse SE(3) transform: T^-1 = [-R^T t; R^T].

Transform.to_dict
to_dict(self) -> dict[str, Any]

Serialize transform to a JSON-compatible dictionary.

class Translation(Transform) extends Transform

A Transform with only translation (Identity rotation).

Inherits all methods from Transform.

class Rotation(Transform)

A Transform with only rotation (Zero translation).

Supports multiple construction patterns:

- Quaternion components: Rotation(w=1, x=0, y=0, z=0)

- Quaternion object: Rotation(rotation=q)

- Euler angles: Rotation.from_roll_pitch_yaw(roll=0, pitch=0, yaw=0)

...

Constructors

Rotation.__init__
__init__( self, w: float = 1.0, x: float = 0.0, y: float = 0.0, z: float = 0.0, rotation: quaternion | np.ndarray | list | tuple | None = None )
classmethod Rotation.from_roll_pitch_yaw
from_roll_pitch_yaw( cls, roll: float = 0.0, pitch: float = 0.0, yaw: float = 0.0 ) -> Rotation

Create a Rotation from roll-pitch-yaw angles.

Uses the aerospace/robotics intrinsic **ZYX** (Tait-Bryan) convention:

yaw (Z) → pitch (Y) → roll (X).

Parameters
roll
Rotation about X-axis in radians.
pitch
Rotation about Y-axis in radians.
yaw
Rotation about Z-axis in radians.
Returns

Rotation: A rotation-only transform.

Example

>>> attitude = tf.Rotation.from_roll_pitch_yaw(pitch=np.radians(10)) >>> heading = tf.Rotation.from_roll_pitch_yaw(yaw=np.pi/4)

classmethod Rotation.from_rotation_matrix
from_rotation_matrix( cls, rotation_matrix: np.ndarray, *, validate: bool = True ) -> Rotation

Create a Rotation from a 3x3 rotation matrix.

See :meth:Transform.from_rotation_matrix for full documentation.

Parameters
rotation_matrix
A 3x3 rotation matrix.
validate
If True, verify SO(3) membership.
Returns

Rotation: A rotation-only transform.

classmethod Rotation.from_quaternion
from_quaternion( cls, q: quaternion | np.ndarray | list | tuple, *, convention: str = 'wxyz' ) -> Rotation

Create a Rotation from a quaternion.

See :meth:Transform.from_quaternion for full documentation.

Parameters
q
Quaternion (object or 4-element array).
convention
`"wxyz" or "xyzw"`.
Returns

Rotation: A rotation-only transform.

classmethod Rotation.from_axis_angle
from_axis_angle( cls, axis: np.ndarray | list | tuple, angle: float ) -> Rotation

Create a Rotation from an axis-angle representation.

See :meth:Transform.from_axis_angle for full documentation.

Parameters
axis
3-element rotation axis (auto-normalized).
angle
Rotation angle in radians.
Returns

Rotation: A rotation-only transform.

Methods

Rotation.as_roll_pitch_yaw
as_roll_pitch_yaw(self) -> tuple[float, float, float]

Extract roll, pitch, yaw from the rotation.

Uses the aerospace/robotics intrinsic **ZYX** (Tait-Bryan) convention.

Returns

Tuple[float, float, float]: `(roll, pitch, yaw)` in radians.

Warning

Euler angles have a singularity (gimbal lock) when pitch = ±90°.

Example

>>> rotation = tf.Rotation.from_roll_pitch_yaw(roll=0.1, pitch=0.2, yaw=0.3) >>> roll, pitch, yaw = rotation.as_roll_pitch_yaw()

class Identity(Transform) extends Transform

The identity transform (0 translation, identity rotation).

Inherits all methods from Transform.

class MatrixTransform(BaseTransform) extends BaseTransform

A generic transform held as a raw 4x4 matrix. Used when SE(3) structure is lost or not applicable.

Constructors

classmethod MatrixTransform.from_dict
from_dict(cls, data: dict[str, Any]) -> MatrixTransform

Deserialize transform from a dictionary.

Methods

MatrixTransform.as_matrix
as_matrix(self) -> np.ndarray

Return the stored 4x4 matrix.

MatrixTransform.inverse
inverse(self) -> MatrixTransform

Return the inverse via np.linalg.inv.

.. warning::

Uses raw `np.linalg.inv` for convenience. This method is intended

for quick inspection and non-critical paths. For near-singular or

ill-conditioned matrices, prefer decomposing back into structured

types (`Transform, Projection`) that have numerically stable

inverses.

MatrixTransform.to_dict
to_dict(self) -> dict[str, Any]

Serialize transform to a JSON-compatible dictionary.