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, by default, this is C:/Users/<username>/Documents/OpenSim/4.0/Code/Matlab.
  3. Run the configureOpenSim.m file from the current folder. The script will prompt you to choose your OpenSim installation directory (we will refer to this as OPENSIM_INSTALL_DIR). On Windows, by default, this is C:/OpenSim 4.0
  4. 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.
  5. Windows users: ensure that the OPENSIM_INSTALL_DIR/bin directory (e.g., C:/OpenSim 4.0/bin) appears in your system PATH environment variable, and that it appears before any other OpenSim installations you may have on your PATH. The steps to set your path are shown in the animated image below. Double click the image to zoom in. Or see here for additional help on setting your PATH environment variable.
  6. Restart MATLAB; the OpenSim libraries will not be recognized until doing so.
  7. Test that everything is configured correctly: In the command window, run the following:
Test that OpenSim is properly configured with MATLAB
>>> org.opensim.modeling.opensimCommon.GetVersion()	% This should print the version of OpenSim that you've 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.


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 C:\Users\<username>\Documents\OpenSim\4.0\Code\Matlab\Utilities folder (by default).
    • 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.

Loading OpenSim Libraries 

Once you have set up the OpenSim-Matlab environment you must import the OpenSim libraries to be able to have access to the OpenSim classes. Since imported libraries are not Global variables, you must import the libraries at the beginning of all scripts or functions that use OpenSim classes. This included nested functions or classes. 


To Load the OpenSim Libraries in Matlab
>> import org.opensim.modeling.*		% Import OpenSim Libraries

Finding the Methods Available for a Class in the OpenSim Libraries

Often, it is difficult to know exactly what methods are available for an OpenSim class (e.g., Model, Muscle) and so using the API Documentation regularly will be useful. However, you can very quickly get a list of the available methods and the interfaces to those methods by using the built-in Matlab functions methods and methodsview().

methods() will output a list of all the methods available for a given OpenSim class to the MATLAB command window. Below is an example of methods you can call on the Model class. A list of methods is printed to the command window (cut off here since the list is very long).

View all methods in an OpenSim class
>> methods(Model)
Methods for class Model:

LoadOpenSimLibrary                            getDefaultSubsystem                           notifyAll                                     
Model                                         getDescription                                overrideAllActuators                          
PrintPropertyInfo                             getDiscreteVariableValue                      postScale                                     
RegisterType                                  getDisplayHints                               preScale                                      
RenameType                                    getDocumentFileName                           print                                         
SafeCopy                                      getDocumentFileVersion                        printBasicInfo                                
addAnalysis                                   getFilePath                                   printComponentsMatching                       
addBody                                       getForceSet                                   printControlStorage                           
addComponent                                  getForceSubsystem                             printDetailedInfo                             
addConstraint                                 getForceUnits                                 printInputInfo                                
addContactGeometry                            getFrameList                                  printOutputInfo                               
addController                                 getFunctionClassNames                         printSocketInfo                               
addForce                                      getGravity                                    printSubcomponentInfo                         
addJoint                                      getGravityForce                               readObjectFromXMLNodeOrFile 
...											  ...											...


methodsview() is useful to get a list of the methods and the method signatures (arguments, return type) for an OpenSim class. When calling methodsview(), a Matlab pop-up window will be generated that shows the method names, the arguments you can input, and the return type.

View all method signatures in an OpenSim class
>> myModel = Model()
>> methodsview(myModel)


Tab-completion can be used to get quick access to a method name and is most useful when you know the method name (or the first few letters of the method name).  In the GIF below, the tab key is pressed after "myModel." is typed to open the tab-completion window.


Utilities

OpenSim provides utility functions for some common tasks. If you have installed OpenSim, these scripts are located in the resources directory (e.g., C:/Users/<username>/Documents/OpenSim/4.0/Code/Matlab/Utilities). 

File Name(s)

Description
osimC3D.mImport data from a C3D file to OpenSim Tables. See the c3dExport.m example below for a use case.

osimTableFromStruct.m
osimTableToStruct.m

Convert between an OpenSim Table and Matlab Struct.

These utilities convert between OpenSim TimeSeriesTables (a new storage format from OpenSIm 4.0 for time series data, details below) and Matlab Structs. Be aware that any metadata in your Table will be lost when you convert to a Matlab Struct.

osimVec3FromArray.m
osimVec3ToArray.m
Convert between an OpenSim Vec3 and a Matlab Array.


osimList2MatlabCell.mGet a Matlab cell array populated with an OpenSim's Model's list (e.g., Body). See the section "Using a model's "Lists" through iterators" below for more details and usage.

Example Scripts

If you have installed OpenSim, these scripts are located in the resources directory (e.g., C:/Users/<username>/Documents/OpenSim/4.0/Code/Matlab). 

File Name(s)

Description
c3dExport.mLoad a C3D file into OpenSim Tables and write out the marker and force data to corresponding .trc and .mot files.
OpenSimCreateTugOfWarModel.m
TugOfWar_CompleteRunVisualize.m
Generate a simple tug of war model, run a simulation, and visualize the results.
prescribeMotionInModel.mCreate an OpenSim model with coordinates prescribed according to an input motion file. It uses a helper function defined in the script createPrescribedMotionModel.
setupAndRunAnalyzeBatchExample.m

