Pose and timing¶

Rigid transforms with explicit quaternion order and frame convention, plus deterministic time-grid resampling used by motion and pose sequences.

Pose types¶

Pose ¶

Bases: BaseModel

Rigid transform from a local frame into a named world convention.

Attributes:

Name	Type	Description
`translation`	`FloatArray`	World-frame origin offset, shape `(3,)`.
`quaternion`	`FloatArray`	Unit quaternion in `quaternion_order` layout, shape `(4,)`.
`quaternion_order`	`QuaternionOrder`	Storage order of `quaternion`.
`frame`	`FrameConvention`	World coordinate convention for `translation`.

Methods:

Name	Description
`identity`	Return an identity pose.
`quaternion_as`	Return the quaternion in the requested storage order.
`rotation`	Return this pose's rotation as a SciPy `Rotation`.
`matrix`	Return a 4x4 homogeneous transform matrix.
`inverse`	Return the inverse transform.
`transform_points`	Transform points of shape `(..., 3)` from local to world coordinates.
`inverse_transform_points`	Transform points of shape `(..., 3)` from world to local coordinates.
`to_frame`	Return this pose represented in another coordinate frame convention.
`scaled`	Return a copy with translation scaled and rotation preserved.

Attributes¶

model_config `class-attribute` `instance-attribute` ¶

model_config = ConfigDict(arbitrary_types_allowed=True)

translation `class-attribute` `instance-attribute` ¶

translation: FloatArray = Field(default_factory=lambda: zeros(3, dtype=float64))

quaternion `class-attribute` `instance-attribute` ¶

quaternion: FloatArray = Field(
    default_factory=lambda: array([1.0, 0.0, 0.0, 0.0], dtype=float64)
)

quaternion_order `class-attribute` `instance-attribute` ¶

quaternion_order: QuaternionOrder = WXYZ

frame `class-attribute` `instance-attribute` ¶

frame: FrameConvention = Z_UP_RIGHT_HANDED

Functions¶

identity `classmethod` ¶

identity(*, frame: FrameConvention = Z_UP_RIGHT_HANDED) -> Self

Return an identity pose.

Parameters:

Name	Type	Description	Default
`frame`	`FrameConvention`	World coordinate convention for the pose.	`Z_UP_RIGHT_HANDED`

Returns:

Name	Type	Description
`Pose`	`Self`	Identity transform with zero translation and unit rotation.

quaternion_as ¶

quaternion_as(order: QuaternionOrder) -> FloatArray

Return the quaternion in the requested storage order.

Parameters:

Name	Type	Description	Default
`order`	`QuaternionOrder`	Desired component layout.	required

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	Unit quaternion with shape `(4,)` in `order`.

rotation ¶

rotation() -> Rotation

Return this pose's rotation as a SciPy Rotation.

Returns:

Name	Type	Description
`Rotation`	`Rotation`	Orientation in SciPy's scalar-last `(x, y, z, w)` convention.

matrix ¶

matrix() -> FloatArray

Return a 4x4 homogeneous transform matrix.

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	`(4, 4)` matrix mapping local homogeneous coordinates to world.

inverse ¶

inverse() -> Pose

Return the inverse transform.

Returns:

Name	Type	Description
`Pose`	`Pose`	Transform that maps world coordinates back to the local frame.

transform_points ¶

transform_points(points: Any) -> FloatArray

Transform points of shape (..., 3) from local to world coordinates.

Parameters:

Name	Type	Description	Default
`points`	`Any`	Local-frame positions with trailing dimension 3.	required

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	World-frame positions with the same shape as `points`.

inverse_transform_points ¶

inverse_transform_points(points: Any) -> FloatArray

Transform points of shape (..., 3) from world to local coordinates.

Parameters:

Name	Type	Description	Default
`points`	`Any`	World-frame positions with trailing dimension 3.	required

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	Local-frame positions with the same shape as `points`.

to_frame ¶

to_frame(target: FrameConvention) -> Pose

Return this pose represented in another coordinate frame convention.

Parameters:

Name	Type	Description	Default
`target`	`FrameConvention`	Desired world coordinate convention.	required

Returns:

Name	Type	Description
`Pose`	`Pose`	Same rigid transform expressed in `target`.

scaled ¶

scaled(factor: float) -> Pose

Return a copy with translation scaled and rotation preserved.

Parameters:

Name	Type	Description	Default
`factor`	`float`	Multiplier applied to `translation`.	required

