Motion Representation#

Motion representation utilities and kinematics helpers.

Skeleton#

Skeleton definitions and utilities used across kimodo.

class kimodo.skeleton.SkeletonBase(folder=None, name=None, load=True, **kwargs)[source]#

Bases: <Mock object at 0x768058c46080>[]

Base class that stores a skeleton hierarchy and helper metadata.

Subclasses define the static joint layout (joint names and parent links) and semantic groups (feet, hands, hips). This class builds index mappings, parent tensors, and convenience helpers used by kinematics, constraints, and motion conversion utilities.

bone_order_names_with_parents = None#

hip_joint_names = None#

__init__(folder=None, name=None, load=True, **kwargs)[source]#

Initialize a skeleton instance and optional neutral-pose assets.

Parameters:

folder – Folder containing serialized skeleton assets (for example joints.p and optional standard_t_pose_global_offsets_rots.p).
name – Optional runtime name used to validate subclass compatibility.
load – Whether to load tensor assets from folder.
**kwargs – Unused extra config keys kept for config compatibility.

name = None#

root_idx = None#

bone_order_names_no_root = None#

foot_joint_names = None#

foot_joint_idx = None#

hip_joint_idx = None#

expand_joint_names(joint_names)[source]#

Expand base EE names [LeftFoot, RightFoot, LeftHand, RightHand] actual joint names to constrain position and rotations.

Parameters:: joint_names – list of list of base EE names to constrain
Returns:: list of list of joint names to constrain rotations pos_joint_names: list of list of joint names to constrain positions
Return type:: rot_joint_names

expand_joint_names_batched(joint_names)[source]#

Expand base EE names [LeftFoot, RightFoot, LeftHand, RightHand] actual joint names to constrain position and rotations.

Parameters:: joint_names – list of list of base EE names to constrain
Returns:: list of list of joint names to constrain rotations pos_joint_names: list of list of joint names to constrain positions
Return type:: rot_joint_names

property device#

Device where neutral-joint buffers are stored.

Returns ‘cpu’ if neutral_joints is not present.

fk(local_joint_rots, root_positions)[source]#

Run forward kinematics for this skeleton layout.

Parameters:

local_joint_rots – Local joint rotation matrices with shape (…, J, 3, 3).
root_positions – Root translations with shape (…, 3).

Returns:

Tuple of (global_joint_rots, posed_joints, posed_joints_norootpos).

to_standard_tpose(local_rot_mats)[source]#: Convert local rotations into the skeleton’s standard T-pose frame.

from_standard_tpose(local_rot_mats)[source]#: Convert local rotations from the skeleton’s standard T-pose frame.

global_rots_to_local_rots(global_joint_rots)[source]#: Convert global joint rotations to local rotations for this hierarchy.

get_skel_slice(skeleton)[source]#

Build index mapping from another skeleton into this skeleton order.

Parameters:: skeleton – Source skeleton whose joint order is used by input tensors.
Returns:: A list of source indices ordered as self.bone_order_names.
Raises:: ValueError – If at least one required joint is missing from skeleton.

class kimodo.skeleton.G1Skeleton34(folder=None, name=None, load=True, **kwargs)[source]#

Bases: SkeletonBase

Unitree G1 skeleton with 32 articulated joints plus 2 toe endpoints.

name = 'g1skel34'#

right_foot_joint_names = ['right_ankle_roll_skel', 'right_toe_base']#

left_foot_joint_names = ['left_ankle_roll_skel', 'left_toe_base']#

right_hand_joint_names = ['right_wrist_yaw_skel', 'right_hand_roll_skel']#

left_hand_joint_names = ['left_wrist_yaw_skel', 'left_hand_roll_skel']#

hip_joint_names = ['right_hip_pitch_skel', 'left_hip_pitch_skel']#

