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:\OpenSim 3.3\sdk\APIExamples\plugins\AnalysisPluginExample) to a working folder. In this example, we will assume the working folder is C:\OpenSimPlugins\AnalysisPluginExample, but the name and path are arbitrary.
• Rename Template. In your working plug-in directory (e.g., C:\OpenSimPlugins\AnalysisPluginExample), 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:\OpenSimPlugins\AnalysisPluginExample).
  2. Select a directory for "Where to build the binaries." For this example, we will use the folder C:\OpenSimPlugins\AnalysisPluginExample-build.
  3. Hit Configure and select the appropriate compiler (e.g., Visual Studio 2013), and you will see four lines highlighted in red. CMAKE_CONFIGURATION_TYPES (the 1st line) specifies the build types, "RelWithDebInfo" (Release with Debug Info) and "Release" by default.  CMAKE_INSTALL_PREFIX (the second line) specifies where your plugin will be installed; this should be inside the OpenSim 3.3 install location inside a folder called plugins (e.g., C:/OpenSim 3.3/plugins).  OPENSIM_INSTALL_DIR (the 3rd line) specifies where OpenSim 3.3 is installed (C:/OpenSim 3.3, by default).  PLUGIN_NAME (the 4th line) specifies the name of the library that will be generated (osimPlugin, by default).  Update any of these values it if needed (or desired).
     The following changes are recommended:
     a) Make your plugin install in the recommended location by setting CMAKE_INSTALL_PREFIX to the same as OPENSIM_INSTALL_DIR (c:/OpenSim 3.3, by default).
     b) Change PLUGIN_NAME to "myAnalysisPlugin" so that your output will be consistent with the rest of this tutorial. 
  4. Click Configure again and then Generate.

• Open the solution file OpenSimPlugin.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. Note that you will need to name future plugins you may write to something unique to avoid name conflicts.  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 (if it is not already there). This enables the GUI to load the Analysis, making it accessible to models and available through the GUI menu option (Tools->User Plugins).
• 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="MyAnalysis">
	<!--Flag (true or false) specifying whether whether on. True by default.-->
	<on> true </on>
	<!--Start time.-->
	<start_time>       0.50000000 </start_time>
	<!--End time.-->
	<end_time>       4.00000000 </end_time>
	<!--Specifies how often to store results during a simulation. More
		specifically, the interval (a positive integer) specifies how many
		successful integration steps should be taken before results are
		recorded again.-->
	<step_interval> 1 </step_interval>
	<!--Flag (true or false) indicating whether the results are in degrees or not.-->
	<in_degrees> true </in_degrees>
	<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:

• Go inside TestPlugin directory inside the plugin example directory that you copied.

• Run Analyze tool using the command:

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 directory Results which contains your analysis results (the .sto file consists of 6 columns per body, with the columns containing position and orientation relative to ground). Compare the result in Results directory with the file inside ExpectedResults directory. They should be the same.

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