py-soma-x 0.3.4

Documentation · PyPI · Hugging Face · Changelog

Overview

SOMA-X provides a canonical, differentiable representation for parametric human bodies and hands. It maps supported identity models to shared SOMA topology and rig conventions so applications can reuse one animation, retargeting, and geometry pipeline across model families. Runtime skinning and fitting are accelerated with NVIDIA Warp.

The package includes:

• SOMALayer for full-body models at mid, low, and extra-low LODs.
• SOMAHandLayer for wrist-local left and right hands at the same three LODs.
• Native SOMA body and hand identity models, plus optional MHR, Anny, SMPL-family, GarmentMeasurements, and MANO interoperability.
• Pose inversion, procedural rig controls, smoothing, conversion, USD/NPZ I/O, and reusable geometry utilities.

All identity models below are driven by SOMA's unified body and hand skeletons.

Installation

pip install py-soma-x

Assets are downloaded from nvidia/SOMA-X on first use and cached by huggingface_hub. Optional identity backends have additional dependencies and some require separately licensed model files. See the installation guide for source installation, extras, and model-file setup.

Quick start

Full body

import torch

from soma import SOMALayer

body = SOMALayer(identity_model_type="mhr", device="cpu")
poses = torch.zeros(1, 77, 3)
identity = torch.zeros(1, body.num_shape_components)

output = body(poses, identity)
vertices = output.vertices
joints = output.joints

SOMA Hand

import torch

from soma import SOMAHandLayer

hand = SOMAHandLayer(hand_type="right", lod="mid", device="cpu")
poses = torch.zeros(1, 25, 3)
identity = torch.zeros(1, hand.num_shape_components)

output = hand(poses, identity)
vertices = output.vertices
joints = output.joints

SOMAHand.npz includes the native hand identity model and bind-relative articulation prior. MANO interoperability uses user-supplied MANO v1.2 files; licensed MANO models are not redistributed.

Supported identity models

Documentation

• Installation and optional backends
• Demos, conversion tools, and pose sampling
• Full-body API
• SOMA Hand API
• Body data assets
• SOMA Hand data assets
• Pose inversion
• Procedural control format

Related projects

• GEM-X — SOMA-based video pose estimation.
• Kimodo — controllable text-to-motion generation.
• ARDY — an autoregressive diffusion model designed for interactive motion generation.
• MotionBricks — a real-time motion in-betweener.
• BONES-SEED — human and humanoid motion dataset in SOMA format.
• SOMA Retargeter — SOMA-to-Humanoid retargeting.
• ProtoMotions — physically simulated character learning.
• GR00T Whole-Body Control — a state-of-the-art whole-body controller.

Citation

If you use SOMA-X in your work, please cite:

@article{soma2026,
  title={SOMA: Unifying Parametric Human Body Models},
  author={Jun Saito and Jiefeng Li and Michael de Ruyter and Miguel Guerrero and Edy Lim and Ehsan Hassani and Roger Blanco Ribera and Hyejin Moon and Magdalena Dadela and Marco Di Lucca and Qiao Wang and Xueting Li and Sam Wu and Chaeyeon Chung and Yeongho Seol and Jan Kautz and Simon Yuen and Umar Iqbal},
  eprint={2603.16858},
  archivePrefix={arXiv},
  year={2026},
  url={https://arxiv.org/abs/2603.16858},
}

Acknowledgements

• SMPL-Body was used to create the SMPL-to-SOMA topology correspondence, courtesy of the Max Planck Institute for Intelligent Systems.
• MHR was used to learn the pose corrective model.
• Anny provided the basis for Warp-accelerated sparse linear blend skinning.
• GarmentMeasurements was used to augment the native body shape model.

License

SOMA-X is licensed under Apache-2.0. Optional third-party models and dependencies retain their own license terms.