SOMA-X gives parametric human bodies one shared skeleton and topology

One topology and one rig across several body model families

SOMA-X provides a canonical, differentiable representation for parametric human bodies and hands. The word canonical does the work here: the point of the package is not to add another body model, it is to be the layer that other body models agree on.

The mechanism is stated directly in the overview. SOMA-X maps supported identity models to shared SOMA topology and rig conventions, so applications can reuse one animation, retargeting and geometry pipeline across model families. If your pipeline currently has a separate path for each body model, this is the piece that would let you delete those paths.

Two layers are exposed. SOMALayer handles full-body models at mid, low and extra-low levels of detail, and SOMAHandLayer handles wrist-local left and right hands at the same three levels of detail. Both are driven by SOMA's unified body and hand skeletons, which is why a hand from one backend and a body from another can still be posed together.

Around those two layers the package includes pose inversion, procedural rig controls, smoothing, conversion, USD and NPZ input and output, and reusable geometry utilities. Runtime skinning and fitting are accelerated with NVIDIA Warp.

The audience is technical animators and researchers rather than application developers: teams doing pose estimation, motion retargeting, character rigging and digital human work, who need a model to be differentiable and GPU friendly rather than merely pretty.

The project comes from NVlabs, publishes documentation at nvlabs.github.io/SOMA-X, and has a technical report on arXiv.

Two layer classes, two different pose tensor shapes

The quick start shows how little code it takes to evaluate a model, and how the two layers differ.

For the 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

For the 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

The differences tell you the shape of the data. The body takes 77 pose parameters and the hand takes 25, which reflects the two different skeleton sizes. The hand layer takes a hand_type of right or left and a lod of mid, low or extra-low, while the body layer takes the identity backend name and a device. Both take a pose tensor and an identity tensor, and both return vertices and joints.

The identity vector size is not hard coded, it is read from the layer as num_shape_components, so the same code works across backends with different numbers of shape parameters.

The examples run on the CPU deliberately, which is the fastest way to check an installation. The device argument is where you switch to CUDA, and the Warp backend is where the acceleration lives.

The backend table decides whose licence you need

SOMA-X supports several identity backends, and the support table is really a table of licences.

For the body, MHR is listed as the default high-fidelity body backend, SOMA is the native option with PCA identity and body-part scaling, Anny provides anthropometric controls with broad age coverage, and SMPL, SMPL-H and SMPL-X are supported through user-supplied licensed model files. GarmentMeasurements adds a user-generated local PCA asset.

For the hand, SOMA is the native 20-component hand identity model, MANO is supported through user-supplied MANO v1.2 model files, and MHR contributes a hand identity sliced from the MHR body model.

The distinction that matters commercially is between the native and the borrowed. SOMA's own body and hand identity models ship with the package. The SMPL and MANO models do not, and the README is explicit that MANO interoperability uses user-supplied MANO v1.2 files and that licensed MANO models are not redistributed. The acknowledgements section records the same pattern for the others, crediting SMPL-Body for the SMPL-to-SOMA topology correspondence, MHR for the pose corrective model, Anny for the basis of Warp-accelerated sparse linear blend skinning and GarmentMeasurements for augmenting the native body shape model.

So a team can start with the native SOMA backends with no third-party model file at all, and add SMPL or MANO later if it holds those licences already. That is a sensible order of adoption, and it is also the one with the least legal surface.

Installing py-soma-x and the assets that arrive later

Installation is a single pip command:

pip install py-soma-x

The second half of setup is not in the wheel. Assets are downloaded from the nvidia/SOMA-X repository on Hugging Face on first use and cached by huggingface_hub. That means the first call that needs a model file will reach the network, and the cache is what makes subsequent calls fast. In a locked down environment you need to think about that before the first run rather than after it.

Optional identity backends have additional dependencies, and some of them require separately licensed model files. The installation guide referenced by the README covers source installation, extras and model-file setup, which is where the extras such as smpl and anny are defined.

The runtime dependencies are pinned exactly in requirements.txt, and the list tells you what this package expects:

numpy==1.23.5
scipy==1.15.3
torch==2.10.0
trimesh==4.11.1
warp-lang==1.11.1

The remaining entries cover rtree, chumpy, anny, Pillow, pyrender, tqdm, imageio with ffmpeg, ruff, pre-commit, uv, cholespy and usd-core, which is the OpenUSD Python package.

A container is provided as well. The Dockerfile is based on the pytorch/pytorch 2.5.1 image with CUDA 12.4 and cuDNN 9, installs EGL and OpenGL libraries plus xvfb for headless rendering, and installs the package with the smpl and anny extras.

One detail in that Dockerfile is worth reading if you plan to build it yourself: chumpy is installed without build isolation and its sources are patched to replace inspect.getargspec, which was removed in Python 3.11, with inspect.getfullargspec. That is a compatibility patch applied at build time, not a change to the library.

Where SOMA-X is the wrong tool

The package is opinionated in ways that matter for a decision.

