ANNY

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

Setup

ANNY downloads automatically on first use. To prefetch and save the path:

# Download the ANNY assets and store their path in the body-models config.
body-models download anny

API

body_models.bodies.anny.numpy.ANNY

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

Bases: BodyModel

ANNY body model with NumPy backend.

Initialize the ANNY model.

PARAMETER	DESCRIPTION
model_path	Path to model assets, or the default assets when omitted. TYPE: Path | str | None DEFAULT: None
rig	Rig variant to load. TYPE: str DEFAULT: 'default'
topology	Mesh topology variant to load. TYPE: str DEFAULT: 'default'
all_phenotypes	Whether to expose the full phenotype control set. TYPE: bool DEFAULT: False
extrapolate_phenotypes	Whether phenotype values may extend beyond the trained range. TYPE: bool DEFAULT: False
simplify	Mesh simplification factor to apply while loading. TYPE: float DEFAULT: 1.0
rotation_type	Rotation representation expected by pose inputs. TYPE: RotationType DEFAULT: 'axis_angle'
kernel	Backend kernel used for forward evaluation. TYPE: Literal['numpy', 'numba'] DEFAULT: 'numpy'

METHOD	DESCRIPTION
forward_vertices	Compute posed mesh vertices.
forward_skeleton	Compute posed joint transforms.
prepare_identity	Precompute phenotype-dependent state for repeated forward passes.
phenotype_to_shape	Pack named phenotype controls into the ANNY shape vector.
prepare_pose	Precompute pose-dependent state for repeated forward passes.
joint_index	Resolve a standard joint to this model's native joint index.

ATTRIBUTE	DESCRIPTION
common_joints	Common anatomical joints mapped to this model's native joint names. TYPE: Mapping[Joint, str]

Source code in src/body_models/bodies/anny/numpy.py

def __init__(
    self,
    model_path: Path | str | None = None,
    *,
    rig: str = "default",
    topology: str = "default",
    all_phenotypes: bool = False,
    extrapolate_phenotypes: bool = False,
    simplify: float = 1.0,
    rotation_type: RotationType = "axis_angle",
    kernel: Literal["numpy", "numba"] = "numpy",
) -> None:
    """Initialize the ANNY model.

    Args:
        model_path: Path to model assets, or the default assets when omitted.
        rig: Rig variant to load.
        topology: Mesh topology variant to load.
        all_phenotypes: Whether to expose the full phenotype control set.
        extrapolate_phenotypes: Whether phenotype values may extend beyond the trained range.
        simplify: Mesh simplification factor to apply while loading.
        rotation_type: Rotation representation expected by pose inputs.
        kernel: Backend kernel used for forward evaluation.
    """
    if rig not in ("default", "default_no_toes", "cmu_mb", "game_engine", "mixamo"):
        raise ValueError(f"Invalid rig: {rig}")
    if topology not in ("default", "makehuman"):
        raise ValueError(f"Invalid topology: {topology}")
    if simplify < 1.0:
        raise ValueError("simplify must be >= 1.0")
    if rotation_type not in VALID_ROTATION_TYPES:
        raise ValueError(f"Invalid rotation_type: {rotation_type}")
    if kernel not in self.kernels:
        raise ValueError(f"Invalid kernel: {kernel}")

    self.weights = load_model_data_numpy(model_path, rig=rig, topology=topology, simplify=simplify)
    self.extrapolate_phenotypes = extrapolate_phenotypes
    self.all_phenotypes = all_phenotypes
    self.rotation_type = rotation_type
    self.num_rot_dims = 2 if rotation_type in ("matrix", "rotmat") else 1
    self._kernel = _get_kernel(kernel)
    self.phenotype_labels = (
        PHENOTYPE_LABELS if all_phenotypes else [x for x in PHENOTYPE_LABELS if x not in EXCLUDED_PHENOTYPES]
    )

common_joints property

common_joints

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

forward_vertices

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

Compute posed mesh vertices.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B 64 N'] | Float[ndarray, 'B 64 3 3']
head_pose	Local head and facial joint rotations. TYPE: Float[ndarray, 'B 60 N'] | Float[ndarray, 'B 60 3 3']
hand_pose	Local hand joint rotations. TYPE: Float[ndarray, 'B 38 N'] | Float[ndarray, 'B 38 3 3']
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B N'] | Float[ndarray, 'B 3 3']
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
vertex_indices	Optional subset of vertices to return. TYPE: Any | None DEFAULT: None
shape	Packed phenotype controls. TYPE: Float[ndarray, '*batch 6'] | None DEFAULT: None
identity	Optional output from :meth:prepare_identity. TYPE: AnnyIdentity | None DEFAULT: None

RETURNS	DESCRIPTION
Float[ndarray, 'B V 3']	Posed vertex positions.

Source code in src/body_models/bodies/anny/numpy.py

def forward_vertices(
    self,
    body_pose: Float[np.ndarray, "B 64 N"] | Float[np.ndarray, "B 64 3 3"],
    head_pose: Float[np.ndarray, "B 60 N"] | Float[np.ndarray, "B 60 3 3"],
    hand_pose: Float[np.ndarray, "B 38 N"] | Float[np.ndarray, "B 38 3 3"],
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"],
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    vertex_indices: Any | None = None,
    *,
    shape: Float[np.ndarray, "*batch 6"] | None = None,
    identity: AnnyIdentity | None = None,
) -> Float[np.ndarray, "B V 3"]:
    """Compute posed mesh vertices.

    Args:
        body_pose: Local body joint rotations.
        head_pose: Local head and facial joint rotations.
        hand_pose: Local hand joint rotations.
        global_rotation: Global model rotation.
        global_translation: Global model translation.
        vertex_indices: Optional subset of vertices to return.
        shape: Packed phenotype controls.
        identity: Optional output from :meth:`prepare_identity`.

    Returns:
        Posed vertex positions.
    """
    if identity is None:
        assert shape is not None
        pose = pose_utils.pack_pose(np, global_rotation, body_pose, head_pose, hand_pose)
        batch_shape = tuple(pose.shape[: -(self.num_rot_dims + 1)])
        shape = np.broadcast_to(shape, (*batch_shape, shape.shape[-1]))
        identity = self.prepare_identity(shape)
    prepared_pose = self.prepare_pose(body_pose, head_pose, hand_pose, global_rotation, identity=identity)
    return self._kernel.forward_vertices(
        self.weights,
        identity["rest_vertices"],
        prepared_pose["skinning_transforms"],
        global_translation=global_translation,
        vertex_indices=vertex_indices,
    )

