API reference¶

Public names are exported from body_models, model packages, and backend modules. See model pages for model-specific APIs.

Model creation¶

body_models.create_model ¶

create_model(model_name, *, runtime='numpy', **kwargs)

Create a model from its public catalog name.

PARAMETER	DESCRIPTION
`model_name`	Name returned by :func:`list_models`. Names are case-insensitive, and underscores are treated as hyphens. TYPE: `str`
`runtime`	Array backend name. TYPE: `Literal` DEFAULT: `'numpy'`
`**kwargs`	Model-specific constructor options. TYPE: `Any`

RETURNS	DESCRIPTION
`SkinnedModel`	The requested articulated model.

RAISES	DESCRIPTION
`ValueError`	If `model_name` is unknown.

body_models.list_models ¶

list_models(*, pattern=None)

List public model factory names.

PARAMETER	DESCRIPTION
`pattern`	Optional case-insensitive shell-style pattern such as `"smpl"`. TYPE:* `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[str]`	Sorted matching model names.

Model contracts¶

Every model provides get_rest_pose(). Models with whole-body presets also expose get_tpose() and get_apose().

body_models.SkinnedModel ¶

Bases: abc.ABC

Base class for skinned body models.

METHOD	DESCRIPTION
`apply_pose_correctives`	Apply prepared pose correctives to identity-dependent rest vertices.
`forward_points`	Compute positions defined by a prepared vertex mapping.
`forward_skeleton`	Compute skeleton joint transforms.
`forward_vertices`	Compute mesh vertices.
`get_rest_pose`	Construct canonical parameter defaults from :attr:`parameter_spec`.
`joint_index`	Resolve a common joint to this model's native joint index.
`prepare_point_regressor`	Preproject a vertex mapping for repeated point forwards.

ATTRIBUTE	DESCRIPTION
`common_joints`	Common anatomical joints mapped to this model's native joint names.
`faces`	Mesh face indices. Shape [F, 3] for triangles or [F, 4] for quads.
`has_face`	bool(x) -> bool
`has_hands`	bool(x) -> bool
`joint_names`	Joint names in joint index order.
`num_joints`	Number of joints in the skeleton.
`num_vertices`	Number of mesh vertices.
`parameter_spec`	Machine-readable parameters accepted by this model.
`parents`	Parent indices in joint_names order, with -1 for the root.
`pose_joint_indices`	Canonical joints whose local transforms are driven by each pose parameter.
`rest_vertices`	Mesh vertices in rest pose. Shape [V, 3].
`runtime`	Array runtime used by this model.
`skin_weights`	Skinning weights aligned with the public skeleton. Shape [V, J].
`skinning_spec`	Static topology, render-rig weights, and optional pose correctives.
`symmetric_joints`	Left/right joint pairs as `(left_index, right_index)`, in joint order.

common_joints `property` ¶

common_joints

Common anatomical joints mapped to this model's native joint names.

faces `property` ¶

faces

Mesh face indices. Shape [F, 3] for triangles or [F, 4] for quads.

has_face `class-attribute` ¶

has_face = False

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

has_hands `class-attribute` ¶

has_hands = False

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

joint_names `property` ¶

joint_names

Joint names in joint index order.

num_joints `property` ¶

num_joints

Number of joints in the skeleton.

num_vertices `property` ¶

num_vertices

Number of mesh vertices.

parameter_spec `property` ¶

parameter_spec

Machine-readable parameters accepted by this model.

parents `property` ¶

parents

Parent indices in joint_names order, with -1 for the root.

pose_joint_indices `property` ¶

pose_joint_indices

Canonical joints whose local transforms are driven by each pose parameter.

rest_vertices `property` ¶

rest_vertices

Mesh vertices in rest pose. Shape [V, 3].

runtime `property` ¶

runtime

Array runtime used by this model.

skin_weights `property` ¶

skin_weights

Skinning weights aligned with the public skeleton. Shape [V, J].

skinning_spec `property` ¶

skinning_spec

Static topology, render-rig weights, and optional pose correctives.

symmetric_joints `property` ¶

symmetric_joints

Left/right joint pairs as (left_index, right_index), in joint order.

Indices address the J axis of :meth:forward_skeleton outputs and cover the whole native skeleton, including joints outside the :class:Joint vocabulary. Unpaired joints lie on the midline. Pairs describe index correspondence only, not how to mirror a pose.

RAISES	DESCRIPTION
`ValueError`	If a sided joint name has no counterpart.

