MyoConverter

MyoConverter is a tool for converting OpenSim musculoskeletal (MSK) models to the MuJoCo model format with optimized muscle kinematics and kinetics.

Building upon the foundation of the previous O2MConverter project, we extensively rewrote the functions, incorporated new features, and ensured compatibility with the latest OpenSim 4.0+ models. Additionally, two optimization steps were introduced to enhance the accuracy of muscle properties in both kinematics and kinetics.

See the documentation for more information about the converter and the conversion process.

Model List | Documentation | MyoSuite | Current Limitations

Example models

Here we present a few example models that have been processed with the MyoConverter tool. We try to keep these converted models up-to-date (in case of bug fixes etc.), but it is recommended to run the conversions yourself to ensure up-to-date models.

Model name	Source	Validation	Conversion Speed*
Tug of War - 1 DoF - 2 Muscles	Osim	Report	Regular: 2 seconds
Simple Arm - 2 DoFs - 6 Muscles * In MyoSim	Osim	Report	Regular: 11 sec
Single Leg - 6 DoFs - 9 Muscles	Osim	Report	Regular: 37 sec
2D Gait Model - 10 DoFs - 18 Muscles	Osim	Report	Regular: 60 sec
3D Gait Model - 23 DoFs - 54 Muscles	Osim	Report	Regular: 5 min 35 sec
Neck Model - 6 DoFs - 72 Muscles	Osim	Report	Regular: 54 min 02 sec

Please also see this list of models converted using MyoConverter.

NOTE: Speed test was done on a 12th Gen Intel® Core™ i5-12500H × 16. Parallel computing is implemented, so more Threads in CPU will lead to faster conversion.

NOTE: The converted XML model contains a keyframe which should be used when initialising the model. This keyframe sets the joint values such that all the joint/muscle path constraints are met. However, MuJoCo does not load the keyframe by default. When using the MuJoCo simulate GUI, please hit the Load key button to load the keyframe. When loading the model using MuJoCo P ython bindings, you can use following functions to load the keyframe:

import mujoco
model = mujoco.MjModel.from_xml_path("path/to/model.xml")
data = mujoco.MjData(model)
mujoco.mj_resetDataKeyframe(model, data, 0)

Download & Setup

We recommend installing MyoConverter via conda / mamba if you're running Linux (tested on Ubuntu 20.04 & 22.04). In earlier development phases we encountered issues in Windows. Hence, for Windows / MacOS users, we provide a docker image (follow this link for more instructions), which contains the tested Linux setup. If you try the conda / mamba approach on Windows / MacOS, please let us know how it goes!

conda / mamba

Clone the repo

git clone git@github.com:MyoHub/myoconverter.git; cd myoconverter

Create a conda environment with the conda_env.yml file

conda env create -n myoconverter -f conda_env.yml
conda activate myoconverter

Note conda is very slow in solving the dependencies and installing the environment (>15 minutes). We recommend installation via mamba instead, which installs the environment in a couple of minutes. With mamba, the environment is created by replacing conda with mamba:

mamba env create -n myoconverter -f conda_env.yml
mamba activate myoconverter

Add MyoConverter project folder to PYTHONPATH

export PYTHONPATH=${PYTHONPATH}:/path/to/myoconverter

Optional: Test installation by running a model unit test

python myoconverter/tests/model_unit_test.py

Quick example

Call a Python function

from myoconverter.O2MPipeline import O2MPipeline

# define pipeline configurations
kwargs = {}  # define kwargs inputs
kwargs['convert_steps'] = [1, 2, 3]    # All three steps selected
kwargs['muscle_list'] = None           # No specific muscle selected, optimize all of them
kwargs['osim_data_overwrite'] = True   # Overwrite the Osim model state files
kwargs['conversion'] = True            # Yes, perform 'Cvt#' process
kwargs['validation'] = True            # Yes, perform 'Vlt#' process
kwargs['speedy'] = False               # Do not reduce the checking notes to increase speed
kwargs['generate_pdf'] = True          # Do not generate validation pdf report
kwargs['add_ground_geom'] = True       # Add ground to the model
kwargs['treat_as_normal_path_point'] = False    # Using constraints to represent moving and conditional path points

############### Simple Arm 2 DoFs 6 Muscles ################ 
osim_file = './models/osim/Arm26/arm26.osim'
geometry_folder = './models/osim/Arm26/Geometry'
output_folder = './models/mjc/Arm26'
O2MPipeline(osim_file, geometry_folder, output_folder, **kwargs)

More conversion examples can be found in the example folder. Detailed description of the conversion setup/process is in the documentation.

Contribution

We highly encourage both users and experts to actively contribute to this open-source software. By sharing your insights and expertise, you can help enhance the functionality and maintenance of MyoConverter for the benefit of all users. For more detailed information about the tool, please refer to the documentation.

Citation

@inproceedings{wang2022myosim,
  title={MyoSim: Fast and physiologically realistic MuJoCo models for musculoskeletal and exoskeletal studies},
  author={Wang, Huawei and Caggiano, Vittorio and Durandau, Guillaume and Sartori, Massimo and Kumar, Vikash},
  booktitle={2022 International Conference on Robotics and Automation (ICRA)},
  pages={8104--8111},
  year={2022},
  organization={IEEE}
}

@inproceedings{ikkala2022converting,
  title={Converting biomechanical models from opensim to Mujoco},
  author={Ikkala, Aleksi and H{\"a}m{\"a}l{\"a}inen, Perttu},
  booktitle={Converging Clinical and Engineering Research on Neurorehabilitation IV: Proceedings of the 5th International Conference on Neurorehabilitation (ICNR2020), October 13--16, 2020},
  pages={277--281},
  year={2022},
  organization={Springer}
}

License

The licenses and credits for the original OpenSim models can be found in each respective model folder in models/osim. The code presented in this repository and the converted models are licensed with Apache 2.0.