MHR

MHR is an expressive full-body model with neural pose correctives.

Setup

MHR downloads from the public abcamiletto/body-models Hugging Face repository on first use. The hosted package keeps the original MHR checkpoint for the default LOD 1 path and adds preprocessed FBX-derived mesh assets for LODs 0 through 6.

To prefetch and save the path:

# Download the MHR assets and store their path in the body-models config.
body-models download mhr

The original MHR license is included with the hosted assets.

API

body_models.bodies.mhr.numpy.MHR

MHR(model_path=None, *, lod=1, simplify=1.0)

Bases: SkinnedModel

MHR body model with NumPy backend.

Initialize the MHR model.

PARAMETER	DESCRIPTION
model_path	Path to model assets, or the default assets when omitted. TYPE: Path | str | None DEFAULT: None
lod	Level-of-detail variant to load. TYPE: int DEFAULT: 1
simplify	Mesh simplification factor to apply while loading. TYPE: float DEFAULT: 1.0

METHOD	DESCRIPTION
forward_vertices	Compute posed mesh vertices.
forward_skeleton	Compute posed joint transforms.
prepare_identity	Precompute shape- and expression-dependent state for repeated forward passes.
prepare_pose	Precompute pose-dependent state for repeated forward passes.
joint_index	Resolve a standard joint to this model's native joint index.
prepare_skinning	Pack prepared model state into renderer-ready skinning inputs.

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

def __init__(
    self,
    model_path: Path | str | None = None,
    *,
    lod: int = 1,
    simplify: float = 1.0,
) -> None:
    """Initialize the MHR model.

    Args:
        model_path: Path to model assets, or the default assets when omitted.
        lod: Level-of-detail variant to load.
        simplify: Mesh simplification factor to apply while loading.
    """
    self.weights = load_model_data(get_model_path(model_path), lod=lod, simplify=simplify)

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,
    expression,
    global_rotation=None,
    global_translation=None,
    vertex_indices=None,
    *,
    shape=None,
    identity=None,
)

Compute posed mesh vertices.

PARAMETER	DESCRIPTION
shape	Shape coefficients. TYPE: Float[ndarray, '*batch 45'] | None DEFAULT: None
body_pose	Local body joint rotations. TYPE: Float[ndarray, '*batch 94']
head_pose	Local head and facial controls. TYPE: Float[ndarray, '*batch 6']
hand_pose	Local hand joint rotations. TYPE: Float[ndarray, '*batch 104']
expression	Facial expression coefficients. TYPE: Float[ndarray, '*batch 72']
global_rotation	Global model rotation. TYPE: Float[ndarray, '*batch 3'] | None DEFAULT: None
global_translation	Global model translation. TYPE: Float[ndarray, '*batch 3'] | None DEFAULT: None
vertex_indices	Optional subset of vertices to return. TYPE: Any | None DEFAULT: None

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

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

def forward_vertices(
    self,
    body_pose: Float[np.ndarray, "*batch 94"],
    head_pose: Float[np.ndarray, "*batch 6"],
    hand_pose: Float[np.ndarray, "*batch 104"],
    expression: Float[np.ndarray, "*batch 72"],
    global_rotation: Float[np.ndarray, "*batch 3"] | None = None,
    global_translation: Float[np.ndarray, "*batch 3"] | None = None,
    vertex_indices: Any | None = None,
    *,
    shape: Float[np.ndarray, "*batch 45"] | None = None,
    identity: MhrIdentity | None = None,
) -> Float[np.ndarray, "*batch V 3"]:
    """Compute posed mesh vertices.

    Args:
        shape: Shape coefficients.
        body_pose: Local body joint rotations.
        head_pose: Local head and facial controls.
        hand_pose: Local hand joint rotations.
        expression: Facial expression coefficients.
        global_rotation: Global model rotation.
        global_translation: Global model translation.
        vertex_indices: Optional subset of vertices to return.

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

forward_skeleton

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

Compute posed joint transforms.

PARAMETER	DESCRIPTION
shape	Shape coefficients. TYPE: Float[ndarray, '*batch 45'] | None DEFAULT: None
body_pose	Local body joint rotations. TYPE: Float[ndarray, '*batch 94']
head_pose	Local head and facial controls. TYPE: Float[ndarray, '*batch 6']
hand_pose	Local hand joint rotations. TYPE: Float[ndarray, '*batch 104']
expression	Facial expression coefficients. TYPE: Float[ndarray, '*batch 72']
global_rotation	Global model rotation. TYPE: Float[ndarray, '*batch 3'] | None DEFAULT: None
global_translation	Global model translation. TYPE: Float[ndarray, '*batch 3'] | None DEFAULT: None
joint_indices	Optional subset of joints to return. TYPE: Any | None DEFAULT: None

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

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

def forward_skeleton(
    self,
    body_pose: Float[np.ndarray, "*batch 94"],
    head_pose: Float[np.ndarray, "*batch 6"],
    hand_pose: Float[np.ndarray, "*batch 104"],
    expression: Float[np.ndarray, "*batch 72"],
    global_rotation: Float[np.ndarray, "*batch 3"] | None = None,
    global_translation: Float[np.ndarray, "*batch 3"] | None = None,
    joint_indices: Any | None = None,
    *,
    shape: Float[np.ndarray, "*batch 45"] | None = None,
    identity: MhrIdentity | None = None,
) -> Float[np.ndarray, "*batch J 4 4"]:
    """Compute posed joint transforms.

    Args:
        shape: Shape coefficients.
        body_pose: Local body joint rotations.
        head_pose: Local head and facial controls.
        hand_pose: Local hand joint rotations.
        expression: Facial expression coefficients.
        global_rotation: Global model rotation.
        global_translation: Global model translation.
        joint_indices: Optional subset of joints to return.

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

prepare_identity

prepare_identity(shape, expression, skip_vertices=False)

Precompute shape- and expression-dependent state for repeated forward passes.

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

def prepare_identity(
    self,
    shape: Float[np.ndarray, "*batch 45"],
    expression: Float[np.ndarray, "*batch 72"],
    skip_vertices: bool = False,
) -> MhrIdentity:
    """Precompute shape- and expression-dependent state for repeated forward passes."""
    return backend.prepare_identity(self.weights, shape, expression=expression, skip_vertices=skip_vertices)

prepare_pose

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

Precompute pose-dependent state for repeated forward passes.

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

def prepare_pose(
    self,
    body_pose: Float[np.ndarray, "*batch 94"],
    head_pose: Float[np.ndarray, "*batch 6"],
    hand_pose: Float[np.ndarray, "*batch 104"],
    *,
    identity: MhrIdentity | None = None,
    skip_vertices: bool = False,
) -> MhrPreparedPose:
    """Precompute pose-dependent state for repeated forward passes."""
    pose = pack_pose(np, body_pose, head_pose, hand_pose)
    return backend.prepare_pose(self.weights, pose, 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)

prepare_skinning

prepare_skinning(*, identity, pose)

Pack prepared model state into renderer-ready skinning inputs.

Source code in src/body_models/base.py

def prepare_skinning(self, *, identity: Mapping[str, Any], pose: Mapping[str, Any]) -> SkinningPayload:
    """Pack prepared model state into renderer-ready skinning inputs."""
    skinning: SkinningPayload = {
        "rest_vertices": identity["rest_vertices"],
        "skinning_transforms": pose["skinning_transforms"],
        "skin_weights": self.skin_weights,
        "faces": self.faces,
    }
    if "pose_offsets" in pose:
        skinning["pose_offsets"] = pose["pose_offsets"]
    return skinning