ANNY

ANNY is a phenotype-driven body model with configurable rigs and topology.

Setup

ANNY downloads automatically on first use from the abcamiletto/body-models Hugging Face repository (ANNY: Apache 2.0; MPFB2: CC0). To prefetch:

body-models download anny

API

Portable fitted poses

Save rotation_type with fitted parameters. Convert the parameters when loading into a model with a different representation:

from body_models.anny import convert_pose
from body_models.anny.torch import ANNY

model = ANNY(rotation_type="sixd")
parameters = convert_pose(cached_parameters, src=cached_rotation_type, dst=model.rotation_type)
vertices = model.forward_vertices(**parameters)

body_models.anny.numpy.ANNY

ANNY(
    *,
    model_path=None,
    rig="default",
    topology="default",
    all_phenotypes=False,
    extrapolate_phenotypes=False,
    rotation_type="axis_angle",
    simplify=1.0,
)

Bases: body_models.anny._model.ANNY

Phenotype-driven skinned body model.

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 posed ANNY joint transforms.
forward_vertices	Compute posed ANNY vertices.
get_rest_pose	Return centered phenotype controls and identity rotations.
joint_index	Resolve a common joint to this model's native joint index.
prepare_point_regressor	Preproject a vertex mapping for repeated point forwards.
get_apose	Return the ANNY rest A-pose.
get_tpose	Return the ANNY T-pose.
phenotype_to_shape	Pack named phenotype controls into the ANNY shape vector.
prepare_identity	Precompute phenotype-dependent state for repeated forward passes.
prepare_pose	Precompute pose-dependent state for repeated forward passes.

ATTRIBUTE	DESCRIPTION
common_joints	Common anatomical joints mapped to this model's native joint names.
has_face	bool(x) -> bool
has_hands	bool(x) -> bool
num_joints	Number of joints in the skeleton.
pose_joint_indices	Canonical joints whose local transforms are driven by each pose parameter.
runtime	Array runtime used by this model.
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.
NUM_BODY_CONTROLS	int([x]) -> integer
NUM_HAND_CONTROLS	int([x]) -> integer
NUM_HEAD_CONTROLS	int([x]) -> integer
NUM_SHAPE_COEFFS	int([x]) -> integer

common_joints property

common_joints

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

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 = True

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.

num_joints property

num_joints

Number of joints in the skeleton.

pose_joint_indices property

pose_joint_indices

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

runtime property

runtime

Array runtime used by this model.

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.

NUM_BODY_CONTROLS class-attribute

NUM_BODY_CONTROLS = 64

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

NUM_HAND_CONTROLS class-attribute

NUM_HAND_CONTROLS = 38

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

NUM_HEAD_CONTROLS class-attribute

NUM_HEAD_CONTROLS = 60

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

NUM_SHAPE_COEFFS class-attribute

NUM_SHAPE_COEFFS = 6

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

apply_pose_correctives

apply_pose_correctives(*, identity, pose)

Apply prepared pose correctives to identity-dependent rest vertices.

Source code in src/body_models/_base.py

def apply_pose_correctives(
    self,
    *,
    identity: SkinningIdentity,
    pose: SkinningPose,
) -> Float[Array, "*batch V 3"]:
    """Apply prepared pose correctives to identity-dependent rest vertices."""
    vertices = identity["rest_vertices"]
    coefficients = pose.get("pose_coefficients")
    if coefficients is None:
        return vertices
    basis = self._corrective_basis
    if basis is None:
        raise RuntimeError("Prepared pose has corrective coefficients, but the model has no corrective basis.")
    return vertices + basis.apply(coefficients)

forward_points

forward_points(
    body_pose,
    head_pose,
    hand_pose,
    *,
    point_regressor,
    shape=None,
    identity=None,
    global_rotation=None,
    global_translation=None,
)

Compute positions defined by a prepared vertex mapping.

Source code in src/body_models/anny/_model.py

