Last updated: 05.2018 If you find errors in this tutorial, outdated information and/or identify links that are no longer working, please notify Vivek Hari Sridhar by email or by reporting an issue on GitHub. These issues will be fixed as soon as possible. N.B. Hyperlinks in the text will direct you to relevant information when you click on them.

Manuscript: https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.13166

About
Requirements
Installation
    a. Install miniconda
    b. Create and activate a virtual environment in miniconda
    c. Install necessary python packages
    d. Install OpenCV
    e. Download tracktor
    f. Open a jupyter notebook
    g. Running the example code
    h. Running tracktor on your videos
Running tracktor
FAQ

About

Tracktor is an OpenCV based object tracking software. The software is able to perform single-object tracking in noisy environments or multi-object tracking in uniform environments while maintaining individual identities.

Tracktor is command based (i.e. there is no graphical user interface (GUI)) but anyone with basic coding/scripting skills such as R users can readily use it.

Requirements

Tracktor works on all operating systems (Windows, Linux and Mac). Below is a step by step guide to install the software and dependencies required to run Tracktor. Most of the code lines you will have to run for the installation must be entered into the Terminal (Mac/Linux) or the Command Prompt (Windows), which is readily available on your computer. Please note that if you are not familiar with python and/or opencv, this might be a bit overwhelming in the beginning, but we provide enough information to allow you to get started. Once you have overcome the initial challenge to get the software running, you will find that Tracktor is an efficient and versatile tool that can be used for many simple tracking problems. Furthermore, it’s a great way to start learning a bit of coding in python and how object detection algorithms work in general!

Installation

Follow the steps outlined below. We recommend both installing OpenCV and running Tracktor within a virtual environment using miniconda. A virtual environment can be seen as a closed ‘box’ (i.e the environment) within your computer, in which you can install various things and run software separately from your main system installation. This approach makes it easier to 1) install and 2) prevent potential issues if your machine already runs python (Mac/Linux) or if you have an earlier version of python installed on your machine.

a. Install miniconda

Miniconda is an open source distribution of python that aims to simplify package management and deployment. Python is a programming language and requires an interpreter (i.e. software) to run. We recommend using python 3 since the code for Tracktor was designed using this version, but python 2.7+ should also work. Download and install miniconda with python3 from the following link (please note that Anaconda, a more elaborate version of miniconda, will also work in the same manner):

https://conda.io/miniconda.html

Important: tick the box "Add Anaconda to my PATH environment variable” when the installer launches, otherwise you will have issues with later stages of this installation tutorial (see step 2 below). The installer states that this is not recommended but the risks to your machine are minimal and establishing a path to Anaconda is needed to run commands from the Terminal (Mac/Linux) or the Command Prompt (Windows).

b. Create and activate a virtual environment in miniconda

Creating a virtual environment will allow to install everything you need in this separate “box”, thus preventing any changes to your main system. Once miniconda is installed, you can create a virtual environment with a simple command in the terminal/command prompt.

In the Terminal/Command prompt, type:

conda create --name myenv (replace “myenv” with any name you want to give this environment)

You will be asked to confirm (proceed ([y]/n)?), type “y”. That’s it! Your virtual environment has been created. Now you can activate it (=work from within this environment) anytime you want by typing this line in the Terminal/Command prompt:

source activate myenv (Mac/Linux)

activate myenv (Windows)

(N.B. replace “myenv” with the name of your environment)

All the following steps in this tutorial should be performed from within the virtual environment you just created (= after activating it).

If you want to deactivate the virtual environment, run:

source deactivate (Mac/Linux)

deactivate (Windows)

c. Install necessary python packages

All packages should be installed from within your virtual environment. Activate your virtual environment as explained in section 2.

Once this is done, we will use pip, a python installer, to install all relevant packages. Run:

conda install pip

If you are having difficulty running Pip, information is available here. Install all dependencies/packages by running pip install packagename in the Terminal or Command Prompt, from within your environment virtual. Install the following packages (e.g. pip install numpy):
• numpy
• pandas
• scipy
• scikit-learn
• matplotlib
• ipython
• ipykernel (“conda install ipykernel” also works if you run into issues with pip)
• jupyter notebook*

*Jupyter notebook is optional. However, it is highly recommended for interactive coding. All example notebooks in this tutorial are written as jupyter notebooks. Jupyter is an application that allows editing and running code in an interactive way, via a web browser (+/- similar to Rcommander for the R users, more information here). For basic information on how to work/run lines or ‘cells’ of code in Jupyter notebook, see here. For e.g., it is useful to know that you can 1) display line numbers for your code by selecting View > Toggle line numbers from the menu, and 2) use the shortcut keys shift + enter to run a code cell rather than clicking on the button >|Run.

Once all of these packages are installed, create a ‘kernel’ for your virtual environment, which will be necessary for running Tracktor in Jupyter Notebook. Run the following and replace “myenv” with the name you gave your virtual environnement.

python -m ipykernel install --user --name myenv --display-name "python (myenv)”

d. Install OpenCV

OpenCV (Open Source Computer Vision) is a library of programming functions focused on real-time computer vision. OpenCV is freeware that works across all platforms but installing it on your computer might be the trickiest part of getting Tracktor to run on your machine. Fortunately miniconda allows installing OpenCV easily. Run:

conda install -c menpo opencv3

or (if this doesn’t work):

conda install -c fonda-forge opencv

or (if this doesn't work either):

pip install opencv-contrib-python

If you do not get an error message, OpenCV is now installed in your virtual environment. You can check if the installation worked by typing:

python import cv2

If these two lines give no error: congratulations, the installation was successful! You can exit Python for now using the exit() command. Note: you entered python by typing ‘python’ above. ‘import cv2’ is used to check if OpenCV works correctly. Once this is done, you need to exit python (with the “exit()” command) to go back to using the normal terminal commands.

It is possible that the installation does not work as described on your machine. If you are having difficulties with this part, please first check online for solutions, or get in touch with an IT specialist at your institution or a computer savvy colleague to help you out. As mentioned, installing OpenCV is the trickiest part of getting Tracktor up and running, but as soon as OpenCV is properly installed, you will be able to get on with your tracking. For more information, see: https://anaconda.org/menpo/opencv3

e. Download tracktor

Go on Tracktor’s GitHub page and click the green “clone or download” button. Download the .zip file to your choice location on your computer, and unzip th

Tracktor

Install / Use

README

Contents