Returns:

Name	Type	Description
`Pose`	`Pose`	Copy with scaled translation and unchanged orientation.

PoseSequence ¶

Bases: BaseModel

Time-indexed sequence of poses.

Attributes:

Name	Type	Description
`poses`	`tuple[Pose, ...]`	Per-frame rigid transforms sharing one `frame`.
`fps`	`float`	Sampling rate in Hz for time-based resampling.

Methods:

Name	Description
`quaternions`	Stacked quaternions with shape `(T, 4)`.
`identity`	Return `frame_count` identity poses.
`from_arrays`	Build a pose sequence from position and quaternion arrays.
`to_frame`	Return this sequence represented in another coordinate frame convention.
`scaled`	Return this sequence with translations scaled and rotations preserved.
`resampled`	Return this pose sequence sampled on a new FPS grid.

Attributes¶

model_config `class-attribute` `instance-attribute` ¶

model_config = ConfigDict(arbitrary_types_allowed=True)

poses `instance-attribute` ¶

poses: tuple[Pose, ...]

fps `class-attribute` `instance-attribute` ¶

fps: float = 30.0

frame_count `property` ¶

frame_count: int

Number of poses.

frame `property` ¶

frame: FrameConvention

Coordinate frame used by every pose.

positions `property` ¶

positions: FloatArray

Stacked translations with shape (T, 3).

Functions¶

quaternions ¶

quaternions(order: QuaternionOrder = WXYZ) -> FloatArray

Stacked quaternions with shape (T, 4).

Parameters:

Name	Type	Description	Default
`order`	`QuaternionOrder`	Storage order for each frame's quaternion.	`WXYZ`

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	Quaternion array with shape `(T, 4)`.

identity `classmethod` ¶

identity(
    frame_count: int, *, fps: float = 30.0, frame: FrameConvention = Z_UP_RIGHT_HANDED
) -> PoseSequence

Return frame_count identity poses.

Parameters:

Name	Type	Description	Default
`frame_count`	`int`	Number of frames to create.	required
`fps`	`float`	Sampling rate in Hz.	`30.0`
`frame`	`FrameConvention`	World coordinate convention for every pose.	`Z_UP_RIGHT_HANDED`

Returns:

Name	Type	Description
`PoseSequence`	`PoseSequence`	Sequence of identity transforms.

from_arrays `classmethod` ¶

from_arrays(
    positions: Any,
    quaternions: Any,
    *,
    fps: float = 30.0,
    quaternion_order: QuaternionOrder = WXYZ,
    frame: FrameConvention = Z_UP_RIGHT_HANDED,
) -> PoseSequence

Build a pose sequence from position and quaternion arrays.

Parameters:

Name	Type	Description	Default
`positions`	`Any`	Translations with shape `(T, 3)`.	required
`quaternions`	`Any`	Orientations with shape `(T, 4)` in `quaternion_order`.	required
`fps`	`float`	Sampling rate in Hz.	`30.0`
`quaternion_order`	`QuaternionOrder`	Layout of each row in `quaternions`.	`WXYZ`
`frame`	`FrameConvention`	World coordinate convention for every pose.	`Z_UP_RIGHT_HANDED`

Returns:

Name	Type	Description
`PoseSequence`	`PoseSequence`	One `Pose` per matched time index.

to_frame ¶

to_frame(target: FrameConvention) -> PoseSequence

Return this sequence represented in another coordinate frame convention.

Parameters:

Name	Type	Description	Default
`target`	`FrameConvention`	Desired world coordinate convention.	required

Returns:

Name	Type	Description
`PoseSequence`	`PoseSequence`	Copy with each pose converted to `target`.

scaled ¶

scaled(factor: float) -> PoseSequence

Return this sequence with translations scaled and rotations preserved.

Parameters:

Name	Type	Description	Default
`factor`	`float`	Multiplier applied to every pose translation.	required

Returns:

Name	Type	Description
`PoseSequence`	`PoseSequence`	Copy with scaled translations and unchanged orientations.

resampled ¶

resampled(fps: float) -> PoseSequence

Return this pose sequence sampled on a new FPS grid.

Parameters:

Name	Type	Description	Default
`fps`	`float`	Target sampling rate in Hz.	required

Returns:

Name	Type	Description
`PoseSequence`	`PoseSequence`	Endpoint-preserving resample with linear translation and spherical-linear rotation interpolation.

