This website will be undergoing maintenance on Wednesday July 18 from 2pm to 5pm PDT. We are also in the process of updating this documentation for OpenSim 4.0. Are you looking for OpenSim 3.3 documentation?



OpenSim 4.0 requires 64-bit Matlab.

When referring to indexed elements remember that Matlab begins indexing at 1 while OpenSim data structures begin at 0.


What's Available?

  • Access to the OpenSim API to create and simulate models 
  • Users can instantiate and run tools from setup files or programmatically 
  • Repeated/batch runs of tools
  • A visualizer for API users that can be invoked through Matlab

Limitations

  • In this mode, there’s no access to the plotter (you can use Matlab’s native plotter) or the graphics window (use the model visualizer instead).
  • Some internal Simtk classes (that belong to the SimTK namespace and simbody internals) are not available for construction, but the most commonly used classes are available as of version 3.1 (SimTK::Vec3, Vector, Mat33, State, Inertia).

Loading OpenSim Libraries 

Once you have set up the OpenSim-Matlab environment (see below) you will need to load the OpenSim libraries to call OpenSim methods. Use the following call at the beginning of your OpenSim-Matlab scripts. 

 

To Load the OpenSim Libraries in Matlab

To view the methods in an OpenSim class, you can use the following in the MATLAB command window:

View all methods in an OpenSim class

You can obtain a window that lists the signatures (arguments, return type) of all methods in an OpenSim class:

View all method signatures in an OpenSim class

The MATLAB command window also supports tab completion.

 

Available Example Scripts

Scripts can are located in the OpenSim distribution in the /Scripts/Matlab folder. 

Script Name

Description
OpenSimCreateTugOfWarModel.m and TugOfWar_CompleteRunVisualize.mThese scripts generate a simple tug of war model, run a simulation, and visualize the results.
prescribeMotionInModel.mScript to create an OpenSim model with coordinates prescribed according to an input motion file. It uses a helper function defined in the script createPrescribedMotionModel.
setupAndRunAnalyzeBatchExample.m

This is a Matlab function that generates OpenSim Setup Files for the Analyze>MuscleAnalysis tool and runs the Analyze tool. You must run setupAndRunIKBatchExample first to generate the motion files used in this example.

setupAndRunIKBatchExample.mRuns multiple inverse kinematics trials for the model Subject01 located in the subfolder "testData\subject01". User must specify the results directory (e.g. "IKResults"), the .osim model (e.g. "subject01_gait2392_scaled.osim"), and the .trc files (e.g. in folder "MarkerData"). To see the results, load the model and IK output in the GUI.
simpleOptimizerExample.mRuns a simple optimization to find the elbow flexion angle where the moment arm of the biceps femoris short head is maximized.
simpleOptimizerObjectiveFunction.mRuns model simulation for gvien coefficients, returns integration
strengthScaler.mFunction that loads a model and its muscles, then creates a new model where all muscles are scaled by a common scale factor. Takes 3 inputs: 1) the path and name of an existing OpenSim model, 2) the path and name of the new model to be outputted, and 3) the scale factor. If no input model names are given, the user is prompted to choose a model to scale and all muscle strengths are doubled.

 

Setting up your Matlab Scripting Environment

These instructions assume that you've already installed OpenSim version 4.0 or later (see Installation Guide for more info). As noted above, OpenSim 4.0 requires 64-bit Matlab.

  1. Launch MATLAB. If you're using Windows and you have OpenSim 3.x configured with Matlab, make sure to "Run as administrator" (available by right-clicking the MATLAB application in the start menu, etc.).
  2. Change your Current Folder to the OpenSim Matlab Scripts directory; on Windows, this is OPENSIM_INSTALL_DIR/sdk/Scripts/Matlab.
  3. Run the configureOpenSim.m file from the current folder. When the script finishes, you should see a dialog box notifying you if the script succeeded. If the script did not succeed, read the output in the command window for more information.
  4. Windows users: ensure that the OPENSIM_INSTALL_DIR\bin directory appears in your system PATH environment variable, and that it appears before any other OpenSim installations you may have on your PATH.
  5. Restart MATLAB; the OpenSim libraries will not be recognized until doing so.
  6. Test that everything is configured correctly: In the command window, run the following:
Test that OpenSim is properly configured with MATLAB

