Soma-retargeter

Soma-retargeter converts human motion into AI Sapiens CSV joint data. It accepts SOMA BVH, converted SOMA77/Kimodo NPZ, and, with the optional SOMA-X runtime, raw SMPL-family NPZ motion. It then solves the target robot pose with Newton and NVIDIA Warp and writes AI Sapiens .csv files.

For AI Sapiens, use the ROBOTIS-GIT/soma-retargeter fork. It includes the AI Sapiens retarget target, MJCF generation, and CSV export layout used in the AI Sapiens motion workflow.

Raw SMPL, SMPL-H, and SMPL-X motion can now be converted to SOMA77 and retargeted in one GUI or headless workflow. Existing BVH-only workflows remain available and do not require SOMA-X or a human model file.

info

Use the ROBOTIS soma-retargeter fork for AI Sapiens integration. Upstream research remains from NVIDIA (NVIDIA/soma-retargeter). Prefer the ROBOTIS repo and install steps below for the latest fork-specific options.

AI Sapiens Soma-retargeter Demo

Resources

• ROBOTIS Soma-retargeter repository (recommended)
• AI Sapiens submodule source
• Installation and conversion steps on this page
• Upstream NVIDIA Soma-retargeter
• SOMA-X preprocessing guide
• Official NVIDIA SOMA-X repository
• Newton physics
• NVIDIA Warp
• SEED dataset

Workflow

The AI Sapiens workflow is driven by:

assets/default_ai_sapiens_bvh_to_csv_converter_config.json

Key settings:

Area	AI Sapiens setting
Retarget target	ai_sapiens
Converter config	assets/default_ai_sapiens_bvh_to_csv_converter_config.json
Retargeter config	soma_retargeter/configs/ai_sapiens/soma_to_ai_sapiens_retargeter_config.json
Retarget MJCF	soma_retargeter/configs/ai_sapiens/ai_sapiens_retarget.xml
AI Sapiens target URDF	third_party/ai_sapiens/ai_sapiens_description/urdf/k1_rev1/k1.urdf
AI Sapiens visual meshes	third_party/ai_sapiens/ai_sapiens_description/meshes/k1_rev1/
CSV output layout	AISapiens23DOF_CSVConfig

The accepted input paths are:

• SOMA input (.bvh or SOMA77/Kimodo .npz): Load it directly into Soma-retargeter and export AI Sapiens CSV.
• Raw SMPL-family NPZ with a matching human model: Convert it to SOMA with SOMA-X, then retarget it and export AI Sapiens CSV.

The application determines the path from the input extension and NPZ schema. There is no --input-format option.

Retargeting Pipeline

Stage	Role
Input classification	Distinguishes SOMA BVH, SOMA77/Kimodo NPZ, and raw SMPL-family NPZ by extension and data schema.
Optional SOMA-X preprocessing	Converts raw SMPL, SMPL-H, or SMPL-X motion into the SOMA77 matrix representation. This stage runs only for raw SMPL-family input.
Fixed SOMA BVH generation	Converts accepted NPZ motion into the SOMA BVH representation used by the existing retargeting pipeline.
SOMA BVH loading	Reads the source skeleton and animation frames from .bvh files.
AI Sapiens model loading	Resolves the generated AI Sapiens retarget MJCF.
Human-to-robot scaling	Converts SOMA body proportions into AI Sapiens target bodies using scaler config values.
Multi-objective IK	Solves AI Sapiens body position and rotation objectives with Newton IK.
Joint-limit objective	Penalizes or constrains motion near AI Sapiens joint limits during solving.
CSV export	Writes AI Sapiens root and 23 joint columns through the AI Sapiens CSV config.

Requirements

• Python 3.12 or newer
• Git LFS
• Git submodule support
• Windows x86-64, Linux x86-64, or Linux aarch64
• NVIDIA GPU, Maxwell generation or newer, for CUDA acceleration
• NVIDIA driver 545+ with CUDA 12 runtime support when using CUDA
• Python environment manager such as conda
• Linux OpenGL GUI only: Tkinter system package (python3-tk on Ubuntu 24.04)

Headless conversion supports --device cpu and does not require Tkinter. The OpenGL viewer requires Tkinter, a working display, and an OpenGL context.

Installation

1. Clone the Repository

Clone the ROBOTIS soma-retargeter fork and enter the repository root:

git clone --recursive https://github.com/ROBOTIS-GIT/soma-retargeter.git
cd soma-retargeter

The commands that use . or tools/... must be run from the soma-retargeter repository root. The repository root is the directory that contains:

pyproject.toml
app/
assets/
soma_retargeter/
tools/

Do not run pip install ... -e . or python tools/generate_ai_sapiens_retarget_mjcf.py from the parent directory such as ~/work. In those commands, . means the current directory.

2. Download LFS Files and Submodules

Initialize Git LFS and make sure the AI Sapiens submodule is available:

git lfs install
git submodule sync --recursive
git submodule update --init --recursive
git lfs pull
git -C third_party/ai_sapiens lfs pull

Check the submodule state from the repository root:

git submodule status --recursive

If the status line for third_party/ai_sapiens starts with -, the submodule is not initialized. Run git submodule update --init --recursive again from the repository root. If the viewer reports missing STL files under third_party/ai_sapiens, run git -C third_party/ai_sapiens lfs pull.

3. Create a Python Environment

Soma-retargeter requires Python 3.12 or newer. The repository .python-version file uses 3.12, and the Ubuntu 24.04 example below uses the distro python3.12 packages.

On Ubuntu 24.04 or inside a clean Docker container, install the required Python venv packages first:

apt-get update
apt-get install -y \
  python3.12-venv \
  python3.12-dev \
  python3-tk \
  python3-pip \
  build-essential

python3-tk provides the Tkinter file dialogs used by --viewer gl. It is an operating-system package and is not installed by pip install -e .. You may omit it on a headless-only system that always uses --viewer null.

Then create and activate the environment:

python3.12 -m venv .venv
source .venv/bin/activate

If you already use conda, you can use a conda environment instead:

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

If you use another Python version, it must satisfy the project requirement >=3.12 and the required binary wheels for dependencies such as Newton, Warp, MuJoCo, SciPy, and imgui-bundle must be available for that Python version.

4. Install Soma-retargeter in Editable Mode

After activating either environment, upgrade pip tooling and install the checked-out repository in editable mode from the repository root:

python -m pip install --upgrade pip setuptools wheel
python -m pip install --extra-index-url https://pypi.nvidia.com -e .

Use -e . instead of .. Editable mode makes Python import soma_retargeter from the checked-out repository, so repo-local assets such as third_party/ai_sapiens, assets, and tools stay available.

Optional: Install SOMA-X Preprocessing

The base installation is sufficient for SOMA BVH and SOMA77/Kimodo NPZ input. To convert raw SMPL-family motion, install the optional SOMA-X runtime instead:

python -m pip install --extra-index-url https://pypi.nvidia.com -e '.[soma-x]'

If you use uv:

uv sync --extra soma-x

The optional extra installs py-soma-x[smpl]==0.2.1. It is imported only when raw SMPL-family input is converted.

SOMA-X also requires a licensed SMPL, SMPL-H, or SMPL-X human model file. Human model files are not included in the repository. Obtain and use them under their respective licenses.

License boundaries

The optional install combines components with separate terms:

1. The SOMA-X codebase is Apache-2.0 licensed.
2. The smplx Python dependency uses its own license for non-commercial scientific research and related permitted non-commercial uses. Review that license and its commercial-license contact before use.
3. SMPL, SMPL-H, and SMPL-X model files are separately licensed assets obtained from their official providers. They are not included or redistributed by Soma-retargeter.

Installing .[soma-x] does not replace or expand the rights granted by the dependency and model-file licenses.

5. Check the Installation

Run the check from the repository root:

python --version
python tools/generate_ai_sapiens_retarget_mjcf.py --check

The remaining commands assume the same activated Python environment and the soma-retargeter repository root.

AI Sapiens Retarget MJCF

During conversion, Soma-retargeter loads the AI Sapiens retarget MJCF. The AI Sapiens URDF is used as the generator input when the retarget MJCF is created or regenerated:

generator input URDF = third_party/ai_sapiens/ai_sapiens_description/urdf/k1_rev1/k1.urdf
visual mesh assets   = third_party/ai_sapiens/ai_sapiens_description/meshes/k1_rev1/
generated MJCF       = soma_retargeter/configs/ai_sapiens/ai_sapiens_retarget.xml

The generator:

• reads the AI Sapiens submodule URDF,
• resolves package://ai_sapiens_description/meshes/k1_rev1 to the submodule STL directory,
• temporarily adds a floating world -> pelvis root before MuJoCo compilation,
• checks the compiled model dimensions as nq=30, nv=29,
• inserts retargeting proxy/TCP bodies from ai_sapiens_retarget_mjcf_patch.json,
• writes the generated MJCF with meshdir="../../../third_party/ai_sapiens/ai_sapiens_description/meshes/k1_rev1".

Primitive MJCF files are not generated or used.

When the MJCF Is Generated

The default behavior is an ensure-style flow:

Case	Behavior
ai_sapiens_retarget.xml exists	Use the existing file and validate it.
The file does not exist	Generate it from the submodule URDF/STL, then validate it.
--force is used	Regenerate and overwrite the existing file.
--check is used	Validate only. Do not generate or overwrite.

Validate the current MJCF:

python tools/generate_ai_sapiens_retarget_mjcf.py --check

Regenerate it explicitly:

python tools/generate_ai_sapiens_retarget_mjcf.py --force

During normal conversion, the default AI Sapiens MJCF is generated only when the default file is missing. User-specified absolute MJCF paths or environment overrides are not auto-generated.

Supported Motion Input

The application accepts the following motion types:

Input	Required runtime or model	Processing path
SOMA .bvh	Base installation	Retarget directly to AI Sapiens CSV.
SOMA77/Kimodo .npz	Base installation	Generate fixed SOMA BVH, then retarget.
Raw SMPL .npz	SOMA-X extra and matching SMPL model	Convert to SOMA77, generate BVH, then retarget.
Raw SMPL-H .npz	SOMA-X extra and matching SMPL-H model	Convert to SOMA77, generate BVH, then retarget.
Raw SMPL-X .npz	SOMA-X extra and matching SMPL-X model	Convert to SOMA77, generate BVH, then retarget.

Raw SMPL-family motion can use combined or equivalent separated pose fields. Supported combined pose widths are 72 values for SMPL, 156 or body-only 66 values for SMPL-H, and 165, 156, or 66 values for SMPL-X. Kimodo matrix exports with 22 local_rot_mats joints are also accepted as raw SMPL-X motion.

Licensed human models may be supplied as .npz or .pkl, with neutral, male, or female parameters. The selected human model is authoritative. Model type is detected from model topology and parameter structure, not from its filename or motion gender metadata. If the selected model family does not match the motion schema, conversion stops with Human model and motion do not match. instead of silently coercing the data.

Human model lookup order is:

1. --human-model in the unified CLI, --model in the standalone CLI, or the current GUI selection.
2. SOMA_RETARGETER_SOMA_X_HUMAN_MODEL.
3. soma_x_human_model in the converter config.

The legacy SMPL-X settings SOMA_RETARGETER_SOMA_X_SMPLX_MODEL and soma_x_smplx_model remain fallback options.

Unified Headless Conversion

Use app/bvh_to_csv_converter.py for a single file or a recursive directory. The command classifies each input automatically. Unified mode requires --input and --output-dir together.

Retarget Existing SOMA BVH or SOMA77 NPZ

This path starts with motion that is already represented by the SOMA skeleton. It does not run SOMA-X. A SOMA BVH is sent directly to Newton, while a SOMA77/Kimodo NPZ is first converted to a fixed SOMA BVH. Both inputs finish as an AI Sapiens CSV.

python ./app/bvh_to_csv_converter.py \
  --config ./assets/default_ai_sapiens_bvh_to_csv_converter_config.json \
  --viewer null \
  --input /data/motion.bvh \
  --output-dir /data/k1-output

The same command accepts an already converted SOMA77/Kimodo .npz file without --human-model.

Convert Raw SMPL-family Motion and Retarget It

python ./app/bvh_to_csv_converter.py \
  --config ./assets/default_ai_sapiens_bvh_to_csv_converter_config.json \
  --viewer null \
  --input /data/motion_stageii.npz \
  --human-model /models/SMPLX_NEUTRAL.npz \
  --output-dir /data/k1-output \
  --device cuda:0

Convert a Directory Recursively

python ./app/bvh_to_csv_converter.py \
  --config ./assets/default_ai_sapiens_bvh_to_csv_converter_config.json \
  --viewer null \
  --input /data/motions \
  --human-model /models/SMPLX_NEUTRAL.npz \
  --output-dir /data/k1-output \
  --device cuda:0

The recursive mode processes .bvh and .npz files while preserving relative paths. It uses one human model for the entire run and validates all raw inputs against that model before conversion starts. The input and output directories must not overlap. Inputs with the same relative stem, such as walk.bvh and walk.npz, are rejected because both would produce the same CSV path.

Output Directory Layout

The unified command preserves each input's relative path below --output-dir, but it creates only the artifacts required by that input type:

Input type	Files written below --output-dir
SOMA BVH	retargeted_csv/<relative-path>.csv
SOMA77/Kimodo NPZ	soma_bvh/<relative-path>.bvh, then retargeted_csv/<relative-path>.csv
Raw SMPL-family NPZ with --human-model	soma_npz/<relative-path>.npz, then soma_bvh/<relative-path>.bvh, then retargeted_csv/<relative-path>.csv

For example, raw input /data/motions/set_a/walk.npz under an input root of /data/motions produces:

/data/k1-output/
  soma_npz/set_a/walk.npz
  soma_bvh/set_a/walk.bvh
  retargeted_csv/set_a/walk.csv

The intermediate directories are conditional. Direct SOMA BVH input creates neither soma_npz/ nor soma_bvh/. The final robot-motion output is always under retargeted_csv/.

Headless Options

Option	Purpose
--input-fps	Override raw-motion FPS and generated BVH FPS.
--soma-x-batch-size	Override the SOMA-X frame batch size.
--source-coordinate {auto,amass,kimodo}	Override raw source coordinates.
--canonicalize-heading / --no-canonicalize-heading	Enable or disable frame-zero heading alignment.
--heading-yaw-degrees	Apply an additional heading rotation.
--rebase-root-horizontal / --no-rebase-root-horizontal	Enable or disable frame-zero horizontal root rebasing.
--bvh-template	Select the template used for NPZ-to-BVH conversion.
--bvh-offsets	Select SOMA77 rest-pose offsets for fixed-Euler BVH generation.
--bvh-position-scale	Override generated BVH root-position scale.
--force	Replace stale or invalid retained preprocessing output.

An explicit --device is used by both SOMA-X and Newton. Without it, SOMA-X uses soma_x_device from the config, whose default is auto. Use --device cpu for headless CPU conversion.

FPS and Coordinate Handling

For unified headless NPZ conversion, FPS is selected in this order:

1. --input-fps.
2. SOMA_RETARGETER_KIMODO_NPZ_FPS.
3. kimodo_npz_fps in the converter config.
4. Motion metadata such as mocap_frame_rate, fps, sample_rate, or source_fps.
5. A same-stem sidecar BVH, such as walk.bvh beside walk.npz.
6. A 30 FPS compatibility fallback when no valid value is available.

The GUI has no --input-fps argument, so it starts with the environment variable and then follows steps 3 through 6. The converter reports the selected FPS source in headless mode and warns when it reaches the 30 FPS fallback.

With --source-coordinate auto, raw parameter NPZ files use AMASS coordinates and 22-joint Kimodo matrix files retain Kimodo coordinates. By default, frame-zero anatomical forward is aligned to Kimodo +Z, frame-zero horizontal root position is rebased to the origin, and vertical position plus relative trajectory displacement are preserved.

Resume and Cache Behavior

Raw SOMA-X conversion stores a signature derived from the source, selected human model, SOMA-X version, and conversion options. A retained soma_npz result is reused only when its required fields and signature still match. Stale or invalid intermediates stop with an error; rerun with --force only when replacement is intentional. The retained BVH can be regenerated from a valid SOMA77 NPZ without repeating PoseInversion.

Config-only BVH Batch Conversion

The original BVH batch workflow remains available. Run without --input and --output-dir:

python ./app/bvh_to_csv_converter.py \
  --config ./assets/default_ai_sapiens_bvh_to_csv_converter_config.json \
  --viewer null

The default AI Sapiens config contains:

Config key	Default value
import_folder	assets/motions/bvh
export_folder	assets/motions/ai_sapiens-csv
timestamp_result_folder	false
batch_size	1
retargeter	Newton
retarget_source	soma
retarget_target	ai_sapiens
retarget_source_facing_direction	Mujoco
retargeter_config	ai_sapiens/soma_to_ai_sapiens_retargeter_config.json
ai_sapiens_mjcf	ai_sapiens/ai_sapiens_retarget.xml

This mode recursively converts every .bvh under import_folder and writes matching CSV files under export_folder while preserving relative paths.

Generate SOMA77 Input Only with SOMA-X

Use the standalone tool only when raw SMPL-family motion must be converted to a reusable SOMA77 intermediate without running Newton or producing an AI Sapiens CSV:

python ./tools/convert_smpl_to_retarget_npz.py \
  --input /data/motion_stageii.npz \
  --output /data/converted/motion_stageii.npz \
  --model /models/SMPLX_NEUTRAL.npz \
  --device auto

convert_smpl_to_retarget_npz.py detects the model family automatically. Add --model-type smpl, smplh, or smplx only when an explicit override is required.

This is different from Retarget Existing SOMA BVH or SOMA77 NPZ: the standalone tool stops after SOMA-X preprocessing, whereas the unified command consumes SOMA motion and finishes robot retargeting.

For a single file, the SOMA77 NPZ is written to the exact --output path. With --emit-bvh, a same-stem BVH is written beside it unless --bvh-output is provided. Directory mode mirrors paths from --input-dir below --output-dir; --bvh-output-dir can place optional BVH files in a separate mirrored tree.

The tool also supports --input-dir, --emit-bvh, --exclude-dir, and --inspect. tools/convert_smplx_to_retarget_npz.py remains a compatibility entry point that defaults to SMPL-X and delegates to the same implementation.

Launch the Interactive Viewer

Run the converter with the OpenGL viewer:

python ./app/bvh_to_csv_converter.py \
  --config ./assets/default_ai_sapiens_bvh_to_csv_converter_config.json \
  --viewer gl

The Motion panel provides independent controls for BVH Motion, NPZ Motion, SOMA-X, and CSV Motion.

Load BVH or SOMA77 NPZ

1. Click Load next to BVH Motion or NPZ Motion.
2. Select a compatible motion file.
3. Check the source motion in the viewport.
4. Click the corresponding Retarget button.
5. Preview the result with the playback controls.
6. Click Save next to CSV Motion and choose the output path.

Convert Raw SMPL-family Motion with SOMA-X

The SOMA-X row follows this sequence:

SOMA-X: [Human Model] [Motion] [Retarget]

When the viewer starts, it checks whether the required SOMA-X runtime is available. If SOMA-X is not installed, has the wrong version, or is missing a required Python module, Human Model, Motion, and Retarget are all disabled. The information line below the row shows only the unavailable reason in red. Install the optional runtime with the command below from the repository root, then restart the viewer:

python -m pip install --extra-index-url https://pypi.nvidia.com -e '.[soma-x]'

1. Select a licensed SMPL, SMPL-H, or SMPL-X file with Human Model. Before selection, the information line lists the supported model families.
2. Confirm the detected family and filename shown below the row. A valid model enables Motion.
3. Select matching raw motion. Conversion starts in a subprocess, the controls lock, and frame progress appears as a percentage beside the model information.
4. Wait until the converted SOMA77 motion is loaded and 100% is displayed. The Retarget button then becomes available.
5. Click Retarget, preview the AI Sapiens result, and save it through CSV Motion.

Selecting a different human model invalidates the previously converted motion. A recognized model/motion mismatch appears in red on the information line without opening a traceback popup. Other conversion errors use the normal error popup. Closing the viewer terminates an active GUI conversion subprocess.

The GUI processes one selected motion. Use unified headless directory mode for recursive conversion.

If you run the GUI inside Docker, install python3-tk inside the container and provide a valid host display. Confirm that echo $DISPLAY is not empty and that /tmp/.X11-unix is mounted.

Why STL Mesh Files Are Required

The viewer loads the generated AI Sapiens MJCF to display the robot model. That MJCF references STL meshes from the AI Sapiens submodule:

<compiler angle="radian" meshdir="../../../third_party/ai_sapiens/ai_sapiens_description/meshes/k1_rev1" />
<mesh name="left_hip_pitch_link" file="left_hip_pitch_link.stl" />

The <geom type="mesh" ... /> entries resolve to those STL files when MuJoCo or Newton loads the MJCF. The STL files are robot geometry assets used for model loading and visualization. They are not motion files and not BVH input files.

If the submodule is missing, the viewer cannot load the robot model. Headless conversion can also fail before solving if the MJCF mesh references cannot be resolved.

Check the submodule state from the repository root:

git submodule status --recursive

AI Sapiens Converter Config Fields

Field	Description
ai_sapiens_viewer_default_orientation_yaw_deg	Viewer-only yaw applied to the displayed AI Sapiens model; it does not modify retargeted or exported motion.
ai_sapiens_root_translation_yaw_deg	Yaw rotation applied to exported root translation.
ai_sapiens_root_orientation_yaw_deg	Yaw rotation applied to exported root orientation.
ai_sapiens_root_translation_xy_scale	Scale applied to exported root XY translation.
ai_sapiens_target_position_yaw_deg	Yaw rotation applied to AI Sapiens IK target positions before solving.
ai_sapiens_target_orientation_yaw_deg	Yaw rotation applied to AI Sapiens IK target orientations before solving.
ai_sapiens_target_yaw_pivot	Pivot mode for target yaw correction: origin, first_root, or per_frame_root.
ai_sapiens_ground_align	When enabled, applies a root-Z offset based on non-plane geoms.

The default AI Sapiens converter config sets root translation, root orientation, target-position, and target-orientation yaw corrections to 0.0. It sets the viewer-only ai_sapiens_viewer_default_orientation_yaw_deg to -90.0, keeps XY scale at 1.0, and leaves ai_sapiens_ground_align disabled. The viewer value changes presentation only; it does not rotate the retargeted CSV. Retargeter solver options are defined separately in soma_retargeter/configs/ai_sapiens/soma_to_ai_sapiens_retargeter_config.json.

SOMA-X Integration Config Fields

These fields belong to the Soma-retargeter integration layer that invokes SOMA-X. They are not native SOMA-X configuration fields.

Field	Default	Description
soma_x_human_model	Empty	Default licensed SMPL-family model path.
soma_x_device	auto	SOMA-X conversion device when --device is not supplied.
soma_x_batch_size	32	Number of frames processed per SOMA-X conversion batch.
soma_x_source_coordinate	auto	Selects automatic, AMASS, or Kimodo source coordinates.
soma_x_canonicalize_heading	true	Aligns frame-zero anatomical forward to Kimodo +Z.
soma_x_rebase_root_horizontal	true	Moves frame-zero horizontal root position to the origin.

SOMA77 NPZ Conversion Config Fields

After SOMA-X produces SOMA77 NPZ data, or when SOMA77/Kimodo NPZ is loaded directly, Soma-retargeter uses these fields to generate the fixed SOMA BVH consumed by the retargeting pipeline.

Field	Default	Description
kimodo_npz_template_bvh	Example SOMA BVH	Supplies the SOMA hierarchy and channel layout for generated BVH.
kimodo_npz_offsets	Empty (automatic fallback)	Optional SOMA77 rest-pose offsets file. An empty value uses the packaged standard offsets when available.
kimodo_npz_fps	Empty (automatic detection)	Optional FPS override used before NPZ metadata and a same-stem sidecar BVH.
kimodo_npz_position_scale	100.0	Scales NPZ root position for BVH output.

Corresponding CLI options override these integration and conversion config values for the current run. Rest-pose offsets are resolved in this order: --bvh-offsets in unified headless mode, SOMA_RETARGETER_KIMODO_NPZ_OFFSETS, kimodo_npz_offsets, the packaged soma_retargeter/configs/soma/standard_t_pose_global_offsets_rots.p, and then a compatible nearby Kimodo checkout. The BVH template follows the equivalent CLI, environment, config, and bundled-example fallback order.

Project Structure Reference

Path	Purpose
app/bvh_to_csv_converter.py	Main entry point for GUI, config-only BVH batch, and unified headless file/directory conversion.
assets/default_ai_sapiens_bvh_to_csv_converter_config.json	Default AI Sapiens converter config.
soma_retargeter/assets/ai_sapiens.py	AI Sapiens path and CSV root convention helpers.
soma_retargeter/assets/ai_sapiens_mjcf.py	URDF-based retarget MJCF generator and validator.
soma_retargeter/assets/motion_input.py	Unified BVH/NPZ schema classification and headless input planning.
soma_retargeter/assets/smplx_motion.py	SMPL-family model inspection, schema validation, SOMA-X conversion, and cache signatures.
soma_retargeter/assets/kimodo_npz.py	SOMA77/Kimodo NPZ FPS detection and fixed BVH conversion.
soma_retargeter/configs/ai_sapiens/soma_to_ai_sapiens_retargeter_config.json	AI Sapiens IK body map and solver settings.
soma_retargeter/configs/ai_sapiens/ai_sapiens_retarget_mjcf_patch.json	Retarget proxy/TCP body patch data.
soma_retargeter/configs/ai_sapiens/ai_sapiens_retarget.xml	Generated AI Sapiens retarget MJCF.
third_party/ai_sapiens/	AI Sapiens submodule containing URDF and STL mesh assets.
tools/generate_ai_sapiens_retarget_mjcf.py	CLI wrapper for MJCF ensure/check/force generation.
tools/convert_smpl_to_retarget_npz.py	Standalone SMPL/SMPL-H/SMPL-X to SOMA77 conversion entry point.
tools/convert_smplx_to_retarget_npz.py	SMPL-X-compatible conversion entry point and shared standalone implementation.

Output CSV

Soma-retargeter writes the AISapiens23DOF_CSVConfig layout:

Frame,
root_translateX, root_translateY, root_translateZ,
root_rotateX, root_rotateY, root_rotateZ,
<23 AI Sapiens joint columns>

Units:

Data	CSV unit
Root translation	centimeters
Root rotation	XYZ Euler degrees
Joint values	degrees

AI Sapiens joint columns:

left_hip_pitch_joint_dof
left_hip_roll_joint_dof
left_hip_yaw_joint_dof
left_knee_joint_dof
left_ankle_pitch_joint_dof
left_ankle_roll_joint_dof
right_hip_pitch_joint_dof
right_hip_roll_joint_dof
right_hip_yaw_joint_dof
right_knee_joint_dof
right_ankle_pitch_joint_dof
right_ankle_roll_joint_dof
waist_yaw_joint_dof
left_shoulder_pitch_joint_dof
left_shoulder_roll_joint_dof
left_shoulder_yaw_joint_dof
left_elbow_joint_dof
left_wrist_roll_joint_dof
right_shoulder_pitch_joint_dof
right_shoulder_roll_joint_dof
right_shoulder_yaw_joint_dof
right_elbow_joint_dof
right_wrist_roll_joint_dof

After creating a CSV file, use it as the motion source for a Cyclo Lab mimic policy. See How to Add Your Own Mimic Task for the conversion, task setup, training, and export workflow.

Verification Checklist

Check the submodule:

git submodule status --recursive

Validate the generated MJCF:

python tools/generate_ai_sapiens_retarget_mjcf.py --check

Check Python syntax:

python -m compileall app soma_retargeter tools

Check the unified and standalone command interfaces:

python app/bvh_to_csv_converter.py --help
python tools/convert_smpl_to_retarget_npz.py --help

Check the retarget MJCF patch JSON:

python -m json.tool soma_retargeter/configs/ai_sapiens/ai_sapiens_retarget_mjcf_patch.json

Run an optional smoke test after setup to confirm conversion end to end. For BVH, use one input file with unified headless mode. For raw SMPL-family input, also supply a licensed matching human model and verify that soma_npz, soma_bvh, and retargeted_csv contain the expected outputs.

This guide covers setup and conversion only. It does not certify retargeting quality, initial pose equivalence, physical stability, or hardware safety.

Troubleshooting

Log message or symptom	Meaning	Check
ERROR: Directory '.' is not installable. Neither 'setup.py' nor 'pyproject.toml' found.	pip install ... -e . was run outside the soma-retargeter repository root.	Run cd soma-retargeter first. Confirm ls pyproject.toml succeeds, then rerun the install command.
ModuleNotFoundError: No module named 'soma_retargeter'	Soma-retargeter was not installed in the active Python environment, or the wrong environment is active.	Activate the environment and run pip install --extra-index-url https://pypi.nvidia.com -e . from the repository root.
All three SOMA-X GUI buttons are disabled and the information line is red	SOMA-X is not installed, has the wrong version, or is missing a required Python module.	Run python -m pip install --extra-index-url https://pypi.nvidia.com -e '.[soma-x]' from the repository root, then restart the viewer. BVH and SOMA77 input do not require this extra.
Human model and motion do not match.	The selected SMPL, SMPL-H, or SMPL-X model family does not match the raw motion schema.	Select a licensed model from the same family as the motion. Do not rename files to bypass schema validation.
A raw NPZ reports that no human model is configured	None of the CLI, environment, or config model paths resolved to a file.	Pass --human-model, set SOMA_RETARGETER_SOMA_X_HUMAN_MODEL, or set soma_x_human_model in the config.
Input and output directories overlap	Recursive conversion would scan or overwrite its own generated files.	Use separate input and output roots.
Existing preprocessing output has a signature mismatch	The source, human model, SOMA-X version, or conversion options changed.	Confirm the change, then use --force only if replacing the retained output is intended.
CUDA device is unavailable	CUDA was requested but the host or container does not expose a compatible GPU.	Expose the GPU correctly or run headless conversion with --device cpu.
NPZ-to-BVH conversion reports a rest-pose offset error	The fixed BVH converter cannot resolve SOMA77 offsets.	Configure kimodo_npz_offsets or pass --bvh-offsets with the standard SOMA rest-pose offsets file.
python: can't open file '.../tools/generate_ai_sapiens_retarget_mjcf.py': [Errno 2] No such file or directory	The command was run outside the repository root, or the repository was not cloned.	Run cd soma-retargeter first. Confirm ls tools/generate_ai_sapiens_retarget_mjcf.py succeeds.
[ERROR]: Main config json file not found: ...	The path passed to --config does not exist.	Confirm the command uses ./assets/default_ai_sapiens_bvh_to_csv_converter_config.json or another valid config path.
[ERROR]: Import folder does not exist ...	import_folder in the config points to a missing directory.	Create the directory or edit import_folder.
[ERROR]: Import folder ..., does not contain any BVH files.	Batch mode found no .bvh files under import_folder.	Add SOMA-compatible .bvh files or point import_folder to the correct folder.
[ERROR]: No export folder specified.	export_folder is empty in the config.	Set export_folder to the CSV output directory.
[ERROR]: AI Sapiens source URDF not found: ...	The AI Sapiens submodule is missing or not initialized.	Run git submodule update --init --recursive.
[ERROR]: AI Sapiens STL mesh directory not found: ...	The submodule mesh directory is missing.	Run git submodule update --init --recursive and check third_party/ai_sapiens/ai_sapiens_description/meshes/k1_rev1.
AI Sapiens submodule commit mismatch ...	The submodule is checked out at a different commit than the generator patch expects.	Run git submodule update --init --recursive from the parent repository to restore the recorded submodule commit.
Generated MJCF references missing mesh files ...	The MJCF meshdir points to STL files that are not available.	Initialize the submodule and validate the generated MJCF again.
Compiled AI Sapiens URDF has unexpected dimensions ...	The URDF compiled into an unexpected MuJoCo model shape.	Confirm the submodule commit and the generator patch JSON.
AssertionError: [ERROR]: Unexpected number of joints in input motion. Expected ..., got ...	A BVH file in the batch does not match the skeleton structure of the first BVH file.	Keep one expected SOMA skeleton format per batch.
[ERROR]: Invalid retarget solver selected [...]. Use 'Newton'.	The config uses an unsupported retargeter value.	Set retargeter to Newton.
ModuleNotFoundError: No module named 'tkinter', display error, or OpenGL context error when using --viewer gl	The interactive viewer dependency or display context is unavailable.	Install python3-tk and confirm a display/OpenGL context. For headless conversion, use --viewer null.
Output appears in a different folder than expected	Unified mode uses --output-dir; config-only BVH mode uses export_folder and timestamp_result_folder.	Check which mode was launched. Unified final CSV files are under retargeted_csv/.

Attribution

This page is an AI Sapiens integration guide for the ROBOTIS-GIT/soma-retargeter fork.

• The ROBOTIS fork builds on NVIDIA soma-retargeter (NVIDIA/soma-retargeter).
• Verify the latest license and model terms before production deployment, redistribution, or commercial release.

warning

Do not execute retargeted CSV motion directly on AI Sapiens hardware. Validate the result in simulation and confirm joint limits, contacts, balance, and safety behavior before hardware execution.