Frame & quaternion helpers¶

reorder_quaternion ¶

reorder_quaternion(
    quaternion: ndarray, source: QuaternionOrder, target: QuaternionOrder
) -> ndarray

Convert quaternion storage order without changing the represented rotation.

Parameters:

Name	Type	Description	Default
`quaternion`	`ndarray`	Quaternion components in `source` layout.	required
`source`	`QuaternionOrder`	Storage order of `quaternion`.	required
`target`	`QuaternionOrder`	Desired storage order.	required

Returns:

Type	Description
`ndarray`	np.ndarray: Quaternion with the same rotation in `target` layout.

frame_transform_matrix ¶

frame_transform_matrix(source: FrameConvention, target: FrameConvention) -> FloatArray

Return the rotation matrix that maps coordinates from source to target.

Parameters:

Name	Type	Description	Default
`source`	`FrameConvention`	Input coordinate convention.	required
`target`	`FrameConvention`	Output coordinate convention.	required

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	`(3, 3)` rotation matrix `R` with `p_target = R @ p_source`.

convert_points_frame ¶

convert_points_frame(
    points: Any, source: FrameConvention, target: FrameConvention
) -> FloatArray

Convert point coordinates between supported right-handed frame conventions.

Parameters:

Name	Type	Description	Default
`points`	`Any`	Array-like positions with trailing dimension 3.	required
`source`	`FrameConvention`	Convention of the input coordinates.	required
`target`	`FrameConvention`	Desired output convention.	required

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	Points re-expressed in `target`, preserving the input shape.

Resampling¶

resampling_times ¶

resampling_times(
    frame_count: int, source_fps: float, target_fps: float
) -> tuple[FloatArray, FloatArray]

Return source and target sample times for endpoint-preserving interpolation.

Parameters:

Name	Type	Description	Default
`frame_count`	`int`	Number of frames in the source sequence.	required
`source_fps`	`float`	Source sampling rate in Hz.	required
`target_fps`	`float`	Target sampling rate in Hz.	required

Returns:

Type	Description
`tuple[FloatArray, FloatArray]`	tuple[FloatArray, FloatArray]: `(source_times, target_times)` in seconds, with the final target time clamped to the source duration.

resample_linear ¶

resample_linear(values: Any, source_fps: float, target_fps: float) -> FloatArray

Linearly resample an array whose first axis is time.

Parameters:

Name	Type	Description	Default
`values`	`Any`	Array-like data with time as axis 0.	required
`source_fps`	`float`	Source sampling rate in Hz.	required
`target_fps`	`float`	Target sampling rate in Hz.	required

Returns:

Name	Type	Description
`FloatArray`	`FloatArray`	Resampled array with the same trailing dimensions as `values`.

Pose and timing¶

Pose types¶

Pose ¶

Attributes¶

model_config class-attribute instance-attribute ¶

translation class-attribute instance-attribute ¶

quaternion class-attribute instance-attribute ¶

quaternion_order class-attribute instance-attribute ¶

frame class-attribute instance-attribute ¶

Functions¶

identity classmethod ¶

quaternion_as ¶

rotation ¶

matrix ¶

inverse ¶

transform_points ¶

inverse_transform_points ¶

to_frame ¶

scaled ¶

PoseSequence ¶

Attributes¶

model_config class-attribute instance-attribute ¶

poses instance-attribute ¶

fps class-attribute instance-attribute ¶

frame_count property ¶

frame property ¶

positions property ¶

Functions¶

quaternions ¶

identity classmethod ¶

from_arrays classmethod ¶

to_frame ¶

scaled ¶

resampled ¶

Frame & quaternion helpers¶

reorder_quaternion ¶

frame_transform_matrix ¶

convert_points_frame ¶

Resampling¶

resampling_times ¶

resample_linear ¶

model_config `class-attribute` `instance-attribute` ¶

translation `class-attribute` `instance-attribute` ¶

quaternion `class-attribute` `instance-attribute` ¶

quaternion_order `class-attribute` `instance-attribute` ¶

frame `class-attribute` `instance-attribute` ¶

identity `classmethod` ¶

model_config `class-attribute` `instance-attribute` ¶

poses `instance-attribute` ¶

fps `class-attribute` `instance-attribute` ¶

frame_count `property` ¶

frame `property` ¶

positions `property` ¶

identity `classmethod` ¶

from_arrays `classmethod` ¶