Utilities

Convenience functions, serialization, and quaternion interop

class Pose

A user-friendly wrapper around Transform for pose representation.

Represents the pose of 'child_frame_id' relative to 'frame_id'.

Properties
position
The 3D position [x, y, z] in the parent frame.
orientation
The orientation as a unit quaternion.

Constructors

Pose.__init__
__init__( self, position: np.ndarray | list | tuple | None = None, orientation: quaternion | np.ndarray | list | tuple | None = None, frame_id: str | int | UUID | None = None, child_frame_id: str | int | UUID | None = None )
classmethod Pose.from_transform
from_transform( cls, tf: Transform, frame_id: str | int | UUID | None = None, child_frame_id: str | int | UUID | None = None ) -> Pose

Creates a Pose from a Transform.

Methods

Pose.as_transform
as_transform(self) -> Transform

Returns the underlying Transform object.

Pose.inverse
inverse( self, new_frame_id: str | int | UUID | None = None, new_child_frame_id: str | int | UUID | None = None ) -> Pose

Returns the inverse pose.

By default, swaps frame_id and child_frame_id:

Inverse(T_A->B) = T_B->A

Pose.compose
compose(self, other)

Returns self * other

Pose.to_list
to_list(self) -> list[float]

Returns [px, py, pz, qw, qx, qy, qz]

Pose.to_matrix
to_matrix(self) -> np.ndarray

Return the 4x4 homogeneous transformation matrix.

Module Functions

from_roll_pitch_yaw
from_roll_pitch_yaw( roll: float = 0.0, pitch: float = 0.0, yaw: float = 0.0 ) -> quaternion

Create a quaternion from roll-pitch-yaw angles.

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

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

For other conventions (ZYZ, XYZ, etc.), use scipy directly::

from scipy.spatial.transform import Rotation as R

q_scipy = R.from_euler('ZYZ', [alpha, beta, gamma])

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

quaternion.quaternion: The resulting quaternion.

Warning

This function uses `scipy.spatial.transform.Rotation with true ZYX intrinsic ordering. It is **not** compatible with quaternion.from_euler_angles(alpha, beta, gamma)`, which uses ZYZ convention.

as_roll_pitch_yaw
as_roll_pitch_yaw(q: quaternion) -> tuple[float, float, float]

Extract roll, pitch, yaw from a quaternion.

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

For other conventions (ZYZ, XYZ, etc.), use scipy directly::

from scipy.spatial.transform import Rotation as R

angles = R.from_quat([q.x, q.y, q.z, q.w]).as_euler('ZYZ')

Parameters
q
The input quaternion.
Returns

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

register_transform
register_transform( cls: type[BaseTransform] ) -> type[BaseTransform]

Decorator to register a transform class for serialization.

Usage:

@register_transform

class MyTransform(BaseTransform):

...

serialize_transform
serialize_transform(transform: BaseTransform) -> dict[str, Any]

Serialize any transform to a JSON-compatible dictionary.

Parameters
transform
Any BaseTransform subclass instance.
Returns

Dict containing the serialized transform with a "type" key.

deserialize_transform
deserialize_transform(data: dict[str, Any]) -> BaseTransform

Deserialize a transform from a dictionary.

Automatically determines the correct class from the "type" field

and calls its from_dict() method.

Parameters
data
Dictionary previously created by serialize_transform() or to_dict().
Returns

BaseTransform: The deserialized transform instance.

Raises
transform_points
transform_points( points: np.ndarray, transform_object: BaseTransform | TransformGraph, source_frame: str | None = None, target_frame: str | None = None ) -> np.ndarray

Applies a transformation to a set of 3D points.

Supports polymorphic second argument:

1. transform_points(points, transform)

Directly applies a transform object.

2. transform_points(points, graph, source_frame, target_frame)

Uses the graph to find the transform from source to target.

If target is a projection frame (e.g. image), returns unnormalized 3D

coordinates [u*z, v*z, z].

Parameters
points
Nx3 points array.
transform_object
BaseTransform object OR TransformGraph.
source_frame
Source frame ID (required if using graph).
target_frame
Target frame ID (required if using graph).
Returns

np.ndarray: Nx3 array of transformed points.

project_points
project_points( points: np.ndarray, transform_object: BaseTransform | TransformGraph, source_frame: str | None = None, target_frame: str | None = None ) -> np.ndarray

Projects 3D points to 2D coordinates (homogenized).

Signatures:

1. project_points(points, projection_transform)

2. project_points(points, graph, source_frame, target_frame)

Returns

np.ndarray: Nx2 array of pixel coordinates [u, v].