def forward_points(
    self,
    body_pose: Float[Array, "*batch 64 N"] | Float[Array, "*batch 64 3 3"],
    head_pose: Float[Array, "*batch 60 N"] | Float[Array, "*batch 60 3 3"],
    hand_pose: Float[Array, "*batch 38 N"] | Float[Array, "*batch 38 3 3"],
    *,
    point_regressor: PointRegressor,
    shape: Float[Array, "*batch 6"] | None = None,
    identity: AnnyIdentity | None = None,
    global_rotation: Float[Array, "*batch N"] | Float[Array, "*batch 3 3"] | None = None,
    global_translation: Float[Array, "*batch 3"] | None = None,
) -> Float[Array, "*batch K 3"]:
    """Compute positions defined by a prepared vertex mapping."""
    self._validate_identity_arguments(identity, shape=shape)
    if identity is None:
        batch_shape = body_pose.shape[: -(self._num_rot_dims + 1)]
        identity = self.prepare_identity(*self._resolve_identity_coefficients(batch_shape, shape=shape))

    pose = self.prepare_pose(body_pose, head_pose, hand_pose, identity=identity)
    return self._deform_points(point_regressor, identity, pose, global_rotation, global_translation)

forward_skeleton

forward_skeleton(
    body_pose,
    head_pose,
    hand_pose,
    *,
    shape=None,
    identity=None,
    global_rotation=None,
    global_translation=None,
    joint_indices=None,
)

Compute posed ANNY joint transforms.

Source code in src/body_models/anny/_model.py

def forward_skeleton(
    self,
    body_pose: Float[Array, "*batch 64 N"] | Float[Array, "*batch 64 3 3"],
    head_pose: Float[Array, "*batch 60 N"] | Float[Array, "*batch 60 3 3"],
    hand_pose: Float[Array, "*batch 38 N"] | Float[Array, "*batch 38 3 3"],
    *,
    shape: Float[Array, "*batch 6"] | None = None,
    identity: AnnyIdentity | None = None,
    global_rotation: Float[Array, "*batch N"] | Float[Array, "*batch 3 3"] | None = None,
    global_translation: Float[Array, "*batch 3"] | None = None,
    joint_indices: Sequence[int] | None = None,
) -> Float[Array, "*batch J 4 4"]:
    """Compute posed ANNY joint transforms."""
    xp = self._runtime.xp
    self._validate_identity_arguments(identity, shape=shape)
    batch_shape = tuple(body_pose.shape[: -(self._num_rot_dims + 1)])
    if identity is None:
        resolved = self._resolve_identity_coefficients(batch_shape, shape=shape)
        skeleton_identity = self._prepare_skeleton_identity(*resolved)
    else:
        skeleton_identity = identity

    root_rotation = SO3.identity_as(
        body_pose,
        batch_dims=batch_shape,
        rotation_type=self.rotation_type,
        xp=xp,
    )
    packed_pose = pose_utils.pack_pose(xp, root_rotation, body_pose, head_pose, hand_pose)
    skeleton = core.prepare_skeleton(
        self._runtime,
        self._assets.kinematic_tree,
        packed_pose,
        self.rotation_type,
        rest_skeleton_transforms=skeleton_identity["rest_skeleton_transforms"],
        joint_indices=joint_indices,
    )
    return skinning.transform_skeleton(
        skeleton,
        global_rotation,
        global_translation,
        self.rotation_type,
        xp=xp,
    )

forward_vertices

forward_vertices(
    body_pose,
    head_pose,
    hand_pose,
    *,
    shape=None,
    identity=None,
    global_rotation=None,
    global_translation=None,
    vertex_indices=None,
)

Compute posed ANNY vertices.

Source code in src/body_models/anny/_model.py

def forward_vertices(
    self,
    body_pose: Float[Array, "*batch 64 N"] | Float[Array, "*batch 64 3 3"],
    head_pose: Float[Array, "*batch 60 N"] | Float[Array, "*batch 60 3 3"],
    hand_pose: Float[Array, "*batch 38 N"] | Float[Array, "*batch 38 3 3"],
    *,
    shape: Float[Array, "*batch 6"] | None = None,
    identity: AnnyIdentity | None = None,
    global_rotation: Float[Array, "*batch N"] | Float[Array, "*batch 3 3"] | None = None,
    global_translation: Float[Array, "*batch 3"] | None = None,
    vertex_indices: Sequence[int] | None = None,
) -> Float[Array, "*batch V 3"]:
    """Compute posed ANNY vertices."""
    xp = self._runtime.xp
    self._validate_identity_arguments(identity, shape=shape)
    if identity is None:
        batch_shape = body_pose.shape[: -(self._num_rot_dims + 1)]
        identity = self.prepare_identity(*self._resolve_identity_coefficients(batch_shape, shape=shape))

    pose = self.prepare_pose(body_pose, head_pose, hand_pose, identity=identity)
    vertices = self._runtime._skin_vertices(
        identity["rest_vertices"],
        pose["skinning_transforms"],
        skinning=self._assets.compact_skinning,
        vertex_indices=vertex_indices,
    )
    return skinning.apply_global_transform(
        vertices,
        global_rotation,
        global_translation,
        self.rotation_type,
        xp=xp,
    )

