AnimatLab Scripting

Watch the video tutorial on this subject!

Purpose of the Scripting System

The purpose of this system is to give external programs the ability to modify and run AnimatLab simulations. This allows third party tools, like optimization software, to have access to the parameters within AnimatLab and run simulations so that it can perform tasks like parameter sensitivity analysis and optimization. One thing to keep in mind is that the current scripter can only modify parameters on already existing objects. You will not be able to create or delete parts with the scripting system. That will need to be done manually within the application.

Using the Scripter

There is a new AnimatLabScripter.exe application located in the bin folder of AnimatLab. If you installed to the default location then the bin folder is located at C:\Program Files\AnimatLab\bin. The third party tool will use a shell execute command to start this application up and pass some key information to it on its command line. Below is an example command line that runs one of the tutorial applications called LimbStiffness. Below that is a list of the parameters that are required. You must set the working directory to be the AnimatLab bin folder.

C:\>AnimatLabScripter "C:\Program Files\AnimatLab\Tutorials\Examples\Limb Stiffness" "Limb Stiffness.aproj" "API_File.txt" "StandAlone.asim"

1.	The first parameter is the full path to the directory of the project you are attempting to load and modify. If any item in the path has a space in the name then you must enclose the whole path in quotes.
2.	The second parameter is the name of the project file that is located within the project directory. This file has an .aproj file extension.
3.	The third parameter is the name you will use for the script file you will be creating. The scripter will wait in the background until a file with this name is created inside the project directory.
4.	The fourth parameter is the name of the stand-alone simulation file that the scripter should create when a script file is processed successfully. This should have a .asim file extension.

Once the scripter application is started it will remain running for the entire scripting session. When it starts up it will use the project information that you passed to it to load in the project. This may take several seconds. So in order for the third party tool to know when the project has been loaded and the scripter is ready the third party tool should first create a blank API script file before starting the scripter. Then when the project is loaded and everything is ready to go the scripter will delete the blank script file and this will be the signal to the third party tool that it can now send script files to the scripter.

The scripter runs in the background and looks for the creation of the script file. It only sees the creation, not modifications. So it is important that if the script file already exists for some reason then you must first delete it and then re-create it for the scripter to see and process it. One a script file is created the scripter application opens it, parses it, modifies the parameters outlined in the file, saves out a stand-alone simulation file, and the returns the parameters back to their original values so the next script file will start from the same starting point.

The script file is a comma separated file that contains 3 data items per row. Below is an example of a single row in a script file and a description of each column. You can only have one parameter change per row.

4dae3358-9d54-49a4-9ac4-c67e3c99b1d7,Kse,2000

1.	Column 1 is the unique ID for the object that will be modified.
2.	Column 2 is a unique name of a property of the object that will be modified. This must be the name used for the property in the actual source code class. This is not necessarily the same thing as the textual name displayed within the running application.
3.	This is the new value that will be used for the parameter. This setting must always be the actual value. For instance, if you are setting Kse and it is listed in the application as 1 kN/m or 1 kilo-Newton per meter, the value you would use in the script file is 1000, not 1.

Finding the Unique ID Values

Getting the ID is pretty easy. Simply go to the object that you want to modify and select it. Within the property grid there will be a read-only ID property. This is the unique ID for this object. Click on the ID and copy it and then paste it in the first row of your script file. Lets do this for the ID of our biceps muscle.

Next, we need the property name. This can be a little more tricky. The problem is that the text that is shown for the property in the property grid may not always match exactly the name of the property, and the scripter must have the exact name of the property in the class in order to work. Typically, if the property text that is displayed in the property grid is a single word then it will match exactly. If it is multiple words then you usually just need to eliminate the spaces between words. However, on rare occasions this will not be the case. For these situations there is a new tool in the bin folder called Reflector. This application allows you to look at all of the classes in the AnimatLab system and see the actual names of the parameters.

Running the Simulations

Simulations are run using the AnimatSimulator.exe application that is also located in the bin folder. One thing you need to know about the stand-alone simulator is that any data charts that have a start and end time and that are open when the sim file is created will be saved out as a data file when it is run in a stand-alone mode. The data will be saved out at the end time of the data chart. Below is an example command line that starts a simulation running, and below that is a description of the command line parameters.

C:\>AnimatSimulator -d3d -library vortexanimatlibrary_vc7.dll -project "C:\Program Files\AnimatLab\Tutorials\Examples\Limb Stiffness\StandAlone.asim" -runtime 10.5

-d3d or -null	This tells the simulator what type of graphics window to open. -d3d opens a directX window so you can see the simulation running. -null does not open any window.
-library	This tells which physics engine library to use for the simulation. Currently the only valid option is to use vortexanimatlibrary_vc7.dll.
-project	This is the full path to the simulation file that will be run. You will specify the stand-alone simulation file created by the scripter here. Don't forget to add quotes around this if there any spaces in the path name.
-runtime	This specifies how long, in simulation time, the project is to run. Make sure that you specify a time that is longer than the longest running data chart in order for your data to be saved out.

Conclusion

In this document we have covered the basics needed to get the scripter up and running, and how to generate a script file and run simulations. Good luck on your scripting projects.