SwisTrack/Developers/Implementing a new component

SwisTrack is component-based, i.e. processing an image is a matter of calling a series of (well-configured) components in a certain order. If you have an application which requires special image processing, you are welcome to write your own component. Writing a component for SwisTrack has many advantages over writing your own program:

• You can use existing components for all task that are not special to your application. Even if you need to implement a very special algorithm, you can most probably use camera components to acquire images.
• SwisTrack provides you with a GUI which allows you to easily visualize the result (and even intermediate steps) of your processing.
• SwisTrack allows you measure the performance of your algorithm, by measuring how much time was consumed by your component and allowing you to set lap times.
• Last but not least, you can easily share your components with other SwisTrack users.

Before Implementing a Component

Before implementing a component, think about the individual steps of your algorithm. If you can split your image processing algorithm into different parts, some of the tasks might already by implemented by existing components. Sometimes it makes sense to split your algorithm into two or more components. This can ease the configuration and provide a better insight into the structure of the algorithm. For a first implementation, however, the simplest approach is to start with a single component. This page therefore sticks to the implementation of one component.

Core Data Structures

Data is passed between components using the SwisTrackCore class. It has data structures to hold tracks, particles and images. Each component in the pipeline updates these data structures directly, usually by resetting the pointer to use the one in its own class instance.

Tracks are stored in two data structures: SwisTrackCore::mDataStructureTracks and SwisTrackCore::mDataStructureParticles. mDataStructureTracks stores a window of the last 50 points of the track, for drawing and computing. mDataStructureParticles is the output from the blob finder, and stores the particles for the current frame, along with their track association, and their location in the real world.

Creating a New Component

We describe here how to proceed to create a new component called "MyFavoriteAlgorithm". Of course, you are free to choose another name for your component (and we even suggest to do so). We will proceed in three steps to create the new component: Creating and registering a new component class, implementing the algorithm, and creating a configuration file.

1. Creating and Registering a New Component Class

1. Make a copy of the files code/core/ComponentTemplate.cpp and code/core/ComponentTemplate.h. Give your new files the name ComponentMyFavoriteAlgorithm.cpp and ComponentMyFavoriteAlgorithm.h. (Note that if an existing component does something similar to what you want to implement, you may also copy that existing component instead of copying the more general template component.)
2. Open these two files and replace "Template" (case-sensitive) by "MyFavoriteAlgorithm".
3. Make sure you also change the component name that is initialized in the constructor.
4. Open the file SwisTrackCore.cpp and add your component to the include files, i.e.

#include "ComponentMyFavoriteAlgorithm.h"

and to the list of available components in the constructor:

mAvailableComponents.push_back(new ComponentMyFavoriteAlgorithm(this));

Finally, generate an XML file in the "components" directory where the SwisTrack GUI resides that describes your component and its parameters. Use the components that are already there as a template.

If you compile and run SwisTrack now, you should be able to add your new component to processing pipeline.

2. Implementing the Algorithm

1. Constructor: data structure relations.

1. Implement the OnStart() method.
2. Implement the OnReloadConfiguration() method.
3. Implement the OnStep() method.
4. Implement the OnStepCleanup() method.
5. Implement the OnStop() method.

3. Creating a Configuration file

1. Copy the file SwisTrackEnvironment/Components/Template.xml and name your new file MyNewComponent.xml.
2. Open this file in a text editor (preferable XML-capable) and replace the title, description and URL of the component.

More to come ...