Human demonstrations capture the coordination and timing of natural movement, but a robot cannot simply copy a human joint trajectory because of different proportions, joint structures, and ranges of motion. The open‑source SOMA Retargeter (v0.2) helps convert human motion represented on the SOMA skeleton into robot‑specific joint trajectories that downstream controllers and learning pipelines can use.
What the retargeter does
SOMA Retargeter reads Biovision Hierarchy (BVH) animations defined on the SOMA base skeleton, scales the motion to the target robot’s proportions, solves for joint poses using inverse kinematics (IK), and applies configurable post‑processing. The tool outputs a CSV file containing the robot’s root position, orientation, and joint angles for each frame — a trajectory format suitable for later control or policy training.
Sources of human motion
Input motion can come from motion capture, video reconstruction, online datasets, or generative models. Converting diverse source skeletons into the SOMA representation gives the retargeter a consistent input. Examples supported within the SOMA ecosystem include:
- Motion capture data: the BONES‑SEED collection provides human mocap recordings.
- Video reconstruction: GEM‑X reconstructs whole‑body 3D human motion from a single video using the SOMA body model and demonstrates connecting video reconstruction to G1 retargeting.
- Motion generation: Kimodo and ARDY generate SOMA‑skeleton motion from text and pose constraints; Kimodo creates sequences and ARDY enables interactive steering.
Supported robots and examples (v0.2)
The SOMA Retargeter v0.2 release includes sample motions from Bones (BONES‑SEED), reference retargeting results, and configurations for five humanoid robots: Unitree G1, Unitree H2, Booster T1, AgiBot X2 Ultra, and AgiBot A3T3. These examples illustrate how joint angles and foot placement vary across embodiments due to different proportions and motion limits, and provide starting points for users to compare and refine their own outputs.
A practical example uses the supplied Unitree G1 configuration to retarget a forward walk from the sample motions. After installing SOMA Retargeter, the viewer is started with:
uv run python app/bvh_to_csv_converter.py --config assets/default_bvh_to_csv_converter_config.json --viewer gl
The BVH to CSV Converter opens with unitree_g1 selected. In Scene Options → Motion, load the bundled BVH file and then select Retarget on the BVH Motion row. The retargeter scales the source targets to G1, solves configured IK objectives per frame, and applies post‑processing. The viewer displays the human source and the retargeted robot animation side by side; gizmos let you separate and inspect them. Use the playback controls to check for a coherent forward walk and continuous motion. Save the result under CSV Motion (for example my_first_retarget.csv) to store the robot’s root pose and joint values over time.
You can compare your output to the supplied G1 reference result by loading each CSV and inspecting corresponding frames; general movement should match though exact values may vary with configuration and dependency versions. The first‑retarget guide covers this example in more detail.
Configuring a robot and refining motion
The included G1 configuration is a starting point. The Robot Configurator lets you refine an existing robot configuration or create one for a new robot by loading its robot description, aligning human and robot reference poses, adjusting scale, and mapping the source skeleton to robot body parts. The saved configuration can be reused across clips.
The retargeting solver uses Newton’s IK built with NVIDIA Warp to find joint poses that follow the scaled human targets. When a robot cannot satisfy every target simultaneously, IK weights determine which body parts take priority. The experimental IK weight optimizer tunes these weights on a small, representative set of motions by retargeting them and evaluating how closely and smoothly the robot follows the targets; selected weights are stored in the retargeting configuration.
To address artifacts such as sliding feet, the foot‑plant correction adjusts foot motion during detected contact intervals so that planted contacts in the reference motion do not conflict with downstream motion‑tracking policies. After refining a configuration on representative clips, headless batch retargeting can apply the configuration to larger motion collections without using the viewer interactively.
Using retargeted motion to train robot policies
During training, a motion‑tracking policy learns to convert the retargeted reference into control actions while observing the robot’s current state. SONIC’s training workflow includes a SOMA CSV converter for G1 that converts retargeted trajectories into SONIC’s motion‑library format. ProtoMotions is another physics‑based motion‑tracking framework; in either case the input representation and policy must match the target robot.
Simulation is the next evaluation stage, where a trained policy can be assessed for balance, ground contact, actuator limits, and tracking accuracy. In a MicroDuck experiment, BONES human motion was adapted and used to train a controller for each clip in physics simulation; comparisons show the human source, the MicroDuck reference, and the trained controller executing the motion in simulation.
Real‑time generation with MotionBricks
MotionBricks’ SOMA human model can generate continuous whole‑body motion in real time, and SOMA Retargeter can adapt those generated motions to a target robot. The MotionBricks G1 model was trained in part on BONES‑SEED motions that were adapted to G1 with the SOMA Retargeter, enabling real‑time generation of G1 motion between changing target poses. The MotionBricks paper and project video demonstrate this pipeline on a physical Unitree G1, with the G1‑specific MotionBricks model producing motion targets and SONIC controlling their execution.
Getting started
The SOMA Retargeter repository contains installation instructions, reference configurations, and examples for interactive and batch retargeting. The Robot Configurator guide explains how to add a humanoid embodiment, and the batch‑retargeting guide covers processing motion collections for a target robot. Louis Marcoux is acknowledged for contributing to the work discussed in the blog.
SOMA Retargeter offers a complete path from human demonstrations (capture, reconstruction, or generation) through retargeting and post‑processing to CSV trajectories usable for policy training and simulation evaluation of humanoid robots.
