Implementation:Isaac sim IsaacGymEnvs RetargetMotion

Knowledge Sources	IsaacGymEnvs
Domains	Motion_Retargeting, Character_Animation
Last Updated	2026-02-15 11:00 GMT

Overview

RetargetMotion implements a motion retargeting pipeline that converts motion capture data from source skeletons (such as CMU or SFU mocap) to the AMP humanoid skeleton format, including joint projection for 1-DOF constraints and height adjustment.

Description

The project_joints() function constrains specific joints to single degree-of-freedom (1-DOF) rotation by projecting the full 3D rotations of elbows and knees onto their respective hinge axes. For each limb (right arm, left arm, right leg, left leg), it computes the angle between the upper and lower segments, creates a 1-DOF quaternion rotation around the Y-axis, and then compensates the parent joint rotation (shoulder or hip) to preserve the end-effector position. Hand rotations are zeroed out to identity quaternions. The result is a new SkeletonMotion with physically plausible joint angles suitable for the AMP humanoid model.

The main() function orchestrates the complete retargeting pipeline. It loads a JSON configuration file specifying the source motion, source and target T-poses, joint mapping, rotation offset, and scale. The pipeline proceeds through several stages: loading the source motion clip, performing skeleton retargeting via retarget_to_by_tpose() with the provided joint mapping and scale, trimming to the specified frame range, projecting joints to 1-DOF constraints, adjusting root height so feet rest on the ground plane (with an optional offset to prevent ground penetration), and finally saving the retargeted motion to disk.

This script is designed to be run as a standalone tool during the data preparation phase of AMP training. It bridges the gap between raw motion capture recordings and the specific skeleton topology required by the AMP humanoid reinforcement learning environment.

Usage

Use this module when preparing reference motion data for AMP (Adversarial Motion Priors) training. Run it as a script to convert motion capture files from CMU, SFU, or similar datasets to the AMP humanoid format. The project_joints() function can also be imported and used independently when you need to enforce 1-DOF joint constraints on any skeleton motion.

Code Reference

Source Location

• Repository: IsaacGymEnvs
• File: isaacgymenvs/tasks/amp/poselib/retarget_motion.py
• Lines: 1-282

Signature

def project_joints(motion: SkeletonMotion) -> SkeletonMotion:
    """Projects arm and leg joints to single degree-of-freedom rotations
    and adjusts parent joint rotations to compensate."""
    ...

def main():
    """Loads retarget config, performs skeleton retargeting, projects joints,
    adjusts height, and saves the result."""
    ...

Import

from isaacgymenvs.tasks.amp.poselib.retarget_motion import project_joints

I/O Contract

Inputs

Name	Type	Required	Description
motion	SkeletonMotion	Yes	Input skeleton motion with full 3D joint rotations to be projected to 1-DOF
retarget_data_path	str	Yes (main)	Path to JSON config file containing retarget parameters
source_motion	str	Yes (config)	Path to source motion npy file in SkeletonMotion format
source_tpose	str	Yes (config)	Path to source skeleton T-pose npy file
target_tpose	str	Yes (config)	Path to target skeleton T-pose npy file
joint_mapping	dict	Yes (config)	Mapping of joint names from source to target skeleton
rotation	list[float]	Yes (config)	Root rotation offset quaternion (XYZW) from source to target skeleton
scale	float	Yes (config)	Scale factor from source to target skeleton
trim_frame_beg	int	Yes (config)	Start frame index for trimming (-1 for beginning)
trim_frame_end	int	Yes (config)	End frame index for trimming (-1 for end)
root_height_offset	float	Yes (config)	Additional height offset to prevent ground penetration
target_motion_path	str	Yes (config)	Output path for the retargeted motion npy file

Outputs

Name	Type	Description
new_motion	SkeletonMotion	Retargeted motion with projected 1-DOF joints (from project_joints)
target_motion file	npy file	Saved retargeted motion on disk at target_motion_path (from main)

Usage Examples

# Run as standalone script for motion retargeting
# python isaacgymenvs/tasks/amp/poselib/retarget_motion.py

# Or use project_joints programmatically
import torch
from poselib.skeleton.skeleton3d import SkeletonMotion
from isaacgymenvs.tasks.amp.poselib.retarget_motion import project_joints

# Load a retargeted motion that needs joint projection
motion = SkeletonMotion.from_file("data/retargeted_motion.npy")

# Project elbows and knees to 1-DOF hinge joints
projected_motion = project_joints(motion)

# Save the result
projected_motion.to_file("data/projected_motion.npy")

# Example retarget config JSON structure:
# {
#     "source_motion": "data/cmu_walk.npy",
#     "target_motion_path": "data/amp_humanoid_walk.npy",
#     "source_tpose": "data/cmu_tpose.npy",
#     "target_tpose": "data/amp_humanoid_tpose.npy",
#     "joint_mapping": {"Hips": "pelvis", "Spine": "torso", ...},
#     "rotation": [0.0, 0.0, 0.0, 1.0],
#     "scale": 0.01,
#     "trim_frame_beg": 0,
#     "trim_frame_end": -1,
#     "root_height_offset": 0.0
# }