eden-soma-retargeter 0.1.1

No project description provided

Note: This is an unofficial fork of https://github.com/NVIDIA/soma-retargeter.

SOMA Retargeter

Convert SOMA human motion captures into humanoid robot joint animation. Takes BVH motion files as input and produces robot-playable CSV joint data as output using GPU-optimized inverse kinematics via Newton and high-performance computation with NVIDIA Warp.

The retargeting pipeline handles proportional human-to-robot scaling, multi-objective IK solving with joint limits, feet stabilization to maintain ground contact, and per-DOF joint limit clamping. Currently supports SOMA as the input skeleton and Unitree G1 (29 DOF) as the output robot. Additional robot targets are planned.

SOMA Retargeter is part of the SOMA body model ecosystem for humanoid motion data.

Note: This project is in active development. The API may change between releases as the design is refined.

Requirements

• Python: 3.12
• Git LFS: Installed and initialized for asset downloads
• OS: Windows (x86-64) and Linux (x86-64, aarch64)
• GPU: NVIDIA GPU (Maxwell or newer), driver 545+ (CUDA 12). No local CUDA Toolkit installation required.

Installation

From PyPI (recommended)

pip install eden-soma-retargeter
soma-bvh-to-csv --help

This installs the soma_retargeter Python package and the soma-bvh-to-csv console script. The default retargeting config and the SOMA zero-frame BVH ship inside the wheel, so no LFS checkout is needed for the standard pipeline.

Runtime requirements: Python 3.12, NVIDIA GPU (Maxwell or newer), driver 545+.

From source (for contributors)

LFS only needs to be pulled if you plan to use the sample motions in assets/motions/ or rebuild the docs in assets/docs/. The wheel itself bundles only the default config and the SOMA zero-frame BVH that already live under soma_retargeter/configs/.

Method 1 (conda + pip)

1. Create and Activate Conda Environment

conda create -n soma-retargeter python=3.12 -y
conda activate soma-retargeter

2. Download LFS Assets

git lfs pull

3. Install the Library

pip install .

Method 2 (uv)

1. Install uv

Follow the official installation guide if uv is not yet installed.

2. Download LFS Assets

git lfs pull

3. Sync the Project

uv sync creates an isolated .venv virtual environment inside the project directory, installs the correct Python version and resolves all dependencies.

uv sync

Platform-specific notes

Note (Linux): For the GUI viewer to work, install tkinter

sudo apt-get install python3.12-tk

Note (Windows): If imgui-bundle fails to install, the Microsoft Visual C++ Redistributables may be missing. Download from the official Microsoft documentation.

Motion Data

This repo includes 10 sample BVH/CSV pairs in assets/motions/ for immediate testing.

For large-scale motion data, see the SEED dataset (Skeletal Everyday Embodiment Dataset) published by Bones Studio. SEED provides a large-scale collection of human motions on the SOMA uniform-proportion skeleton, which is the expected input format for this tool. The G1 robot motion data included in SEED was retargeted using SOMA Retargeter.

Quick Start

When using uv, replace soma-bvh-to-csv with uv run soma-bvh-to-csv in the commands below.

Interactive viewer (OpenGL)

soma-bvh-to-csv --viewer gl

This uses the bundled default config. To override:

soma-bvh-to-csv --config ./my_config.json --viewer gl

The viewer displays the source SOMA motion alongside the retargeted robot in a 3D viewport. Use the right panel to load BVH files, run retargeting, and save CSV output. Playback controls at the bottom allow scrubbing, speed adjustment, and looping. Toggle visibility of the skinned mesh, skeleton, joint axes, and positioning gizmos.

Batch conversion (headless)

Process a folder of BVH files without a display. Set import_folder and export_folder in the config file, then run:

soma-bvh-to-csv --config ./my_config.json --viewer null

Batch mode recursively finds all .bvh files in the import folder, processes them in configurable batch sizes, and writes CSV files to the export folder mirroring the input directory structure.

The same entry point is also reachable as a Python module, useful for embedding in other tools:

python -m soma_retargeter.app.bvh_to_csv_converter --viewer null

Code Overview

soma_retargeter/

Module	Description
app/bvh_to_csv_converter.py	Main entry point (also exposed as the soma-bvh-to-csv console script). Drives both interactive and headless batch retargeting modes.
animation/	Core data structures for skeletons, animation buffers, IK, and skinned meshes.
assets/	File I/O for BVH, CSV, and USD formats.
pipelines/	Retargeting pipeline: IK solving, feet stabilization, and joint limit clamping.
robotics/	Human-to-robot scaling and robot output formatting.
renderers/	Visualization for the interactive viewer.
utils/	Math, pose, coordinate conversion, Newton and Warp helpers.
configs/	JSON configuration for retargeting, scaling, and feet stabilization parameters, plus the default default_bvh_to_csv_converter_config.json shipped with the wheel.

Related Work

SOMA Retargeter is a support tool within the SOMA ecosystem for humanoid motion data:

• SOMA Body Model - Parametric human body model with standardized skeleton, mesh, and shape parameters
• GEM-X - Human motion estimation from video
• Kimodo - Kinematic motion diffusion model for text and constraint-driven 3D human and robot motion generation
• ProtoMotions - GPU-accelerated simulation and learning framework for training physically simulated digital humans and humanoid robots
• SONIC - Whole-body control for humanoid robots, training locomotion and interaction policies

Acknowledgments

This project draws inspiration and builds upon excellent open-source work, including:

• GMR - General Motion Retargeting
• PyRoki - A Modular Toolkit for Robot Kinematic Optimization

License

This codebase is licensed under Apache-2.0.

This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.