Exports

Export utilities for common formats.

Export utilities for converting internal motion representations into common file formats.

This module is intended to hold lightweight serialization / export helpers that can be reused outside of interactive demos.

kimodo.exports.bvh.motion_to_bvh(

local_rot_mats,

root_positions,

*,

skeleton,

fps,

standard_tpose=False,

)

Convert local rotations and root positions to BVH format; return UTF-8 string.

Parameters:

• local_rot_mats – (T, J, 3, 3) or (1, T, J, 3, 3) local rotation matrices.

• root_positions – (T, 3) or (1, T, 3) root joint positions (e.g. from posed joints).

• skeleton – Skeleton with bone_order_names, bvh_neutral_joints, etc.

• fps – Frames per second for the motion.

• standard_tpose – If True, export with the rest pose being the standard T-pose rather than the rest pose consistent with the BONES-SEED dataset.

Notes

BVH is plain-text. Root is named “Root” with ZYX rotation order; leaf joints have no End Site block.

kimodo.exports.bvh.motion_to_bvh_bytes(

local_rot_mats,

root_positions,

*,

skeleton,

fps,

standard_tpose=False,

)

Convert local rotations and root positions to BVH bytes (UTF-8).

Convenience wrapper around motion_to_bvh().

kimodo.exports.bvh.save_motion_bvh(

path,

local_rot_mats,

root_positions,

*,

skeleton,

fps,

standard_tpose=False,

)

Write local rotations and root positions to a BVH file at the given path.

kimodo.exports.bvh.read_bvh_frame_time_seconds(path)

Read Frame Time from a BVH file (seconds per frame).

kimodo.exports.bvh.bvh_to_kimodo_motion(path, skeleton=None, *, standard_tpose=False)

Load a Kimodo-style SOMA BVH into a Kimodo motion dict.

Expects the same hierarchy as save_motion_bvh() (Root wrapper + SOMA77 joints). The frame rate is always read from the BVH Frame Time header. Callers that need a different playback rate should resample the returned motion dict (see resample_motion_dict_to_kimodo_fps()).

Returns:

(motion_dict, source_fps) where source_fps is the native BVH frame rate read from the file header.

Convert kimodo motion (y-up, z-forward) to MuJoCo qpos (z-up, x-forward) for G1 skeleton.

class kimodo.exports.mujoco.MujocoQposConverter(

input_skeleton,

xml_path='/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons/g1skel34/xml/g1.xml',

)

Bases: object

Fast batch converter from our dictionary format to mujoco qpos with precomputed transforms.

In mujoco, the coordination is z up and x forward, right handed.

Features (30 joints): - root (pelvis, 7 = translation + rotation) + 29 dof joints (29)

In kimodo, the coordinate system is y up and z forward, right handed. Features (34 joints): - root (pelvis) + (34 - 1) joints; among these joints, 4 are end-effector joints added by kimodo.

Cached by (input_skeleton id, xml_path); repeated calls with the same args return the same instance.

__init__(

input_skeleton,

xml_path='/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons/g1skel34/xml/g1.xml',

)

Initialize converter with precomputed transforms.

Parameters:

xml_path – Path to the mujoco XML file containing joint definitions

dict_to_qpos(

output,

device=None,

root_quat_w_first=True,

numpy=True,

mujoco_rest_zero=False,

)

Convert kimodo output dict to mujoco qpos format.

Parameters:

• output – dict with keys “local_rot_mats” and “root_positions”.

• device – device to use for the output.

• root_quat_w_first – If True, quaternion in qpos is (w,x,y,z).

• numpy – If True, convert the output to numpy array.

• mujoco_rest_zero – If True, joint angles are written so that kimodo rest (t-pose) maps to q=0 in MuJoCo. If False, write raw joint_dofs.

Returns:

(B, T, 7+J) mujoco qpos format.

Return type:

qpos

qpos_to_motion_dict(

qpos,

source_fps,

*,

root_quat_w_first=True,

mujoco_rest_zero=False,

)

Inverse of to_qpos() / dict_to_qpos() for MuJoCo CSV (T, 36) rows.

Parameters:

• qpos – Shape (T, 36) or (1, T, 36) (root xyz, root quat wxyz, 29 joint angles).

• source_fps – Source frame rate (Hz) of the qpos data.

• root_quat_w_first – Must match how the CSV was written (default True).

• mujoco_rest_zero – Must match dict_to_qpos() / to_qpos().

Returns:

Kimodo motion dict (see kimodo.exports.motion_io.complete_motion_dict()).

save_csv(qpos, csv_path)

project_to_real_robot_rotations(

local_rot_mats,

root_positions,

clamp_to_limits=True,

mujoco_rest_zero=False,

)

Project full 3D local rotations to G1 real robot DoF and back to 3D for viz.

Joint angles are extracted along each hinge axis, optionally clamped to XML limits, then reconstructed to 3D rotations. When mujoco_rest_zero=False (default), raw angles are used (baked-with-quat). When True, angles are relative to rest (0 = T-pose in MuJoCo).

to_qpos(

local_rot_mats,

root_positions,

root_quat_w_first=True,

mujoco_rest_zero=False,

)

Fast batch conversion from kimodo features to mujoco qpos format.

Parameters:

• local_rot_mats – (B, T, J, 3, 3) local rotation matrices (kimodo convention).

• root_positions – (B, T, 3) root positions.

• root_quat_w_first – If True, quaternion in qpos is (w,x,y,z).

• mujoco_rest_zero – If True, joint angles are written so that kimodo rest (t-pose) maps to q=0 in MuJoCo. If False, write raw joint_dofs.

Returns:

• root_trans (3) + root_quat (4) + joint_dofs (29) = 36 columns

Return type:

torch.Tensor of shape [batch, numFrames, 36] containing mujoco qpos data

kimodo.exports.mujoco.apply_g1_real_robot_projection(

skeleton,

joints_pos,

joints_rot,

clamp_to_limits=True,

)

Project G1 motion to real robot DoF (1-DoF per joint) with optional axis limits.

Extracts a single angle per hinge along its axis (1-DoF), optionally clamps to joint limits from the MuJoCo XML (when clamp_to_limits=True), then reconstructs 3D rotations and runs FK. T-pose (identity local rotations) is preserved.

Parameters:

• skeleton – G1 skeleton instance.

• joints_pos – (T, J, 3) or (B, T, J, 3) joint positions in global space.

• joints_rot – (T, J, 3, 3) or (B, T, J, 3, 3) global rotation matrices.

• clamp_to_limits – If True, clamp joint angles to XML axis limits (default True).

Returns:

(posed_joints, global_rot_mats) as tensors, same shape as inputs (batch preserved).

Convert kimodo motion to AMASS/SMPL-X compatible parameters (axis-angle, Y-up or Z-up).

kimodo.exports.smplx.kimodo_y_up_to_amass_coord_rotation_matrix()

3x3 rotation mapping Kimodo Y-up (+Z forward) to AMASS Z-up (+Y forward).

Used by get_amass_parameters() and amass_arrays_to_kimodo_motion() (inverse).

kimodo.exports.smplx.get_amass_parameters(

local_rot_mats,

root_positions,

skeleton,

z_up=True,

)

Convert local rot mats and root positions to AMASS-style trans and pose_body; optional z_up coordinate transform.

Our method generates motions with Y-up and +Z forward; if z_up=True, transform to Z-up and +Y forward as in AMASS.

kimodo.exports.smplx.amass_arrays_to_kimodo_motion(

trans,

root_orient,

pose_body,

skeleton,

source_fps,

*,

z_up=True,

)

Inverse of get_amass_parameters() for a single sequence (AMASS → Kimodo motion dict).

Parameters:

• trans – (T, 3) AMASS root translation (same as trans in AMASS NPZ).

• root_orient – (T, 3) axis-angle root orientation in AMASS coordinates (z-up when z_up).

• pose_body – (T, 63) body pose axis-angle (21 joints × 3).

• skeleton – SMPLXSkeleton22 instance.

• source_fps – Source frame rate (Hz) of the AMASS recording.

• z_up – If True, invert the same Y-up↔Z-up transform as get_amass_parameters(..., z_up=True).

Returns:

Motion dict compatible with kimodo.exports.motion_io.save_kimodo_npz().

kimodo.exports.smplx.amass_npz_to_kimodo_motion(

npz_path,

skeleton,

source_fps=None,

*,

z_up=True,

)

Load an AMASS-style .npz and return a Kimodo motion dict.

Parameters:

• npz_path – Path to AMASS NPZ (trans, root_orient, pose_body, …).

• skeleton – SMPL-X skeleton instance.

• source_fps – Source frame rate (Hz); if None, uses mocap_frame_rate from the file when present, else 30.0.

• z_up – Same meaning as amass_arrays_to_kimodo_motion().

class kimodo.exports.smplx.AMASSConverter(

fps,

skeleton,

beta_path='/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons/smplx22/beta.npy',

mean_hands_path='/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons/smplx22/mean_hands.npy',

)

Bases: object

__init__(

fps,

skeleton,

beta_path='/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons/smplx22/beta.npy',

mean_hands_path='/home/drempe/projects/motion_foundation_model/kimodo-oss-release/mfm-oss/kimodo/assets/skeletons/smplx22/mean_hands.npy',

)

convert_save_npz(output, npz_path, z_up=True)

save_npz(

trans,

root_orient,

pose_body,

base_output,

npz_path,

)