This webpage has all the information needed to run our tracking program, as described in the paper "A generative statistical model for tracking multiple smooth trajectories", which can can be obtained here. We provide two different tracking programs, a Gibbs tracker and a MCMCDA tracker, called gibbs_tracker and mcmcda_tracker, respectively. Of the two, the Gibbs tracker performed better in our tests and, consequently, we recommend its use over the MCMCDA tracker, and focus on it for the remainder of this document.
The tracker has a standard command line interface (CLI). If you are not familiar with command line programs, please read the following section. Otherwise, you may skip it and go directly to "Getting started".
In a CLI, users interact with the terminal (also called shell) by typing in commands, which are nothing but file paths of software programs. The command line interface thus consists of a user calling programs by typing in their paths as 'commands' and hitting the ENTER key. For example, we can call the program called "ls" -- which stands for "list" -- by typing in its path and hitting ENTER:
When called in this way, the this particular program simply lists the files and directories in the current directory. Most programs calls may also receive arguments which modify their behavior. For example, we can call the "ls" program with an argument
and it will list the files and directories contained in the directory /lib. Some arguments are known as "options", and are usually given by words or letters preceeded by one ore two hyphens. For example
tells "ls" to list the files and directories in /bin in "long format". If you run this, you will notice a difference in how the output is presented.
For convenience, most shells have a concept of a PATH variable, which contains paths in which the shell will look for programs when only a name is specified. For example, you may have noticed that you can call the "ls" program without specifying its full path:
The reason this works is that the directory /bin is in the PATH variable, and the shell will automatically look for any program you call in that directory. The benefits of this are obvious: one need not memorize nor type in the full path of a program every time it needs to be called. Another convienent feature of shells is the concept of a working directory. When in a terminal session, the user is always "in" a directory, called the (current) working directory. You can always show the current working directory by calling the "pwd" program (which stands for "print working directory"). To change the working directory, we use the "cd" command with the new directory as an argument, e.g.
would set the working directory to /var/www (thus, calling "pwd" would output "/var/www"). In this way, if we wanted to call a program with path /path/to/some/program, we could either type in the whole path as before, or use two commands:
Notice the leading "." in the call to "program". It stands for the current working directory, and can be used anytime we are specifying a path. To use a previous example, listing the contents of /bin can be accomplished in two ways: the one shown above, and using relative path specification:
The final "." here is telling "ls" to list the files in the current working directory (which is /bin, and which happens to contain the "ls" program).
The first you need to do is get the program. In this directory there are links to binaries for several different architectures. Click on the appropriate one and download the necessary binaries. After putting the executables in an adequate location, you must give execute permissions to at least your user. You can accomplish this using the "chmod" command, as follows:
Repeat this call for any other binary you have downloaded.
Although we usually run trackers on image data, our tracker actually operates on input point measurements. These point measurements are either in 2D or 3D, and may come from any kind of data, including images. The tracker then attempts to find the best association of the given points, thereby generating tracks. The tracker expects these points in a certain, very simple, format. There must be one file per time-step (frame) that contains the coordinates of the points, one per line. For example, the two files
could represent measurements in two time-steps, where time-step 1 contains three measurements and time-step 2 contains two measurements (in 2D). As mentioned above, there should be one such file for each frame. The tracker is then called and given as input these points in the form of a list of files via command line parameters. The file names should be given in order of ascending time; perhaps the easiest way to do it is using wild cards, i.e.
where OPTIONS is a place-holder for the command line options, described below.
For convenience, we provide a tool for finding these points in certain types of images. At the moment, this tool -- called find_points -- works best with GFP confocal microscope pollen tube data. We are in the midst of creating a much more generic and robust tool for finding points in images.
We also provide the image data used in the paper. For convenience, we also provide the extracted points files for each of the videos. That is, we provide the output of the point-finding program on the pollen-tube images described in the paper. Both of these items are available for download here.
As mentioned above, our tracker program has a command line interface. One calls it by invoking the program on the desired input, with the desired options. One of those options is "--help", which lists and describes the possible options to the program. Giving --help to the program generates the following:
The arguments to the tracking program can be separated into two categories: program parameters and algorithm parameters. The program arguments are quite self-explanatory and are very easy to set. In contrast, the algorithm parameters take some time to get used to and can be a little tricky to set. Here is a brief description of those parameters, along with reasonable ranges for most applications.
| d-bar | Number of time-steps targets are allowed to be missing (consecutively). Usual values range between 2 and 6. |
| v-bar | Maximum velocity of targets; units are in relative coordinates per time step (e.g., a value of 0.5 indicates a velocity of 0.5 the size of the image per time step). Usual values range between 0.01 and 0.15. |
| gp-noise-sigma | Variance of detector noise process. This parameter models the small gaps between detected points and the inferred tracks. In relative terms, a larger value means that a detection may deviate farther from the center of its 'true' track. The units are relative coordinates (like v-bar). Note that this parameter does not model stray, outlier spots on the image. Low values -- around 0.001 -- work reasonably well. |
| gp-scale | Scale of smoothness of the motion model. Larger values create smoother tracks; i.e., tracks with less and less abrupt changes. Reasonable values are between 5 and 20. |
| p-z | Probability of death of a target -- at each time-step, each target stops existing with this probability and persists with its complmenet (1 - p-z). Usually ranges between 0.1 and 0.4. |
| lambda-b | Birth rate of targets, in births per time-step; i.e., each time-step will see (on average) this many tracks begin to exist. This usually ranges between 0.6 and 0.9. |
| p-d | Probability of detection of targets -- at each time-step, each target is detected with this probability. Values in 0.8-0.99 work well. |
| lambda-f | Rate of false alarms per time step. At each time-step, on aveage this many spurious measurements will appear. Values between 0.1 and 0.5 work well here. |
Let's see an example. Assume that we have our point measurements in files names points_t01, points_t02, ..., points_t50, located in directory /path/to/input. Assuming we want our output file to be in /path/to/output, and we want the following set of options, we would call the program in the following way.
A final note: if you want to use the mcmcda_tracker, simply replace the program name with mcmcda_tracker; the options can be looked up using the --help option.
The output of the program is a file that contains information about the association of data points. This file is not human-readable, and is output only for the purposes of recreating the output of the tracker. The path to this file is taken from the option --output-file (see --help). In addition to this file, the tracker outputs a set of files, one per track found, with their position at each time step in which they exist. For example, the file
represents a 2D track that lasts from frame 51 to frame 54, whose positions are given by the points shown. These files will be created in the same directory which contains the output file, under a directory called "tracks"; the file names will be track_001, track_002, ..., track_NNN, where NNN is the last track found. Evidently, these files are human readable and their format is meant to be so simple that writing a program or script to automatically process them is an easy task.
For question or comments, please contact Ernesto Brau (ernesto@cs.arizona.edu) or Kobus Barnard (kobus@sista.arizona.edu).