bone_order_names_with_parents = [('pelvis_skel', None), ('left_hip_pitch_skel', 'pelvis_skel'), ('left_hip_roll_skel', 'left_hip_pitch_skel'), ('left_hip_yaw_skel', 'left_hip_roll_skel'), ('left_knee_skel', 'left_hip_yaw_skel'), ('left_ankle_pitch_skel', 'left_knee_skel'), ('left_ankle_roll_skel', 'left_ankle_pitch_skel'), ('left_toe_base', 'left_ankle_roll_skel'), ('right_hip_pitch_skel', 'pelvis_skel'), ('right_hip_roll_skel', 'right_hip_pitch_skel'), ('right_hip_yaw_skel', 'right_hip_roll_skel'), ('right_knee_skel', 'right_hip_yaw_skel'), ('right_ankle_pitch_skel', 'right_knee_skel'), ('right_ankle_roll_skel', 'right_ankle_pitch_skel'), ('right_toe_base', 'right_ankle_roll_skel'), ('waist_yaw_skel', 'pelvis_skel'), ('waist_roll_skel', 'waist_yaw_skel'), ('waist_pitch_skel', 'waist_roll_skel'), ('left_shoulder_pitch_skel', 'waist_pitch_skel'), ('left_shoulder_roll_skel', 'left_shoulder_pitch_skel'), ('left_shoulder_yaw_skel', 'left_shoulder_roll_skel'), ('left_elbow_skel', 'left_shoulder_yaw_skel'), ('left_wrist_roll_skel', 'left_elbow_skel'), ('left_wrist_pitch_skel', 'left_wrist_roll_skel'), ('left_wrist_yaw_skel', 'left_wrist_pitch_skel'), ('left_hand_roll_skel', 'left_wrist_yaw_skel'), ('right_shoulder_pitch_skel', 'waist_pitch_skel'), ('right_shoulder_roll_skel', 'right_shoulder_pitch_skel'), ('right_shoulder_yaw_skel', 'right_shoulder_roll_skel'), ('right_elbow_skel', 'right_shoulder_yaw_skel'), ('right_wrist_roll_skel', 'right_elbow_skel'), ('right_wrist_pitch_skel', 'right_wrist_roll_skel'), ('right_wrist_yaw_skel', 'right_wrist_pitch_skel'), ('right_hand_roll_skel', 'right_wrist_yaw_skel')]#

class kimodo.skeleton.SOMASkeleton30(folder=None, name=None, load=True, **kwargs)[source]#

Bases: SkeletonBase

Compact 30-joint SOMA variant with reduced hand and end-effector detail.

name = 'somaskel30'#

right_foot_joint_names = ['RightFoot', 'RightToeBase']#

left_foot_joint_names = ['LeftFoot', 'LeftToeBase']#

right_hand_joint_names = ['RightHand', 'RightHandMiddleEnd']#

left_hand_joint_names = ['LeftHand', 'LeftHandMiddleEnd']#

hip_joint_names = ['RightLeg', 'LeftLeg']#

bone_order_names_with_parents = [('Hips', None), ('Spine1', 'Hips'), ('Spine2', 'Spine1'), ('Chest', 'Spine2'), ('Neck1', 'Chest'), ('Neck2', 'Neck1'), ('Head', 'Neck2'), ('Jaw', 'Head'), ('LeftEye', 'Head'), ('RightEye', 'Head'), ('LeftShoulder', 'Chest'), ('LeftArm', 'LeftShoulder'), ('LeftForeArm', 'LeftArm'), ('LeftHand', 'LeftForeArm'), ('LeftHandThumbEnd', 'LeftHand'), ('LeftHandMiddleEnd', 'LeftHand'), ('RightShoulder', 'Chest'), ('RightArm', 'RightShoulder'), ('RightForeArm', 'RightArm'), ('RightHand', 'RightForeArm'), ('RightHandThumbEnd', 'RightHand'), ('RightHandMiddleEnd', 'RightHand'), ('LeftLeg', 'Hips'), ('LeftShin', 'LeftLeg'), ('LeftFoot', 'LeftShin'), ('LeftToeBase', 'LeftFoot'), ('RightLeg', 'Hips'), ('RightShin', 'RightLeg'), ('RightFoot', 'RightShin'), ('RightToeBase', 'RightFoot')]#

property somaskel77#

to_SOMASkeleton77(local_joint_rots_subset)[source]#

