Usage

This software can be used in different ways. You can use the graphical interface, the command line interface (from the terminal) or import the modules from a python interpreter.

Using the Graphical interface:

To use the Graphical interface, start a terminal window and then:

Change your working directory to that of the source of the program (subfolder src). This must fit your installation folder. For example if user rcajal downloaded on the desktop:

cd ~/Desktop/pyperMotionTracking/src

Then actually launch the program:

python tracking_gui.py

When using the graphical interface, hovering over buttons and other elements should display tooltips explaining what these do.

You are greeted by the welcome tab. To navigate between functionalities, please select a corresponding tab on the left. The Preview and Track tabs require a video to analyse to be loaded. To do so, use the file menu or the standard open shortcut on your platform. The record tab will pop up without a camera attached but will require one to select the path to save the video. The analysis tab requires to have performed the tracking or recording step before use.

Please note never input empty parameters in the number fields as these are checked for valid numbers.

The Preview tab

The preview tab enables you to have a look at a downscaled version of your video to select your start and end point for the analysis as well as the frame that will serve as a reference. Currently, the reference frame must appear before the data frames. This may change in the future and also a dialog may be added to load a picture to serve as a reference. You can navigate in your video using the controls on the left of the progress bar at the bottom. Then, when on the desired frame select Ref, Start or End accordingly. An end of -1 corresponds to the end of the file. It is advised to select a frame that is not the first one (e.g. 5 onwards) for the Ref as the camera may take a few frames to adjust some parameters and the video may also alter the very first frames.

The Track Tab

This tab is more advanced. It allows you to Track a specimen in the open field from a pre recorded video. The Ref, Start and End parameters set in the preview tab apply to the Track tab.

The parameters below (except the type of frame displayed) will only be taken into account the next time the track button is pressed.

You should then set a threshold Thrsh for the brightness of you sample in the difference image. You can get an idea for this parameter by using the diff option from the drop down menu at the bottom. The min and max parameters refer the minimum and maximum areas of the sample respectively. These are experessed in pixels^2. The Mvmt parameter refers to the maximum displacement in either dimension of the specimen between two consecutive frames.

In addition, you can supply a number of frames to average for the reference (starting from the Ref frame). If detection is difficult, specifying several reference frames and setting the Sds parameter will enable you to use variation in the current frame relative to the standard deviation of the averages.

Finaly, the Clear parameter will clear object touching the border of the image, The Extract parameter is used if the arena is white on a dark background, this option will automatically detect it as an ROI. Finaly, the Norm parameter removes the slight variations in global brightness between frames. it will normalise each frame to the brightness of the reference.

The default detection parameter should be appropriate for the example videos.

The drop down menu allows you to select between the type of image (level of processing) you want to display. Please note that this option only applies to the portion of the recording that is being actively tracked, the ignored portion will just be displayed as the source (i.e. raw).

Finaly, you can define a region of interest using the yellow circle icon. When the mouse enters this ROI, the program will trigger a callback method. The default method draws a square at the bottom right of the image but this behaviour can be altered by overwritting the callback method in a subclass of the GuiTraker class (see API).

If you cannot detect your sample successfuly, please refer to the troubleshooting section.

The Record Tab

This tab essentialy reproduces the behaviour of the Track tab but for videos that are being recorded through a USB or FireWire camera for example. Before starting you must supply a destination path to save the video. The extension will determine the format. The available formats will dependend on the codecs available to ffmpeg in you installation. In tests, best restults were obtained with .avi and .mpg

The Calibration tab

This menu computes the parameters of the lens used to acquire the videos and once calculated, these parameters will be used automatically to undistort the images in the Track and the Record tabs. To use this functionnality, you must provide a folder containing a series (e.g. 10) of images acquired with the same lens and parameters as the video and containing a reference chessboard. A printable template can be found at http://docs.opencv.org/2.4/_downloads/pattern.png which will work with the default parameters. Once the folder is selected, press Calibrate and wait for the calibration to finish. Once done, the controls will become available and allow you to browse through the images used for calibration, the images with the features drawn and the undistorted images. You can also save the camera matrix for reference. In the future, it should become possible to load a calibration file from the Track and Record tabs.

The Analyse tab

This tab provides simple analysis and graphing features as well as the ability to save the list of coordinates.

First select the checkbox that corresponds to the tab you want to analyse. Then, click Update and you can finaly save your coordinates and plot graphs of distance made by the specimen between frames and change of directions at each frame. To save the graphs, right click on them and a menu will promt you for a destination path.

Using the Command Line Interface: