pymomentum.skel_state_np

Skeleton State Utilities (NumPy)

NumPy implementation of skeleton state utilities for PyMomentum.

This module mirrors skel_state but uses NumPy arrays instead of PyTorch tensors. See skel_state for full documentation on the skeleton state format and operations.

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

pymomentum.skel_state_np.blend(skel_states: NDArray, weights: NDArray | None = None) → NDArray

Blend k skeleton states with the passed-in weights.

Parameters:

  • skel_states – 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_np.check(skel_state: NDArray) → None

Check if the skeleton state has the correct shape.

Parameters:

skel_state – The skeleton state to check.

Raises:

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

pymomentum.skel_state_np.from_matrix(matrices: NDArray) → NDArray

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

Parameters:

matrices – An array of 4x4 matrices.

Returns:

The corresponding skeleton states.

pymomentum.skel_state_np.from_quaternion(rotation: NDArray) → NDArray

Create a skeleton state from rotation.

Parameters:

rotation – The rotation component.

Returns:

The skeleton state.

pymomentum.skel_state_np.from_scale(scale: NDArray) → NDArray

Create a skeleton state from scale.

Parameters:

scale – The scale component.

Returns:

The skeleton state.

pymomentum.skel_state_np.from_translation(translation: NDArray) → NDArray

Create a skeleton state from translation.

Parameters:

translation – The translation component.

Returns:

The skeleton state.

pymomentum.skel_state_np.identity(size: ~collections.abc.Sequence[int] | None = None, dtype: ~numpy.dtype = <class 'numpy.float32'>) → NDArray

Returns a skeleton state representing the identity transform.

Parameters:

  • size – The size of each dimension in the output array. Defaults to None, which means the output will be a 1D array with 8 elements.

  • dtype – The data type for the array.

Returns:

The identity skeleton state.

pymomentum.skel_state_np.inverse(skeleton_states: NDArray) → NDArray

Compute the inverse of a skeleton state.

Parameters:

skeleton_states – The skeleton state to invert.

Returns:

The inverted skeleton state.

pymomentum.skel_state_np.multiply(s1: NDArray, s2: NDArray) → NDArray

Multiply two skeleton states.

Parameters:

  • s1 – The first skeleton state.

  • s2 – The second skeleton state.

Returns:

The product of the two skeleton states.

pymomentum.skel_state_np.multiply_assume_normalized(s1: NDArray, s2: NDArray) → NDArray

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 – The first skeleton state.

  • s2 – The second skeleton state.

Returns:

The product of the two skeleton states.

pymomentum.skel_state_np.slerp(s0: NDArray, s1: NDArray, t: NDArray | float) → NDArray

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_np.split(skel_state: NDArray) → tuple[NDArray, NDArray, NDArray]

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

Parameters:

skel_state – The skeleton state to split.

Returns:

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

pymomentum.skel_state_np.to_matrix(skeleton_state: NDArray) → NDArray

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

Parameters:

skeleton_state – The skeleton state to convert.

Returns:

An array containing 4x4 matrix transforms.

pymomentum.skel_state_np.transform_points(skel_state: NDArray, points: NDArray) → NDArray

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

Parameters:

  • skel_state – The skeleton state to use for transformation.

  • points – The points to transform.

Returns:

The transformed points.

pymomentum.skel_state_np.transform_points_assume_normalized(skel_state: NDArray, points: NDArray) → NDArray

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 – The skeleton state to use for transformation.

  • points – The points to transform.

Returns:

The transformed points.