The TopoWatch Project
About TopoWatch

TopoWatch is an open source freezing detection software for automated fear conditioning. TopoWatch can analyze video streams in several formats (MPEG-4) and trace the freezing behavior of the of the observed animal (tested on mice). TopoWatch requires the camera to be steady (it doesn't work if the camera moves during the experiment). The software is capable of exploiting multicore architecture up to N cores.

TopoWatch uses the FFMPEG library for video encoding, that means it can support all the video formats FFMPEG supports (AVI, MPEG-4, etc...). TopoWatch is available for both Linux and Windows.



Open a video file using the "Open" button. If TopoWatch recognize the file format the first frame of the stream will be displayed in the left frame. Use your mouse to select the "area of interest". First click on the left-up corner and later click on the bottom-right corner, a green rectangle will be drawn. The rectangle represent the area that will be monitored by TopoWatch to detect the freezing behavior.
(The area can be changed during the simulation as well)

To start the simulation just click the "Execute" button. When the simulation is running, a red rectangle will be drawn around the moving objects. The precision of the motion detection algorithm depends on a couple of variables which can be manually configured when the simulation is running. The "background-to-mouse threshold" measures the sensibility of the mouse detector (because the contrast between the background and the moving object can be different). This threshold decides what is background and what is not and changing that value changes the size of the red rectangle that encloses the mouse. A value that completely wraps the mouse should be detected for each video (it depends on the quality of the video, background and light used).
B2M Threshold = 100
B2M Threshold = 40
The "Mouse Color" should be set to the appropriate vale, when the mouse is dark select "black", otherwise "white". The "Noise Level" value depends on the quality of the input stream and the compression used. This value can be used to cancel that noise. The right frame of the application shows the result of the difference between the stream frames. When a low level of noise is chosen, the noise level increases on the right frame and the motion detection is more sensible.

The "Noise Level" value is strictly related to the "Freezing Threshold". This value express the minimum number of pixels that must be change between two successive frames to do not consider the behavior as freezing. The number of pixel that changes between two successive frames is related to the noise level (the noise due to the video compression should be properly cancelled using an appropriate value of Noise Level). During the video analysis, the detected freezing should be visualized on the right side of the window indicating when it starts and the end. The list can be exported as CSV (comma separated values) file using the "Export Data" button (CSV files can be easily imported into OpenOffice Calc or Microsoft Office Excel).

News & Releases


Current realese of TopoWatch is 0.3

# 0.3

  • "Advanced"->"Number of Cores": Possibility to specify the number of available cores
  • Selection of the valid (green) area: It is possible to specify which is the area TopoWatch has to check for movement
Download & Installation

Source code

The latest release of TopoWatch source code can be downloaded here, or via SVN. Look below for the installatoin procedure.

Compile from source

In order to build TopoWatch the following libraries are required:
  • ffmpeg: to install ffmeg follow these instructions:
    • svn checkout svn:// ffmpeg
    • cd ffmeg
    • ./configure --enable-shared --enable-swscale --enable-pthreads --prefix=FFMPEG_HOME
    • make && make install
  • boost: Download and install the boost library
    • ./configure --with-libraries=boost_thread,boost_signals --prefix=BOOST_HOME
    • make && make install
  • Boost::Threadpool: Download the boost.threadpool library from here and unzip in the THREADPOOL_HOME directory.
Once the dependencies are installed, checkout the TopoWatch source code from the SVN repository:
svn co topowatch
cd topowatch
Now modify the ENV variables of the Makefile in order to point to the exact location of the FFMPEG, BOOST and Threadpool library. The make command will produce the topowatch executable in the same directory.
In order to run topowatch be sure the file TopoWatchUI.xml is in the same directory of the executable. Configure the LD_LIBRARY_PATH in a way it's possible to reach the FFMPEG and BOOST libraries.
enjoy TopoWatch!

Windows Binary

TopoWatch is also available for windows, and the Windows executable (plus dlls) can be downloaded from here. The zip file provides the executable (compiled by using the MinGW system) and all the dlls TopoWatch needs to work.


TopoWatch is developed by Simone Pellegrini

TopoWatch is developed in my free time. If you want to contribute to the project you can make a donation through paypal, or by contacting me.

Support This Project
Contribute to TopoWatch

A lot of work should be done on TopoWatch in order to compete with commercial systems. Experiments have demonstrated that the accuracy of the freezing-detection algorithm is good (compared to other systems) and also the performances are great. Anyway the UI should be improved, for that reason GTK+ and FFMPEG experts are really welcome to join the project. Furthermore, the web site and mainly the user manual, should be improved.

In order to join the TopoWatch project, please refear to the TopoWatch page at SourceForge.