This framework provides a suite of motion imitation algorithms for training motion controllers. This codebase includes implementations of:
We also include the following RL algorithms:
Install IsaacGym: https://developer.nvidia.com/isaac-gym
Install requirements:
pip install -r requirements.txt
Download assets and motion data from here, then extract the contents into data/.
To train a model, run the following command:
python mimickit/run.py --mode train --num_envs 4096 --env_config data/envs/deepmimic_humanoid_env.yaml --agent_config data/agents/deepmimic_humanoid_ppo_agent.yaml --visualize true --log_file output/log.txt --out_model_file output/model.pt
--modeselects eithertrainortestmode.--num_envsspecifies the number of parallel environments used for simulation.--env_configspecifies the configuration file for the environment.--agent_configspecifies configuration file for the agent.--visualizeenables visualization. Rendering should be disabled for faster training.--log_filespecifies the output log file, which will keep track of statistics during training.--out_model_filespecifies the output model file, which contains the model parameters.--loggerspecifies the logger used to record training stats. The options are tensorboardtborwandb.
Instead of specifying all arguments through the command line, arguments can also be loaded from an arg_file:
python mimickit/run.py --arg_file args/deepmimic_humanoid_ppo_args.txt --visualize true
The arguments in arg_file are treated the same as command line arguments. Arguments for all algorithms are provided in args/.
To test a model, run the following command:
python mimickit/run.py --arg_file args/deepmimic_humanoid_ppo_args.txt --num_envs 4 --visualize true --mode test --model_file data/models/deepmimic_humanoid_spinkick_model.pt
--model_filespecifies the.ptfile that contains the parameters of the trained model. Pretrained models are available indata/models/.
To use distributed training with multi-CPU or multi-GPU:
python mimickit/run.py --arg_file args/deepmimic_humanoid_ppo_args.txt --num_workers 2 --device cuda:0
--num_workersspecifies the number of worker processes used to parallize training.--devicespecifies the device used for training, which can becpuorcuda:0. When training with multiple GPUs, the number of worker processes used to parallize training must be less than or equal to the number of GPUs available on the system.
When using the tensorboard logger during training, a tensorboard events file will be saved the same output directory as the log file. The log can be viewed with:
tensorboard --logdir=output/ --port=6006 --bind_all --samples_per_plugin scalars=999999
The output log .txt file can also be plotted using the plotting script plot_log.py.
Motion data is stored in data/motions/. The motion_file field in the environment configuration file can be used to specify the reference motion clip. In addition to imitating individual motion clips, motion_file can also specify a dataset file, located in data/datasets/, which will train a model to imitate a dataset containing multiple motion clips.
The view_motion environment can be used to visualize motion clips:
python mimickit/run.py --mode test --arg_file args/view_motion_humanoid_args.txt --visualize true
Motion clips are represented by the Motion class implemented in motion.py. Each motion clip is stored in a .pkl file. Each frame in the motion specifies the pose of the character according to
[root position (3D), root rotation (3D), joint rotations]
where 3D rotations are specified using 3D exponential maps. Joint rotations are recorded in the order that the joints are specified in the .xml file (i.e. depth-first traversal of the kinematic tree). For example, in the case of humanoid.xml, each frame is represented as
[root position (3D), root rotation (3D), abdomen (3D), neck (3D), right_shoulder (3D), right_elbow (1D), left_shoulder (3D), left_elbow (1D), right_hip (3D), right_knee (1D), right_ankle (3D), left_hip (3D), left_knee (1D), left_ankle (3D)]
The rotations of 3D joints are represented using 3D exponential maps, and the rotations of 1D joints are represented using 1D rotation angles.
If you find this codebase helpful, please cite:
@misc{MimicKit,
title = {MimicKit},
author = {Peng, Xue Bin},
year = {2025},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/xbpeng/MimicKit}},
}
Please also consider citing the relevant papers:
@article{
2018-TOG-deepMimic,
author = {Peng, Xue Bin and Abbeel, Pieter and Levine, Sergey and van de Panne, Michiel},
title = {DeepMimic: Example-guided Deep Reinforcement Learning of Physics-based Character Skills},
journal = {ACM Trans. Graph.},
issue_date = {August 2018},
volume = {37},
number = {4},
month = jul,
year = {2018},
issn = {0730-0301},
pages = {143:1--143:14},
articleno = {143},
numpages = {14},
url = {http://doi.acm.org/10.1145/3197517.3201311},
doi = {10.1145/3197517.3201311},
acmid = {3201311},
publisher = {ACM},
address = {New York, NY, USA},
keywords = {motion control, physics-based character animation, reinforcement learning},
}
@article{
AWRPeng19,
author = {Xue Bin Peng and Aviral Kumar and Grace Zhang and Sergey Levine},
title = {Advantage-Weighted Regression: Simple and Scalable Off-Policy Reinforcement Learning},
journal = {CoRR},
volume = {abs/1910.00177},
year = {2019},
url = {https://arxiv.org/abs/1910.00177},
archivePrefix = {arXiv},
eprint = {1910.00177},
timestamp = {Tue, 01 October 2019 11:27:50 +0200},
bibsource = {dblp computer science bibliography, https://dblp.org}
}
@article{
2021-TOG-AMP,
author = {Peng, Xue Bin and Ma, Ze and Abbeel, Pieter and Levine, Sergey and Kanazawa, Angjoo},
title = {AMP: Adversarial Motion Priors for Stylized Physics-Based Character Control},
journal = {ACM Trans. Graph.},
issue_date = {August 2021},
volume = {40},
number = {4},
month = jul,
year = {2021},
articleno = {1},
numpages = {15},
url = {http://doi.acm.org/10.1145/3450626.3459670},
doi = {10.1145/3450626.3459670},
publisher = {ACM},
address = {New York, NY, USA},
keywords = {motion control, physics-based character animation, reinforcement learning},
}
@article{
2022-TOG-ASE,
author = {Peng, Xue Bin and Guo, Yunrong and Halper, Lina and Levine, Sergey and Fidler, Sanja},
title = {ASE: Large-scale Reusable Adversarial Skill Embeddings for Physically Simulated Characters},
journal = {ACM Trans. Graph.},
issue_date = {August 2022},
volume = {41},
number = {4},
month = jul,
year = {2022},
articleno = {94},
publisher = {ACM},
address = {New York, NY, USA},
keywords = {motion control, physics-based character animation, reinforcement learning}
}
@inproceedings{
zhang2025ADD,
author={Zhang, Ziyu and Bashkirov, Sergey and Yang, Dun and Shi, Yi and Taylor, Michael and Peng, Xue Bin},
title = {Physics-Based Motion Imitation with Adversarial Differential Discriminators},
year = {2025},
booktitle = {SIGGRAPH Asia 2025 Conference Papers (SIGGRAPH Asia '25 Conference Papers)}
}