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"

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.

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

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.