from_SOMASkeleton77(local_joint_rots_full)[source]#: Extract the 30-joint subset from 77-joint local rotation data.

output_to_SOMASkeleton77(output)[source]#

Convert model output dict from somaskel30 to somaskel77.

Expands local_rot_mats to 77 joints, re-runs FK for global_rot_mats and posed_joints. Root and foot-contact keys are unchanged.

class kimodo.skeleton.SOMASkeleton77(folder=None, name=None, load=True, **kwargs)[source]#

Bases: SkeletonBase

High-detail 77-joint SOMA skeleton with full finger and toe chains.

name = 'somaskel77'#

right_foot_joint_names = ['RightFoot', 'RightToeBase', 'RightToeEnd']#

left_foot_joint_names = ['LeftFoot', 'LeftToeBase', 'LeftToeEnd']#

right_hand_joint_names = ['RightHand', 'RightHandThumb1', 'RightHandThumb2', 'RightHandThumb3', 'RightHandThumbEnd', 'RightHandIndex1', 'RightHandIndex2', 'RightHandIndex3', 'RightHandIndex4', 'RightHandIndexEnd', 'RightHandMiddle1', 'RightHandMiddle2', 'RightHandMiddle3', 'RightHandMiddle4', 'RightHandMiddleEnd', 'RightHandRing1', 'RightHandRing2', 'RightHandRing3', 'RightHandRing4', 'RightHandRingEnd', 'RightHandPinky1', 'RightHandPinky2', 'RightHandPinky3', 'RightHandPinky4', 'RightHandPinkyEnd']#

left_hand_joint_names = ['LeftHand', 'LeftHandThumb1', 'LeftHandThumb2', 'LeftHandThumb3', 'LeftHandThumbEnd', 'LeftHandIndex1', 'LeftHandIndex2', 'LeftHandIndex3', 'LeftHandIndex4', 'LeftHandIndexEnd', 'LeftHandMiddle1', 'LeftHandMiddle2', 'LeftHandMiddle3', 'LeftHandMiddle4', 'LeftHandMiddleEnd', 'LeftHandRing1', 'LeftHandRing2', 'LeftHandRing3', 'LeftHandRing4', 'LeftHandRingEnd', 'LeftHandPinky1', 'LeftHandPinky2', 'LeftHandPinky3', 'LeftHandPinky4', 'LeftHandPinkyEnd']#

hip_joint_names = ['RightLeg', 'LeftLeg']#

