body-models
body-models provides a shared interface for parametric human body, head, hand,
anatomical, measurement, and robot models with NumPy, PyTorch, and JAX runtimes.
Documentation: https://abcamiletto.github.io/body-models/
Features
- NumPy, PyTorch, and JAX runtimes
- Optional Warp acceleration for Torch skinning
- Separate mesh and skeleton forwards with
forward_vertices()andforward_skeleton() - Prepared identities for repeated poses with fixed shape/expression parameters
- Mesh simplification and vertex-subset forwards for supported mesh models
- Multiple rotation representations for supported pose models
Install
uv add body-models
Install optional extras when needed:
uv add "body-models[torch]"
uv add "body-models[jax]"
uv add "body-models[torch,warp]"
Public model assets download on first use into the operating system's private
user cache. Licensed assets use body-models download MODEL, which prompts for
credentials. Use body-models download MODEL --output-dir PATH when assets
should live in a specific directory; run body-models to inspect the cache and
configured paths.
Quick Start
from body_models.smpl.torch import SMPL
model = SMPL(gender="neutral")
params = model.get_rest_pose(batch_dims=(1,))
vertices = model.forward_vertices(**params)
skeleton = model.forward_skeleton(**params)
Every model exposes a machine-readable description of those parameters:
model.parameter_spec
# {
# "shape": ParameterSpec(shape=(10,), role="identity", ...),
# "body_pose": ParameterSpec(shape=(23, 3), role="pose", rotation_type="axis_angle", ...),
# ...
# }
Each entry reports the unbatched array shape, semantic role, numeric default,
and rotation representation when applicable. A rotation representation implies
the corresponding identity rotation. get_rest_pose() constructs its arrays
directly from this specification.
Select NumPy, Torch, or JAX in the import path. Torch models expose their skinning implementation directly:
from body_models.smpl.torch import SMPL
model = SMPL(gender="neutral", skinning_backend="warp")
model = model.cuda()
Models imported from a torch module are torch.nn.Module instances, so
.to(), .cuda(), and state_dict() work directly.
The equivalent NumPy and JAX classes live in body_models.smpl.numpy and
body_models.smpl.jax. Discover available model names with
body_models.list_models(). The create_model() factory remains available
when the model and runtime must be selected dynamically.
Public API
The stable API consists of names exported from body_models and each model
backend package. For example, body_models.smpl.torch.SMPL is public;
underscore-prefixed modules such as body_models.smpl._model are
implementation details and are not covered by semantic-versioning
compatibility guarantees. Every model
derives from body_models.ArticulatedModel. Skinned model packages also export
model-specific prepared-state types when their schema is unique. Shared linear
models use body_models.LinearIdentity and body_models.SkinningPose.
Required numerical inputs may be positional; optional model arguments are
keyword-only.
The shared metadata API exposes joint_names, parents, num_joints,
common_joints, has_hands, and has_face. Fixed model dimensions use
NUM_* class constants such as NUM_BODY_JOINTS, NUM_SHAPE_COEFFS, and
NUM_BODY_POSE_COEFFS; a model defines only the dimensions that are meaningful
for that model. Dimensions selected by a constructor option remain instance
properties, such as SOMA's num_shape_coeffs.
When shape-dependent identity parameters stay fixed across many poses, prepare
them once and pass the returned dictionary back through identity. This avoids
recomputing rest joints, local offsets, and rest vertices on every forward pass.
shape = params.pop("shape")
identity = model.prepare_identity(shape)
vertices = model.forward_vertices(**params, identity=identity)
skeleton = model.forward_skeleton(**params, identity=identity)
For models with expression-dependent rest state, such as SMPL-X and FLAME, pass
both identity controls to prepare_identity(shape, expression). Prepared
identities and poses on skinned models are always complete mesh-ready values;
skeleton forwards use separate lightweight internal preparation and never
return partial state.
Supported Models
- Full bodies: SMPL, SMPL-H, SMPL-X, ANNY, MHR, SOMA, GarmentMeasurements
- Anatomicals: SKEL, MyoFullBody
- Heads: FLAME
- Hands: MANO
- Robots and humanoids: BrainCo, G1, SmplHumanoid
See the model docs for setup, supported runtimes, inputs, and model-specific behavior. The architecture guide describes the model, runtime, and shared-operation boundaries.
Development
uv run ruff format .
uv run ruff check .
uv run ty check
License
See the documentation and upstream model projects for model-specific license terms.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file body_models-0.22.0.tar.gz.
File metadata
- Download URL: body_models-0.22.0.tar.gz
- Upload date:
- Size: 146.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1834ff499411c08780946c3e094bf9aa05d888f47c0997dd5fd8de55fde50674
|
|
| MD5 |
bbcb2746e859325584728d1169d9357c
|
|
| BLAKE2b-256 |
e08607f9c8cceb86cc16afe98c8b8c863d7b7de56001f0cb7493ab7338c2ce27
|
File details
Details for the file body_models-0.22.0-py3-none-any.whl.
File metadata
- Download URL: body_models-0.22.0-py3-none-any.whl
- Upload date:
- Size: 210.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
634057d7bf3a526bcfb7003ad027256225ee50158f66ebba8291ff7d295a2faf
|
|
| MD5 |
3c78cf34f7a2585ca880912eabfccbb1
|
|
| BLAKE2b-256 |
6a494a927d71874ad04aa03a9cd9e974ed068b2c347f4778333fd0b504e292fd
|
