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
import body_models
model = body_models.create_model("smpl", runtime="torch")
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.
Runtime-specific options stay in the runtime rather than every model signature:
runtime = body_models.TorchRuntime(skinning_backend="warp")
model = body_models.create_model("smpl", runtime=runtime)
module = model.as_module().cuda()
as_module() returns one cached torch.nn.Module view per model. The view
shares numeric state with the model, so device and dtype changes apply to both,
without changing the underlying model class.
Discover available model names with body_models.list_models(). Model options
such as gender="male" or side="left" are passed as constructor kwargs.
Public API
The stable API consists of names exported from body_models and each model
package. For example, body_models.smpl.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 and runtime
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.21.1.tar.gz.
File metadata
- Download URL: body_models-0.21.1.tar.gz
- Upload date:
- Size: 141.2 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 |
2b4254514de8cec1750dfda7b6caf11136a316413b63da6b95419cdda2a8755d
|
|
| MD5 |
d28c439327c9f852e9eeea9f2b83a389
|
|
| BLAKE2b-256 |
599c765e28485f4aa4eb566878b6923e6823f092cc72264a682d644c21d2497b
|
File details
Details for the file body_models-0.21.1-py3-none-any.whl.
File metadata
- Download URL: body_models-0.21.1-py3-none-any.whl
- Upload date:
- Size: 197.1 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 |
7c6f646403fb610f47614d8a4118351956e15b8e831daf439c3575ab306df69f
|
|
| MD5 |
126958afc7579ff4670c2ef1c04dc7bb
|
|
| BLAKE2b-256 |
0fa6c5311fdec7a5896491dd80068ad65a0a494890d1024c96409c13389645dc
|
