KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #codex #typescript #ai-agents #ai-agent #cli #claude-code #open-source #deepseek-harness #dsh-plugin #python #mcp

musclemimic_models

★ 54 Open GitHub ↗

Musculoskeletal models released from musclemimic research: fullbody musculoskeletal model

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MuscleMimic Models

[![PyPI version](https://img.shields.io/pypi/v/musclemimic-models.svg)](https://pypi.org/project/musclemimic-models/)
[![Downloads](https://img.shields.io/pypi/dm/musclemimic-models.svg)](https://pypi.org/project/musclemimic-models/)
[![Total Downloads](https://static.pepy.tech/badge/musclemimic-models)](https://pepy.tech/project/musclemimic-models)
[![Python Version](https://img.shields.io/pypi/pyversions/musclemimic-models.svg)](https://pypi.org/project/musclemimic-models/)
[![License](https://img.shields.io/pypi/l/musclemimic-models.svg)](https://github.com/amathislab/musclemimic_models/blob/main/LICENSE)
[![Preprint](https://img.shields.io/badge/Preprint-arXiv-b31b1b)](https://arxiv.org/abs/2603.25544)

Oneline install:
```bash
pip install musclemimic-models
```

Load a model in two lines:
```python
import musclemimic_models as mm

model, data = mm.load("myofullbody")   # or "bimanual"
```

Other helpers:
```python
import mujoco, mujoco.viewer
import musclemimic_models as mm

# List available models
print(list(mm.REGISTRY))               # ['bimanual', 'myofullbody']

# Get the raw MJCF path
xml_path = mm.get_xml_path("bimanual")
model = mujoco.MjModel.from_xml_path(str(xml_path))

# Launch the interactive viewer
model, data = mm.load("bimanual")
mujoco.viewer.launch(model, data)
```

Musclemimic_models is part of the [**MuscleMimic**](https://github.com/amathislab/musclemimic) research project, in which we created physiologically realistic, muscle-driven musculoskeletal models built on top of [MyoSuite](https://github.com/myohub/myosuite).  This repository is designed to provide users with two musculoskeletal models: MyoBimanualArm and MyoFullBody, that could be used together or independently from the Musclemimic pipeline.

MyoFullBody enables realistic full-body motion control with pure muscle actuation. Below are example fullbody motions demonstrating the model's capabilities, all policies were trained with MuscleMimic.

<table>
 <tr>
 <td align="center" width="50%">
 Backwards Walking
 <video src="https://github.com/user-attachments/assets/c413767a-e8d2-4a73-80d3-bc58bd8f90b7" width="320" controls></video>
 </td>
 <td align="center" width="50%">
 Walking Running
 <video src="https://github.com/user-attachments/assets/305e34e2-49ff-4f1b-a62d-2bc8376dcf4f" width="320" controls></video>
 </td>
 </tr>
 <tr>
 <td align="center" width="50%">
 Walking Turning
 <video src="https://github.com/user-attachments/assets/1fb2ea5d-1435-45d8-8cce-094500cfe76a" width="320" controls></video>
 </td>
 <td align="center" width="50%">
 Dancing
 <video src="https://github.com/user-attachments/assets/12abc09d-4d36-49d3-9138-65e4ee4fa4bd" width="320" controls></video>
 </td>
 </tr>
</table>

MyoFullbody also allows accurate kinematics when trained with MuscleMimic on AMASS data

![Untitled design (1)](https://github.com/user-attachments/assets/13312e4b-6b52-4c8c-8707-499510db676d)

**MyoBimanualArm** focuses on upper-limb musculoskeletal control, enabling faster training convergence while preserving full finger articulation capabilities.
(The videos shown below were recorded with finger actuation disabled)

<table>
 <tr>
 <td align="center" width="50%">
 Lifting Box
 <video src="https://github.com/user-attachments/assets/f31f1c0a-0652-47d2-b9b4-2d6abd2cab84" width="320" controls></video>
 </td>
 <td align="center" width="50%">
 Waving
 <video src="https://github.com/user-attachments/assets/dcdb0e93-28c9-46a5-b4be-3fc22cebf6f7" width="320" controls></video>
 </td>
 </tr>
 <tr>
 <td align="center" width="50%">
 Drinking Water
 <video src="https://github.com/user-attachments/assets/b2b97ed0-cc9e-40bc-a18c-538250081674" width="320" controls></video>
 </td>
 <td align="center" width="50%">
 Jumpingjack
 <video src="https://github.com/user-attachments/assets/b9716c13-da84-4571-bc0f-ae47018d6b8d" width="320" controls></video>
 </td>
 </tr>
</table>

---

## Musculoskeletal Models

Both musculoskeletal models are built on MyoSuite components, combining **[MyoArm](https://github.com/MyoHub/myo_sim/tree/main/arm)**, **[MyoLegs](https://github.com/MyoHub/myo_sim/tree/main/leg)**, and **[MyoTorso](https://github.com/MyoHub/myo_sim/tree/main/torso)** models with Hill-type muscle actuators in MuJoCo. This enables studying motor control at the **neuromuscular level** and realistic muscle output, rather than via idealized joint torque controllers.

### Environment Summary

| Model           | Type        | Joints | Muscles | DoFs | Focus                        |
|-----------------|-------------|--------|---------|---------|------------------------------|
| MyoBimanualArm  | Fixed-base  | 76 (36*)    | 126 (64*)     | 54 (14*) | Upper-body manipulation      |
| MyoFullBody     | Free-root   | 123 (83*)    | 416 (354*)    | 72 (32*) | Locomotion and manipulation    |

##### $^*$ denotes configurations with finger muscles temporarily disabled.

### MyoBimanualArm Environment

The **MyoBimanualArm** environment is designed for **upper-body manipulation task**. Explicit contacts are enabled in between both arms and with the thorax.

 <img width="90%" alt="BimanualMuscle" src="https://github.com/user-attachments/assets/67e68c50-43dd-4f0f-845e-53cd3a984f1f" />

### MyoFullBody Environment

The **MyoFullBody** environment provides a **comprehensive full-body musculoskeletal system** with full biomechanical detail and rich contact dynamics, suitable for **locomotion**, **manipulation**, and **whole-body imitation**. We explicitly enable additional collision pairs, such as leg–leg, arm–leg, foot-foot, to capture the required self-contact behavior, including bimanual interactions.

---

## Getting Started

### Prerequisites

The minimum required MuJoCo version for both models is `mujoco==3.2.1`. To use spec with the main Musclemimic environment, please use `mujoco>=3.3.0`.

### Overview

The structure of the Musclemimic model is as follows. We use MyoFullBody as an example. 
```
musclemimic_models/
└── model/
    ├── arm/
    │   ├── assets/
    │   └── myoarm_bimanual.xml
    ├── body/
    │   └── myofullbody.xml
    ├── head/
    │   └── assets/
    ├── leg/
    │   └── assets/
    ├── torso/
    │   └── assets/
    ├── meshes/
    └── scene/
└── tests/
```
- `assets/` : includes both the kinematics chain files and the assets definition files for each body segment that its under. 
- `meshes/` : shared mesh files used across models for bones and skulls
- `scene/` : MJCF “scene” files used in both MSK as backgrounds
- `arm/`, `body/`, `head/`, `leg/`, `torso/` : model components and their associated assets/
- `*.xml` : MJCF model definition(s) (e.g., `myofullbody.xml`, `myoarm_bimanual.xml`)
- `test/`: testing files for symmetry between bodies, geoms, sites and muscle

### Usage

#### Via Pypi
Install:

```bash
pip install musclemimic-models
```

#### Via `git clone`
Clone and install editable (recommended for development):

```bash
git clone https://github.com/amathislab/musclemimic_models.git
cd musclemimic_models
pip install -e .
```

---
### MSK Model Refinement and Validation
**Muscle Jump and Symmetry**

While building MyoFullBody and MyoBimanualArm, we corrected left–right limb asymmetries and addressed several unexpected muscle-jumping behaviors. A few representative fixes are shown below.

**Muscle Validation**

We also cross-validate the current model using previously published cadaver studies and MRI data. A few illustrative examples are included here.

## License
This project is licensed under the [Apache License](https://github.com/amathislab/musclemimic_models/blob/main/LICENSE).
See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.

## Citation
If you use MuscleMimic in your research, please cite:
```bibtex
@article{Li2026MuscleMimic,
  title={Towards Embodied AI with MuscleMimic: Unlocking full-body musculoskeletal motor learning at scale},
  author={Li, Chengkun and Wang, Cheryl and Ziliotto, Bianca and Simos, Merkourios and Kovecses, Jozsef and Durandau, Guillaume and Mathis, Alexander},
  journal={arXiv preprint arXiv:2603.25544},
  year={2026}
}
```

## Acknowledgements
The models in this repository build upon [MyoSuite](https://github.com/myohub/myosuite), an open-source musculoskeletal simulation framework.

musclemimic_models

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README