API reference¶

This page covers the interface every model shares. Model-specific options are on each model page.

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.

Models¶

Every model provides get_rest_pose(); whole-body models also provide 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, such as a marker or joint regressor, without building the posed mesh. The vertex count must match the model, including any mesh simplification.

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)

A prepared regressor stays on the device it was prepared on, so prepare it after moving the model. Mapped points are positions; forward_skeleton() returns joint transforms.

body_models.PointRegressor ¶

Bases: builtins.dict

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

Parameters and joints¶

ParameterRole is "identity", "pose", or "transform". RotationType is "axis_angle", "quat", "sixd", "matrix" (any 3×3 transform), or "rotmat" (a proper SO(3) rotation).

pose_joint_indices maps each pose parameter to the joints whose local transforms it drives. Rotational controls follow the same order, so control i ([..., i, :], or [..., i, :, :] for matrices) drives joint indices[i]:

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, and a control also moves its joint's descendants outside the group.

symmetric_joints lists (left, right) index pairs over the whole native skeleton, including joints outside Joint; unpaired joints lie on the midline. Use it for symmetry losses or 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, :, :]

Swapping indices does not mirror a pose: the rotations must also be reflected in the model's 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.