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.

We evaluate the accuracy of the converter with a handful of models. However, these models do not cover all possible features of OpenSim models. Hence, when converting a new model, there is a chance the conversion fails due to a missing implementation. In this case, you can open an issue, or, preferably, contribute to the project and create a pull request.

Example Model List | External Model List | Documentation | myoSuite | Current Limitations

Example models

Here we present a collection of models, as examples, 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
	Turg of War - 1 DoF - 2 Muscles	Osim	Report	Regular: 30 sec Speedy: 30 sec
	Simple Arm - 2 DoFs - 6 Muscles	Osim	Report	Regular: 5 min 30 sec Speedy: 4 min 37 sec
	Single Leg - 6 DoFs - 9 Muscles	Osim	Report	Regular: 4 min 3 sec Speedy: 3 min 41 sec
	2D Gait Model - 10 DoFs - 18 Muscles	Osim	Report	Regular: 8 min 21 sec Speedy: 7 min 33 sec
	3D Gait Model - 23 DoFs - 54 Muscles	Osim	Report	Regular: 34 min 21 sec Speedy: 22 min 58 sec
	Neck Model - 6 DoFs - 72 Muscles	Osim	Report	Regular: 200 min 14 sec Speedy: 57 min 43 sec

MyoConverter has been extensively used to build up the MyoSim MSK models that have been used in the MyoSuite framework. These converted models underwent additional manual adjustments to address minor issues, ensuring their suitability for functional task simulations.

Besides, a list of third-party converted models using this tool can be found here.

We encourage you to review these models before embarking on any redundant efforts. However, we must emphasize that we cannot guarantee the accuracy of these models, as there is no universal test for this. If you have specific concerns or questions regarding any of the models, we recommend reaching out directly to the respective model creators for further information and clarification.

Download & Setup

Linux

If you would like to convert your own MSK model, you can use myoConverter by following the steps outlined below:

• 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 -f conda_env.yml
conda activate myoConverter

• Test installation

python -c "import myoConverter"

Windows/MacOS

In Windows and MacOS, we provide a docker image that has the myoConverter ready to be used. Please follow the following usage instructions: ....

Quick example

Call a Python function

from myoconverter import O2MPipeline
O2MPipeline(osim_file, geometry_folder, output_folder, **kwargs)

converts "/path/to/*.osim" to a MuJoCo XML file and outputs the model into folder "/path/to/output/folder". The **kwargs may contain the optional parameters as listed below:

• convert_steps : Selected conversion steps, could be any subset of [1, 2, 3] based on the needs, Default = [1, 2, 3]
• muscle_list : Selected specific muscles for the conversion and validation steps, Default = None
• osim_data_overwrite : If true, overwrite extracted Osim model state files, Default = False [overwrite is needed, if Osim model has changed]
• conversion : If true, perform the conversion functions of selected steps, Default = True
• validation : If true, perform the validation functions of selected steps, Default = True
• speedy : If true, reduce the number of checking notes in optimization steps to increase speed, Default = False
• generate_pdf : If true, generate a pdf report of the validation results, Default = False
• add_ground_geom : If true, a geom (of type plane) is added to the MuJoCo model as ground, Default = False
• treat_as_normal_path_point : If true, MovingPathPoints and ConditionalPathPoints will be treated as normal PathPoints, Default = False

The following example can be used to setup the **kwargs

# 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

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 myoConverter/models/osim. The code presented in this repository and the converted models are licensed with Apache 2.0.