Quick Guide to Tracking
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.
- See step 1. Don't skip it. You can go ahead and try tracking poor videos, but you'll have only yourself to blame.
- Download and install Ctrax for Windows, Ctrax for Mac or Ctrax for Ubuntu Linux (or follow the Linux repository instructions). You can also install from source, but in that case, you probably need the full installation instructions.
- Open a trackable video. The most common are probably AVI movies, but there are other options. Note that virtually all video compression codecs lose data, meaning that tracking results may be affected negatively.
- Run the Tracking Wizard (Track->Tracking Wizard). The wizard will guide you through configuring the most common and important settings. There are many additional settings available through the Settings menu, as well.
- Before analyzing the data, fix the inevitable tracking errors. Rather than fixing them, it is faster in the long run to prevent tracking errors by using a better arena setup or altering some of the myriad tracking parameters. However, some number of errors will always remain.
- 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.
- Analyze your data further in the environment of your choice. We provide the BehavioralMicroarray Toolbox for Matlab and additionally recommend the JAABA tools. Of course, there is a wide spectrum of other Matlab analysis tools available, and Matlab data can be exported into other formats, as well.
Frequently Asked Questions
How important is it that the arena be 2D?
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.
Why won't Ctrax read my movie?
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.
Can I speed Ctrax up?
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.
How do I access the raw data on fly movements?
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.
I have a question that isn't answered here. Can I get help?
We have instructions on how to request more help via the community email list.