forward_skeleton

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

Compute posed joint transforms.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B 64 N'] | Float[ndarray, 'B 64 3 3']
head_pose	Local head and facial joint rotations. TYPE: Float[ndarray, 'B 60 N'] | Float[ndarray, 'B 60 3 3']
hand_pose	Local hand joint rotations. TYPE: Float[ndarray, 'B 38 N'] | Float[ndarray, 'B 38 3 3']
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B N'] | Float[ndarray, 'B 3 3']
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
joint_indices	Optional subset of joints to return. TYPE: Any | None DEFAULT: None
shape	Packed phenotype controls. TYPE: Float[ndarray, '*batch 6'] | None DEFAULT: None
identity	Optional output from :meth:prepare_identity. TYPE: AnnyIdentity | None DEFAULT: None

RETURNS	DESCRIPTION
Float[ndarray, 'B J 4 4']	Joint transforms in the model hierarchy.

Source code in src/body_models/bodies/anny/numpy.py

def forward_skeleton(
    self,
    body_pose: Float[np.ndarray, "B 64 N"] | Float[np.ndarray, "B 64 3 3"],
    head_pose: Float[np.ndarray, "B 60 N"] | Float[np.ndarray, "B 60 3 3"],
    hand_pose: Float[np.ndarray, "B 38 N"] | Float[np.ndarray, "B 38 3 3"],
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"],
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    joint_indices: Any | None = None,
    *,
    shape: Float[np.ndarray, "*batch 6"] | None = None,
    identity: AnnyIdentity | None = None,
) -> Float[np.ndarray, "B J 4 4"]:
    """Compute posed joint transforms.

    Args:
        body_pose: Local body joint rotations.
        head_pose: Local head and facial joint rotations.
        hand_pose: Local hand joint rotations.
        global_rotation: Global model rotation.
        global_translation: Global model translation.
        joint_indices: Optional subset of joints to return.
        shape: Packed phenotype controls.
        identity: Optional output from :meth:`prepare_identity`.

    Returns:
        Joint transforms in the model hierarchy.
    """
    if identity is None:
        assert shape is not None
        pose = pose_utils.pack_pose(np, global_rotation, body_pose, head_pose, hand_pose)
        batch_shape = tuple(pose.shape[: -(self.num_rot_dims + 1)])
        shape = np.broadcast_to(shape, (*batch_shape, shape.shape[-1]))
        identity = self.prepare_identity(shape, skip_vertices=True)
    prepared_pose = self.prepare_pose(
        body_pose,
        head_pose,
        hand_pose,
        global_rotation,
        identity=identity,
        skip_vertices=True,
    )
    return self._kernel.forward_skeleton(
        self.weights,
        prepared_pose["skeleton_transforms"],
        global_translation=global_translation,
        joint_indices=joint_indices,
    )

prepare_identity

prepare_identity(shape, skip_vertices=False)

Precompute phenotype-dependent state for repeated forward passes.

Source code in src/body_models/bodies/anny/numpy.py

def prepare_identity(
    self,
    shape: Float[np.ndarray, "*batch 6"],
    skip_vertices: bool = False,
) -> AnnyIdentity:
    """Precompute phenotype-dependent state for repeated forward passes."""
    return self._kernel.prepare_identity(
        self.weights,
        shape,
        extrapolate_phenotypes=self.extrapolate_phenotypes,
        skip_vertices=skip_vertices,
    )

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/bodies/anny/numpy.py

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

prepare_pose

prepare_pose(
    body_pose,
    head_pose,
    hand_pose,
    global_rotation,
    *,
    identity,
    skip_vertices=False,
)

Precompute pose-dependent state for repeated forward passes.

Source code in src/body_models/bodies/anny/numpy.py

def prepare_pose(
    self,
    body_pose: Float[np.ndarray, "B 64 N"] | Float[np.ndarray, "B 64 3 3"],
    head_pose: Float[np.ndarray, "B 60 N"] | Float[np.ndarray, "B 60 3 3"],
    hand_pose: Float[np.ndarray, "B 38 N"] | Float[np.ndarray, "B 38 3 3"],
    global_rotation: Float[np.ndarray, "B N"] | Float[np.ndarray, "B 3 3"],
    *,
    identity: AnnyIdentity,
    skip_vertices: bool = False,
) -> AnnyPreparedPose:
    """Precompute pose-dependent state for repeated forward passes."""
    pose = pose_utils.pack_pose(np, global_rotation, body_pose, head_pose, hand_pose)
    return self._kernel.prepare_pose(
        self.weights,
        pose,
        rotation_type=self.rotation_type,
        rest_skeleton_transforms=identity["rest_skeleton_transforms"],
        skip_vertices=skip_vertices,
    )

joint_index

joint_index(joint)

Resolve a standard 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 standard 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 standard joint {joint.value!r}") from exc
    return self.joint_names.index(native_name)