Retarget parkour, dance, and interaction clips onto any humanoid in ~30 seconds.
Download · Run from source · Docs · Project page · 中文说明
| Workflow | How it works |
|---|---|
| Motion → Robot | Load a clip → pick a robot → calibrate once → retarget → export. Newton IK for flat motion; MPC-SQP interaction mesh for terrain and objects. |
| Robot → Robot | Retarget existing robot trajectories (CSV, PKL, IsaacLab NPZ) onto a new URDF. |
| Video → Motion | Run official GVHMR on a video and add the result to your Motion Library (optional, needs CUDA). |
| Dataset analysis | Point at a folder → scan, tag, embed, and cluster → export a subset. |
- Bring any robot. Drag in a URDF and its meshes; joints are detected automatically.
- Bring your data. BVH, GLB, and the SMPL family, with adapters for AMASS, LAFAN, 100STYLE, OMOMO, OmniContact, PHUMA, and more.
- Trust the result. Diagnostics compare the robot with the IK targets it tracked and grade the error relative to robot height.
- Automate it. Batch from the CLI, or drive jobs from an agent over JSON CLI or MCP.
The desktop app is the quickest way to start. It includes 30 motions and seven robots: ROBOTO 01, Unitree G1, ROBOTO_ORIGIN, AgiBot X2, Asimov 1, Fourier GR-2, and Berkeley Humanoid Lite.
| Platform | Download (0.1.6) | Good to know |
|---|---|---|
| Windows x64 | EXE installer | Ready to run, no Python needed. Self-signed, so SmartScreen may warn. |
| Linux amd64 | Debian package | First launch sets up a private Python environment (needs internet). |
| macOS 12+, Apple Silicon | DMG installer | Same first-launch setup. Not notarized; allow it under Privacy & Security. Retargets on CPU, no Video → Motion. |
See the installation guide for step-by-step instructions and checksums, or browse all releases.
Install uv, then:
git clone https://github.com/Roboparty/human-humanoid-tools.git
cd human-humanoid-tools
uv sync --locked --extra all
uv run python scripts/install_builtin_robots.py # add --only rp1 for a single robot
uv run hhtools web # then open http://127.0.0.1:8009Linux and Windows use an NVIDIA GPU (CUDA 12) when available. Smaller installs are covered in the installation guide.
All of them share the same motion, robot, and retargeting core.
| Mode | Best for | Launch |
|---|---|---|
| Desktop app | Getting started, no terminal needed | Application menu or hhtools-desktop |
| WebUI | Interactive work on a workstation or server | uv run hhtools web |
| CLI | Large datasets, SSH, and scripts | uv run hhtools ... |
| Agent | Scripted H2R, scene-free R2R, and batch jobs (a subset of the WebUI) | hhtools agent / hhtools-mcp |
| Guide | What's inside |
|---|---|
| Installation | Desktop setup per platform, checksums, source install options |
| CLI and batch jobs | Commands, converting and importing data, offline batch retargeting |
| Robot tuning | Adding robots, robot.yaml fields, fixing common pose problems |
| Datasets | Supported datasets, where to get them, per-dataset notes |
| Video → Motion | Setting up GVHMR on Linux and Windows |
| Agent and MCP | Installation, scope, and the smoke-first workflow |
| Job scheduling | Limiting concurrent jobs on shared or memory-constrained GPUs |
| Desktop packaging | Building the desktop packages |
| Architecture · Contributing | How the code is organized and how to work on it |
Suggestions and ideas are welcome, so please open an issue. New feature requests will be considered once the core functionality is stable.
If you use HHTools in research or products, please cite this repository, along with the upstream datasets and solvers you rely on (see Datasets and NOTICE).
@software{human_humanoid_tools2026,
title = {human-humanoid-tools (hhtools): humanoid motion retargeting and dataset analysis},
author = {jaggerShen and hhtools contributors},
year = {2026},
url = {https://github.com/Roboparty/human-humanoid-tools},
license = {Apache-2.0}
}Code is Apache-2.0; third-party notices are in NOTICE. Datasets are not redistributed. SMPL, SMPL-H, and SMPL-X weights are not included: register with MPI and follow the body model guide. Without them, parameter clips still load as an animated skeleton, but the exact body mesh and joint regression are unavailable.