robot_retargeter: mapping human and source-robot motion onto humanoid robots through inverse kinematics

From human capture to robot motion, in three stages

robot_retargeter is a toolkit for retargeting human motion in SMPL-X form, or source-robot motion, onto target humanoid robots, with side-by-side multi-robot visualization. The README describes a three-stage pipeline: extract skeletal keypoints from SMPL-X `.npz` motion or source-robot `.csv`, map those keypoints to a target robot via inverse kinematics, and play one or more retargeted robots side by side.

The user is a robotics researcher or engineer who wants to drive a humanoid robot with motion captured from humans or transferred from another robot, a common need for humanoid learning, animation and teleoperation research. Retargeting is the necessary bridge because a human skeleton and a robot's joint structure differ, so motion cannot be copied directly.

What makes it usable rather than theoretical is that the inverse-kinematics stage is concrete: the README names mink plus MuJoCo as the IK and simulation backend. That grounds the retargeting in a real physics engine and a maintained IK library rather than a bespoke solver, and the side-by-side visualization lets you compare how the same motion lands on different target robots. The repository has no license, which bounds how it can be reused.

Keypoints, inverse kinematics, and multi-robot visualization

The pipeline's three stages map onto the repository's structure. Keypoint extraction reads SMPL-X `.npz` or LAFAN1-style `.csv` and produces skeletal keypoints. Retargeting maps those keypoints to a target robot model through mink and MuJoCo, generating robot motion. Visualization plays one or more retargeted robots together. The README documents the directory layout accordingly: `asset/` holds robot models as URDF, MJCF or mesh plus SMPL-X models and the skeleton, `config/` holds per-robot and skeleton retargeting configs in YAML, `dataset/` holds input motion, and `scripts/` holds the Python pipeline.

Using inverse kinematics for the mapping is the right general approach: rather than hand-tuning joint angles, the IK solver finds robot joint configurations that place the robot's links to match the extracted keypoints, subject to the robot's own constraints. That is what lets one motion source drive robots with different kinematics.

The multi-robot visualization is more than a demo feature. Because a retargeting result depends heavily on the target robot's structure, seeing several robots perform the same source motion side by side is how you judge whether a retarget is faithful or has introduced artifacts, which is exactly the comparison a researcher needs when choosing configs or robots.

Installing and running a retarget

The setup is a clone plus a Python environment. The README recommends Python 3.10 or newer, developed on 3.11, in a fresh environment:

conda create -n robot_retargeter python=3.11 -y
conda activate robot_retargeter
pip install -e .

The README offers `pip install -r requirements.txt` as an alternative to the editable install. The pieces that are not in the repository are the SMPL-X models and the motion data, both downloaded separately under their own licenses. SMPL-X models are registered and downloaded from the official site and placed under `asset/smplx/` as `SMPLX_NEUTRAL.npz`, `SMPLX_MALE.npz` and `SMPLX_FEMALE.npz`, and a small ACCAD sample from AMASS is included for a quick trial, with more available from AMASS.

The `bash/` directory provides one-command scripts that run all three stages automatically, and the README shows overriding the target robots and motion file through environment variables:

VIS_ROBOTS="g1 jaka_pi h2 t800" \
SMPL_MOTION_FILE="dataset/ACCAD/Form_1_stageii.npz" \
./bash/retarget_from_smplx.sh

The README documents the configurable variables, including `VIS_ROBOTS` for a space-separated list of target robots, `SOURCE_FPS` defaulting to 120, and `RENDER_FPS` defaulting to 30, so a run is customized through the environment rather than editing scripts.

The limitations: external assets, IK fidelity, and no license

The honest limitations start with what you must bring. The SMPL-X models and full motion datasets are not included and carry their own license terms, so a working setup depends on registering for and downloading external assets. The bundled ACCAD sample lets you try the pipeline, but real use means obtaining SMPL-X and AMASS data yourself, which is a registration and licensing step outside the project's control.

Retargeting quality is inherently imperfect. Mapping a human skeleton onto a robot with different proportions and joint limits through inverse kinematics cannot reproduce the source motion exactly; foot contact, balance and self-collision are the usual trouble spots, and the presence of foot-contact and scaling figures in the repository suggests the authors know this is where fidelity is tested. A retarget that looks right in visualization may still not be physically valid on a real robot, so the tool is a starting point for robot motion, not a guarantee of executable motion.

The most consequential gap is legal: the repository ships no license. Under default copyright the author retains all rights, so despite being public, the code cannot be safely reused or built upon until a license is added. Anyone intending more than study should ask the author to add one.

Against writing your own IK retargeting or using a source-specific tool

The alternatives are building your own retargeting with an IK library directly, or using a tool tied to one motion source. Rolling your own with mink and MuJoCo gives full control but means writing the keypoint extraction, the per-robot config system and the visualization yourself, which is exactly the scaffolding robot_retargeter provides. A source-specific tool may handle one input format well but not span both SMPL-X human motion and source-robot CSV.

robot_retargeter's difference is that it packages the whole pipeline, extraction, IK retargeting, and side-by-side visualization, with a config system for multiple robots and one-command bash scripts, across both human and source-robot inputs. The cost is that it is research code without a license and depends on external SMPL-X and AMASS assets. Choose to build your own if you need a bespoke retargeting tightly integrated with your stack. Choose a source-specific tool if you only ever use one input format and it is well supported. Choose robot_retargeter when you want a ready pipeline to retarget SMPL-X or source-robot motion onto several humanoid targets and compare the results, understanding you must supply the external models and resolve the license question.

No license, external dependencies, and where to start

The absence of a license is the first thing to resolve. As shipped, robot_retargeter is public and runnable but not reusable in any legal sense, so anyone planning to adapt it should ask the author to add a license before investing. Its last push was on 2026-06-29, which is recent, so the project is not stale.

Beyond the license, the dependency surface is the maintenance reality: the pipeline relies on mink and MuJoCo, and on externally licensed SMPL-X and AMASS assets, so a working environment is the project plus those, each with its own versioning and terms. The `setup.py` and `requirements.txt` define the Python side, but the model and motion data are separate downloads.

The concrete first step is to run the included ACCAD sample before obtaining any external data, since it lets you exercise the full extract-retarget-visualize pipeline and confirm mink and MuJoCo are working. Use the `VIS_ROBOTS` variable to render a couple of target robots side by side on that sample, judge the retargeting fidelity, especially foot contact and balance, and only then register for SMPL-X and AMASS to run your own motions, while resolving the license question for any use beyond study.

Editorial conclusion

Use robot_retargeter if you need a ready pipeline to map SMPL-X human motion or source-robot motion onto one or more humanoid robots and compare the results: the mink-plus-MuJoCo inverse-kinematics retargeting, the YAML per-robot configs, and the side-by-side visualization driven by the VIS_ROBOTS variable are its real value. It is the wrong choice if you need physically guaranteed, executable robot motion, since IK retargeting across different kinematics is imperfect at foot contact and balance, or if you need clear reuse rights, since the repository ships no license. Start with the bundled ACCAD sample to confirm mink and MuJoCo work and judge fidelity, then register for SMPL-X and AMASS for your own motions and resolve the license question before any use beyond study.

Frequently asked questions

Official sources

1. ccrpRepo/robot_retargeter on GitHub
2. Issues
3. README