Getting Started.
Since the initial design and implementation of Motris was carried out within the harsh time constraints of a diploma thesis, there are still some usability pitfalls for the unwary user that were not ironed out. Most of these manifest as data dependencies not immedeately obvious to a user not well versed in the source code. This document is meant as a guide around most of these pitfalls and as a short reference.
The basic working unit in Motris is called 'Experiment'. After starting the program, the default window allows you to manage experiments. An experiment is comprised of a set of configuration data and possibly action scripts (for non-interactive experiments). For version 1.0, experiment data consists mainly of the three following items:

Image sequence data settings.
  • Filename Mask:
enter the filename of image files, replacing the numerals of the frame number with '#'.
ex.: p_####.pgm is valid for images from p_0000.pgm to p_9999.pgm
  • Camera Parameter Filename:
Enter the path and filename of a camera parameter file. File must be plaintext, in following format:
The first line contains the translation vector, i.e. the origin of the global coordinate system in camera coordinates.
The second to fourth line contains the rotational matrix describing the transformation from global to camera coordinates.
The following lines must contain the listed values (one per line):
focal length in x direction,
focal length in y direction,
principal point x coordinate,
principal point y coordinate,
shadow intensity,
light source azimuth,
light source polar.

Unfortunately, there is no option to edit or view the camera parameters in the program, yet.
  • Interlaced
Check this option if an image file contains two interlaced images. Some algorithms (optical flow calculation & derivative calculation) use different convolution masks for interlaced images.
  • Interpolate Interlaced Image
If the image sequence is interlaced, checking this option will keep the image resolution unchanged; the missing lines will be copied from one of the adjoining ones. If you intend to use optical flow or derivative calculation, this option is required, due to missing mask size adaptions.
  • First Row = First Half frame
This option is currently not in use. It is present in the current system due to compatibility issues in the past, and will be reused in a future revision of the data managing system.

Actor settings.
Actors encapsulate everything concerning trackable models, i.e. volumetric descriptions, state, dynamic model, etc. Actors are typically read from .xml files. It is important to understand the order of events when loading actors, since there is plenty of room for misunderstanding. After the .xml file is read, the extracted parameters are merged with the default parameters, with conflicting extracted parameters overriding the default ones. The resulting parameter set is used to build the actor starting with partial models, in the process adding parameters labeled "FREEPARAMETER" to the actor state (provided they do not already exist). Also, a new tracker with default tracking parameters is added for each actor.

Examples of .xml files describing actors can be found in various subdirectories of the 'experiments/' directory. However, many of these files can only be loaded in conjunction with a set of specific default parameters, since they lack several important parameters.

After loading an actor, actor properties can be accessed via the toolbar button "Actor settings". The actor properties consist of two main categories, state variables and internal (positional and volumetric) parameters. There are also the following general settings:
  • Which edges are visible
controls which edges of the polygonal model are considered to be visible. This setting controls global visibility, i.e. graphical output is affected as well as all algorithms that depend on model edges.
  • Add shadow edges
adds an additional rectangular shadow polygon below the model. Exact position and shape depends on the volumetric model and the illumination settings in the camera parameter file. Also, some volume types do not support shadows yet.
  •  XTrack Vehicle Reference Number
It is possible to import models from the program XTrack, also used at the IAKS.
  • Reference point in middle of car
This is relevant for car models that use the dynamic model of Schwarz. This model assumes the model origin to be located on the center of the front axis. All other implemented car models place the origin centered equidistant from the axes. To use Schwarz' calculations with these models, adjusting terms must be added.
The state variable category is rather straightforward: it contains the variables of the state vector for the current time and - if present - the stored state for arbitrary frame numbers.
The internal parameters contain the volume parameters and the FIXED positional parameters for each partial model. The positional parameters describe the transformation from the partial model's coordinate system to that of its parent. Note: The fixed parameters are not necessarily named. For example, the orientation angle of most car models corresponds to a rotation about the z-axis in matrix terms, so the remaining fixed rotation parameters are "Pitch" and "Yaw".

Algorithm settings.
The algorithm settings contain several different loosely related categories of settings. These categories will be split accordingly in a future release.

The first category consists of default values.

  • The default actor parameters are used when loading an actor to set default parameters for that actor. Only parameters that were not specified in the actor file are affected;
  • The default tracking parameters are used to initialize trackers for newly loaded actors.

The second category consists of data source configuration. Internally, algorithms can request different data (edge elements, optical flow, etc) from a central data manager. The parameters required to calculate this data are set in the algorithm settings. The following algorithms are currently available:
  • Derivative image
  • Optical Flow image
  • Edge elements
  • Edge element assignment (Edge element adaption)
The third category is actually a subcategory of the default tracking settings and the tracking settings for individual actors:
The actual algorithm to track actors can be selected and, in the respective submenu, configured. So far, every implemented tracking algorithm is a residual minimization problem, and it is possible to select a minimization algorithm as well. The start and stop frame numbers for tracking are used for non-interactive tracking only. Setting these to valid values will cause an immediate execution of the tracking algorithm for all selected frames. It is recommended to use the toolbar buttons in the tracking toolbar instead, unless you want to schedule lengthy experiments.

Using Motris.
There are two main ways to work with Motris. To run Motris non-interactively, it is possible to execute experiment control files ( see /doc directory). These contain the filenames of image sequence data, actors, and algorithm settings and a number of control statements. Running a control file will then automatically set up and run an experiment. However, it is not (yet) possible to do an automated partial save of the results and purge the saved data from memory, so very large experiments might fail due to memory constraints.

Most of the time, Motris will run in interactive mode. After successfully loading the three main components of an experiment, the tracking bar can be used to track interactively. The Buttons in the tracking bar are (from left to right, may wrap to next line):
Algorithm settings (document with a hand)
Predict (\hat{x}^- : In standard terminology of the IAKS, x is the actor state, \hat{x} is the estimated actor state, and the "-" designates this as an "a-priori" state)
Track (\hat{x}^+ : "+" designates an "a-posteriori" state)
Load actor state ( box with an arrow pointing down on it)

If no automation features are used, manual tracking requires the following actions:
  1. switch to the next image, either using the "next image" button, entering the next frame number, or using the slider.
  2. predict the actor state by pressing the Predict button. This will cause the state vector to be updated according to the dynamic model (for example, position will update according to orientation and velocity, etc.)
  3. run the assigned tracker for one frame by pressing the Track button.
This adapts the current state, but does not store it. To store tracking results, the Track button has a drop down menu with the option "Store tracking results". If this checkbox is activated, the post-tracking state will be stored in a separate entry in the actor properties. These steps can be automated for several frames by using the shortcuts "Track 10/100 Frames" in the settings menu. The stored tracking results can be recalled to the current state by pressing the load actor button.

There are two checkbox options that refer to a changing of the current frame number:
The recalling of stored states can be automated by checking the "Automatically load actor state when time changes" checkbox in the dropdown menu of the load state button. This allows easy browsing of results. However, this checkbox should not be activated while automatically tracking. If there are existing stored states, they will interfere with the current tracking.
The other checkbox is located in the dropdown menu of the Predict button. If "Always predict if frame no changes" is checked, step 2 of manual tracking must be omitted (and browsing the image sequence is not advised).