Technical Background

The topics covered in this section include:

What is an API?

An application programming interface (API) is a particular set of rules ('code') and specifications that software programs can follow to communicate with each other. It serves as an interface between different software programs and facilitates their interaction, similar to the way the graphical user interface (GUI) facilitates interaction between humans and computers. Using the OpenSim API, other programs such as any C++ programming software or Matlab can access the OpenSim source code. In this way, OpenSim developers can make use of existing OpenSim code, to build on it and extend the available capabilities. For example, the API can be useful for creating Main programs to build and run models, or for creating new analyses, actuators (e.g. an altered muscle model), or controllers.

Some C++ Basics

OpenSim is written in C+. C+ is a general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level language features (more abstract and conceptual) and low-level language features (directly interfacing with hardware).

If you are not familiar with C+, +it is advisable to learn some basic C++ programming language before starting the examples. A good free, online course is available on http://www.cplusplus.com/doc/tutorial/ Only very limited C++ basics are described here.

C++ code, in contrast to for example Matlab code, needs to be compiled or built, before it can be run. A compiler is a computer program (or set of programs) that transforms source code written in the programming language (the source language) into another computer language (the target language, often having a binary form known as object code). Visual Studio is an example of a compiler. The most common reason for wanting to transform source code is to create an executable program.

An executable (.exe) file is a program that causes a computer to perform indicated tasks according to encoded instructions (as opposed to a data file that must be parsed by a program to be meaningful). These instructions are typically machine code instructions for a physical CPU. Thus, when a C++ program is compiled, the user-readable programming language is transformed to computer-readable instructions.

OpenSim is a collection of executables and dynamically linked libraries (.dll). A C++ library is a collection of functions, constants, classes (see below) that are executable or callable at runt-time and supply the full range functionality to the application (like OpenSim). Libraries enable the same implementation for a given functionality (like reading data from a file) to be supplied to any application that links to it and is therefore more generally useful.

One of the main features of C++ is that it facilitates object-oriented programming. Rather than writing code in a potentially long sequence of executable lines, object-oriented programming allows the programmer to design applications from a point of view of communication between things, known as objects. The code consists of many objects, which all belong to certain classes. These classes interact with each other. This allows a greater reusability of code in a more logical and productive way.

Structure of the OpenSim API

OpenSim is written using object-oriented programming. It consists of a large set of classes. For example, each muscle in an OpenSim model is an object (an instantiation) of a certain muscle model class, eg 'Thelen2003Muscle', which is a member (child) of its parent class 'ActivationFiberLengthMuscle, which in turn is a member of the more general class 'Muscle', which in turn is a member of the more general class 'Actuator', etc.

You can view all classes and their hierarchical structure available in OpenSim using doxygen. This is an automatically generated overview of all available code. You can access doxygen either through your OpenSim installation directory, in the folder:  C:/OpenSim2.3.2/sdk/doc/index.html. If you click on index.html, you will see an overview of the OpenSim hierarchy. As an example, you could click on ModelComponent, which will give you a list of model components, all members of the general class ModelComponent. If you then click on Force, you will get a list of available force generators, etc.

The OpenSim API is built in turn on top of the Simbios "simulation toolkit" SimTK. More details about SimTK code can be found in SimTK Basics.

Using C++, you can interface with OpenSim's libraries and extend or add to them. This could mean that you can build your own class that OpenSim can use, eg. a new muscle model, which could be a child of the more general class 'Muscle'.  This means all the attributes of  Muscle are inherited by your new class and therefore you only need to specify the new or different functionality that defines the behavior of your muscle class. It could also mean that you build a standalone (Main) program that uses existing OpenSim classes, for example to run a simulation, as shown in Chapter 2.

You can also convert your new program to a plug-in, a software component that adds specific abilities to the general OpenSim software. Your plug-in will be a separate dynamically linked library (.dll on Windows), which you will be able to load into the GUI or into your main program or have it be used by different tools. An example of a plug-in is given in Adding New Functionality where an Analysis plug-in is made, and used from within the GUI.