NVlabs/SOMA-X

SOMA‑X – Differentiable Human Body & Hand Models

What it is – SOMA‑X is a Python library that provides a unified, differentiable representation of parametric human bodies and hands. It maps a variety of existing identity models (MHR, SMPL‑X, MANO, etc.) onto a common topology and rig, letting you animate, retarget, and skin models with a single pipeline.

Key components

SOMALayer – full‑body model at three levels of detail (extra‑low, low, mid).
SOMAHandLayer – left/right hand model, same three LODs.
Built‑in identity back‑ends (native SOMA, MHR, Anny, GarmentMeasurements) plus optional support for SMPL‑family, MANO, and others.
Utilities for pose inversion, procedural rig controls, smoothing, USD/NPZ I/O, and geometry helpers.
Runtime skinning and fitting accelerated with NVIDIA Warp.

Installation

pip install py-soma-x

The first time you run the library it automatically downloads required assets from the NVIDIA Hugging Face repo and caches them locally. Optional back‑ends may need extra pip extras and separate model files (e.g., licensed SMPL or MANO files).

Quick‑start example

import torch
from soma import SOMALayer, SOMAHandLayer

# Full body
body = SOMALayer(identity_model_type="mhr", device="cpu")
poses = torch.zeros(1, 77, 3)               # 77 joints, axis‑angle
shape = torch.zeros(1, body.num_shape_components)
out = body(poses, shape)
vertices, joints = out.vertices, out.joints

# Hand
hand = SOMAHandLayer(hand_type="right", lod="mid", device="cpu")
hand_poses = torch.zeros(1, 25, 3)
hand_shape = torch.zeros(1, hand.num_shape_components)
hand_out = hand(hand_poses, hand_shape)
hand_vertices, hand_joints = hand_out.vertices, hand_out.joints

The returned objects contain mesh vertices and joint locations ready for downstream rendering or physics.

Typical use cases

Animation & retargeting – reuse a single pose sequence across many body/hand models.
Differentiable fitting – integrate the model into optimization loops (e.g., pose estimation, motion capture).
Synthetic data generation – sample diverse body shapes and poses for training vision or robotics models.
Virtual‑try‑on & garment simulation – combine with GarmentMeasurements for clothing pipelines.

Related NVIDIA projects

GEM‑X – video‑based pose estimation built on SOMA.
Kimodo – text‑to‑motion generation using SOMA as the underlying character.
ARDY, MotionBricks, GR00T Whole‑Body Control, etc., all consume SOMA‑X data.

Documentation & resources

Full docs: https://nvlabs.github.io/SOMA-X/stable/
PyPI page: https://pypi.org/project/py-soma-x/
Model assets on Hugging Face: https://huggingface.co/nvidia/SOMA-X
Technical report (arXiv 2603.16858) provides the mathematical background.

License – Apache‑2.0 for the library code. Third‑party model files retain their original licenses.

All information above is taken directly from the repository’s README.