MTrackJ: Data File Format

It is possible to use MTrackJ for visualizing tracking results generated by your own (automated or interactive) tracking plugins. To this end, your plugins should write the tracks to a text file that can be loaded by MTrackJ.

The structure of an MTrackJ data file (.mdf) is extremely simple. The following is an example of a data file (there may be many more details in data files produced by MTrackJ itself, but these are not needed per se):

   MTrackJ 1.2.0 Data File
   Assembly 1
   Cluster 1
   Track 1
   Point 1 111.3 126.1 1.0 1.0 1.0
   Point 2 132.5 116.2 1.9 2.0 1.0
   Point 3 147.1 108.6 2.3 3.0 1.0
   Point 4 164.9 111.8 3.4 4.0 1.0
   Point 5 179.3 132.2 4.8 5.0 1.0
   Track 2
   Point 1 182.9 294.0 5.3 3.0 1.0
   Point 2 156.8 272.2 4.1 4.0 1.0
   Point 3 104.4 254.5 3.2 5.0 1.0
   Point 4 134.3 242.7 4.9 6.0 1.0
   Point 5 171.1 245.6 6.8 7.0 1.0
   Cluster 2
   Track 1
   Point 1 ...
   Point 2 ...
   Point 3 ...
   ...
   Track 2
   Point 1 ...
   Point 2 ...
   Point 3 ...
   ...
   End of MTrackJ Data File

The very first line indicates the type of file and contains the MTrackJ data file format version number (1.2.0 in this case). The second line indicates the start of the assembly of clusters of tracks in the file. Currently, the program supports only a single assembly (see also the description of the MTrackJ data structure to get the picture), but this line in the data file is nevertheless obligatory. The very last line indicates the end of the file.

Each cluster of tracks starts with a line of the form "Cluster ID". Each track of a cluster starts with a line of the form "Track ID". And each point of a track is a separate line of the form "Point ID x y z t c". Here, x and y are the image coordinates, which may run from 0 to N-1 (with N being the number of samples in either dimension of the image), and z, t, and c are, respectively, the slice, frame, and channel indices, which may run from 1 to N (in accordance with slice, frame, and channel indexing in ImageJ, with N being the number of slices, frames, or channels of the image). So in the case of 2D image sequences, z and c should be fixed to 1.

Note that all coordinate and index values in the file are allowed to be floating-point numbers (as in the above example). However, naturally, only floating-point x and y coordinate values can be used by MTrackJ to display point locations with subpixel precision (in zoomed images). As of version 1.2.0, floating-point z values are loaded as such, and used in the measurements, but are rounded to the nearest-integer slice index when displaying points. Floating-point t and c values are immediately rounded to the nearest-integer frame and channel indices at load time. Furthermore, since a track can be in a single channel only, the c index of every point of a track is set to the (rounded) c index of the first point at load time.

To simplify the use of MTrackJ in conjunction with your plugins, any of the following lines may be included in your plugin code (after the lines for saving the tracking results to the data file), which will automatically launch MTrackJ for the specified ImagePlus object and load the specified data file.

   // Launch MTrackJ for the ImagePlus with ID = -3:
   IJ.runPlugIn("MTrackJ_","-3");
   
   // Launch MTrackJ for the active ImagePlus and load mytracks.mdf:
   IJ.runPlugIn("MTrackJ_","mytracks.mdf");
   
   // Launch MTrackJ for the ImagePlus with ID = -3 and load mytracks.mdf:
   IJ.runPlugIn("MTrackJ_","-3,mytracks.mdf");