Scripting with Matlab

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:
   

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

Loading OpenSim Libraries 

>> import org.opensim.modeling.*		% Import OpenSim Libraries

Finding the Methods Available for a Class in the OpenSim Libraries

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

>> myModel = Model()
>> methodsview(myModel)

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

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

prop = obj.getPropertyByName("propertyName")
currentValue = PropertyHelper.getValueDouble(prop)
PropertyHelper.setValueDouble(newValue, prop)

Show OpenSim's log messages in the Matlab Command Window

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

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