human-humanoid-tools (hhtools)

Retarget parkour, dance, and interaction clips onto any humanoid in ~30 seconds

Project page · 中文说明

---

We welcome suggestions and ideas — please open an issue or discussion anytime. New feature requests will be considered once the core functionality is stable.

---

Highlights

• Fast retarget — drag a human clip, pick a robot, export CSV/ZIP; Newton IK + MPC-SQP interaction mesh.
• Human formats — BVH / GLB / SMPL family; adapters for AMASS, GVHMR, LAFAN, OMOMO, PHUMA, intermimic, meshmimic, …
• Any URDF — upload any robot in the Web UI: drag in the URDF, drag in meshes; auto-detected, no manual tuning.
• Robot→robot (R2R) — retarget existing robot CSV/PKL exports onto a new URDF.
• Dataset analysis — scan, tag, embed, cluster, and subset human or robot motion libraries in the Web UI.

Requirements: Linux, Python 3.12+. Preview on CPU; retarget needs NVIDIA GPU (CUDA 12).

---

Quick start

git clone https://github.com/Roboparty/human-humanoid-tools.git
cd human-humanoid-tools
curl -LsSf https://astral.sh/uv/install.sh | sh   # if needed
uv sync --extra all
uv run hhtools web

Open http://127.0.0.1:8009.

Panel	Flow
Motion → Robot	Load clip → select robot → calibrate (once) → retarget → download CSV/ZIP
Robot → Robot	Source robot + trajectory → target URDF → calibrate → retarget / batch ZIP
Dataset analysis	Drop a folder → analyze → explore tags & scatter → export subset

Robot tuning: edit configs/robots/unitree_g1/ or uploaded ~/.config/hhtools/robots/<name>/robot.yaml; run hhtools robot validate <name>. Details in framework.md.

Tuning robot.yaml

Paths: bundled presets under configs/robots/<name>/; Web uploads under ~/.config/hhtools/robots/<name>/. Yaml edits apply on the next retarget (no Web restart). Restart hhtools web only after upgrading the Python package.

Section	Purpose
ik_map	Canonical human joint → URDF link. On 3-DOF hips/shoulders, map to the middle link (usually *_roll_link).
weights	IK priorities: t_weight (position), r_weight (orientation).
smooth_joint_filter_masks	High-impact IK regulariser (pairs with default smooth_joint_filter_weight: 5.5 in the pipeline). Per-link values in [0, 1] scale a midpoint pull on each joint — not the same as weights. Scaffold defaults (*_shoulder_roll_link: 1.0) suit G1/RP1-style gimbals where roll is null-space; on uploaded URDFs whose arm pose is driven mainly by shoulder roll, 1.0 can lock the arms open and block tracking even when weights look correct. Lower roll to 0.1–0.3 (or 0 for max arm freedom) if retarget arms stay abducted while the yellow overlay hangs down; keep pitch/yaw masks moderate for stability.
retarget.joint_scale_multipliers	Optional. Per-canonical absolute scale overrides (same units as calibration derived.scales) for manual proportion tweaks without re-calibrating. Example: left_shoulder: 0.5 narrows the upper body. Do not paste a calibration's derived.scales table here (it pollutes other human-reference formats). Values that match the current or any on-disk retarget_calibration_*.yaml scales (or leftover scaffold zero-pose defaults) are ignored. Shoulders affect lateral IK + shoulder roll only (not vertical height).
retarget.feet_stabilizer, apply_feet_stabilizer	Foot planting and body-ground clearance; set apply_feet_stabilizer: false for rolls / flips.
retarget.references.<format>	Per motion-format overrides (e.g. bundled scaler_config).

retarget:
  joint_scale_multipliers:
    left_shoulder: 0.5
    right_shoulder: 0.5
    left_elbow: 1.0
    # … other ik_map keys; omit or leave at calibration values for no change

smooth_joint_filter_masks example — if arms stay in an A-pose while mocap arms hang down, check this before only tweaking weights:

smooth_joint_filter_masks:
  left_shoulder_pitch_link: 0.1
  left_shoulder_roll_link: 0.1   # not 1.0 when roll must move for arm tracking
  left_shoulder_yaw_link: 0.3
  right_shoulder_pitch_link: 0.1
  right_shoulder_roll_link: 0.1
  right_shoulder_yaw_link: 0.3

Template and field notes: configs/robots/_template/robot.yaml. Re-uploading a URDF regenerates robot.yaml from the URDF (calibration files are kept; hand-edited ik_map / weights may be overwritten).

---

Demo clips (assets/motions)

Demo paths only — download full datasets from upstream. Adapters provided; no dataset redistribution.

Mode	Dataset	Paper	Download
mimic	AMASS	arXiv	site
mimic	GVHMR	arXiv	GitHub
mimic	LAFAN1	arXiv	GitHub
mimic	Motion-X	NeurIPS	GitHub
mimic	PHUMA	arXiv	GitHub
mimic	SOMA	arXiv	Hugging Face
intermimic	OMOMO	arXiv	Hugging Face
meshmimic	holosoma	arXiv	GitHub
meshmimic	PARC MS	arXiv	Hugging Face

---

Citation

If you use human-humanoid-tools in research or products, please cite the repository:

@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}
}

Links: GitHub repository · Issues · LICENSE

When publishing results built on bundled adapters, also cite the upstream datasets and solvers listed above and in NOTICE (e.g. SOMA-Retargeter, holosoma).

---

License & assets

• Code: Apache-2.0 · third-party: NOTICE
• SMPL / SMPL-H / SMPL-X weights: not included; register at MPI and place under configs/body_models/ — see configs/body_models/README.md
• More docs: framework.md · CONTRIBUTING.md