pymomentum.skel_state

Skeleton State Utilities

This module provides utilities for working with skeleton states in PyMomentum.

A skeleton state is a compact 8-dimensional representation of a 3D transformation that encodes translation, rotation, and uniform scale. The 8 components are organized as:

  • Translation (3 components): tx, ty, tz - 3D position offset

  • Rotation (4 components): rx, ry, rz, rw - quaternion rotation (x, y, z, w)

  • Scale (1 component): s - uniform scale factor

This representation is generated by forward kinematics functions like pymomentum.geometry.joint_parameters_to_skeleton_state() and represents the transformation from a local joint space to the world space.

Example:

Creating and using a skeleton state:

import torch
from pymomentum import skel_state

# Create identity transform
identity = skel_state.identity()

# Create from translation
translation = torch.tensor([1.0, 2.0, 3.0])
state = skel_state.from_translation(translation)

# Transform points
points = torch.tensor([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
transformed = skel_state.transform_points(state, points)
Note:

All functions in this module expect skeleton states to be PyTorch tensors with the last dimension having size 8, following the (tx, ty, tz, rx, ry, rz, rw, s) format.

pymomentum.skel_state.blend(skel_states: Tensor, weights: Tensor | None = None) → Tensor

Blend k skeleton states with the passed-in weights.

Parameters:

  • skel_states (torch.Tensor) – The skeleton states to blend.

  • weights – The weights to use, if not provided, weights are assumed to be all 1s

Returns:

The blended skeleton state.

pymomentum.skel_state.check(skel_state: Tensor) → None

Check if the skeleton state has the correct shape.

Parameters:

skel_state (torch.Tensor) – The skeleton state to check.

Raises:

ValueError – If the skeleton state does not have the correct shape.

pymomentum.skel_state.from_matrix(matrices: Tensor) → Tensor

Convert 4x4 matrices to skeleton states. Assumes that the scale is uniform.

Args:

matrices (torch.Tensor): A tensor of 4x4 matrices.

Returns:

torch.Tensor: The corresponding skeleton states.

pymomentum.skel_state.from_quaternion(rotation: Tensor) → Tensor

Create a skeleton state from rotation.

Parameters:

rotation (torch.Tensor) – The rotation component.

Returns:

The skeleton state.

Return type:

torch.Tensor

pymomentum.skel_state.from_scale(scale: Tensor) → Tensor

Create a skeleton state from scale.

Parameters:

scale (torch.Tensor) – The scale component.

Returns:

The skeleton state.

Return type:

torch.Tensor

pymomentum.skel_state.from_translation(translation: Tensor) → Tensor

Create a skeleton state from translation.

Parameters:

translation (torch.Tensor) – The translation component.

Returns:

The skeleton state.

Return type:

torch.Tensor

pymomentum.skel_state.identity(size: Sequence[int] | None = None, device: device | None = None) → Tensor

Returns a skeleton state representing the identity transform.

Parameters:

  • sizes (list[int], optional) – The size of each dimension in the output tensor. Defaults to None, which means the output will be a 1D tensor with 8 elements.

  • device (torch.device, optional) – The device on which to create the tensor. Defaults to None, which means the tensor will be created on the default device.

Returns:

The identity skeleton state.

Return type:

torch.Tensor

pymomentum.skel_state.inverse(skeleton_states: Tensor) → Tensor

Compute the inverse of a skeleton state.

Parameters:

skeleton_states (torch.Tensor) – The skeleton state to invert.

Returns:

The inverted skeleton state.

Return type:

torch.Tensor

pymomentum.skel_state.multiply(s1: Tensor, s2: Tensor) → Tensor

Multiply two skeleton states.

Parameters:

  • s1 (torch.Tensor) – The first skeleton state.

  • s2 (torch.Tensor) – The second skeleton state.

Returns:

The product of the two skeleton states.

Return type:

torch.Tensor

pymomentum.skel_state.multiply_assume_normalized(s1: Tensor, s2: Tensor) → Tensor

Multiply two skeleton states. This is an optimized version that assumes both skeleton states are already properly formatted and the quaternions are normalized, skipping validation checks.

Parameters:

  • s1 (torch.Tensor) – The first skeleton state.

  • s2 (torch.Tensor) – The second skeleton state.

Returns:

The product of the two skeleton states.

Return type:

torch.Tensor

pymomentum.skel_state.slerp(s0: Tensor, s1: Tensor, t: Tensor) → Tensor

Spherical linear interpolation between two skeleton states.

Parameters:

  • s0 – The first skeleton state.

  • s1 – The second skeleton state.

  • t – The interpolation factor, where 0 <= t <= 1. t=0 corresponds to s0, t=1 corresponds to s1.

Returns:

The interpolated skeleton state.

pymomentum.skel_state.split(skel_state: Tensor) → tuple[Tensor, Tensor, Tensor]

Split a skeleton state into translation, rotation, and scale components.

Parameters:

skel_state (torch.Tensor) – The skeleton state to split.

Returns:

A tuple of tensors (translation, rotation, scale).

Return type:

tuple[torch.Tensor, torch.Tensor, torch.Tensor]

pymomentum.skel_state.to_matrix(skeleton_state: Tensor) → Tensor

Convert skeleton state to a tensor of 4x4 matrices. The matrix represents the transform from a local joint space to the world space.

Parameters:

skeleton_state (torch.Tensor) – The skeleton state to convert.

Returns:

A tensor containing 4x4 matrix transforms.

Return type:

torch.Tensor

pymomentum.skel_state.transform_points(skel_state: Tensor, points: Tensor) → Tensor

Transform 3d points by the transform represented by the skeleton state.

Parameters:

  • skel_state (torch.Tensor) – The skeleton state to use for transformation.

  • points (torch.Tensor) – The points to transform.

Returns:

The transformed points.

Return type:

torch.Tensor

pymomentum.skel_state.transform_points_assume_normalized(skel_state: Tensor, points: Tensor) → Tensor

Transform 3d points by the transform represented by the skeleton state. This is an optimized version that assumes the skeleton state is already properly formatted and the quaternion is normalized, skipping validation checks.

Parameters:

  • skel_state (torch.Tensor) – The skeleton state to use for transformation.

  • points (torch.Tensor) – The points to transform.

Returns:

The transformed points.

Return type:

torch.Tensor