# SwisTrack/Using SwisTrack - an Introduction

SwisTrack uses a list of so-called components to process images. Each component is in charge of a specific processing step, e.g. image acquisition, background subtraction, thresholding, or blob detection. Getting the right result is a matter of putting the right components together - in the right order, of course. Each component can be configured, and SwisTrack provides a great interface to do this in real time, while showing all intermediate processing results.
This page tells you how to add and remove components, and how to configure them. If you want to know what components you should use for your task, have a look at the examples section. A reference of all components is available on the component list page.

## Main Window

The main window of SwisTrack consists of three parts:
* The main display in the center shows the current frame that is being processed. The frame can be displayed at (almost) all processing steps.
* The component list at the bottom shows the currently selected components and their status. At the right of this list, you'll find two buttons to add or remove components, and two buttons to change the order of the components.
* The configuration panel at the right allows you to configure the selected component.
In addition, SwisTrack shows a timeline at the very bottom of the window.

## Editing the Component List

To add a component, click the plus (+) button on the right of the component list. A dialog will appear and allow you to select a component. Note that the available components are grouped by their category, and you'll often need a component of each category, in the order the categories are listed here.
Components are added to the end of your component list. To move them up and down, use the arrow buttons on the right side. To remove the selected component, simply click on the minus (-) button.
The component list consists of several columns which indicate the type and the state of the component. Next to the name of the component, a few columns are filled with W's, E's and R's. Each of these columns corresponds to a channel (or a data structure), and the letters have the following meaning:
* W: The component is writing to this channel.
* E: The component is modifying (reading, then writing) this channel.
* R: The component reads from this channel, but doesn't change anything there.
Obviously, you first have to write something to a channel before you can read or modify it. Hence, if you look through each columns, all E's and R's should be below the W's. If this isn't the case, then you either forgot to add a component or placed the components in the wrong order.
In the column right after the component name, you may also see some T's. These components include a trigger mechanism (which may be active or not), i.e. they tell SwisTrack when to process the next frame. A setup must have at least one trigger.

## Configuring and Testing your Setup

Once your component list contains a valid setup, you can process one frame by pressing the Step button in the toolbar. This invokes each component in the order they are listed and displays the selected image (i.e. the output of the selected component). Once the frame is processed, the component list indicates the duration of each component, and perhaps error messages. (If you just added some components, it is quite likely that one or the other component will raise an error. You may have to configure them first.) Whenever an error occurs, SwisTrack stops the execution of the frame at that point and doesn't call the subsequent components.
When clicking on a component, SwisTrack displays its configuration panel on the right side of the window. You can now modify the settings and watch how this affects the image. Whenever you change a value, SwisTrack automatically performs a step - hence your modification becomes immediately visible on the screen.
As an advice, start at the top of your component list and configure the components in the order of execution. As the configuration heavily depends on component itself, refer to the online component documentation (link on the top of the configuration panel) for the meaning of each parameter.
While the Step button processes one frame, the Run button processes frames continuously. In run mode, the trigger components (those with a T next to their name) say when the next frame shall be processed. If you don't have any trigger component in your setup, add a Timer Trigger component to configure the processing speed.
Finally, the Reset button allows you to reset all components. Most of the time, SwisTrack finds out automatically when the setup must be restarted (especially when you change the configuration of a component), but there are cases where you want to do that explicitly. When you hit the Reset button, all components are adviced to completely reset their internal state and reload the configuration. This zeroes the frame counter and deletes the track history, for example.

## Running an Experiment

Once your setup is properly configured and working, you probably want to use it for your experiments. This is where the Productive button enters the game.
Before you start your experiment, activate the Productive button. This resets all components and starts them in productive mode. At the end of your experiment, simply hit the Productive button again to release it and switch back to testing mode.
Productive mode has two main differences as compared to testing mode:
* In productive mode, SwisTrack never resets the components automatically. Therefore, only a subset of the configuration parameters are available any more, namely those which do not change the processing completely. For example, you can still adjust the exposure time of a camera, but you cannot change from color to grayscale mode. In addition, it is not possible to add, remove or reorder components in productive mode.
* Output components only write data to the file during productive mode. Hence, your the files contain the data of your experiments only. (Some other components also make slight differences between testing and productive mode. Refer to the component documentation for details.)

## More Information

Now that you know the basics, you may want to have a closer look at the following chapters:
* The Timeline
* Configuration Examples
* List of all Components