Generate 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.mRun 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.m
simpleOptimizerObjectiveFunction.m

Run a simple optimization to find the elbow flexion angle where the moment arm of the biceps femoris short head is maximized.
strengthScaler.mFunctionthat loads a model and itsmuscles,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.
wiringInputsAndOutputsWithTableReporter.mCreate a Reporter and wire the Inputs and Outputs necessary to report the system's center of mass.

Reading in and Writing Data to File

Reading from and writing to files has been improved with the introduction of tables and file adapters (available as of OpenSim 4.0). The code blocks below demonstrate how to read and write vector and scalar (double) data from and to a file.

Reading Data from fileWriting Data to File

Vec3 (Vector) Data

% Define the path to the file 
filepath = 'subject01_walk1.trc';
% Use the Vec3 TimeSeriesTable to read the Vec3 type data file. 
opensimTable = TimeSeriesTableVec3(filepath);
% Use the OpenSim Utility function, osimTable2Struct to 
% convert the OpenSim table into a Matlab Struct for ease of use.
matlabStruct_markerData = osimTableToStruct(opensimTable);
% Define output file name/path
filepath = 'myMarkerTrial_01.trc';

% Write the TimeSeriesTableVec3 to file
TRCFileAdapter().write(opensimTable,filepath)

Double (Scalar) Data

% Define the path to the file
filepath = 'subject01_walk1_grf.mot';
% Use the standard TimeSeriesTable to read the data file. 
opensimTable = TimeSeriesTable(filepath);
% Use the OpenSim Utility function, osimTable2Struct to 
% convert the OpenSim table into a Matlab Struct for ease of use.
matlabStruct_grfData = osimTableToStruct(opensimTable);
% Define output file name/path
filepath = 'myMarkerTrial_01_grf.mot';

% Write the TimeSeriesTable to file
STOFileAdapter().write(opensimTable,filepath)

Adding Geometry Paths to Matlab 

OpenSim verifies that Model's Geometry mesh files exists when you load a model and whenever you subsequently operate on it. If you have a Geometry file defined in your model, and the Geometry path is not set, you will get a warning for each piece of Geometry that can't be found, as shown in the image below.

These warning can get cumbersome, especially if you are doing batch processing or iterative analysis. To stop the warnings, you have to set the Geometry folder path of OpenSim:ModelVisualizer() in Matlab. Copy and paste the below code and update the path to your local OpenSim Geometry directory.

>>> path='/Users/username/Applications/OpenSim 4.0/OpenSim 4.0.app/Contents/Resources/OpenSim/Geometry';
>>> ModelVisualizer.addDirToGeometrySearchPaths(path);

Alternatively, a 'workaround' that if you are not visualizing the model is to remove the geometry from the model. This should only be used if you are doing many model instantiations or initSystem() calls and don't need to visualize the model.


Using a model's "Lists" through iterators

Lists, such as BodyList and MuscleList, are useful ways to get access to all components of that type in the model. Access is available through an iterator. Iterators are a different way of getting references to objects in the model and Matlab users may be unfamiliar with them. For a discussion of iterators, see this StackOverflow discussion.

Iterate over all bodies in a model (even bodies not in the model's BodySet)

model = Model("my_model.osim")
bodyList = model.getBodyList();      # Get the Model's BodyList
iter = bodyList.begin();             # Start the iterator at the beginning of the list
while ~iter.equals(bodyList.end())   # Stay in the loop until the iterator reaches the end of the list
    iter.getName()                   # Print name to console
    iter.next()                      # Move the iterator to the next body in the list
end


Getting a single reference from a list

We have included a Matlab function— osimList2MatlabCell() — that converts an OpenSim List to a Matlab cell array. Then, you can use simple Matlab methods to get references to objects. 

model = Model("my_model.osim")
references = osimList2MatlabCell(model,'Body')  % Get a cell array of references to all the bodies in a model
Pelvis = references{1}							% Get the first body in the list.

Using PropertyHelper to set Property values for plugin classes

Classes defined in plugins are not available for direct access in Matlab, however classes that are subclasses of OpenSim "Object" contain properties that can be accessed and modified using the PropertyHelper class. The exact syntax depends on the basic data type of the property, for example

Use PropertyHelper for classes defined in plugins
prop = obj.getPropertyByName("propertyName")
currentValue = PropertyHelper.getValueDouble(prop)
PropertyHelper.setValueDouble(newValue, prop)


Show OpenSim's log messages in the Matlab Command Window

Applies to OpenSim 4.2 and above.

Some versions of Matlab do not show OpenSim's log messages by default. To see these messages in the Matlab Command Window, run the following command: 

myMatlabLog = JavaLogSink()
Logger.addSink(myMatlabLog)


Additional information

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 C:/Users/<username>/Documents/OpenSim/4.0/Code/Matlab/Utilities folder (by default). The configureOpenSim.m file adds this directory to the MATLAB path.

Troubleshooting

  • 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.
  • 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).