MyoFullBody

MyoFullBody is a MuJoCo-derived musculoskeletal full-body model from amathislab/musclemimic_models. It exposes rigid STL link meshes, body-frame skeleton transforms, site positions, and tendon metadata through the same NumPy, PyTorch, and JAX backend layout as the other models.

Setup

MyoFullBody downloads automatically on first use from https://huggingface.co/abcamiletto/body-models. The Hugging Face repo records the original MuscleMimic Apache 2.0 provenance. To prefetch and save the path:

# Download the MyoFullBody MJCF and referenced mesh assets.
body-models download myofullbody

When passed manually, model_path should contain body/myofullbody.xml and the referenced mesh assets from the upstream musclemimic_models/model/ tree.

Usage

from body_models.myofullbody.numpy import MyoFullBody

# Load the rigid articulated model and start from its bundled A-pose.
model = MyoFullBody()
params = model.get_apose(batch_dims=(1,))

# Evaluate the concatenated link meshes, body-frame skeleton, and link transforms.
vertices = model.forward_vertices(**params)
skeleton = model.forward_skeleton(**params)
links = model.forward_links(**params)

# Lift MuJoCo site positions from local body frames into world coordinates.
sites = model.world_sites(skeleton)

Notes

MyoFullBody is a rigid articulated model, so it does not define skin_weights. Use forward_links, link_mesh, or joint_meshes when rendering or inspecting individual STL links.

API

body_models.skeletons.myofullbody.numpy.MyoFullBody

MyoFullBody(model_path=None)

Bases: RigidBodyModel

MyoSuite-derived full-body MJCF model with rigid STL link meshes.

Initialize the MyoFullBody model.

PARAMETER	DESCRIPTION
model_path	Path to model assets, or the default assets when omitted. TYPE: Path | str | None DEFAULT: None

METHOD	DESCRIPTION
forward_skeleton	Compute posed joint transforms.
forward_meshes	Compute posed model meshes.
joint_index	Resolve a standard joint to this model's native joint index.
unpack_pose	Unpack a flattened pose [..., Q] into name -> [..., dof] arrays.
pack_pose	Pack name -> [..., dof] arrays into a flattened pose [..., Q].
to_qpos	Build full MuJoCo qpos as [root_xyz, root_wxyz, body_pose].

ATTRIBUTE	DESCRIPTION
common_joints	Common anatomical joints mapped to this model's native joint names. TYPE: Mapping[Joint, str]
num_actuated	Number of actuated pose coordinates. TYPE: int
actuated_joint_slices	Consecutive scalar coordinate slices keyed by actuated joint name. TYPE: Mapping[str, slice]

Source code in src/body_models/skeletons/myofullbody/numpy.py

def __init__(self, model_path: Path | str | None = None) -> None:
    """Initialize the MyoFullBody model.

    Args:
        model_path: Path to model assets, or the default assets when omitted.
    """
    self.weights = load_model_data(model_path)

common_joints property

common_joints

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

num_actuated property

num_actuated

Number of actuated pose coordinates.

actuated_joint_slices property

actuated_joint_slices

Consecutive scalar coordinate slices keyed by actuated joint name.

forward_skeleton

forward_skeleton(
    body_pose,
    global_translation=None,
    *,
    global_rotation=None,
    joint_indices=None,
)

Compute posed joint transforms.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B Q']
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
joint_indices	Optional subset of joints to return. TYPE: Any | None DEFAULT: None

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

Source code in src/body_models/skeletons/myofullbody/numpy.py

def forward_skeleton(
    self,
    body_pose: Float[np.ndarray, "B Q"],
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    *,
    global_rotation: Float[np.ndarray, "B 3"] | None = None,
    joint_indices: Any | None = None,
) -> Float[np.ndarray, "B J 4 4"]:
    """Compute posed joint transforms.

    Args:
        body_pose: Local body joint rotations.
        global_translation: Global model translation.
        global_rotation: Global model rotation.
        joint_indices: Optional subset of joints to return.

    Returns:
        Joint transforms in the model hierarchy.
    """
    return backend.forward_skeleton(
        weights=self.weights,
        body_pose=body_pose,
        global_translation=global_translation,
        global_rotation=global_rotation,
        joint_indices=joint_indices,
    )

forward_meshes

forward_meshes(
    body_pose, global_translation=None, *, global_rotation=None
)

Compute posed model meshes.

PARAMETER	DESCRIPTION
body_pose	Local body joint rotations. TYPE: Float[ndarray, 'B Q']
global_translation	Global model translation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None
global_rotation	Global model rotation. TYPE: Float[ndarray, 'B 3'] | None DEFAULT: None

RETURNS	DESCRIPTION
list[Trimesh]	One posed model mesh per batch element.

Source code in src/body_models/skeletons/myofullbody/numpy.py