get_rest_pose

get_rest_pose(*, batch_dims=(), dtype=None, hands='default')

Return centered phenotype controls and identity rotations.

Source code in src/body_models/anny/_model.py

def get_rest_pose(
    self,
    *,
    batch_dims: tuple[int, ...] = (),
    dtype: Any | None = None,
    hands: HandPreset = "default",
) -> dict[str, Float[Array, "..."]]:
    """Return centered phenotype controls and identity rotations."""
    if hands not in ("default", "flat", "rest"):
        raise ValueError(f"Invalid hands: {hands!r}")

    params = super().get_rest_pose(batch_dims=batch_dims, dtype=dtype)
    if hands != "default":
        runtime = self.runtime
        axis_angle = runtime.asarray(ANNY_HAND_PRESETS[hands], like=params["hand_pose"]).reshape(-1, 3)
        axis_angle = runtime.xp.broadcast_to(axis_angle, (*batch_dims, *axis_angle.shape))
        params["hand_pose"] = SO3.convert(
            axis_angle,
            src="axis_angle",
            dst=self.rotation_type,
            xp=runtime.xp,
        )
    return params

joint_index

joint_index(joint)

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

Source code in src/body_models/_base.py

def joint_index(self, joint: Joint) -> int:
    """Resolve a common joint to this model's native joint index."""
    if not isinstance(joint, Joint):
        raise TypeError("joint_index() expects a body_models.Joint; use joint_names.index(...) for native names.")
    try:
        native_name = self.common_joints[joint]
    except KeyError as exc:
        raise KeyError(f"{self.__class__.__name__} has no common joint {joint.value!r}") from exc
    return self.joint_names.index(native_name)

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.

Source code in src/body_models/_base.py

def prepare_point_regressor(
    self,
    mapping: Float[Array, "K V"],
) -> PointRegressor:
    """Preproject a vertex mapping for repeated point forwards.

    For Torch, call this after moving the model to its target device.
    """
    if mapping.ndim != 2 or mapping.shape[0] < 1 or mapping.shape[1] != self.num_vertices:
        raise ValueError(
            f"mapping must have shape [K, {self.num_vertices}] with K >= 1, got {tuple(mapping.shape)}"
        )
    mapping = self._runtime.asarray(mapping, like=self.rest_vertices)
    return point_regression.prepare_point_regressor(
        mapping,
        self._skinning_weights,
        self._corrective_basis,
        runtime=self._runtime,
    )

get_apose

get_apose(*, batch_dims=(), dtype=None, hands='default')

Return the ANNY rest A-pose.

Source code in src/body_models/anny/_model.py

def get_apose(
    self,
    *,
    batch_dims: tuple[int, ...] = (),
    dtype: Any | None = None,
    hands: HandPreset = "default",
) -> dict[str, Float[Array, "..."]]:
    """Return the ANNY rest A-pose."""
    return self.get_rest_pose(batch_dims=batch_dims, dtype=dtype, hands=hands)

get_tpose

get_tpose(*, batch_dims=(), dtype=None, hands='default')

Return the ANNY T-pose.

Source code in src/body_models/anny/_model.py

