Installation of the RodTracker

As the RodTracker is a Python package usually you will be installing it from source or from a *.whl file, but there is also the possibility, that you are provided with a bundled standalone version. Get the executable installer (RodTracker-Setup.exe - Windows, RodTracker-Setup.deb - Linux, RodTracker-Setup.dmg - macOS) from the repository’s releases.

The following installation instructions are only concerning installing the RodTracker as a python package.

Installation from PyPI

Requirements:

  • Python >=3.8

  • pip

Install the default version using pip:

pip install RodTracker

Or use one of the options described in the documentation.

pip install RodTracker[OPTION]

Installation from source

Requirements:

  • Python >=3.8 is installed

  • pip !=22 is installed (see this issue for explanation)

  • Git is installed

  • It is strongly recommended installing RodTracker from a fresh virtual environment (created with venv)

  1. Cloning the repository containing the RodTracker. Do NOT just copy the RodTracker folder. This will lead to a missing dependency during the installation.

  2. Install it using pip.

    YOUR/REPO/PATH/RodTracker$ pip install .

It is also possible to install it directly from GitHub (requires Git to be installed):

pip install 'git+https://github.com/ANP-Granular/ParticleTracking.git#egg=rodtracker&subdirectory=RodTracker'

pip install 'rodtracker[DOCS] @ git+https://github.com/ANP-Granular/ParticleTracking.git#egg=RodTracker&s
ubdirectory=RodTracker'

Installation in conda environments

  1. Create a fresh conda environment with Python >=3.8

(base) YOUR/CURRENT/DIRECTORY$ conda create -n RodTracker python=3.10
        ...
(base) YOUR/CURRENT/DIRECTORY$

  1. Activate the just created environment.

(base) YOUR/CURRENT/DIRECTORY$ conda activate RodTracker
(RodTracker) YOUR/CURRENT/DIRECTORY$

  1. Follow the instructions in Install from source

Important

Do NOT use conda to install/upgrade any packages that the RodTracker software uses. Make sure, that any packages additionally installed with conda have no interaction with the RodTracker software.

Refer to conda’s interoperatbility feature, this Anaconda blog post and issue #59 for more information on the topic.

Installation options

In addition to the user/default installation there are four more options (mostly for developers) to choose from. They can be installed with pip using the extras feature, e.g.

pip install -e .[BUILD]

Please remember to install in editable mode when attempting to change any functionality of the RodTracker.

  • DEV:

    • intended to install all dependencies necessary or useful for the development of RodTracker

    • this will install all dependencies from the other extras as well

  • DOCS:

    • intended for building/extending the documentation

  • BUILD:

    • intended for building a bundled version of the RodTracker

    • this will also install dependencies from DOCS as building the documentation is a required step during the bundling process

  • TEST:

    • intended for running (or developing) the tests of the RodTracker

    • it is recommended to install the DEV extra if one intends to change the tests

Hint

Please remember to install in editable mode when attempting to change any functionality of the RodTracker. It might also make sense to install ParticleDetection in editable mode, which is NOT automatically done when installing RodTracker in editable mode. Simply reinstall ParticleDetection in editable mode after installing RodTracker. Refer to its installation instructions for that.

Installation with GPU support

On Linux the default installation allows running particle detections on a GPU, if an appropriate detection model is selected and no further actions are required.

On Windows the default installation only allows running particle detections on a CPU. This is due to the default behavior of PyTorch and the more complex installation process of CUDA on Windows. Please install CUDA first, then install the RodTracker, and lastly refer to ParticleDetection’s documentation for the necessary steps to enable GPU use.

Note

CUDA is currently not available on macOS and therefore also not supported here.

Post-Installation problems on Linux

When installed on Linux there is a possibility that system libraries are missing and errors like the one shown below occur and the RodTracker crashes.

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

When this happens, for example when running Ubuntu in the Windows Subsystem for Linux it is necessary to install missing libraries manually. For this refer to the pytest-qt documentation or the setup-qt-libs GitHub action.