Installation

We offer two possible installation approaches for our DL_Track_US software. The first option is to download the DL_Track_US executable file. The second option we describe is DL_Track package installation via Github and pythons package manager pip. We want to inform you that there are more ways to install the package. However, we do not aim to be complete and rather demonstrate an (in our opinion) user friendly way for the installation of DL_Track_US. Moreover, we advise users with less programming experience to make use of the first option and download the executable file.

Download the DL_Track_US executable

  1. Got to the OSF webpage containing the DL_Track_US executable, the pre-trained models and the example files using this link.

  2. Download the DL_Track_US_example.zip folder and unpack the file.

  3. Find the DL_Track_US.exe executable located in the DL_Track_US_example/executable folder.

  4. Open the DL_Track_US_GUI by double clicking the DL_Track_US.exe file and start with the testing procedure to check that everything works properly (see Examples and Testing). In case you get an anti-virus notification, trust us and click it away. We assure you the software is harmless.

Install DL_Track_US via Github, pip and Pypi.org

In case you want to use this way to install and run DL_Track_US, we advise you to setup conda (see step 1) and download the environment.yml file from the repo (see steps 5-8). If you want to actively contribute to the project or customize the code, it might be usefull to you to do all of the following steps (for more information see Contributing Guidelines).

Step 1. Anaconda setup (only before first usage and if Anaconda/minicoda is not already installed).

Install Anaconda (click ‘Download’ and be sure to choose ‘Python 3.X Version’ (where the X represents the latest version being offered. IMPORTANT: Make sure you tick the ‘Add Anaconda to my PATH environment variable’ box).

Step 2. (Only required for MacOS users, contributing or development) Git setup (only before first usage and if Git is not already installed). This is optional and only required when you want to clone the whole DL_Track_US Github repository.

In case you have never used Git before on you computer, please install it using the instructions provided here.

Step 3. (Only required for MacOS users, contributing or development) Create a directory for DL_Track.

On your computer create a specific directory for DL_Track_US (for example “DL_Track_US”) and navigate there. You can use Git as a version control system. Once there open a git bash with right click and then “Git Bash Here”. In the bash terminal, type the following:

git init

This will initialize a git repository and allows you to continue. If run into problems, check this website.

Step 4. (Only required for MacOS users, contributing or development) Clone the DL_Track_US Github repository into a pre-specified folder (for example “DL_Track_US”) by typing the following code in your bash window:

git clone https://github.com/PaulRitsche/DL_Track_US.git

This will clone the entire repository to your local computer. To make sure that everything worked, see if the files in your local directory match the ones you can find in the Github DL_Track_US repository. If you run into problem, check this website.

Alternatively, you can only download the environment.yml file from the DL_Track_US repo and continue to the next step.

Step 5. Create the virtual environment required for DL_Track_US.

DL_Track is bound to a specific python version (3.10). To create an environment for DL_Track_US, type the following command in your Git bash terminal:

conda create -n DL_Track_US python=3.10

Step 6. Activate the environment for usage of DL_Track_US.

You can now activate the virtual environment by typing:

conda activate DL_Track_US

An active conda environment is visible in () brackets befor your current path in the bash terminal. In this case, this should look something like (DL_Track_US) C:/user/…/DL_Track_US.Then, download the DL_Track_US package by typing:

Step 7. Install the DL_Track_US package.

Attention: The next part of Step 7 is NOT relevant for MacOS users:

You can directly install the DL_Track_US package from Pypi. To do so, type the following command in your bash terminal:

pip install DL-Track-US==0.2.1

All the package dependencies will be installed automatically. You can verify whether the environment was correctly created by typing the following command in your bash terminal:

conda list

Now, all packages included in the DL_Track_US environment will be listed and you can check if all packages listed in the “DL_Track_US/environment.yml” file under the section “- pip” are included in the DL_Track environment. If you run into problems open a discussion in the Q&A section of DL_Track_US discussions and assign the label “Problem”.

Attention: The next part of Step 7 is ONLY relevant for MacOS users:

Do not install the DL_Track_US package from Pypi. We advise you to use the provided requirements.txt file for environment creation. You need to create and activate the environment first (see Step 5 & 6) and navigate into the folder that you cloned from Github (DL_Track_US) with the bash terminal. You can do that by typing “cd” followed by the path to the folder containing the requirements.txt file. This should look something like:

cd /.../.../DLTrack/DL_Track_US

Then you can install the requirements of DL_Track with:

pip install -r requirements.txt

Install the DL_Track package locally to make use of its functionalities with:

python -m pip install -e .

There are some more steps necessary for DL_Track_US usage, you’ll finde the instructions in the usage section.

Step 8. The First option of running DL_Track_US is using the installed DL_Track package. You do not need the whole cloned repository for this, only the active DL_Track_US environment. You do moreover not need be any specific directory. Type in your bash terminal:

python -m DL_Track_US

The main GUI should now open. If you run into problems, open a discussion in the Q&A section of DL_Track_US discussions and assign the label “Problem”. For usage of DL_Track please take a look at the docs directory in the Github repository.

Step 9. The second option of running DL_Track_US is using the DLTrack_GUI python script. This requires you to clone the whole directory and navigate to the directory where the DL_Track_US_GUI.py file is located. Moreover, you need the active DL_Track_US environment.

The DL_Track_US_GUI.py file is located at the DL_Track_US/DL_Track_US folder. To execute the module type the following command in your bash terminal.

python DL_Track_US_GUI.py

The main GUI should now open. If you run into problems, open a discussion in the Q&A section of DL_Track_US discussions and assign the label “Problem”. You can find an example discussion there. For usage of DL_Track_US please take a look at the docs directory in the Github repository.

GPU setup

Attention: The next section is only relevant for windows users!

The processing speed of a single image or video frame analyzed with DL_Track_US is highly dependent on computing power. While possible, model inference and model training using a CPU only will decrese processing speed and prolong the model training process. Therefore, we advise to use a GPU whenever possible. Prior to using a GPU it needs to be set up. Firstly the GPU drivers must be locally installed on your computer. You can find out which drivers are right for your GPU here. Subsequent to installing the drivers, you need to install the interdependant CUDA and cuDNN software packages. To use DL_Track_US with tensorflow version 2.10 you need to install CUDA version 11.2 from here and cuDNN version 8.5 for CUDA version 11.x from here (you may need to create an nvidia account). As a next step, you need to be your own installation wizard. We refer to this video (up to date, minute 9 to minute 13) or this video (older, entire video but replace CUDA and cuDNN versions). There are procedures at the end of each video testing whether a GPU is detected by tensorflow or not. If you run into problems with the GPU/CUDA setup, please open a discussion in the Q&A section of DL_Track_US discussions and assign the label “Problem”.

Attention : The next section is only relevant for MacOS users!

In case you want to make use of you M1 / M2 chips for model training and / or inference, we refer you to this tutorial. There you will find a detailed description of how to enable GPU support for tensorflow. It is not strictly necessary to do that for model training or inference, but will speed up the process.