Key features of GMR:

• Real-time high-quality retargeting, unlock the potential of real-time whole-body teleoperation, i.e., TWIST.
• Carefully tuned for good performance of RL tracking policies.
• Support multiple humanoid robots and multiple human motion data formats (See our table below).

NOTE: If you want this repo to support a new robot or a new human motion data format, send the robot files (.xml (must), .urdf (must), and meshes (must)) / human motion data to Yanjie Ze or create an issue, we will support it as soon as possible. Please make sure the robot files you sent can be open-sourced in this repo.

This repo is licensed under the MIT License.

Starting from its release, GMR is massively used by the community. See below for cool papers that use GMR:

• arXiv 2025.08, HITTER: A HumanoId Table TEnnis Robot via Hierarchical Planning and Learning
• arXiv 2025.08, Switch4EAI: Leveraging Console Game Platform for Benchmarking Robotic Athletics
• arXiv 2025.05, TWIST: Teleoperated Whole-Body Imitation System

• add doc on ik config offset
• support xsens data

• 2025-10-09: Check TWIST open-sourced code for RL motion tracking.
• 2025-10-02: Tech report for GMR is now on arXiv.
• 2025-10-01: GMR now supports converting GMR pickle files to CSV (for beyondmimic), check scripts/batch_gmr_pkl_to_csv.py.
• 2025-09-25: An introduction on GMR is available on Bilibili.
• 2025-09-16: GMR now supports to use GVHMR for extracting human pose from monocular video and retargeting to robot.
• 2025-09-12: GMR now supports Tienkung, the 14th humanoid robot in the repo.
• 2025-08-30: GMR now supports Unitree H1 2 and PND Adam Lite, the 12th and 13th humanoid robots in the repo.
• 2025-08-28: GMR now supports Booster T1 for both 23dof and 29dof.
• 2025-08-28: GMR now supports using exported offline FBX motion data from OptiTrack.
• 2025-08-27: GMR now supports Berkeley Humanoid Lite, the 11th humanoid robot in the repo.
• 2025-08-24: GMR now supports Unitree H1, the 10th humanoid robot in the repo.
• 2025-08-24: GMR now supports velocity limits for the robot motors, use_velocity_limit=True by default in GeneralMotionRetargeting class (and we use 3*pi as the velocity limit by default); we also add printing of robot DoF/Body/Motor names and their IDs by default, and you can access them via robot_dof_names, robot_body_names, and robot_motor_names attributes.
• 2025-08-10: GMR now supports Booster K1, the 9th robot in the repo.
• 2025-08-09: GMR now supports Unitree G1 with Dex31 hands.
• 2025-08-07: GMR now supports Galexea R1 Pro (this is a wheeled humanoid robot!) and KUAVO, the 7th and 8th humanoid robots in the repo.
• 2025-08-06: GMR now supports HighTorque Hi, the 6th humanoid robot in the repo.
• 2025-08-04: Initial release of GMR. Check our twitter post.

Demo 1: Retargeting LAFAN1 dancing motion to 5 different robots (Unitree G1, Booster T1, Stanford ToddlerBot, Fourier N1, and ENGINEAI PM01):

Demo 2: Galexea R1 Pro, a wheeled humanoid robot, doing human motion

Demo 3: Screen recording of my one command line usage. Switch robots with just changign an argument.

Demo 4: HighTorque robot doing a twist dance

Demo 5: Kuavo robot picking up a box

Demo 6: Unitree H1 doing ChaCha dance

Demo 7: Booster T1 23dof/29dof doing some jumping

Demo 8: Unitree H1 2 doing some jumping

Demo 9: PND Adam lite

Demo 10: Tienkung Walking

Demo 11: extract human pose from monocular video with GVHMR and retarget with GMR

Watch on Bilibili »

The code is tested on Ubuntu 22.04/20.04.

# create conda env
conda create -n gmr python=3.10 -y
conda activate gmr

# install GMR
pip install -e .

# NOTE: after install SMPLX, change `ext` in `smplx/body_models.py` from `npz` to `pkl` if you are using SMPL-X pkl files.

# to resolve some possible rendering issues
conda install -c conda-forge libstdcxx-ng -y

[SMPLX body model] download SMPL-X body models to assets/body_models from SMPL-X and then structure as follows:

- assets/body_models/smplx/
-- SMPLX_NEUTRAL.pkl
-- SMPLX_FEMALE.pkl
-- SMPLX_MALE.pkl

[AMASS motion data] download raw SMPL-X data to any folder you want from AMASS. NOTE: Do not download SMPL+H data.

[OMOMO motion data] download raw OMOMO data to any folder you want from this google drive file. And process the data into the SMPL-X format using scripts/convert_omomo_to_smplx.py.

[LAFAN1 motion data] download raw LAFAN1 bvh files from the official repo, i.e., lafan1.zip.

To better use this library, you can first have an understanding of the human motion data we use and the robot motion data we obtain.

Each frame of human motion data is formulated as a dict of (human_body_name, 3d global translation + global rotation).

Each frame of robot motion data can be understood as a tuple of (robot_base_translation, robot_base_rotation, robot_joint_positions).

NOTE: after install SMPL-X, change ext in smplx/body_models.py from npz to pkl if you are using SMPL-X pkl files.

Retarget a single motion:

# single motion
python scripts/smplx_to_robot.py --smplx_file <path_to_smplx_data> --robot <path_to_robot_data> --save_path <path_to_save_robot_data.pkl> --rate_limit

By default you should see the visualization of the retargeted robot motion in a mujoco window. If you want to record video, add --record_video and --video_path <your_video_path,mp4>.

• --rate_limit is used to limit the rate of the retargeted robot motion to keep the same as the human motion. If you want it as fast as possible, remove --rate_limit.

Retarget a folder of motions:

python scripts/smplx_to_robot_dataset.py --src_folder <path_to_dir_of_smplx_data> --tgt_folder <path_to_dir_to_save_robot_data> --robot <robot_name>

By default there is no visualization for batch retargeting.

First, install GVHMR by following their official instructions.

And run their demo that can extract human pose from monocular video:

# in GVHMR repo
python tools/demo/demo.py --video=docs/example_video/tennis.mp4 -s

Then you should obtain the saved human pose data in GVHMR/outputs/demo/tennis/hmr4d_results.pt.

Then, run the command below to retarget the extracted human pose data to your robot:

python scripts/gvhmr_to_robot.py --gvhmr_pred_file <path_to_hmr4d_results.pt> --robot unitree_g1 --record_video

Retarget a single motion:

# single motion
python scripts/bvh_to_robot.py --bvh_file <path_to_bvh_data> --robot <path_to_robot_data> --save_path <path_to_save_robot_data.pkl> --rate_limit

By default you should see the visualization of the retargeted robot motion in a mujoco window.

• --rate_limit is used to limit the rate of the retargeted robot motion to keep the same as the human motion. If you want it as fast as possible, remove --rate_limit.

Retarget a folder of motions:

python scripts/bvh_to_robot_dataset.py --src_folder <path_to_dir_of_bvh_data> --tgt_folder <path_to_dir_to_save_robot_data> --robot <robot_name>

By default there is no visualization for batch retargeting.

Retarget a single motion:

1. Install fbx_sdk by following these instructions and these instructions. You will probably need a new conda environment for this.
2. Activate the conda environment where you installed fbx_sdk. Use the following command to extract motion data from your .fbx file:

cd third_party
python poselib/fbx_importer.py --input <path_to_fbx_file.fbx> --output <path_to_save_motion_data.pkl> --root-joint <root_joint_name> --fps <fps>

3. Then, run the command below to retarget the extracted motion data to your robot:

conda activate gmr
# single motion
python scripts/fbx_offline_to_robot.py --motion_file <path_to_saved_motion_data.pkl> --robot <path_to_robot_data> --save_path <path_to_save_robot_data.pkl> --rate_limit

By default you should see the visualization of the retargeted robot motion in a mujoco window.

• --rate_limit is used to limit the rate of the retargeted robot motion to keep the same as the human motion. If you want it as fast as possible, remove --rate_limit.

We provide the script to use OptiTrack MoCap data for real-time streaming and retargeting.

Usually you will have two computers, one is the server that installed with Motive (Desktop APP for OptiTrack) and the other is the client that installed with GMR.

Find the server ip (the computer that installed with Motive) and client ip (your computer). Set the streaming as follows:

And then run:

python scripts/optitrack_to_robot.py --server_ip <server_ip> --client_ip <client_ip> --use_multicast False --robot unitree_g1

You should see the visualization of the retargeted robot motion in a mujoco window.

python scripts/vis_robot_motion.py --robot <robot_name> --robot_motion_path <path_to_save_robot_data.pkl>

If you want to record video, add --record_video and --video_path <your_video_path,mp4>.

If you find our code useful, please consider citing our related papers:

@article{joao2025gmr,
title={Retargeting Matters: General Motion Retargeting for Humanoid Motion Tracking},
author= {Joao Pedro Araujo and Yanjie Ze and Pei Xu and Jiajun Wu and C. Karen Liu},
year= {2025},
journal= {arXiv preprint arXiv:2510.02252}
}

@article{ze2025twist,
title={TWIST: Teleoperated Whole-Body Imitation System},
author= {Yanjie Ze and Zixuan Chen and João Pedro Araújo and Zi-ang Cao and Xue Bin Peng and Jiajun Wu and C. Karen Liu},
year= {2025},
journal= {arXiv preprint arXiv:2505.02833}
}

and this github repo:

@software{ze2025gmr,
title={GMR: General Motion Retargeting},
author= {Yanjie Ze and João Pedro Araújo and Jiajun Wu and C. Karen Liu},
year= {2025},
url= {https://github.com/YanjieZe/GMR},
note= {GitHub repository}
}

Designing a single config for all different humans is not trivial. We observe some motions might have bad retargeting results. If you observe some bad results, please let us know! We now have a collection of such motions in TEST_MOTIONS.md.

Our IK solver is built upon mink and mujoco. Our visualization is built upon mujoco. The human motion data we try includes AMASS, OMOMO, and LAFAN1.

The original robot models can be found at the following locations:

• Booster T1: Official website (English).
• EngineAI PM01: Link to file
• Fourier N1: Link to file
• Toddlerbot: Link to file
• Unitree G1: Link to file
• HighToqure Hi
• Galaxea R1 Pro: MIT license
• LEJU Kuavo S45: MIT license
• Berkley Humanoid Lite: CC-BY-SA-4.0 license
• Booster K1