bone_order_names_with_parents = [('Hips', None), ('Spine1', 'Hips'), ('Spine2', 'Spine1'), ('Chest', 'Spine2'), ('Neck1', 'Chest'), ('Neck2', 'Neck1'), ('Head', 'Neck2'), ('HeadEnd', 'Head'), ('Jaw', 'Head'), ('LeftEye', 'Head'), ('RightEye', 'Head'), ('LeftShoulder', 'Chest'), ('LeftArm', 'LeftShoulder'), ('LeftForeArm', 'LeftArm'), ('LeftHand', 'LeftForeArm'), ('LeftHandThumb1', 'LeftHand'), ('LeftHandThumb2', 'LeftHandThumb1'), ('LeftHandThumb3', 'LeftHandThumb2'), ('LeftHandThumbEnd', 'LeftHandThumb3'), ('LeftHandIndex1', 'LeftHand'), ('LeftHandIndex2', 'LeftHandIndex1'), ('LeftHandIndex3', 'LeftHandIndex2'), ('LeftHandIndex4', 'LeftHandIndex3'), ('LeftHandIndexEnd', 'LeftHandIndex4'), ('LeftHandMiddle1', 'LeftHand'), ('LeftHandMiddle2', 'LeftHandMiddle1'), ('LeftHandMiddle3', 'LeftHandMiddle2'), ('LeftHandMiddle4', 'LeftHandMiddle3'), ('LeftHandMiddleEnd', 'LeftHandMiddle4'), ('LeftHandRing1', 'LeftHand'), ('LeftHandRing2', 'LeftHandRing1'), ('LeftHandRing3', 'LeftHandRing2'), ('LeftHandRing4', 'LeftHandRing3'), ('LeftHandRingEnd', 'LeftHandRing4'), ('LeftHandPinky1', 'LeftHand'), ('LeftHandPinky2', 'LeftHandPinky1'), ('LeftHandPinky3', 'LeftHandPinky2'), ('LeftHandPinky4', 'LeftHandPinky3'), ('LeftHandPinkyEnd', 'LeftHandPinky4'), ('RightShoulder', 'Chest'), ('RightArm', 'RightShoulder'), ('RightForeArm', 'RightArm'), ('RightHand', 'RightForeArm'), ('RightHandThumb1', 'RightHand'), ('RightHandThumb2', 'RightHandThumb1'), ('RightHandThumb3', 'RightHandThumb2'), ('RightHandThumbEnd', 'RightHandThumb3'), ('RightHandIndex1', 'RightHand'), ('RightHandIndex2', 'RightHandIndex1'), ('RightHandIndex3', 'RightHandIndex2'), ('RightHandIndex4', 'RightHandIndex3'), ('RightHandIndexEnd', 'RightHandIndex4'), ('RightHandMiddle1', 'RightHand'), ('RightHandMiddle2', 'RightHandMiddle1'), ('RightHandMiddle3', 'RightHandMiddle2'), ('RightHandMiddle4', 'RightHandMiddle3'), ('RightHandMiddleEnd', 'RightHandMiddle4'), ('RightHandRing1', 'RightHand'), ('RightHandRing2', 'RightHandRing1'), ('RightHandRing3', 'RightHandRing2'), ('RightHandRing4', 'RightHandRing3'), ('RightHandRingEnd', 'RightHandRing4'), ('RightHandPinky1', 'RightHand'), ('RightHandPinky2', 'RightHandPinky1'), ('RightHandPinky3', 'RightHandPinky2'), ('RightHandPinky4', 'RightHandPinky3'), ('RightHandPinkyEnd', 'RightHandPinky4'), ('LeftLeg', 'Hips'), ('LeftShin', 'LeftLeg'), ('LeftFoot', 'LeftShin'), ('LeftToeBase', 'LeftFoot'), ('LeftToeEnd', 'LeftToeBase'), ('RightLeg', 'Hips'), ('RightShin', 'RightLeg'), ('RightFoot', 'RightShin'), ('RightToeBase', 'RightFoot'), ('RightToeEnd', 'RightToeBase')]#

property relaxed_hands_rest_pose#

class kimodo.skeleton.SMPLXSkeleton22(folder=None, name=None, load=True, **kwargs)[source]#

Bases: SkeletonBase

SMPL-X skeleton with body-only 22 joints.

name = 'smplx22'#

right_foot_joint_names = ['right_ankle', 'right_foot']#

left_foot_joint_names = ['left_ankle', 'left_foot']#

right_hand_joint_names = ['right_wrist']#

left_hand_joint_names = ['left_wrist']#

hip_joint_names = ['right_hip', 'left_hip']#

bone_order_names_with_parents = [('pelvis', None), ('left_hip', 'pelvis'), ('right_hip', 'pelvis'), ('spine1', 'pelvis'), ('left_knee', 'left_hip'), ('right_knee', 'right_hip'), ('spine2', 'spine1'), ('left_ankle', 'left_knee'), ('right_ankle', 'right_knee'), ('spine3', 'spine2'), ('left_foot', 'left_ankle'), ('right_foot', 'right_ankle'), ('neck', 'spine3'), ('left_collar', 'spine3'), ('right_collar', 'spine3'), ('head', 'neck'), ('left_shoulder', 'left_collar'), ('right_shoulder', 'right_collar'), ('left_elbow', 'left_shoulder'), ('right_elbow', 'right_shoulder'), ('left_wrist', 'left_elbow'), ('right_wrist', 'right_elbow')]#

kimodo.skeleton.batch_rigid_transform(rot_mats, joints, parents, root_idx)[source]#

Perform batch rigid transformation on a skeletal structure.

Parameters:

rot_mats – Local rotation matrices for each joint: (B, J, 3, 3)
joints – Initial joint positions: (B, J, 3)
parents – Tensor indicating the parent of each joint: (J,)
root_idx (int) – index of the root

Returns:

Transformed joint positions after applying forward kinematics.

kimodo.skeleton.fk( local_joint_rots, root_positions, skeleton, root_positions_is_global=True, )[source]#

Compute global joint rotations and positions from local rotations.

Parameters:

local_joint_rots – Local rotation matrices with shape (…, J, 3, 3).
root_positions – Root translations with shape (…, 3).
skeleton – Skeleton object exposing neutral_joints, joint_parents, and root_idx.
root_positions_is_global – If True, neutral joints are recentered so root translations are interpreted in world space.

Returns:

Tuple (global_joint_rots, posed_joints, posed_joints_norootpos).

kimodo.skeleton.build_skeleton( nbjoints, assets_folder=PosixPath('/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons'), )[source]#

Instantiate a known skeleton class from its joint count.

Supported joint counts: 30 (SOMA compact), 34 (G1), 77 (SOMA full), 22 (SMPLX).

Parameters:

nbjoints – Number of joints expected in the skeleton representation.
assets_folder – Base skeleton-assets directory containing per-skeleton subfolders.

Returns:

A configured SkeletonBase subclass instance.

Raises:

ValueError – If nbjoints does not match a registered skeleton.

kimodo.skeleton.global_rots_to_local_rots(global_joint_rots, skeleton)[source]#

Convert global rotations to local rotations using a skeleton hierarchy.

Parameters:

global_joint_rots – Global rotation matrices with shape (…, J, 3, 3).
skeleton – Skeleton object exposing joint_parents and root_idx.

Returns:

Local rotation matrices with the same leading shape as the input.

kimodo.skeleton.to_standard_tpose(local_rot_mats, skeleton)[source]#

Re-express local rotations in the skeleton’s standard T-pose convention.

Parameters:

local_rot_mats – Local rotation matrices with shape (…, J, 3, 3).
skeleton – Skeleton object exposing global_rot_offsets, joint_parents, root_idx, and nbjoints.

Returns:

Tuple (new_local_rot_mats, new_global_rot_mats) in the standard frame.

Forward Kinematics#

Forward-kinematics primitives for articulated skeletons.

kimodo.skeleton.kinematics.fk( local_joint_rots, root_positions, skeleton, root_positions_is_global=True, )[source]#

Compute global joint rotations and positions from local rotations.

Parameters:

local_joint_rots – Local rotation matrices with shape (…, J, 3, 3).
root_positions – Root translations with shape (…, 3).
skeleton – Skeleton object exposing neutral_joints, joint_parents, and root_idx.
root_positions_is_global – If True, neutral joints are recentered so root translations are interpreted in world space.

Returns:

Tuple (global_joint_rots, posed_joints, posed_joints_norootpos).

kimodo.skeleton.kinematics.compute_idx_levels(parents)[source]#

Group joint indices by hierarchy depth for level-wise FK updates.

Parameters:: parents – Parent index tensor of shape (J,) with root parent -1.
Returns:: List of index tensors, where each tensor contains joints at one depth.

kimodo.skeleton.kinematics.batch_rigid_transform(rot_mats, joints, parents, root_idx)[source]#

Perform batch rigid transformation on a skeletal structure.

Parameters:

rot_mats – Local rotation matrices for each joint: (B, J, 3, 3)
joints – Initial joint positions: (B, J, 3)
parents – Tensor indicating the parent of each joint: (J,)
root_idx (int) – index of the root

Returns:

Transformed joint positions after applying forward kinematics.

Motion Representations#

Base motion representation: feature layout, normalization, and conditioning helpers.

class kimodo.motion_rep.reps.base.MotionRepBase(skeleton, fps, stats_path=None)[source]#

Bases: object

Base class for motion representations used in generation and conditioning.

Subclasses define: - size_dict: feature blocks and their shapes, - last_root_feature: last entry of the root block, - local_root_size_dict: local-root feature layout, and implement transform-specific methods such as __call__, inverse, rotate, translate_2d and create_conditions.

