Join members of the OpenSim Team on Wednesday July 26th for an introduction to OpenSim and new tools for rapidly developing musculoskeletal simulations.

New tools for rapidly developing musculoskeletal simulations are enabling more researchers to leverage simulations by reducing the barrier to entry and the burden of processing data. In this workshop, we will present new web-based tools that automatically calculate skeletal kinematics from video (OpenCap) or marker data (AddBiomechanics), and that can be combined with direct collocation methods to generate muscle-driven simulations. Participants will go “under the hood” with a combination of didactic portions and hands-on examples so that they can leverage and extend these open-source tools.

Preparing for the workshop

1. Create accounts

1. Create an OpenCap account: https://www.opencap.ai/.
2. Create an AddBiomechanics account: https://addbiomechanics.org/.

2. Software requirements

The workshop may be completed in either Windows or Mac. The OpenCap portion of the workshop will require a Python environment using Anaconda. On Mac, OpenSim scripting examples may only be performed in Matlab. Windows users may use Matlab or the Python conda environment for the scripting examples.

• Windows 10 or later (64-bit) or Mac (macOS 11 or later)
• Python via Anaconda
  • Python 3.8, 3.9, or 3.10
  • NumPy
  • Matplotlib
• Matlab
  • Matlab 2016b or later (64-bit). Matlab 2018a or later is best.
• A text editor (e.g., Notepad++)

3. Anaconda environment

1. Download and install Anaconda.
2. Open the Anaconda Prompt (or, Powershell on Windows, Terminal on Mac, etc).

3. Before proceeding, you may need to initialize conda for shell interaction by running

   C:\> conda init <shell-name>

   where <shell-name> is one of the following: cmd.exe (Windows default), bash (macOS default), powershell, fish, zsh, tcsh, xonsh.

4. Create a new conda environment with your Python version (e.g., 3.10). TODO update package list for OpenCap.

   C:\> conda create -n tgcs2023 python=3.10 matplotlib 

5. Activate the conda environment.

   C:\> conda activate tgcs2023

4. OpenSim installation

OpenSim with Python (Windows only)

1. If paths to previous OpenSim versions exist on your PYTHONPATH environment variable, remove them and restart the shell.

2. Install the OpenSim conda package. This installs a version of OpenSim including Moco that is compatible with Python 3.10 and NumPy 1.21. 

   C:\> conda install -c opensim-org opensim-moco=4.4.1=py310np121

3. Launch a Python interpreter from your conda environment.

   C:\> python

4. Test the OpenSim configuration by checking the timestamp from running 

   >>> import opensim
   >>> opensim.GetVersionAndDate()

   in the Python interpreter; the date should be in June 2023.

OpenSim with Matlab (TODO update with 4.4.1 build)

1. Download the OpenSim 4.4.1 software.
   1. Windows: 
   2. Mac: 
2. Install OpenSim to a location of your choice; perhaps C:\OpenSim 4.4 (on Windows).
3. If you use Windows, edit your PATH environment variable to include OpenSim’s bin directory (e.g., C:\OpenSim 4.4\bin). See here for instructions. Make sure to remove any previous OpenSim installations from your PATH.
4. Run the OpenSim application to open the GUI. If the instructions below do not work, go the OpenSim executable in the bin folder and launch it from there.  
   1. Windows: open the Start menu and click OpenSim 4.4
   2. Mac: go to Applications and click OpenSim 4.4
5. A prompt will appear to install the OpenSim resources to a location of your choice; perhaps C:\Users\<PROFILE_NAME_HERE>\Documents\OpenSim\4.4 (on Windows; replace <PROFILE_NAME_HERE> with your Windows profile name). We will refer to this directory as <RESOURCES_DIR> in the remaining instructions below.

6. Configure OpenSim with Matlab by starting Matlab and running configureOpenSim.m, located at <RESOURCES_DIR>\Code\Matlab .

7. After the script completes, restart Matlab and test the configuration by checking the timestamp from running 

   >> org.opensim.modeling.opensimCommon.GetVersionAndDate()

    in the Matlab command window; the date should be in July 2022. Test that the visualizer is working by running the following:

   >> cd 'C:\Users\<profile>\Documents\OpenSim\4.4\Code\Matlab\Moco'
   >> exampleSlidingMass

   You should see a visualizer window appear with a sliding mass animation. Hit ESC twice to close the window.

8. Note for OpenSim 3.3 users: You cannot concurrently use OpenSim 3.3 and 4.4 in Matlab; to switch versions you must re-run configureOpenSim.m and edit your PATH environment variable.

5. Download the example data

Download the example data: ExampleData.zip

Part 1: OpenCap

1. Create account

1. Create an OpenCap account: https://www.app.opencap.ai/.

2. Install requirements

This part of the workshop may be completed in Windows, Mac, or Linux. It will require cloning/downloading the opencap-processing Github repository and setting up a Python environment using Anaconda. Follow the install instructions here or perform the following steps:

1. Open the Anaconda Prompt (or, Powershell on Windows, Terminal on Mac, etc).
   1. This assumes you have installed Anaconda already (see above TODO link)

2. Create environment (python 3.9 recommended)

   C:\> conda create -n opencap-processing python=3.9

3. Activate environment

   C:\> conda activate opencap-processing

4. Install OpenSim

   C:\> conda install -c opensim-org opensim=4.4=py39np120

5. (Optional): Install an IDE such as Spyder

   C:\> conda install spyder

6. Clone/download the repository to your machine
   1. Using Git

      • Navigate to the directory where you want to download the code. For example:

        C:\> cd Documents

      • Clone the repository

        C:\Documents> git clone https://github.com/stanfordnmbl/opencap-processing.git

   2. Without using Git
      
      • Download the repository by visiting https://github.com/stanfordnmbl/opencap-processing/archive/refs/heads/main.zip
      • Unzip the folder
        • We will assume your PATH looks like C:\Documents\opencap-processing and that the path to the README file is C:\Documents\opencap-processing\README.md
7. Install required Python packages

   1. Navigate to the directory (make sure you are in Documents)

      C:\Documents> cd opencap-processing

   2. Install packages

      C:\Documents\opencap-processing> python -m pip install -r requirements.txt

8. Create environment variable for authentication, you will be prompted to provide your OpenCap credentials. An environment variable (.env file) will be saved after authenticating.

   C:\Documents\opencap-processing> python createAuthenticationEnvFile.py

9. Run example to verify that everything was correctly installed

   C:\Documents\opencap-processing> python example.py

https://github.com/stanfordnmbl/opencap-processing#install-requirements

Documentation

OpenSim API docs

View the OpenSim API documentation here.

Moco cheat sheet

Moco website

Visit the Moco website here.

Slides

TODO

Publications

Uhlrich SD, Falisse A, Kidzinski L, Muccini J, Ko M, Chaudhari AS, Hicks JL, Delp SL (2022) OpenCap: 3D human movement dynamics from smartphone videos. bioRxiv. https://doi.org/10.1101/2022.07.07.499061

Werling K, Bianco NA, Raitor M, Stingel J, Hicks JL, Collins SH, Delp SL, Liu CK (2023) AddBiomechanics: Automating model scaling, inverse kinematics, and inverse dynamics from human motion data through sequential optimization. bioRxiv. https://doi.org/10.1101/2023.06.15.545116

Dembia CL, Bianco NA, Falisse A, Hicks JL, Delp SL (2020) OpenSim Moco: Musculoskeletal optimal control. PLoS Comput Biol 16(12): e1008493. https://doi.org/10.1371/journal.pcbi.1008493

Workshop survey

Please fill out our post-workshop survey.  Thank you!