What is AddBiomechanics?

In order to analyze motion capture data to create reconstructions of human motion, it is necessary to create scaled models, and calculate inverse kinematics (IK) and then inverse dynamics (ID). This process is tedious and often quite time-consuming. During the process, it is important to consider the marker residual error as well as the force residual error from force plates. This often necessitates manual tweaking to markers and model parameters to achieve a required error tolerance.

AddBiomechanics is a tool developed by Stanford University that attempts to solve this problem in an automated way. They claim you can “upload mocap files and get an optimally scaled OpenSim model and IK and ID back in minutes.” The optimizer is powered by the Nimble Physics engine. The only catch is that all uploaded data is automatically shared with the community under the CC BY 4.0 license. This benefits the community, but there are certain cases where this is not possible. For example, sensitive patient data cannot be uploaded and shared to the cloud.

Navigating to the AddBiomechanics github repository, one immediately notices in the Readme: “A note for non-Stanford devs: these instructions probably won’t help you!” This piqued my interest and made it all the more interesting to unpack the secrets behind the engine of this mystical bilevel optimization black-box.

Setting up the engine locally

To set up the engine locally so that you can run the pipeline without sharing or uploading any data to “the cloud,” follow these steps:

  1. Clone the git repository git clone https://github.com/keenon/AddBiomechanics.git

  2. Navigate to cd AddBiomechanics/server/engine. This is where the engine lives and can process the data, given the correct format

  3. Install uv to manage python environments. Here is a great article on why you should use uv and not pyenv, poetry, pipx, or anaconda.

  4. Build the OpenSim Python 3.11 wheel for your platform. AddBiomechanics requires a specific version of numpy so you should follow my post on building the wheel from source to ensure everything works properly.

  5. From the server/engine dir run:

uv init --python 3.11
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip install <OPENSIM_PYTHON_WHEEL> # from step 4.
uv pip install -e .
  1. Run the script ./test_engine.sh and you should see successful results for the opencap_test

Note: you will need to rerun source .venv/bin/activate from that directory every time you return and want to reinitialize the python environment.

Now that everything is setup properly locally, I will explain how to run your own data through the bilevel optimization pipeline in the next post!