README.md

Agility Meets Stability: Versatile Humanoid Control with Heterogeneous Data

Motion Generation

Contents

• 🏠 Description
• 📦 Setup
• 📚 Usage
• 🔗 Citation
• 📄 License
• 👏 Acknowledgements

🏠 Description

Implementation for “Agility Meets Stability: Versatile Humanoid Control with Heterogeneous Data”, built on Pyroki. Generates stable balance motions for the 29-DoF Unitree G1.

https://github.com/user-attachments/assets/f2b0baa8-7590-4255-9406-594e3957dda9

📦 Setup

conda create -n motion_gen python=3.10
conda activate motion_gen

git clone https://github.com/chungmin99/pyroki.git
cd pyroki && pip install -e . && cd ..

pip install -r requirements.txt

📚 Usage

The motion generation pipeline consists of three main stages: generation, quality assurance (collision checking), and data filtering.

1. Generate motions

Generate stable balance sequences for the Unitree G1.

python g1_sample_sequences.py \
  --sample.num-samples 4 \
  --sample.side both \
  --seq.num-steps 60

Common knobs:

• --sample.output-path PATH (default: motions/g1/sampled_static_poses)
• --sample.max-retries INT
• --sample.float-x-range xmin xmax
• --sample.float-y-abs-range ymin ymax
• --sample.float-z-range zmin zmax
• --sample.pelvis-height-range zmin zmax
• --seq.enable-collision-check BOOL

Output goes to --sample.output-path/<timestamp>/*.pkl.

Output format

Each *.pkl is a dict with one key; value contains:

• root_trans_offset: (T, 3) root position
• root_rot: (T, 4) quaternion xyzw
• dof: (T, 29) joint DoFs
• pose_aa: (T, 30, 3) axis-angle (root + joints)
• fps: int
• stance_leg: "left" / "right"

2. Motion Validation Check

Detect self-collision and ground penetration using the MuJoCo engine.

python scripts/auto_check.py \
  --motion_folder motions/g1/sampled_static_poses/<timestamp> \
  --robot_type unitree_g1 \
  --batch_size 100

Results are written under annotations/<motion_folder_name>/ (progress + abnormal-only reports/annotations).

3. Filter and Merge

Finalize the dataset by removing "abnormal" motions identified in the motion validation step.

python scripts/process_annotations_to_pkl.py \
  -a annotations/<folder>/auto_check_annotations.json \
  --motion_source motions/g1/sampled_static_poses/<timestamp> \
  --save_name filtered_motions

We provide a synthetic balance motion dataset with approximately 10,000 sequences generated using the above pipeline.

• Hugging Face: download from the hugging face dataset page: 🤗 Hugging Face
• Git LFS: clone this repo with Git LFS to fetch the .pkl via git lfs pull.

---

Motion Visualization

We provide a visualization tool to help inspecting the generated motions.

python scripts/vis_motion.py path/to/motion.pkl \
  --urdf robot/unitree_description/urdf/g1/g1_sysid_29dof.urdf \
  --fps 30

🔗 Citation

@article{pan2025ams,
  title={Agility Meets Stability: Versatile Humanoid Control with Heterogeneous Data},
  author={Pan, Yixuan and Qiao, Ruoyi and Chen, Li and Chitta, Kashyap and Pan, Liang and Mai, Haoguang and Bu, Qingwen and Zheng, Cunyuan and Zhao, Hao and Luo, Ping and Li, Hongyang},
  journal={arXiv preprint arXiv:2511.17373},
  year={2025}
}

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👏 Acknowledgements

• Pyroki: We thank the pyroki library for providing a toolkit for kinematic optimization.