Common Scripting Commands

Scripting environments like Matlab, Python and the OpenSim GUI shell allow users to interact with the classes of the OpenSim API (see The OpenSim API). There are many example scripts that are located in the OpenSim scripting folder, available with the distribution to help you get started. This page summarizes some of the common calls that you will make in the scripting environment of your choice. 

Beginner Scripting Resources  

1. Run the example scripts found in the distribution.
2. As you run the example scripts, find the related Classes and Methods in 
3. The structure for classes can often be found in OpenSim's files (.xml or .osim). For example, Setup_Scale.xml shows the hierarchy of the ScaleTool.
4. Use the  to search for a Class or Method in the documentation, on the forum or on the Doxygen pages. 
5. If you are having trouble with a Class or Method, ask a question on the .

Inline Method and Type getting

These are inline commands that help you find the methods available for a class 

Packages and Libraries 

Packages and libraries are collections of classes and methods that have a well-defined interface and can be imported into your programming environment to utilize. These can be packages to browse files, read and write files, do mathematics operations, and run  simulations. The commands below are common Packages or Libraries you will find useful.

>>> import java.io as io				# Import Read/Write package
>>> trcFolder = io.File(trcDataFolder)	# Use package to read TRC file	

Creating New Objects 

Creation of objects is performed by the constructor method of the Class. We can create an object and populate its properties, or pass the class a correctly formatted xml file. 
Note: 'path' indicates your system path to the file (i.e., C:\OpenSim 2.1\Models\...). Delete "modeling." from code for Matlab.

Action	Class Information	Default construction (Scripting shell)	XML construction (Scripting shell)
Marker set object		newMarkerSet = modeling.MarkerSet()	newMarkerSet = modeling.MarkerSet([path 'markerSet.xml'])
Marker data object		markerData = modeling.MarkerData()	markerData = modeling.MarkerData([path 'walkingData.trc'])
Scaling tool object		scaleTool = modeling.ScaleTool()	scaleTool = modeling.ScaleTool([path 'scale_setup.xml'])
Inverse Dynamics analysis object		idTool = modeling.InverseDynamicsTool()	idTool = modeling.InverseDynamicsTool([path 'ID_setup.xml'])
Control Set		rawControls= modeling.ControlSet()	rawControls= modeling.ControlSet([path 'controls.mot'])

>>> markerSetFile="gait2354_MarkerSet.xml"			# Define the full path to the Marker Set file
>>> newMarkers = modeling.MarkerSet(markerSetFile)	# Construct a MarkerSet Object 
>>> myModel.replaceMarkerSet(myState,newMarkers)	# Replace the models existing MarkerSet with new MarkerSet
>>> myModel.initSystem()							# re-initialize the system
>>> myState =myModel.initSystem()					# Define the new state  

>>> myModel = modeling.Model("gait2354.osim")				# Create a Model Object
>>> pelvisbody = myModel.getBodySet().get("pelvis")			# Get a handle to the pelvis body
>>> newMarkerSet = modeling.MarkerSet()						# Create an empty MarkerSet Object
>>> newMarkerSet.addMarkers("LASI", [1, 1, 1], pelvisbody)	# Add a Marker to the MarkerSet called 'LASI', that is attached to the pelvis at [1,1,1]
>>> myModel.replaceMarkerSet(myState,newMarkers)			# Replace the models existing MarkerSet with new MarkerSet
>>> myModel.initSystem()									# re-initialize the system
>>> myState =myModel.initSystem()							# Define the new state  
 

>> nBody  = Body(); 										% Creates an body with default mass=1
>> massCenter = Vec3(-0.0707,0.0,0.0);						% Create a Vec3 Object with Mass center information
>> inertiaMat = Mat33(0.1028,0,0,0,0.0871,0,0,0,0.0579);	% Create a Mat33 (3x3 Matrix) with inertial information
>> nBody.setName('pelvis')									% Set the name of the body using a string
>> nBody.setMass(11)										% Set the mass of the body using a double
>> nBody.setMassCenter(massCenter)							% Set the Mass Center
>> nBody.setInertia(inertiaMat)								% Set the Inertia 
 