The configureOpenSim.m file will detect any installations of OpenSim that were previously configured with MATLAB, and will "remove" them from MATLAB (the other OpenSim installations are not deleted, they are simply no longer configured with MATLAB). The configureOpenSim.m file also backs up any changes it makes to MATLAB configuration files.

 

 Having trouble? Try manual setup...

These manual setup are tailored for Windows and MATLAB 2012b and later, with side notes for macOS and MATLAB 2012a and earlier.

Find the location where you installed OpenSim (e.g., C:\OpenSim 4.0). We will refer to this directory as OPENSIM_INSTALL_DIR. Substitute your specific directory in the instructions below. In the images, we use C:\OpenSim 4.0.

Launch MATLAB

  • If you have MATLAB 2012b or later, you can launch MATLAB regularly.
  • If you have MATLAB 2012a or earlier, you must run MATLAB as an administrator: right-click MATLAB in your Start menu, and select Run as administrator.

 

Tell MATLAB about OpenSim's Java library (.jar)

  • In the MATLAB Command Window, type edit(fullfile(prefdir, 'javaclasspath.txt').
    • For MATLAB 2012a or earlier, type edit classpath.txt instead.
  • Add OPENSIM_INSTALL_DIR\sdk\Java\org-opensim-modeling.jar to the end of the file.
  • On macOS, use forward slashes (/) instead of back slashes (\).
  • Remove any entries for previous versions of OpenSim (in either fullfile(prefdir, 'javaclasspath.txt') or classpath.txt, even if you have MATLAB 2012b or later).

Tell Matlab about OpenSim's C++ libraries, which the Java library depends on

  • In the MATLAB Command Window, type edit(fullfile(prefdir, 'javalibrarypath.txt').
    • For MATLAB 2012a or earlier, type edit librarypath.txt instead.
  • Add OPENSIM_INSTALL_DIR\bin\ to the end of the file.
  • On macOS, use forward slashes (/) instead of back slashes (\).
  • Remove any entries for previous versions of OpenSim (in either fullfile(prefdir, 'javalibrarypath.txt') or librarypath.txt, even if you have MATLAB 2012b or later).

Add the OpenSim Utilities directory to MATLAB's PATH variable

  • In the MATLAB Command Window, type pathtool (or editpath in older versions of MATLAB).
  • Click Add Folder... and select OPENSIM_INSTALL_DIR\sdk\Scripts\Matlab\Utilities.
    • Remove any entries for previous versions of OpenSim.
  • On macOS, you will see forward slashes (/) instead of back slashes (\).

Please report any issues you have with the configureOpenSim.m file so that other users need not perform these manual steps in the future.

 Advanced background information on how MATLAB scripting works...

MATLAB allows one to load and use Java libraries. OpenSim has a Java interface/library (used by the GUI), allowing us to leverage MATLAB's Java capabilities to provide a MATLAB interface to OpenSim.

  1. OpenSim's Java library is located in the file org-opensim-modeling.jar in the OpenSim installation. To allow MATLAB to use OpenSim's Java library, the configureOpenSim.m file tells MATLAB where this .jar library is located by adding the path to the .jar file to the javaclasspath.txt file in MATLAB's preferences directory (determined by running prefdir in MATLAB).
  2. The .jar file depends on OpenSim's C++ library osimJavaJNI.dll (or libosimJavaJNI.dylib on macOS), and the configureOpenSim.m file tells MATLAB the location of this library by adding the appropriate directory to the javalibrarypath.txt file in MATLAB's preferences directory.
  3. The osimJavaJNI library depends on OpenSim's other C++ libraries. On Windows, for MATLAB to find these other libraries, the directory containing these libraries must be on the system PATH. This step is not necessary on macOS.
  4. The MATLAB interface also involves a few pure MATLAB functions in the OPENSIM_INSTALL_DIR/sdk/Scripts/Matlab/Utilities folder. The configureOpenSim.m file adds this directory to the MATLAB path.


Troubleshooting

  • Errors related to osimJavaJNI not being on the path or "java.lang.NoClassDefFoundError" occur because the OPENSIM_INSTALL_DIR\bin directory is not on the system (Windows) path. Be sure the OPENSIM_INSTALL_DIR\bin directory has been added to the system PATH environment variable. (Note that the system PATH environment variable is distinct from MATLAB's path variable.)
  • If you're seeing errors saying failed dependencies with osimJavaJNI.dll, you would need to have Visual Studio redistribution package installed (which would come with any Visual Studio installation). You can just install the package files without Visual Studio on the Microsoft download site (For example 32-bit VS 2010 package is located here).