Versions Compared

Old Version 43

changes.mady.by.user Antoine Falisse

Saved on

compared with

New Version Current

changes.mady.by.user Nicholas Bianco

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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.

...

Please follow the instructions below to prepare for the workshop.   

...

Install Anaconda

Anaconda is a Python distribution that includes package and environment management. It is required for the OpenCap portion of the workshop, and optional for the AddBiomechanics portion. If using Python for both, we will use Anaconda to create separate environments for the OpenCap and AddBiomechanics examples.

  1. Download and install Anaconda.

Part 1: OpenCap

1. Create account

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

2. Demo #1: Colab

The first demo of the OpenCap portion of the workshop will be completed with Colab. In order to execute code, a Google account sign-in is required. Create an account if you don't have one already and if you would like to run code yourself.

Here is the link to the notebook we will use during the workshop.

3. Demo #2: Install requirements

The second demo of the OpenCap portion 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

  2. Create environment (python 3.10 recommended)

    Code Block
    (base) C:\Users\me> conda create -n opencap-processing python=3.10


  3. Activate environment

    Code Block
    (base) C:\Users\me> conda activate opencap-processing


  4. Install OpenSim within environment

    Code Block
    (opencap-processing) C:\Users\me> conda install -c opensim-org opensim=4.4.1=py310np121


  5. (Optional): Install an IDE such as Spyder (you can use any IDE or run code from the terminal)

    Code Block
    (opencap-processing) C:\Users\me> conda install spyder


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

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

        Code Block
        (opencap-processing) C:\Users\me> cd Documents


      2. Clone the repository

        Code Block
        (opencap-processing) C:\Users\me\Documents> git clone https://github.com/stanfordnmbl/opencap-processing.git


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

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

      Code Block
      (opencap-processing) C:\Users\me\Documents> cd opencap-processing


    2. Install packages

      Code Block
      (opencap-processing) C:\Users\me\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.

    Code Block
    (opencap-processing) C:\Users\me\Documents\opencap-processing> python createAuthenticationEnvFile.py


  9. Run example.py to verify that everything was correctly installed so far. If you get some plots popping out, then you can proceed to step 10.

    Code Block
    (opencap-processing) C:\Users\me\Documents\opencap-processing> python example.py


  10. If you're a Mac user, you can stop here. If you're on Windows or Linux, you'll need this extra step. This part of the workshop will involve running dynamic simulations of walking using OpenSimAD, which is a custom version of OpenSim with support for Automatic Differentiation (AD). OpenSimAD requires a compiler, which is not installed by default on Windows, and the OpenBLAS libraries, which you need to manually install on Linux.

    1. (Windows only): Install Visual Studio

      1. The Community variant is sufficient and is free for everyone.

      2. During the installation, select the workload Desktop Development with C++.

      3. The code was tested with the 2017, 2019, and 2022 Community editions.

    2. (Linux only): Install OpenBLAS libraries

      Code Block
      sudo apt-get install libopenblas-base


  11. Run Examples/example_walking_opensimAD.py to verify that everything was correctly installed so far. If you see some IPOPT iterations, then you're all set. We'll go through the example during the workshop.

    Code Block
    (opencap-processing) C:\Users\me\Documents\opencap-processing> cd Examples 
(opencap-processing) C:\Users\me\Documents\opencap-processing\Examples> example_walking_opensimAD.py


  12. (Optional): Download the processed example data from Demo #2 as reference. The folder name (4d5c3eb1-1a59-4ea1-9178-d3634610561c) is the identifier of the session. If you follow all the steps of the workshop, files will be downloaded/generated under opencap-processing/Data/4d5c3eb1-1a59-4ea1-9178-d3634610561c. If you run into issues during the workshop (eg, when compiling files), you can download the processed example data and copy them under ./opencap-processing/Data/4d5c3eb1-1a59-4ea1-9178-d3634610561c (make sure the path to the metadata file looks like: opencap-processing/Data/4d5c3eb1-1a59-4ea1-9178-d3634610561c/sessionMetadata.yaml). This should allow you to complete the workshop.

Part 2: AddBiomechanics

1. Create account

  1. Create an AddBiomechanics account: https://addbiomechanics.org/.

2. Software requirements

The AddBiomechanics portion of 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 a 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.10NumPy
    • Matplotlib
  • Matlab
    • Matlab 2016b or later (64-bit). Matlab 2018a or later is best.
  • A text editor (e.g., Notepad++)

3.

...

 OpenSim installation

OpenSim with Python (Windows only)

  1. Open the Anaconda Prompt (or, Powershell on Windows, Terminal on Mac, etc).Before proceeding, you may need to initialize conda for shell interaction by running
    Code Block
    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.

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

    Code Block
    (base) C:\>Users\me> conda create -n tgcs2023addbio-processing python=3.10 matplotlib


  3. Activate the conda environment.

    Code Block
    (base) C:\>Users\me> conda activate tgcs2023

4. OpenSim installation

...

  1. addbio-processing


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

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

    Code Block
    (addbio-processing) C:\

...

  1. Users\me> conda install -c opensim-org opensim-moco=4.4.1=py310np121


  2. Launch a Python interpreter from your conda environment.

    Code Block
    (addbio-processing) C:\

...

  1. Users\me> python


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

    Code Block
    >>> import opensim
>>> opensim.GetVersionAndDate()

    in the Python interpreter; the date should be in

...

  1. July 2023.

OpenSim with Matlab

...

  1. Go to the OpenSim 4.4.1

...

  1. Download the OpenSim release page here.
  2. In the dropdown window under "Assets", select the distribution for your platform.
    1. Windows users: download opensim-core-4.4.1
    software.
    1. Windows:-win.zip. 
    2. Mac users: download opensim-core-4.4.1-mac.zip. 
  3. Install OpenSim to a location of your choice; perhaps C:\OpenSim opensim-core-4.4.1 (on Windows).
  4. If you use WindowsThe next step is platform dependent:
    1. For Windows users, edit your PATH environment variable to include OpenSim’s bin directory (e.g.,
     
    1. C:\
    OpenSim
    1. opensim-core-4.4.1\bin). See here for instructions. Make sure to remove any previous OpenSim installations from your PATH.
    Run

    1. For Mac users, authorize 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
    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.

    1. distribution by running the following command in the Terminal

      Code Block
      $ xattr -r -d com.apple.quarantine <opensim_install_directory>

      where <opensim_install_directory> is the directory where you unzipped the installation (e.g., /Applications/opensim-core-4.4.1/).

  5. Configure OpenSim with Matlab by starting Matlab and starting Matlab and running configureOpenSim.m, located at <RESOURCES_DIR>at C:\opensim-core-4.4.1\Resources\Code\Matlab .

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

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

     in the Matlab command window; the date should be in July 20222023.

  7. Test that the visualizer is working by running the following:

    Code Block
    >> cd 'C:\Users\<profile>\Documents\OpenSim\opensim-core-4.4.1\Resources\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.

...

4. Download the example data

Download the example data here: ExampleDataAddBiomechanicsExampleFiles.zip

Part 1: OpenCap

...

.

...

  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. This assumes you have installed Anaconda already (see above TODO link)

Create environment (python 3.9 recommended)

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

Activate environment

Code Block
C:\> conda activate opencap-processing

Install OpenSim

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

(Optional): Install an IDE such as Spyder

Code Block
C:\> conda install spyder

...

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

Code Block
C:\> cd Documents

Clone the repository

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

...

...

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

Code Block
C:\Documents> cd opencap-processing

Install packages

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

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

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

Run example to verify that everything was correctly installed so far. If you get some plots popping out, then you can proceed to step 10.

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

If you're a Mac user, you can stop here. If you're on Windows or Linux, you will need this extra step. This part of the workshop will involve running dynamic simulations of walking using OpenSimAD, which is a custom version of OpenSim with support for Automatic Differentiation (AD).

ss

s

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

The top level directory contained in the zip folder is /AddBiomechanics, and contains two subdirectories: /AddBiomechanics/Data and /AddBiomechanics/Results. The Data folder contains the model file, marker trajectories, and ground reaction forces needed to complete the workshop. The text editor you choose should support XML formatting since modifying the OpenSim model file will be necessary. The Results folder contains result files already processed by AddBiomechanics, which will be necessary in the latter half of the tutorial, but may be also useful if technical difficulties occur. The Scripts folder contains copies of the additional Moco scripts from the hands-on portion of the tutorial.

The completed example can be found on the web here: TGCS2023_ExampleSubject. Participants may use this link to view the settings used for the example or to visualize and plot the processed data.

Documentation

OpenSim API docs

...

Visit the Moco website here.

Slides

TODO

View file
nameTGCS2023OpenSimWorkshop.pdf
height250

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

View file
name2022.07.07.499061v1.full.pdf
height250


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

View file
name2023.06.15.545116v1.full.pdf
height250


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

View file
namejournal.pcbi.1008493 (2).pdf
height250

...