Installation of ParticleDetection

Requirements:

Python >=3.8 is installed
pip !=22 is installed (see this issue for explanation)

(Regular) Installation

Install the default version using pip:

pip install ParticleDetection

Or use one of the options described below. Some options require manual installation of additional libraries.

pip install ParticleDetection[OPTION]

Installation from source

Upgrade your version of pip.
```
python -m pip install --upgrade pip
```
Clone the repository containing the ParticleDetection package or only download the ParticleDetection folder, if you are not interested in the RodTracker application.
Install it using pip

YOUR/REPO/PATH/ParticleDetection$ pip install .

Or install a specific option using pip

YOUR/REPO/PATH/ParticleDetection$ pip install .[OPTION]

Or install it directly from GitHub:

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

pip install 'particledetection[DETECTRON] @ git+https://github.com/ANP-Granular/ParticleTracking.git#egg=
particledetection&subdirectory=ParticleDetection'

Installation options

This package has two functionality options. The default version is only intended to use (and potentially evaluate the performance of) object detection models previously created with for use with PyTorch. This means that the Particle.modelling module is not usable.

default:
- Requirement: /
- Post-Installation-Step(s): /
- allows running exported detection models on the CPU/GPU
Note

Depending on the OS only a CPU enabled version of torch is installed by default. Please refer to the DETECTRON extra for the steps necessary to enable use of the GPU.
DETECTRON:
- Requirement: CUDA is installed
- Post-Installation-Step(s):
  - install Detectron2 as per their Installation Guide
  - install imgaug in the version shown below:
```
pip install "https://github.com/aleju/imgaug.git@0101108d4fed06bc5056c4a03e2bcb0216dac326"
```
  - Verify, that the installed version of torch, torchvision, and torchaudio match your installed version of CUDA. Use the PyTorch website to find a version that fits your system.
    
    Hint
    
    On Windows only the CPU version is installed by default.
    
    On Linux a GPU enabled version is installed by default, but CUDA version it uses changes occasionally.
    
    A GPU enabled version is not available on Mac.
- allows training/running/exporting new Detectron2 models (see the ParticleDetection.modelling module)
- allows running exported detection models on the CPU and GPU
Troubleshooting

There have been problems during the use of tensorboard that could be used by the additional dependencies below. These have not been observed on all machines though.
- change the protobuf version to 3.20.1
  pip install protobuf==3.20.1
- install Shapely
  pip install shapely
TEST:
- intended for running (or developing) tests for the package

Warning

Detection models exported with GPU support enabled will not work with a CPU-only installation.

Behavior on Linux

On Linux the GPU version of this package will be installed by default. It is not necessary to manually install CUDA before this installation. If one decides afterwards, that the extended functionality of training new networks is necessary, a simple reinstallation with the DETECTRON extra is needed.

The installation of the CPU version might not work out-of-the-box and will most likely require manual installation of the required dependencies.

Install any version of ParticleDetection
Uninstall any GPU enabled version of torch, torchaudio, and torchvision
Clear the cache of pip to avoid reinstalling the same packages.
Install your systems CPU-only version of torch, torchaudio, and torchvision (see the PyTorch Website).

Behavior on Windows

On Windows the CPU version of this package will be installed by default. This is due to the default behavior of PyTorch and the more complex installation process of CUDA on Windows. If GPU support is necessary on a Windows machine the requirements of the GPU version must be manually installed. 0. Install CUDA on the machine.

Install the default version of ParticleDetection.
Uninstall any CPU-only version(s) of torch, torchaudio and torchvision
Clear the cache of pip to avoid reinstalling the same packages.
Install your systems GPU version of torch, torchaudio and torchvision, that matches the installed CUDA version (see the PyTorch Website)

The DETECTRON version is not available on Windows because Detectron2 does not support an installation on Windows.