%% Alternatively, a body can be created by sending all of these properties directly to the constructor
>> massCenter = Vec3(-0.0707,0.0,0.0);						% Create a Vec3 Object with Mass center information
>> inertiaMat = Mat33(0.1028,0,0,0,0.0871,0,0,0,0.0579);	% Create a Mat33 (3x3 Matrix) with inertial information
>> bodyName = 'pelvis'										% Set the name of the body using a string
>> bodyMass = 11											% Set the mass of the body using a double
>> nBody  = Body(bodyName,bodyMass,massCenter,inertiaMat);	% Creates an body from properties sent to constructor
 
 

>> pBody  = Body('pelvis', bodyMass,massCenter,inertiaMat); 	% Either create or get a handle to the parent body
>> cBody  = Body('femur_r',bodyMass,massCenter,inertiaMat);		% Either create or get a handle to the child body
>> name = 'hip_r'												% Assign the joint name
>> locInParent   = Vec3(-0.0707,-0.0661,0.0835);				% A Vec3 location in the parent frame
>> orienInParent = Vec3(0,0,0);									% A Vec3 orientation in the parent frame
>> locInChild = Vec3(0,0.0,0);									% A Vec3 location in the child frame
>> orienInChild= Vec3(0,0,0);									% A Vec3 orientation in the child frame
>> reverse = 0; 												% Reverse the joint (true/false)
>> rrHip = BallJoint(name,nBody,locInParent,orienInParent,cBody,locInChild,orienInChild,reverse)

>> myModel = Model("gait2354.osim")					# Create a Model Object
>> femur_r = myModel.getBodySet().get('femur_r');	# Get a Handle to the Body A
>> tibia_r  = myModel.getBodySet().get('tibia_r');	# Get a Handle to the Body B
>> zAxisTorque = Vec3(0,0,1);					# A Vec3 of the z-axis
>> torqueActuator = TorqueActuator();			# Create a Torque Actuator Object
>> torqueActuator.setBodyA(femur_r); 			# Set Body A
>> torqueActuator.setBodyB(tibia_r);			# Set Body B
>> torqueActuator.setAxis(zAxisTorque);			# Set the axis about the torque to act
>> torqueActuator.setOptimalForce(10);			# Set the optimal force (gain) of the actuator

Loading, Creating, and Initializing Models

Loading models and dealing with model states is very common. Below are the methods for loading, copying and initializing a model

>>> modelFileName=modelFolder+"\gait2354_simbody.osim"			    # Define the full path to the model file
>>> loadModel(modelFileName)										# Load the model into the GUI
>>> myModel=getCurrentModel()										# Create a handle to the current model
>>> myModel.initSystem()											# Initialize the model 
>>> myState=myModel.initSystem()									# Get a handle to the current states of the model

Exploring and Editing Models and Model Components

You can use the functionality of the OpenSim API to access the properties of a model and change their values. For examples, refer to the distributed scripts muscleScaler and alterTendonSlackLength. The OpenSim API Doxygen lists all of the available functions. For example, executing the following commands in the GUI scripting shell, sets and gets the name of the current model. 

>>> myModel = getCurrentModel()
>>> myModel.setName("My Model")
>>> mymodel.getName()  
>>> "my Model"

The API also allows you to access and edit the components of an OpenSim model, like its bodies, muscles, and joints. Some properties have custom "get" and "set" functions - see the respective classes for details.

Action	Class Information	Getting a Handle to a Set	Reference an Object by index	Get object from a name	Alternative 'long path'
Body Set		bodySet= myModel.getBodySet()	rightFemur = bodySet().get(1)	rightFemur = bodySet().get("femur_r")	rightFemur =myModel.getBodySet().get("femur_r")
Joint Set		jointSet = myModel.getJointSet()	rightHip = jointSet ().get(7)	rightHip = jointSet ().("hip_r")	rightHip = myModel.getJointSet().("hip_r")
Coordinate Set		cordSet= myModel.getCoordinateSet()	hip_coord = cordSet().get(4)	hip_coord = cordSet().get("hip_flexion_r")	hip_coord = cordSet().get("hip_flexion_r")
Muscle Set		muscleSet= myModel.getMuscles()	recFemR= muscleSet().get(3)	rec_fem_r= recFemRt().get("'recFem_r")	rec_fem_r= myModel.getMuscles().get("'recFem_r")
Path Point of a Muscle		pathPoints = myModel.getMuscles().get("'recFem_r").getGeometryPath().getPathPointSet()	recFemPathPoint1 = pathPoints.get(0)	recFemPathPoint1 = pathPoints.get("rect_fem_r-P1")	recFemPathPoint1 =myModel.getMuscles().get("'recFem_r").getGeometryPath().getPathPointSet()