def get_tpose(
    self,
    *,
    batch_dims: tuple[int, ...] = (),
    dtype: Any | None = None,
    hands: HandPreset = "default",
) -> dict[str, Float[Array, "..."]]:
    """Return the ANNY T-pose."""
    params = self.get_rest_pose(batch_dims=batch_dims, dtype=dtype, hands=hands)
    axis_angle = self._runtime.asarray(ANNY_BODY_PRESETS["t_pose"], like=params["body_pose"])
    axis_angle = self._runtime.xp.broadcast_to(axis_angle, (*batch_dims, *axis_angle.shape))
    params["body_pose"] = SO3.convert(
        axis_angle,
        src="axis_angle",
        dst=self.rotation_type,
        xp=self._runtime.xp,
    )
    return params

phenotype_to_shape

phenotype_to_shape(gender, age, muscle, weight, height, proportions)

Pack named phenotype controls into the ANNY shape vector.

Source code in src/body_models/anny/_model.py

def phenotype_to_shape(
    self,
    gender: Float[Array, "*batch"],
    age: Float[Array, "*batch"],
    muscle: Float[Array, "*batch"],
    weight: Float[Array, "*batch"],
    height: Float[Array, "*batch"],
    proportions: Float[Array, "*batch"],
) -> Float[Array, "*batch 6"]:
    """Pack named phenotype controls into the ANNY shape vector."""
    return self._runtime.xp.stack([gender, age, muscle, weight, height, proportions], axis=-1)

prepare_identity

prepare_identity(shape)

Precompute phenotype-dependent state for repeated forward passes.

Source code in src/body_models/anny/_model.py

def prepare_identity(
    self,
    shape: Float[Array, "*batch 6"],
) -> AnnyIdentity:
    """Precompute phenotype-dependent state for repeated forward passes."""
    return core.prepare_identity(
        xp=self._runtime.xp,
        template_vertices=self._assets.template_vertices,
        blendshapes=self._assets.blendshapes,
        template_bone_heads=self._assets.template_bone_heads,
        template_bone_tails=self._assets.template_bone_tails,
        bone_heads_blendshapes=self._assets.bone_heads_blendshapes,
        bone_tails_blendshapes=self._assets.bone_tails_blendshapes,
        bone_rolls_rotmat=self._assets.bone_rolls_rotmat,
        phenotype_mask=self._assets.phenotype_mask,
        anchors=self._assets.anchors,
        y_axis=self._assets.y_axis,
        degenerate_rotation=self._assets.degenerate_rotation,
        extrapolate_phenotypes=self.extrapolate_phenotypes,
        shape=shape,
    )

prepare_pose

prepare_pose(body_pose, head_pose, hand_pose, *, identity)

Precompute pose-dependent state for repeated forward passes.

Source code in src/body_models/anny/_model.py

def prepare_pose(
    self,
    body_pose: Float[Array, "*batch 64 N"] | Float[Array, "*batch 64 3 3"],
    head_pose: Float[Array, "*batch 60 N"] | Float[Array, "*batch 60 3 3"],
    hand_pose: Float[Array, "*batch 38 N"] | Float[Array, "*batch 38 3 3"],
    *,
    identity: AnnyIdentity,
) -> SkinningPose:
    """Precompute pose-dependent state for repeated forward passes."""
    xp = self._runtime.xp
    batch_shape = tuple(body_pose.shape[: -(self._num_rot_dims + 1)])
    root_rotation = SO3.identity_as(
        body_pose,
        batch_dims=batch_shape,
        rotation_type=self.rotation_type,
        xp=xp,
    )
    packed_pose = pose_utils.pack_pose(xp, root_rotation, body_pose, head_pose, hand_pose)
    return core.prepare_pose(
        self._runtime,
        self._assets.kinematic_tree,
        packed_pose,
        self.rotation_type,
        rest_skeleton_transforms=identity["rest_skeleton_transforms"],
    )

body_models.anny.convert_pose

convert_pose(parameters, *, src, dst)

Convert the rotations in an ANNY parameter dictionary.

Source code in src/body_models/anny/_pose.py

def convert_pose(
    parameters: Mapping[str, Any],
    *,
    src: rotations.RotationType,
    dst: rotations.RotationType,
) -> dict[str, Any]:
    """Convert the rotations in an ANNY parameter dictionary."""
    converted = dict(parameters)
    for key in ("body_pose", "head_pose", "hand_pose", "global_rotation"):
        value = converted.get(key)
        if value is not None:
            converted[key] = SO3.convert(value, src=src, dst=dst)
    return converted