- Quick Guide to Tracking
- Frequently Asked Questions
Don't be impatient!
Tracking animals in video is a very hard problem, even though it is very easy for the human eye. (This fact ought to teach us something about the evolution of our neural circuitry for vision.) Ctrax does its best, but it needs all the help you can give it. Ctrax is optimized to track adult fruit flies (D. melanogaster) walking in a non-varying, two-dimensional space, and any other conditions may result in widely varying outcomes.
This so-called "quick" guide gives the shortest sequence of steps required to achieve reliable tracking results.
- Design your arena to produce good (i.e., easily trackable) movies. Good movies are more likely to be produced in arenas that meet the following criteria:
- Flies' movements are constrained to two dimensions. This is not in any way optional. Flies cannot crawl up the walls or fly away. Best results are achieved by clipping the flies' wings and using heated walls to keep them in the center of the arena (though heated walls require an actively cooled floor). Simpler, alternate arena designs have been published, as well (see Simon and Dickinson, 2010 and White, et al., 2010).
- The background is static and consistently provides high luminance contrast with the flies' bodies. Note that standard incandescent (and fluorescent) lighting flickers at 50/60 Hz, yielding video frames that can vary in lighting quality and hinder automatic tracking. LED lighting is recommended, and in particular, infrared LEDs can be used to light the arena quite brightly without affecting the flies.
- All flies are approximately the same size and have a constant, elliptical shape. This is not an issue when tracking adult fruit flies (or cockroaches), but will result in tracking errors in videos of larvae or mixed species.
- Export the data for Matlab (File->Export as MAT-file).
- Download the Ctrax Matlab tools (you will also need the Matlab Image Processing Toolbox and the Matlab Statistics Toolbox). Install them by unzipping the tools file and copying the unzipped Matlab code to a known location.
- Run Matlab and add all of the Ctrax tools directories and subdirectories to your path.
- Type FixErrors to run the FixErrors GUI.
- In FixErrors, open the MAT-file you exported from Ctrax. It will prompt you for the number of camera pixels per millimeter, and the number of camera frames per second. If you don't know, it's best to enter 1 for both, and then your fly speeds will be in pixels/frame rather than mm/s.
- FixErrors will search for "suspicious" sequences of tracking data and give you tools to correct them. See the FixErrors GUI instructions for details on usage.
It's critical. The tracking algorithm will not work well or at all if flies regularly change shape (crawl up walls), change size (come closer to the camera), or occlude each other.
Ctrax will only read FlyMovieFormat (FMF) videos, FMF derivatives, and AVI videos which are either uncompressed or are readable by OpenCV. There are too many video formats for us to support them all, but there are free software packages on the Internet that will allow you to convert your movies to an AVI. See the detailed discussion of input video formats. We also provide the any2ufmf program to help converting AVI files to μFMFs, which are many times smaller and tracked equally well (and more quickly) by Ctrax.
If you have an uncompressed AVI video that Ctrax will not read, we may be able to help. Send an email to the Ctrax Google Group.
Several factors can influence how long Ctrax requires to process movies. To make it go faster, try the following:
- Decrease the frame rate. Every frame Ctrax tracks requires more time. The original publication used 20 frames per second, and results have been published with as few as 5 fps. Just don't go so low that Ctrax has difficulty telling which fly is which between frames.
- Make the tracking easier (see step 1 in the Quick Guide above). Good videos can easily track 2-3 times faster than bad videos. In addition, proper configuration of the tracking settings will improve both quality and speed.
- Decrease the video resolution. Larger frames take more time to load and process, and may not improve tracking quality. 4 pixels per millimeter is a reasonable benchmark.
- Track fewer flies. The relationship between the number of flies in a video and its processing time is sublinear but still significant.
- Decrease the display's refresh rate using the "rewind" button on the Ctrax window, or eliminate the display altogether by running Ctrax from the command line.
- Multi-core CPUs will not speed up Ctrax, but if you have sufficient RAM, you can use multiple instances of Ctrax to process different movies simultaneously on a multi-core machine.
Tracking rates of 1-2 frames per second on a circa-2009 computer are not unreasonable. Ctrax versions >= 0.4 are approximately twice as fast as earlier versions.
The Ctrax Matlab Toolboxes include scripts to parse an annotation file. The simplest method is to use load_tracks(), which returns a variable containing per-fly location information. See, for example, the sample code in the email thread discussing positional analysis.
Beyond simple positions, you also can use compute_perframe_stats() to calculate each fly's instantaneous velocity, angular velocity, sideslip magnitude, etc., etc.
If you want to parse an annotation file yourself, we also provide a description of the file format.
We have instructions on how to request more help via the community email list.