__init__(skeleton, fps, stats_path=None)[source]#: Initialize feature slicing metadata and optional normalization stats.

get_root_pos(features, fallback_to_smooth=True)[source]#

Extract root positions from a feature tensor.

Supports both root_pos and smooth_root_pos representations.

global_root_to_local_root( root_features, normalized, lengths, )[source]#

Convert global root features to local-root motion features.

Parameters:

root_features – Root feature tensor containing root position and global heading, shaped [B, T, D_root].
normalized – Whether root_features are normalized.
lengths – Optional valid lengths per sequence.

Returns:

Tensor [B, T, 4] with local root rotational velocity, planar velocity, and global root height.

get_root_heading_angle(features)[source]#: Compute root heading angle from cosine/sine heading features.

rotate_to( features, target_angle, return_delta_angle=False, )[source]#: Rotate each sequence so frame-0 heading matches target_angle.

rotate_to_zero(features, return_delta_angle=False)[source]#: Rotate each sequence so frame-0 heading becomes zero.

randomize_first_heading( features, return_delta_angle=False, )[source]#: Rotate each sequence to a random frame-0 heading.

translate_2d_to( features, target_2d_pos, return_delta_pos=False, )[source]#: Translate each sequence so frame-0 root (x, z) matches a target.

translate_2d_to_zero(features, return_delta_pos=False)[source]#: Translate each sequence so frame-0 root (x, z) is at the origin.

canonicalize(features)[source]#: Canonicalize heading and planar position at frame 0.

normalize(features)[source]#: Normalize features using per-part stats (global_root, local_root, body).

unnormalize(features)[source]#: Undo feature normalization using per-part stats.

create_conditions_from_constraints( constraints_lst, length, to_normalize, device, )[source]#: Create a conditioning tensor and mask from constraint objects.

create_conditions_from_constraints_batched( constraints_lst, lengths, to_normalize, device, )[source]#

Batched version of create_conditions_from_constraints.

Supports either one shared constraint list for all batch elements, or a per-sample list of constraint lists.

class kimodo.motion_rep.reps.kimodo_motionrep.KimodoMotionRep(skeleton, fps, stats_path=None)[source]#

Bases: MotionRepBase

Global root / global joints rotations representation, relative to a smooth root.

__init__(skeleton, fps, stats_path=None)[source]#: Initialize feature slicing metadata and optional normalization stats.

rotate(features, angle)[source]#: Rotate root/joint positional and rotational features by heading.

translate_2d(features, translation_2d)[source]#: Translate smooth root planar position by (dx, dz).

inverse( features, is_normalized, posed_joints_from='rotations', return_numpy=False, )[source]#: Decode smooth-root features into motion tensors.

create_conditions( index_dict, data_dict, length, to_normalize, device, )[source]#: Build sparse conditioning tensors for smooth-root representation.

TMR motion representation: global root, global joints, velocities, and foot contacts.

class kimodo.motion_rep.reps.tmr_motionrep.TMRMotionRep(skeleton, fps, stats_path=None)[source]#

Bases: MotionRepBase

Motion representation with global root and global joint positions.

Feature layout: - root position (x, y, z) - root heading as (cos(theta), sin(theta)) - local joint positions (root removed, ground-referenced) - global joint velocities - binary foot contacts

__init__(skeleton, fps, stats_path=None)[source]#: Initialize feature slicing metadata and optional normalization stats.

rotate(features, angle)[source]#: Rotate all spatial features by a heading delta (radians).

translate_2d(features, translation_2d)[source]#: Translate root planar position by (dx, dz).

inverse( features, is_normalized, posed_joints_from='positions', return_numpy=False, )[source]#

Decode features back to a motion dictionary.

Parameters:

features – Feature tensor [B, T, D].
is_normalized – Whether input features are normalized.
posed_joints_from – Must be "positions" for this representation.
return_numpy – Whether to convert tensors to numpy arrays.

Returns:

Dictionary containing reconstructed positions and auxiliary data.

Utilities#

Foot contact detection from joint positions and velocities.