def forward_meshes(
    self,
    body_pose: Float[np.ndarray, "B Q"],
    global_translation: Float[np.ndarray, "B 3"] | None = None,
    *,
    global_rotation: Float[np.ndarray, "B 3"] | None = None,
) -> list[Trimesh]:
    """Compute posed model meshes.

    Args:
        body_pose: Local body joint rotations.
        global_translation: Global model translation.
        global_rotation: Global model rotation.

    Returns:
        One posed model mesh per batch element.
    """
    return backend.forward_meshes(
        weights=self.weights,
        body_pose=body_pose,
        global_translation=global_translation,
        global_rotation=global_rotation,
    )

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)

unpack_pose

unpack_pose(pose)

Unpack a flattened pose [..., Q] into name -> [..., dof] arrays.

Source code in src/body_models/base.py

def unpack_pose(self, pose: Any) -> dict[str, Any]:
    """Unpack a flattened pose ``[..., Q]`` into ``name -> [..., dof]`` arrays."""
    if pose.shape[-1] != self.num_actuated:
        raise ValueError(f"pose must have shape [..., {self.num_actuated}], got {tuple(pose.shape)}")
    return {name: pose[..., joint_slice] for name, joint_slice in self.actuated_joint_slices.items()}

pack_pose

pack_pose(pose_by_joint)

Pack name -> [..., dof] arrays into a flattened pose [..., Q].

Source code in src/body_models/base.py

def pack_pose(self, pose_by_joint: Mapping[str, Any]) -> Any:
    """Pack ``name -> [..., dof]`` arrays into a flattened pose ``[..., Q]``."""
    pieces = []
    expected_names = set(self.actuated_joint_slices)
    extra_names = set(pose_by_joint) - expected_names
    if extra_names:
        raise KeyError(f"Unknown actuated joint names: {sorted(extra_names)}")
    for name, joint_slice in self.actuated_joint_slices.items():
        if name not in pose_by_joint:
            raise KeyError(f"Missing actuated joint name: {name!r}")
        value = pose_by_joint[name]
        dof = joint_slice.stop - joint_slice.start
        if value.shape[-1] != dof:
            raise ValueError(f"{name!r} must have shape [..., {dof}], got {tuple(value.shape)}")
        pieces.append(value)
    return get_namespace(*pieces).concat(pieces, axis=-1)

to_qpos

to_qpos(
    body_pose,
    global_translation=None,
    *,
    global_rotation=None,
    clamp_to_limits=False,
)

Build full MuJoCo qpos as [root_xyz, root_wxyz, body_pose].

body_pose is the model's flattened scalar coordinate vector [..., Q]. The root prefix is converted from the model coordinate frame to MuJoCo's coordinate frame.

Source code in src/body_models/base.py

def to_qpos(
    self,
    body_pose: Any,
    global_translation: Any | None = None,
    *,
    global_rotation: Any | None = None,
    clamp_to_limits: bool = False,
) -> Any:
    """Build full MuJoCo ``qpos`` as ``[root_xyz, root_wxyz, body_pose]``.

    ``body_pose`` is the model's flattened scalar coordinate vector ``[..., Q]``.
    The root prefix is converted from the model coordinate frame to MuJoCo's
    coordinate frame.
    """
    if body_pose.shape[-1] != self.num_actuated:
        raise ValueError(f"body_pose must have shape [..., {self.num_actuated}], got {tuple(body_pose.shape)}")

    xp = get_namespace(body_pose)
    batch_shape = tuple(body_pose.shape[:-1])
    if global_translation is None:
        global_translation = zeros_as(body_pose, shape=(*batch_shape, 3), xp=xp)
    if global_rotation is None:
        root_ref = zeros_as(body_pose, shape=(*batch_shape, 3), xp=xp)
        root_rot = eye_as(root_ref, batch_dims=batch_shape, xp=xp)
    else:
        root_rot = SO3.convert(global_rotation, src="axis_angle", dst="rotmat", xp=xp)

    coord = xp.asarray(self.mujoco_to_model, dtype=body_pose.dtype)
    model_to_mujoco = coord.mT if hasattr(coord, "mT") else xp.swapaxes(coord, -1, -2)
    root_t = xp.squeeze(model_to_mujoco @ global_translation[..., None], axis=-1)
    root_rot_mujoco = model_to_mujoco @ root_rot @ coord
    root_quat = SO3.conversions.from_rotmat_to_quat(root_rot_mujoco, convention="wxyz", xp=xp)

    if clamp_to_limits:
        limits = xp.asarray(self.actuated_joint_limits, dtype=body_pose.dtype)
        body_pose = xp.clip(body_pose, limits[:, 0], limits[:, 1])
    return xp.concat([root_t, root_quat, body_pose], axis=-1)