Skip to content
tracker

tracker

banner build status coverage report

Tracker is a cross platform application for tracking particles in videos. The application is written in Python and uses Opencv, scipy, and numpy to process videos and images, find the same object (particle) across frames and determine the particle velocity.

screenshot

Install

TODO: Construct *.whl and conda package, upload to mfix.netl.doe.gov/dist

Dependencies

The following dependencies need to be satisfied:

  • python >= 3
  • opencv >= 2
  • Qt >= 5
  • a Qt wrapper (PyQt4, PyQt5, or pyside)
  • qtpy
  • numpy
  • scipy
  • matplotlib

Optional dependencies are:

  • psutil (allows for ram and cpu monitoring)

These dependencies can be easily meet by downloading and installing Anaconda. Once Anaconda is installed, install the required modules by opening a console on linux and mac or the Anaconda prompt on windows and executing the following command:

conda install opencv numpy qtpy scipy pyqt psutil matplotlib

Getting Started

To start the application from the source directory, open a console on linux and mac or the Anaconda prompt on windows and enter the following command from the top-level of the source directory (where this README.md file is):

python -m tracker

There are a number of command line options that can be passed to the application. For a list of all the options, pass a -h when starting:

python -m tracker -h

No GUI

The application can be run in a "no gui" mode by passing a *.trak file and the --nogui or -ng flag. This will not run the Qt based GUI. The application will open the passes *.trak file and processing the entire media (video, image, synthetic) as specified in the *.trak file:

python -m tracker examples/50_synthetic_hough_circles.trak --nogui

Multiple *.trak files can be processed at the same time by using wild cards when specifing the *.trak file. For example, process all the included examples with:

python -m tracker examples/*.trak --nogui

Code Structure

Most of the files in this repository support the GUI with app.py being the main entry point. Both the GUI and command line interface (no_app.py) are started there. The basic image processing pipeline is achieved over three main files:

  • videos and images are read with methods in media_reader.py
  • images are processes with the functions in process_image.py
  • particles are tracked using functions in track.py

A collection of workers in workers.py perform the multithreading or multiprocessing of the GUI and video or image processing. Note: multiprocessing is not support on windows.

Synthetic data is created with the routines in synthetic_images.py and supporting functions in particle_generators.py.

Some common support functions are contained in the following files:

  • constants.py holds various "global" constants
  • stats.py contains methods for calculating and saving statics from the tracks
  • tools.py contains common functions, mainly supporting the GUI.

The rest of the files support the GUI:

  • app.py is the main entry point and GUI code
  • image_viewer.py is the image viewer widget that shows the images and draws the tracks, etc.
  • main_menu.py is the code for the main menu (save, load, examples, info, help, etc.)
  • tone_curve.py is the tone curve widget
  • widget_map.py contains the dictionary that relates the GUI widgets to variables. This is what is saved and is available to the processing functions
  • widgets.py contains custom widgets used throughout the GUI

The *.ui files stored under uifiles/ are xml files created with Qt's designer. This is where the majority of the widgets are defined and placed in the GUI.

Tests

There are a collection of unit tests located under the tests directory. These tests are run using the pytest library which can be installed using conda:

conda install pytest pytest-cov

These tests can be run by executing the following command in a console on linux and mac or the Anaconda prompt on windows in the top level directory:

pytest

A coverage report can be generated with the following command

pytest --cov=tracker