It is a research toolkit, not a service dependency. The dependency set is large and includes torch, warp-lang, usd-core, pyrender and chumpy, and the repository pins exact versions. Chumpy in particular carries a build-time patch because of a removed Python API, which tells you what you are signing up for in maintenance terms.

It is also GPU oriented even though the examples run on the CPU. The README points at Warp for accelerating runtime skinning and fitting, and the repository topics include CUDA and GPU, so the interesting performance case is on a CUDA device with a warp-lang backend.

The asset story is a constraint for air-gapped or offline deployments, since model files are fetched from Hugging Face on first use and cached by huggingface_hub. Teams that cannot reach that host need to mirror the assets themselves.

Licensing is the sharpest edge. Optional third-party models and dependencies retain their own licence terms, so a production deployment using SMPL or MANO backends inherits obligations that the Apache-2.0 grant on this repository does not cover. If you only need the native SOMA backends, that whole category of problem disappears.

Finally, the interoperability is a unification, not a superset. Mapping models onto one topology means the rig conventions of SOMA win, and any feature specific to another backend has to be expressed through the common skeleton. The README does not describe a compatibility table for edge cases, so evaluate the specific backends you need rather than the list length.

Test markers, tooling and the shape of the repository

The pytest configuration in pyproject.toml is a good map of what the project considers its own risk areas, and the markers are unusually descriptive.

The marker list separates asset_heavy tests that load large assets or construct full model layers, cpu tests for CPU-backend smoke and portability coverage, gpu tests for the CUDA and Warp backend, hand tests for hand-model or hand-specific coverage that is isolated for public releases, internal tests for the internal tooling that are also isolated for public releases but still run in CI, multiprocess tests for DataLoader, spawn, fork and distributed multiprocessing coverage, slow tests that are excluded from lightweight merge request CI but included in full, manual or scheduled runs, and xlo tests for topology and skeleton transfer coverage.

That is a project with a clear sense of where its risk is: the hand model, the asset loading, the GPU path and the cross-topology transfers each get their own isolation.

The tooling is in a separate tools directory, and the ruff configuration lists the scripts that add the repository to the path before importing, which tells you those scripts are meant to be run from a checkout rather than installed. There are conversion scripts for moving between SOMA and MANO, a pose converter, an AMASS to SOMA converter and a demo visualisation script. The documentation set includes pages for installation and optional backends, demos and conversion tools, the full body API, the hand API, body and hand data assets, pose inversion and the procedural control format.

The repository also carries a Dockerfile, RELEASE.md, an ATTRIBUTIONS.MD file, a pre-commit configuration and a Changelog.

A 0.3.x release line, Apache-2.0, and a citation to carry

SOMA-X is on a 0.3.x line and moving quickly. Releases v0.3.2 on 2026-09-28, v0.3.3 on 2026-09-29 and v0.3.4 on 2026-10-09 came in twelve days, and the last push was on 2026-10-09, the same day as the newest tag. The repository is not archived.

That cadence is fine for a research package whose API is still settling, and it is a reason to pin an exact version rather than track the latest. The CHANGELOG.md file is where the differences between those patch versions are recorded.

The licence is Apache-2.0 for the package itself, with the README noting that optional third-party models and dependencies retain their own terms. The setup.py header carries the SPDX identifier and an NVIDIA copyright notice for 2026, and the licence file sits at the root of the repository.

The package is published on PyPI as py-soma-x, the model assets are hosted on Hugging Face under the nvidia organisation, and there is also a Dockerfile and a release process documented in RELEASE.md.

The project asks to be cited, and the reference is a technical report:

@article{soma2026,
  title={SOMA: Unifying Parametric Human Body Models},
  eprint={2603.16858},
  archivePrefix={arXiv},
  year={2026},
  url={https://arxiv.org/abs/2603.16858},
}

The surrounding ecosystem is worth knowing about, because it shows where this package sits. GEM-X is SOMA-based video pose estimation, the SOMA Retargeter does SOMA-to-Humanoid retargeting, Kimodo is controllable text-to-motion generation, ARDY is an autoregressive diffusion model for interactive motion generation, MotionBricks is a real-time motion in-betweener, ProtoMotions is physically simulated character learning and BONES-SEED is a human and humanoid motion dataset in SOMA format. If your pipeline needs to move between estimation, retargeting and generation, that ecosystem is where the unified format pays off.

Editorial conclusion

Research and animation teams that have to move between parametric body models should adopt SOMA-X, because the unified topology and rig let one pipeline serve MHR, SOMA, Anny, SMPL and MANO backends instead of a bespoke path per model. It is the wrong choice for a project that only needs one body model with no interoperability, since the dependency stack is heavy for that. Before adopting, confirm which optional backend licences you already hold, because SMPL and MANO files are not redistributed and must be supplied by you, and check the asset download step on first use, since the model files come from Hugging Face rather than the package.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. NVlabs/SOMA-X on GitHub
3. Project website
4. README
5. Releases