BrainCo

BrainCo is a rigid articulated model of the BrainCo Revo 2 robotic hand using the official MuJoCo XML and STL assets.

Setup

BrainCo downloads from the public abcamiletto/body-models Hugging Face repository on first use. To prefetch and save the path:

# Download the BrainCo MuJoCo XML and STL assets.
body-models download brainco

When passed manually, model_path should contain left.xml, right.xml, and meshes/{left,right}/*.STL.

The original BrainCo Revo2 description license is included with the hosted assets.

Usage

from body_models.brainco.numpy import BrainCoHand

# Load the right hand with scalar hinge coordinates for the active joints.
hand = BrainCoHand(side="right", rotation_type="hinge")

Notes

The model exposes the six active Revo 2 joints for each hand: thumb metacarpal, thumb proximal, and the proximal joints for index, middle, ring, and pinky. Passive distal joints are included in the skeleton and meshes.

API

body_models.robots.brainco.numpy.BrainCoHand

BrainCoHand(model_path=None, *, side='right')

Bases: RigidBodyModel

BrainCo Revo 2 as rigid STL links attached to its MuJoCo hand skeleton.

Initialize the BrainCoHand model.

PARAMETER	DESCRIPTION
model_path	Path to model assets, or the default assets when omitted. TYPE: Path | str | None DEFAULT: None
side	Hand side to load. TYPE: Side DEFAULT: 'right'

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.
get_tpose	Get parameters for the SMPL-style T-pose.
get_apose	Get parameters for the MHR-style A-pose.
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
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/robots/brainco/numpy.py

def __init__(
    self,
    model_path: Path | str | None = None,
    *,
    side: Side = "right",
) -> None:
    """Initialize the BrainCoHand model.

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

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(
    hand_pose,
    global_translation=None,
    *,
    global_rotation=None,
    joint_indices=None,
)

Compute posed joint transforms.

PARAMETER	DESCRIPTION
hand_pose	Local hinge coordinates. 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: list[int] | None DEFAULT: None

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

Source code in src/body_models/robots/brainco/numpy.py

def forward_skeleton(
    self,
    hand_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: list[int] | None = None,
) -> Float[np.ndarray, "B J 4 4"]:
    """Compute posed joint transforms.

    Args:
        hand_pose: Local hinge coordinates.
        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(
        self.weights,
        hand_pose,
        global_translation,
        global_rotation=global_rotation,
        joint_indices=joint_indices,
    )

forward_meshes

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

Compute posed model meshes.

PARAMETER	DESCRIPTION
hand_pose	Local hinge coordinates. 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/robots/brainco/numpy.py

def forward_meshes(
    self,
    hand_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:
        hand_pose: Local hinge coordinates.
        global_translation: Global model translation.
        global_rotation: Global model rotation.

    Returns:
        One posed model mesh per batch element.
    """
    return backend.forward_meshes(
        self.weights,
        hand_pose,
        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)

get_tpose

get_tpose(batch_dims=(), **kwargs)

Get parameters for the SMPL-style T-pose.

Source code in src/body_models/base.py

def get_tpose(
    self,
    batch_dims: tuple[int, ...] = (),
    **kwargs: Any,
) -> dict[str, Any]:
    """Get parameters for the SMPL-style T-pose."""
    raise NotImplementedError("Canonical body poses are not defined for this model.")

get_apose

get_apose(batch_dims=(), **kwargs)

Get parameters for the MHR-style A-pose.

Source code in src/body_models/base.py

def get_apose(
    self,
    batch_dims: tuple[int, ...] = (),
    **kwargs: Any,
) -> dict[str, Any]:
    """Get parameters for the MHR-style A-pose."""
    raise NotImplementedError("Canonical body poses are not defined for this model.")

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)