Once a Handle to the component has been created you can edit its properties and methods. 

Action	Class Information	Example
Get the optimal fiber length		recFemFiberLength = RectusFemoris.getOptimalFiberLength()
Set the optimal fiber length		RectusFemoris.setOptimalFiberLength(0.23)
Set the tendon slack length		RectusFemoris.setTendonSlackLength(0.2105)
Get the muscle maximum isometric force		recFemMaxForce = RectusFemoris.getMaxIsometricForce()

>>> ECRB = myModel.getMuscles().get("ECRB")							# Get a handle to the ECRB
>>> backupTendonSlackLength = ECRB.getTendonSlackLength()			# Back up the original tendon slack length (just in case)
>>> ECRB.setTendonSlackLength(0.2105)								# Prescribe a new Tendon slack length
>>> myModel.initSystem()											# Re-initialize the states

You may need to downcast an object from an abstract class (e.g., Muscle)  to a derived class (e.g., Thelen2003Muscle) in order to gain access to its properties and methods. Here is an example:

>> import org.opensim.modeling.*
>> myModel = Model('arm26.osim');
>> mcl_TRIlong = Thelen2003Muscle.safeDownCast( myModel.getMuscles().get('TRIlong') );
>> mcl_TRIlong.setFmaxTendonStrain( 0.5*mcl_TRIlong.getFmaxTendonStrain() );

Using the Tools

Tools contain a number of grouped Methods that allow you to run a study. For example, to scale a Model to match experimental data the ScaleTool groups GenericModelMaker(), ModelScaler() and MarkerPlacer() together. The AnalyzeTool() can group StaticOptimization() and MuscleAnalysis() together to output muscle states of a Static Optimization.  

Class	Doxygen Link	Default construction (Scripting shell)	XML construction (Scripting shell)
Scale		scaleTool = modeling.ScaleTool()	scaleTool = modeling.ScaleTool([path 'scale_Setup.xml'])
InverseKinematicsTool		ikTool = modeling.InverseKinematicsTool()	idTool = modeling.InverseKinematicsTool([path 'IK_Setup.xml'])
InverseDynamicsTool		idTool = modeling.InverseDynamicsTool()	idTool = modeling.InverseDynamicsTool([path 'ID_Setup.xml'])
RRATool		rraTool = modeling.RRATool()	rraTool = modeling.RRATool([path 'RRA_Setup.xml'])
CMCTool		cmcTool = modeling.CMCTool()	cmcTool = modeling.CMCTool([path 'CMC_Setup.xml'])
ForwardTool		cmcTool = modeling.ForwardTool()	cmcTool = modeling.ForwardTool([path 'forward_Setup.xml'])
AnalyzeTool		analyzeTool = modeling.AnalyzeTool()	analyzeTool = modeling.AnalyzeTool([path 'analyze_Setup.xml'])

Working with Files and Paths

Below are examples of the OpenSim GUI shells native commands with files and file paths. Matlab and Python environments have their own methods for dealing with files and file paths. 

Plotting

GUI Scripting Shell

In the GUI scripting shell, we've provided a set of commands that allow you to easily perform some basic plotting functionality. This includes adding a plot window, adding curves, changing the legend, plotting from file, exporting the plot, etc.

https://simtk.org/api_docs/opensim/gui_docs/org/opensim/console/OpenSimPlotter.html

These commands are exercised in the example "plotMuscleFiberLengthAgainstFile.py" and "plotMuscleMomentArmAgainstMotion.py".

There are additional advanced commands that you can call (the ones used by the GUI itself), though these commands have not been fully documented and tested with the scripting functionality, so please use with caution. 

https://simtk.org/api_docs/opensim/gui_docs/org/opensim/console/gui.html

Matlab

We encourage you to use Matlab's host of built in plotting capabilities. You can import OpenSim .sto and .mot files using Matlab's "Import Data" interface (see MATLAB's importdata function). 

Working with Vectors, Matrices, and Other SimTK Classes

OpenSim 3.1 and later

In OpenSim 3.1 and later we've exposed the most commonly used SimTK classes. In particular:

Helpful tips:

• For Simbody doxygen links above Vec3P corresponds to a modeling.Vec3 object and RealP corresponds to a double value.
• To see the available methods for these objects, use methodsview() or tab completion (Matlab only).
• You can find more information in the SimTK Basics section of the User's Guide. Note that only the SimTK classes listed above are available through scripting.
• You can also find more information in the section below on Handling C++ Templates.

Templates are advanced C++ constructs that are used extensively throughout the OpenSim API and Simbody API. C++ provides templates to allow for compiler generated classes from a common code base. This approach is useful primarily for containers (e.g. Array<double>, Array<int>, Array<string>) since it avoids code duplication making the code easier to maintain; however, these templates exist only in C++ and do not map easily to scripting languages. One way to work around that is to specialize templates into classes, give those classes unique names and then use them. The attached file lists template specializations used in OpenSim API (C++) & Doxygen and the corresponding named classes to be used in scripting (the list is current as of OpenSim 3.2):

OpenSim 3.0 and 3.0.1

In many cases the function you're trying to call takes an argument type different from the object you have already. This is true even moving data between Matlab and Java objects, and between objects in the SimTK namespace and those in the OpenSim namespace. The following set of convenience methods are "Adaptors" intended to help you pass data around between OpenSim objects and low level SimTK objects.

Handling C++ Templates (e.g. Array<double>)

Templates are advanced C++ constructs that are used extensively throughout the OpenSim API and Simbody API. If you see notation like Array<double> in the doxygen or C++ code that you are trying to replicate, this means you're working with a templatized class and will need to find its appropriate mapping in the scripting environment.

C++ templates allow the compiler to automatically generate classes from a common code base. This approach is useful primarily for containers (e.g. Array<double>, Array<int>, Array<string>) since it avoids code duplication making the code easier to maintain; however, these templates exist only in C++ and do not map easily to scripting languages.

One way to work around this is to specialize templates into classes, give those classes unique names, and then use them in scripting. The attached file lists template specializations used in OpenSim API (C++) & Doxygen and the corresponding named classes to be used in scripting (the list is current as of OpenSim 3.2):

Mapping of Templates to Class Names for Scripting

Obtaining Position and Velocity Information

For more information regarding multibody system states, refer to the SimTK Simulation Concepts documentation in the Developer's Guide.

In order to obtain simulation position or velocity state information you must have a State object in hand. 

>>> si = myModel.initSystem();
>>> myModel.equilibrateMuscles(si);

Now you can call the SimBodyEngine's getVelocity() (or getPosition()) method in order to fill a pre-allocated Vec3 object with velocity information.

>>> massCenter = Vec3(0.0,0.0,0.0);
>>> velocity   = Vec3(0.0,0.0,0.0);
>>> bodySet = myModel.getBodySet()
>>> bodySet.get('r_ulna_radius_hand').getMassCenter(massCenter); 
>>> simbodyEngine = myModel.getSimbodyEngine();
>>> simbodyEngine.getVelocity(si, osimModel.getBodySet().get('r_ulna_radius_hand'), massCenter, velocity);

Using the SimTK Visualizer in Matlab

You can use the visualizer from SimTK in Matlab. To do so call the "setUseVisualizer" method and pass in the parameter "true", and when you run the simulation the Visualizer GUI will pop up. The example of usage is described in "TugOfWar_CompleteRunVisualizer.m"

osimModel = Model('tug_of_war_muscles_controller.osim');
osimModel.setUseVisualizer(true);

Batch Processing

There are several examples in the Matlab scripts and GUI scripts that show how to perform batch processing by calling the OpenSim API (e.g. Analyze, IK). We encourage you to use this approach rather than using Matlab's xml parsing tools. To read more about why this is the case, please see the scripting FAQ:

Frequently Asked Questions

References

• Java File IO: http://docs.oracle.com/javase/1.4.2/docs/api/java/io/File.html
• Using Java in Jython: http://www.jython.org/jythonbook/en/1.0/JythonAndJavaIntegration.html
• Jython Swing examples: http://wiki.python.org/jython/SwingExamples