Creating Your Own Analysis Part One

The steps included in part one are:

Build a Body Position Analysis from the Template

In this example, you will learn how to a build and use an Analysis. The Analysis itself is a simple one that outputs the position of the center of mass of each body in the model.

• Prepare a working directory: Copy the folder containing the Analysis template from the installation folder (by default, this is C:\Program Files\OpenSim 2.0\sdk\examples\plugin) to a working folder. In this example, we will assume the working folder is C:\OpenSimPlugin\plugin, but the name and path are arbitrary.
• Rename Template. In your working plug-in directory (e.g., C:\OpenSimPlugin\plugin), rename the AnalysisPlugin_Template.h and AnalysisPlugin_Template.cpp files to MyAnalysis.h and MyAnalysis.cpp, respectively. (Any other name that is unique from the built-in analyses will also be acceptable.) The template analysis simply reports the center-of-mass position of selected bodies.
• Run CMake.Launch CMake. In the dialog box that appears:
  1. For the field "Where is the source code," select the working plug-in directory you just created (e.g., C:\OpenSimPlugin\plugin).
  2. Select a directory for "Where to build the binaries." For this example, we will use the folder C:\OpenSimPlugin\pluginBuild.
  3. Populate the "Cache Values" as shown below. Make sure that the correct installation directory is specified for OPENSIM_INSTALL_DIR, and update it if needed. If you use any directory other than the default for installation, you will also need to update CMAKE_INSTALL_PREFIX to have the same value as OPENSIM_INSTALL_DIR. The PLUGIN_NAME is the name of the dll that will be created by the solution file (in this case myAnalysisPlugin).
  4. Click Configure and then OK.

• Open the solution file OsimPlugin.sln (located in whatever directory you instructed CMake to build the binaries). This will launch Visual Studio. Do a search and replace (on the entire solution) to replace AnalysisPlugin_Template with MyAnalysis or whatever name you gave your analysis in Step 2.

• Build solution. Use Visual Studio's "Build" menu to compile your analysis into a dll (plugin). You need to switch from "Debug" to either "Release" or "RelWithDebInfo" if you do not have debuggable OpenSim libraries against which to link.

After building the dll, build the Install project within Visual Studio. It should install the dll in <OpenSimInstallDir>\plugins.

Using your Analysis

Option A: The section above demonstrated Option A, creating an analysis that can be built into a dynamic link library. In this case, the dynamic library myAnalysisPlugin.dll was created. Below, we examine three of the ways this library can be used:

• With the OpenSim GUI: To use your analysis within the OpenSim GUI, place the dynamic library myAnalysisPlugin.dll in the plugins folder under the OpenSim installation directory. This enables the GUI to load the Analysis, making it accessible to models and available through the GUI menu option (Tools->User Plugins). You can also accomplish this by executing the Install project within Visual Studio.
• With other OpenSim tools:  To use your Analysis with other OpenSim tools, you need to:
  • Change the setup file for the tool to include your Analysis in the set of Analyses to be executed. You would use the following XML tags for your new analysis, replacing MyAnalysis with whatever name you actually selected for your class:

<MyAnalysis name="">
  <start_time> 0.0 </start_time>
  <end_time> 1.0 </end_time>
  <in_degrees> true </in_degrees>

  <!--Names of the bodies on which to perform the analysis.The key word 'All' indicates that the analysis should be performed for all bodies.-->
  <body_names> all </body_names>
</MyAnalysis> 

• Run the OpenSim tool from the command line, including the option

–L myAnalysisPlugin.dll 

replacing the name myAnalysisPlugin.dll with the name you gave to the dynamic library.

For example, to test your Analysis during an InverseDynamics run of the arm26 model you would do the following:

• Create a new empty test directory (e.g, OpenSimPlugin\test).

• Copy the files arm26.osim, arm26_InverseKinematics.mot, and arm26_Setup_InverseDynamics.xml from the installation folder (under examples\Arm26\InverseDynamics) to the test folder. (Note: if you use a model from an older version of OpenSim, you may see a lot of "illegal tag" messages. You can clean up the model by reading it into the OpenSim GUI and then saving it.)

• Run InverseDynamics using the command:

analyze –S arm26_Setup_InverseDynamics.xml 

• Modify the setup file arm26_Setup_InverseDynamics.xml by adding the tags for the analysis you created directly below the </InverseDynamics> tag.

• Save the new setup file as arm26_myAnalysis_ID.xml

• Make sure your dll is either in the PATH or that you have copied it to the test directory. Then, run the tool again from the command line:

analyze –S arm26_myAnalysis_ID.xml –L myAnalysisPlugin  

You should see the line "Loaded library myAnalysisPlugin" printed on stdout. You should also see a new file arm26pos.sto in the Results directory that contains your analysis results (the .sto file consists of 6 columns per body, with the columns containing position and orientation relative to ground).

• Now load the model arm26.osim that you used above in the GUI. Then, load the motion arm26_InverseKinematics.mot. Plot the quantity r_ulna_radius_hand_Y (from the file arm26pos.sto) and the location of the marker r_radius_styloid_ty from the motion. The results should look like that shown below:

• With a main program: If you are writing a main program, you can use your analysis by including the header files and linking to the export library (.lib on Windows).

Option B: For Option B, where you wrote your Analysis as part of your main program, there is no plug-in to build separately. You just compile and link the code for your Analysis along with the rest of the code of your main program. The analysis can be added to the model using the calls:

MyAnalysis* comReporter = new MyAnalysis (&osimModel);
osimModel.addAnalysis(comReporter);