 |
Ctrax Installation |
|
Ctrax Installation |
Ctrax is Python-based, and it and all dependent software are open-source and (somewhat) platform-independent. A description of the computer hardware and software requirements for Ctrax is given in Computer and Software Requirements. Usage instructions are given at Ctrax Usage. An overview of the video and physical arena requirements is given in Arena and Video Requirements.
Ctrax has been installed and tested on 32- and 64-bit Windows, 64-bit Mac OS, and 32- and 64-bit Linux systems. As it is written in Python and Python is a platform-independent language, it conceivably can be run on other platforms as well. Installation instructions are at Ctrax Installation. Memory usage is not demanding for reasonably short videos -- all that is needed is enough memory to store the ellipse fit for each fly in each frame. Ctrax will run faster on faster computers, but has no minimal speed requirements.
All of our published data were derived from Fly Movie Format (FMF) and Static Background Fly Movie Format (SBFMF) videos.
The AVI container is rather poorly defined, and the built-in AVI reader for Ctrax has only been tested with the uncompressed AVIs output by Matlab, mencoder (Linux or Mac), and VirtualDub (Windows). These videos can be highly compressed without affecting Ctrax by converting them to UFMF format using any2ufmf.
To convert any movie type to an uncompressed AVI using VirtualDub:
To convert any movie type to an uncompressed AVI using mencoder, use the following command:
mencoder compressedmovie.avi -o uncompressedmovie.avi -vf format=rgb24 -ovc raw -nosound
Currently, the tracker converts the RGB video into grayscale, ignoring all hue information.
A user sent in the following notes on installing FFmpeg on Mac OS X:
For downloading ffmpegx, you also have to download a couple other components that don't come bundled because of the open-sourceness of this all. They are linked on the ffmpegx install page. For this component: mpeg2enc.intel, this website: http://mjpeg.sourceforge.net/MacOS/ will take you to a download page, but to download pre-compiled software, you can't download it directly (if you click the link it goes to awful html crap), you have to do option + click to download it, and that only works in Safari, not Firefox.
As of version 0.5.0, Ctrax uses OpenCV (version 2.4.8) to read many types of movie files and codecs. The codecs supported by OpenCV depend on your platform (Windows/Mac/Linux).
While Ctrax may be able to read a given file format, it may not be able to successfully track the flies if video compression degrades the image quality. It has been reported that M-JPEG compressed movies, as output by Avidemux, still provide good tracking, but this may not be true for all M-JPEG configurations and video capture conditions.
Motmot's Fly Movie Format (FMF) is the uncompressed movie format output by fview, the program we use to capture uncompressed, high-resolution, high-frame-rate video in our labs.
Static Background Fly Movie Format (SBFMF) is a compressed video format designed to work well with background-subtraction-based tracking algorithms. It stores the static background model for the entire video, then only the pixel intensities and locations for those pixels in a frame that are sufficiently different from the background model. Using this format, we have achieved 100x compression without affecting tracking results. Ctrax can optionally output an SBFMF while tracking so that this smaller file can be stored and transferred instead of the original, uncompressed video.
The UFMF format is similar to SBFMF (above), but can be saved in real time by fview. We also provide the any2ufmf program to assist in converting AVI videos to UFMF. These videos can be 100x smaller than the original AVIs and are tracked equally well by Ctrax.
25 female and 25 male wild-type flies in a 24.5 cm-diameter open arena. Video is recorded at 20 fps in near-infrared; hence, the flies appear as white specks on a black background. Flies are approximately 8 pixels in length. Their wings have been clipped to keep them from flying, and a heat barrier restricts them from climbing the arena walls.
A description of the tracking algorithm and the apparatuses we used it with is given in the article "High-Throughput Ethomics in Large Groups of Drosophila". Here, we discuss briefly the assumptions made by the algorithm, and the constraints they put on the physical arena setup. Here are links to videos of tracking results in our two arena types:
Please contact Kristin Branson if you have successfully applied Ctrax in your experimental set-up and have a video to share.
14 male fruitless flies in a 5 in-diameter chamber with glass top. Video is recorded at 20 fps in the visible spectrum, and flies appear as black specks on a white background. Flies are approximately 17.5 pixels in length. Their wings have not been clipped.
Ctrax is based on background subtraction. It estimates a static model of what the arena looks like without flies, then classifies pixels in each frame as foreground (belonging to a fly) or background (belonging to the arena) based on the difference between the current frame and the background model. Thus, there must not be anything moving or changing appearance in the video other than the flies [note: using the Ctrax GUI, the user can specify pixel locations to ignore changes in and always classify as background, relaxing this assumption slightly]. Incandescent lights flickering at 60 Hz, for example, can cause big changes in background appearance, and Ctrax is not robust to this type of noise. Poor camera quality and video compression can also cause changes in the background appearance. We repeat: video compression artifacts that are unnoticeable to the human eye can have huge effects on background subtraction and tracking. At this point, we advocate recording video in uncompressed format, then simultaneously compressing and tracking using the Static Background Fly Movie Format (SBFMF), which in our setup achieves 100x compression without affecting tracking performance (see below). We also provide the any2ufmf program to convert AVI movies to Micro Fly Movie Format, very similar to SBFMF.
Ctrax also performs better if the flies are significantly different-looking from the background; thus, large amounts of light are preferable, particularly at higher shutter speeds. We record in near-infrared (IR), as flooding the arena with IR light does not affect the flies' behavior. We have experimented with front-lit flies on a black background (so the flies appear as white specks on a black surround) and back-lit flies on a white background (so the flies appear as black specks on a white background). See the example movies.
To keep track of identities, Ctrax relies on the flies moving with an approximately constant velocity. Given the previous two positions of each fly, it predicts that fly's position in the current frame. It matches predicted positions to observed positions so as to best obey the constant-velocity assumption. In general, we've found that this assumption is obeyed by walking flies at 20 fps (we have not tried slower frame rates, though White, et al. were able to track at 5 fps). Problems with the assumption only occur when two flies jump in close proximity to each other.
After subtracting the background, leftover pixels are called "foreground". Foreground pixels that are adjacent to each other are called connected components. Usually, each connected component of foreground pixels corresponds to exactly one fly. If two flies are touching, they will be detected as a single connected component. More rarely, two separate areas of connected foreground pixels might be part of the same fly. Ctrax uses the expected size of a fly to decide whether to merge or split connected components, and again to decide how many flies a large component probably contains. Mistakes are not uncommon when choosing the number of flies to split a large component into, as well as when choosing which pixels of a component belong to which fly. There is an added step of logic called the hindsight step which tries to avoid the births and deaths of trajectories by fixing potential errors in this part of the algorithm. It relies on the splitting steps being correct in most of the frames, and only occasionally incorrect. If the flies spend long periods of time clustered in large, tight groups, then there is the chance that too many mistakes will be made to fix during the hindsight step.
The hindsight step mentioned above tries to fix errors made in other parts of the algorithm to avoid new trajectories being born or trajectories dying in the middle of the video. This is based on the assumption that flies rarely enter or leave the arena. The hindsight logic can be disabled if flies commonly leave or enter the arena, but performance is better in a closed-world setup with the hindsight logic enabled.
Ctrax is written in Python and depends only on other open-source projects, and thus can theoretically be installed on all platforms. For Windows and Mac OS X, we have developed easy-to-use installers. For Ubuntu Linux, we have developed Debian packages. For other systems, Ctrax must be installed from source, in addition to the packages Ctrax builds upon.
For Windows systems, we have developed a downloadable Windows Installer. Run the installer to install Ctrax to your Desktop and/or Start Menu. Ctrax can then be launched by double-clicking the Ctrax icon on the Desktop or selecting Ctrax from the Start Menu.
Ctrax requires Windows 7 or later.
For Mac OS X systems, we have developed a downloadable Mac OS X Installer. Run the installer package to install Ctrax to your Applications folder. Ctrax can then be launched from your Applications menu.
Ctrax requires Mac OS X 10.6 (Snow Leopard) or later. In OS X 10.8 (Mountain Lion) and higher, running Ctrax may require installing the XQuartz package, which Apple used to include with the operating system but no longer does.
For Ubuntu Linux systems, we have developed Debian packages containing pre-compiled versions of Ctrax for 32- and 64-bit architectures. These are distributed from the Ctrax PPA Repository.
To install, you must add both the Ctrax PPA and the Straw Lab's repository to your sources list and then install the package python-ctrax. Subsequently, you can run Ctrax from the command line by typing Ctrax. From the command line, this sequence of commands should install and run Ctrax under Ubuntu Xenial or Yakkety:
wget -q http://debs.strawlab.org/astraw-archive-keyring.gpg -O - | sudo apt-key add - sudo sh -c 'echo "deb http://debs.strawlab.org/ xenial/" >> \ /etc/apt/sources.list.d/strawlab_public.list' sudo sh -c 'echo "deb-src http://debs.strawlab.org/ xenial/" >> \ /etc/apt/sources.list.d/strawlab_public.list' sudo add-apt-repository ppa:ctrax/ppa sudo apt-get update sudo apt-get install python-ctrax python-matplotlib python-opencv Ctrax
For some mysterious reason, python-matplotlib has to be specified as above, otherwise it will not install automatically. If pieces of the Straw Lab's Motmot toolkit do not install correctly, installing the python-motmot-fview package should retrieve them.
Ctrax can be installed directly from source on any architecture, as long as the Ctrax Python dependencies and a C++ compiler like gcc can also be installed on that machine. To automatically download, build, and install from the Python Package Index, you might be able to simply run pip install Ctrax or easy_install Ctrax, although these options have not been tested much.
The source code for Ctrax can be downloaded per se from Sourceforge or PyPI. Uncompress the archive, change into the downloaded source directory, and run the command python setup.py build to compile the code and sudo python setup.py install to install Ctrax. It can then be run from the command line with the command Ctrax.
Alternately, the latest development version can be retrieved following the Subversion instructions on Sourceforge, then built as above.
Ctrax depends on the following Python packages:
The easy way to install all of these dependencies in Ubuntu Linux, in order to build Ctrax from source, is to type these commands at the command line before building Ctrax as above:
sudo apt-get install python-wxgtk2.8 python-scipy python-imaging \ python-opencv python-matplotlib cython python-dev wget http://debs.strawlab.org/astraw-archive-keyring.gpg -O | sudo apt-key add - sudo sh -c 'echo "deb http://debs.strawlab.org/ precise/" >> \ /etc/apt/sources.list.d/strawlab_public.list' sudo sh -c 'echo "deb-src http://debs.strawlab.org/ precise/" >> \ /etc/apt/sources.list.d/strawlab_public.list' sudo apt-get update sudo apt-get install python-motmot-wxvideo python-motmot-wxvalidatedtext
Within the source bundle, there are extra instructions and notes specifically for building Ctrax from source under Windows. Look in the docs/Installing_Ctrax_on_Windows_from_source.txt file and the py2exe/maintain/howtomakeexe.txt file.
Within the source bundle, there are extra instructions and notes specifically for building Ctrax from source under Mac OS X. Look in the docs/mac-install-notes.txt file.
The FixErrors GUI is written in Matlab, and requires Matlab version >= 2009b. Licenses for the Matlab Image Processing Toolbox and the Matlab Statistics Toolbox are also necessary.
The BehavioralMicroarray toolbox has been tested with Matlab version >= 2009b. A license for the Matlab Statistics Toolbox is required.
FixErrors and BehavioralMicroarray rely on a common library of Matlab helper functions. If you plan to use both the FixErrors Matlab GUI and the BehavioralMicroarray Matlab Toolbox, download the latest release of all the Matlab code for the Ctrax Matlab Toolboxes Latest Release.
The functionality of the FixErrors GUI is described at FixErrors Usage. To run the GUI:
The functions/scripts of interest in the BehavioralMicroarray Toolbox are described at BehavioralMicroarray Usage. To run any of these: