FicTrac is an open-source software library for reconstructing the fictive path of an animal walking on a patterned sphere. The software is fast, flexible, easy to use, and simplifies the setup of closed-loop tracking experiments.
FicTrac was originally developed by researchers at the Queensland Brain Institute at the University of Queensland, Australia for tracking honeybees and fruit flies during closed-loop tethered walking experiments, but it has since proved useful for tracking a wide range of animals with different movement speeds, track ball diameters and patterns, and stimuli.
On this page you'll find information for:
- Getting started - including hardware requirements, and basic steps for installing, configuring, and running FicTrac.
- Research - including works to cite and links to the original FicTrac publication and preprint (pdf).
- Contributing - how to go about making your fixes, additions, and customisations available for other users.
- Re-use - licensing information, if you plan on using FicTrac or the source code.
You might also be interested in the following links:
- Demo video - Quick (30s) overview of what FicTrac does and how it works.
- FicTrac manual - Detailed instructions, description of output data, parameters, recommendations, etc.
- Homepage - Contact details for the main author/developer, links, and further info.
- Forum - Subreddit for faqs, support, advice, discussions, etc.
- Mailing list - Subscribe to receive important announcements and updates.
Happy tracking!
If you're just setting up your lab, or wondering whether FicTrac is suitable for your setup (spoiler: yes, probably), check the hardware requirements section below for the basic requirements.
If you already have an experimental enclosure with a camera, you can use FicTrac to either process recorded videos offline or to run live from the camera. Skip ahead to install, configure, and run FicTrac.
Very briefly, FicTrac imposes almost no special requirements on your experimental setup, other than that a pattern must be applied to the track ball. However, there are a number of tips that can help you get the best results from using FicTrac.
A typical FicTrac experimental setup might include at least the following equipment:
- Animal tether/harness - for keeping the animal stationary on the track ball
- Stimulus - sensory feedback for the animal
- Track ball support - structure to hold track ball in place whilst allowing free rotation
- Track ball - lightweight sphere that is rotated by the animal's walking/turning motions. Surface pattern should ideally be high-contrast, non-repeating, non-reflective (not glossy), and contain around 10~50 variously sized blobby shapes.
- Video camera - for monitoring the track ball (and animal). Resolution is not important, and for vertebrates a USB webcam is likely sufficient. For faster moving insects, the camera should support frame rates >100 Hz. In all cases, the frame rate, exposure, and lens should be chosen to ensure the track ball pattern is well-exposed under all lighting/stimulus conditions and that there is no motion blur during the fastest expected movements. At least one half of one hemisphere of the track ball surface should be visible by the camera.
- PC/laptop - for running FicTrac software (and generating closed-loop stimuli). Processor should be somewhat recent (>2 GHz, multi-core).
- Lighting - ambient lighting should be diffuse (no specular reflections from track ball surface) and bright enough to give good track ball surface exposure at chosen frame rate.
FicTrac imposes no requirements on the italicised items; how you design these is completely dependent on other factors.
The FicTrac source code can be built for both Windows and Ubuntu (Linux) operating systems. You can even build and run FicTrac from within a virtual machine on any operating system.
Note: If you plan on using a USB3 camera, FicTrac may have issues using the OpenCV capture interface. The work around is to tell FicTrac to use the SDK provided with your camera instead of OpenCV to do the frame grabbing. See USB3 camera installation.
- Download and install required dependencies:
- Cmake build system (binary distribution)
- OpenCV computer vision library (version 4.0.1 Win pack)
- NLopt optimisation library (precompiled DLL)
- Clone or download the FicTrac repository, then navigate to that folder, open a terminal, and create a build directory:
mkdir build
cd build
- Next, we will configure and build the FicTrac project. FicTrac is written in C++, so you'll need a suitable compiler. In this example we will use MSVS Build Tools. If you don't already have Visual Studio, you will need to install the build tools.
- Run Cmake to prepare the necessary build files for FicTrac. Here we also need to provide the paths to where we installed OpenCV and NLopt (I have given example paths here, you will need to modify them for your installation):
cmake -G "Visual Studio 15 2017 Win64" -D OPENCV_DIR="C:\path\to\opencv-4.0.1\build" -D NLOPT_DIR="C:\path\to\nlopt-2.4.2\" ..
- Finally, build and install FicTrac:
cmake --build . --config Release -j 4
If everything went well, the executables for FicTrac and a configuration utility will be placed under the bin directory in the FicTrac project folder.
- Install the required dependencies:
sudo apt-get install gcc cmake libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-dev libdc1394-22-dev libopencv-dev libnlopt-dev
- Clone or download the FicTrac repository, then navigate to that folder and create a build directory:
mkdir build
cd build
- Run Cmake to prepare the necessary build files for FicTrac (if OpenCV and NLopt are not installed in the default location, you can help Cmake find them by defining OPENCV_DIR and NLOPT_DIR - see Windows installation for an example):
cmake ..
- Finally, build and install FicTrac:
cmake --build . --config Release -- -j 4
If everything went well, the executables for FicTrac and a configuration utility will be placed under the bin directory in the FicTrac project folder.
If you are using a USB3 camera and are receiving error messages when FicTrac tries to connect to your camera, you may need to tell FicTrac to use the SDK provided with your camera, rather than the generic OpenCV interface. The instructions for switching to the camera's SDK are different for each manufacturer. Currently there is support for PGR (FLIR) USB3 cameras via the Spinnaker SDK.
- Download and install the latest Spinnaker (full) SDK from PGR downloads page.
- When preparing the build files for FicTrac using Cmake, you will need to specify to use Spinnaker using the switch
-D PGR_USB3=ONand depending on where you installed the SDK, you may also need to provide the SDK directory path using the switch-D PGR_DIR=.... For example, for a Windows installation you would replace step 4 with:
cmake -G "Visual Studio 15 2017 Win64" -D OPENCV_DIR="C:\path\to\opencv-3.4.2\build" -D NLOPT_DIR="C:\path\to\nlopt-2.4.2\" -D PGR_USB3=ON -D PGR_DIR="C:\path\to\Spinnaker" ..
- Follow the other build steps for either Windows or Ubuntu (Linux) as normal.
Before running FicTrac, you may configure your camera (frame rate, resolution, etc) as desired using the SDK utilities.
There are two necessary steps to configure FicTrac prior to running the program:
- You must provide a text file that contains important configuration parameters for your setup. At a minimum, this config file must define the parameters
src_fnandvfov, which define the image source (path to video file or camera index) and vertical field of view (in degrees) of your camera respectively. You will find an example config file in thesampledirectory. - You must run the interactive configuration program (configGui). This program will guide you through the configuration of the track ball region of interest within your input images and the transformation between the camera's and animal's frames of reference.
A more detailed guide on how to configure FicTrac for your setup and an explanation of all the configuration parameters can be found in the doc directory.
To configure FicTrac for the provided sample data, simply open a terminal in the FicTrac project folder and type:
cd sample
[Windows] ..\bin\Release\configGui.exe config.txt
[Linux] ../bin/configGui config.txt
The sample config file config.txt is already configured for the sample data, but you can step through the configuration process to check that everything looks ok.
Then, to run FicTrac, type:
[Windows] ..\bin\Release\fictrac.exe config.txt
[Linux] sudo ../bin/fictrac config.txt
FicTrac will usually generate two output files:
- Log file (*.log) - containing debugging information about FicTrac's execution.
- Data file (*.dat) - containing output data. See data_header for information about output data.
The output data file can be used for offline processing. To use FicTrac within a closed-loop setup (to provide real-time feedback for stimuli), you should configure FicTrac to output data via a socket (IP address/port) in real-time. To do this, just set out_port to a valid port number in the config file. There is an example Python script for receiving data via sockets in the scripts directory.
Note: If you encounter issues trying to generate output videos (i.e. save_raw or save_debug), you might try changing the default video codec via vid_codec - see config params for details. If you receive an error about a missing H264 library, you can download the necessary library (i.e. OpenCV 4.0.1 requires openh264-1.8.0-win64.dll) from the above link and place it in the dll folder under the FicTrac main directory. You will then need to re-run the appropriate cmake .. and cmake --build commands for your installation.
If you use FicTrac as part of your research, please cite the original FicTrac publication:
RJD Moore, GJ Taylor, AC Paulk, T Pearson, B van Swinderen, MV Srinivasan (2014). "FicTrac: a visual method for tracking spherical motion and generating fictive animal paths", Journal of Neuroscience Methods, Volume 225, 30th March 2014, Pages 106-119. [J. Neuroscience Methods link] [Preprint (pdf) link]
This publication contains technical details on how FicTrac works, performance analysis, results, and other discussion.
If you have modified the FicTrac source code to fix issues, add functionality, or to better suit your setup, please consider making those additions available to other users!
To do so, just follow the standard Github fork and pull request workflow.
See the LICENSE file for more info.