apply_pose_correctives ¶

apply_pose_correctives(*, identity, pose)

Apply prepared pose correctives to identity-dependent rest vertices.

forward_points ¶

forward_points(*args, **kwargs)

Compute positions defined by a prepared vertex mapping.

Signatures vary by model. Outputs use the model's native coordinate system and meters.

forward_skeleton ¶

forward_skeleton(*args, **kwargs)

Compute skeleton joint transforms.

Signatures vary by model. Outputs use the model's native coordinate system and meters.

RETURNS	DESCRIPTION
`Float[Any, '*batch J 4 4']`	World-space transforms with shape `[*batch, J, 4, 4]` in meters.

forward_vertices ¶

forward_vertices(*args, **kwargs)

Compute mesh vertices.

Signatures vary by model. Outputs use the model's native coordinate system and meters.

RETURNS	DESCRIPTION
`Float[Any, '*batch V 3']`	Mesh vertices with shape `[*batch, V, 3]` in meters.

get_rest_pose ¶

get_rest_pose(*, batch_dims=(), dtype=None)

Construct canonical parameter defaults from :attr:parameter_spec.

PARAMETER	DESCRIPTION
`batch_dims`	Leading batch dimensions. TYPE: `tuple[int, ...]` DEFAULT: `()`
`dtype`	Optional floating-point dtype. TYPE: `Any \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Float[Any, ...]]`	Complete model parameters at rest.

joint_index ¶

joint_index(joint)

Resolve a common joint to this model's native joint index.

prepare_point_regressor ¶

prepare_point_regressor(mapping)

Preproject a vertex mapping for repeated point forwards.

For Torch, call this after moving the model to its target device.

Mapped points¶

forward_points() evaluates a dense [points, vertices] mapping without producing the posed mesh. Its vertex dimension must match the model and mesh simplification. Prepare the regressor after moving a Torch model to its final device:

import numpy as np
import torch

from body_models.smplx.torch import SMPLX

model = SMPLX(gender="neutral").cuda()
mapping = np.load("captury_J_regressor.npz")["J_regressor"]
regressor = model.prepare_point_regressor(mapping)
params = model.get_rest_pose(batch_dims=(2048,))

with torch.inference_mode():
    points = model.forward_points(**params, point_regressor=regressor)
# points.shape == (2048, 67, 3)

Mapped points contain positions; forward_skeleton() returns native joint transforms. Prepared regressors do not follow later .to() calls.

body_models.PointRegressor ¶

Bases: builtins.dict

A vertex mapping projected through a model's static deformation state.

Parameter and joint metadata¶

ParameterRole is the literal "identity", "pose", or "transform". RotationType accepts "axis_angle", "quat", "sixd", "matrix", or "rotmat". matrix is an arbitrary 3×3 transform; rotmat is a proper SO(3) rotation.

pose_joint_indices maps pose parameters to the distinct canonical joints whose local transforms they drive. Use these tuples to select skeleton outputs:

hand_indices = model.pose_joint_indices["hand_pose"]
hand_skeleton = model.forward_skeleton(**params, joint_indices=hand_indices)

Indices refer to the full skeleton. Groups may overlap and omit fixed joints. Changing a local transform also moves descendants outside its group. Rotational controls map one-to-one to indices in control order: [..., i, :] for vectors, [..., i, :, :] for matrices.

symmetric_joints lists (left_index, right_index) pairs for symmetry losses and left/right swaps:

order = list(range(model.num_joints))
for left, right in model.symmetric_joints:
    order[left], order[right] = right, left
swapped = model.forward_skeleton(**params)[..., order, :, :]

Pairs cover the native skeleton, including joints outside Joint, such as SMPL's collars. Unpaired joints lie on the midline. Swapping indices does not mirror a pose; callers must also reflect rotations in the model's coordinate frame and parameterization.

body_models.ParameterSpec ¶

ParameterSpec(dims, role, *, default=0.0, rotation_type=None)

Array dims, role, and numeric default of one model parameter.

METHOD	DESCRIPTION
`rotation`	Describe one rotation or a vector of rotations.

ATTRIBUTE	DESCRIPTION
`default`	Convert a string or number to a floating point number, if possible.

default `class-attribute` ¶

default = 0.0

Convert a string or number to a floating point number, if possible.

rotation `classmethod` ¶

rotation(rotation_type, *, count=None, role='pose')

Describe one rotation or a vector of rotations.