| Table of Contents |
|---|
| Anchor | ||||
|---|---|---|---|---|
|
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.
- 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.).
- 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.
- 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.
- 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.
- 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.
- Restart MATLAB; the OpenSim libraries will not be recognized until doing so.
- Test that everything is configured correctly: In the command window, run the following:
| Code Block | ||
|---|---|---|
| ||
>>> 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.
| Expand | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
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
Tell MATLAB about OpenSim's Java library (.jar)
Tell Matlab about OpenSim's C++ libraries, which the Java library depends on
Add the OpenSim Utilities directory to MATLAB's PATH variable
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
| Code Block | ||
|---|---|---|
| ||
>> 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).
| Code Block | ||
|---|---|---|
| ||
>> 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.
| Code Block | ||
|---|---|---|
| ||
>> 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.m | Import data from a C3D file to OpenSim Tables. See the c3dExport.m example below for a use case. |
osimTableFromStruct.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.m | Get 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
...
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)
| Code Block |
|---|
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.
| Code Block |
|---|
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
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
prop = obj.getPropertyByName("propertyName")
currentValue = PropertyHelper.getValueDouble(prop)
PropertyHelper.setValueDouble(newValue, prop)
|
Show OpenSim's log messages in the Matlab Command Window
| Info |
|---|
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:
| Code Block |
|---|
myMatlabLog = JavaLogSink() Logger.addSink(JavaLogSink()myMatlabLog) |
Additional information
| Expand | ||
|---|---|---|
| ||
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.
|
...