kimodo.motion_rep.feet.foot_detect_from_pos_and_vel( positions, velocity, skeleton, vel_thres, height_thresh, )[source]#

Compute foot contact labels using heuristics combining joint height and velocities.

Parameters:

positions (torch.Tensor) – [X, T, J, 3] global joint positions
velocity (torch.Tensor) – [X, T, J, 3] velocities (already padded correctly), already multiplied by 1 / dt
vel_thres (float) – threshold for joint velocity
height_thresh (float) – threshold for joint height

Returns:

[X, T, 4] contact labels for left and right foot joints (heel/toe order follows the skeleton joint index definition), where 1 denotes contact.

Return type:

torch.Tensor

Feature normalization statistics (mean/std) for motion representations.

class kimodo.motion_rep.stats.Stats(folder=None, load=True, eps=1e-05)[source]#

Bases: <Mock object at 0x768058b50880>[]

Utility module for feature normalization statistics.

Normalization follows: (data - mean) / sqrt(std**2 + eps)

__init__(folder=None, load=True, eps=1e-05)[source]#

sliced(indices)[source]#: Return a new Stats object containing selected feature indices.

load()[source]#: Load mean.npy and std.npy from self.folder.

register_from_tensors(mean, std)[source]#: Register mean/std tensors as non-persistent buffers.

normalize(data)[source]#: Normalize data using the stored statistics.

unnormalize(data)[source]#: Undo normalization using the stored statistics.

is_loaded()[source]#: Return whether statistics are currently available.

get_dim()[source]#: Return feature dimensionality.

save(folder=None, mean=None, std=None)[source]#: Save statistics to folder as mean.npy and std.npy.

Smooth root trajectory: ADMM-based smoother with margin constraints and get_smooth_root_pos helper.

class kimodo.motion_rep.smooth_root.TrajectorySmoother( margins, pos_weight=0.0, loop=False, admm_iters=100, alpha_overrelax=1.0, circle_project=False, )[source]#

Bases: object

Modify trajectories to hit target values while respecting soft constraints.

This smoother keeps the trajectory close to the original positions while minimizing accelerations. Targets are enforced at specified frames via soft constraints.

__init__( margins, pos_weight=0.0, loop=False, admm_iters=100, alpha_overrelax=1.0, circle_project=False, )[source]#

Initialize the TrajectorySmoother.

Parameters:

margins – Array of margin values for each frame. margins[i] < 0: unconstrained margins[i] == 0: pinned on this frame margins[i] > 0: can deviate within the margin
pos_weight – Weight for position preservation
loop – Whether the trajectory should loop
admm_iters – Number of ADMM iterations

smooth(targets, x0)[source]#

Interpolate between reference positions while satisfying constraints.

Parameters:

observations – Target positions for constrained frames (numpy array)
ref_positions – Reference positions defining original shape (numpy array)

Returns:

Interpolated positions (numpy array)

x_update(x, z, u, x_t)[source]#: Update x in the ADMM iteration.

z_update(z, x, z_t, u)[source]#: Update z in the ADMM iteration using vectorized operations.

u_update(u, x, z)[source]#: Update u in the ADMM iteration using vectorized operations.

kimodo.motion_rep.smooth_root.smooth_signal( x, margins, pos_weight=0, alpha_overrelax=1.8, admm_iters=500, circle_project=False, )[source]#

Multigrid trajectory smoothing with margin constraints.

Parameters:

x – Input trajectory [T, D] as a NumPy array.
margins – Allowed radius around each target frame [T].
pos_weight – Weight for staying close to the original signal.
alpha_overrelax – ADMM over-relaxation coefficient.
admm_iters – ADMM iterations per multigrid level.
circle_project – If True, project each vector to the unit sphere.

Returns:

Smoothed trajectory of shape [T, D].

kimodo.motion_rep.smooth_root.get_smooth_root_pos(hip_translations)[source]#

Smooth root trajectory in the ground plane while preserving height.

Parameters:: hip_translations – Root translations [B, T, 3].
Returns:: Smoothed root translations [B, T, 3] where x/z are smoothed and y remains unchanged.