Installation#

Note

If you encounter problems during installation, send an email to idtrackerai@gmail.com. We will try our best to assist you.

Requirements#

Idtracker.ai is a Python package (uploaded to PyPI) tested on Linux (Mint and Ubuntu) and Windows. Currently, we don’t give support for macOS but, as all the components of idtracker.ai work on macOS, idtracker.ai should too (at your own risk).

Idtracker.ai uses neural networks to track and identify animals, for which it depends on Pytorch. That’s why to run idtracker.ai’s tracking algorithms, a dedicated Nvidia GPU is required. If your machine does not have a dedicated NVIDIA GPU, you still can use some of the tools idtracker.ai offers; see Install without a NVIDIA GPU.

Heavy videos

Tracking and working with heavy videos (4K resolution, >10min duration, >20 animals) may have higher requirements, especially in RAM.

Besides the neural networks, idtracker.ai is a resource consuming software so it is recommended to run on a moderately equipped computer. The following is the recommended minimum configuration:

  • 12GB RAM memory

  • 100GB free space

  • Intel i5 or equivalent

  • 2GB GPU memory

Check Nvidia drivers#

idtracker.ai depends on PyTorch which works with Cuda >= 11.7 . Assuming you computer is using a Nvidia GPU, you need Cuda >= 11.7. Check your current NVIDIA drivers installation by opening a terminal (Anaconda prompt on Windows) and typing:

nvidia-smi

to get an output similar to this:

nvidia-smi output#
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.78.01    Driver Version: 525.78.01    CUDA Version: 12.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:01:00.0 Off |                  N/A |
| N/A   60C    P0    N/A /  35W |      5MiB /  4096MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|    0   N/A  N/A      2186      G   /usr/lib/xorg/Xorg                  4MiB |
+-----------------------------------------------------------------------------+

Check your Cuda version in the part “CUDA Version:”, if it is equal or higher than 11.7, you can go to the next installation step, Check Conda environments.

If your Cuda version is lower than 11.7 (or you don’t get the nvidia-smi output at all) you need to update (or install) the Nvidia drivers in your machine.

Tip

As a rule of thumb, avoid manually installing critical drivers like Nvidia’s ones. Let your operating system update them automatically.

Give Ubuntu a chance to install drivers by its own by running a general update with:

sudo apt update
sudo apt upgrade

and reboot if asked.

If the nvidia-smi output stays the same, open Ubuntu’s application Software & Updates (if you don’t find it on your applications, you can launch it running the command software-properties-gtk)

../_images/software%26updates_dark.png

Ubuntu’s Software & Updates application#

../_images/software%26updates_light.png

Ubuntu’s Software & Updates application#

In the tab Additional Drivers, select the NVIDIA driver (proprietary, tested) and click Apply Changes. Wait the installation to finish and reboot when asked.

Give Windows a chance to install drivers by its own by running a general update with Windows Update, you can run it with the command

control update

This command will launch a graphical application, check for updates there and install. Reboot when asked.

If the nvidia-smi output stays the same, open Nvidia’s application GeForce Experience (or install it from their website).

../_images/GeForceExperience.png

Nvidia’s GeForce Experience application#

In the tab DRIVERS, click CHECK FOR UPDATES. Update your drivers and reboot when asked. If everything fails, you can still try to manually install drivers from Nvidia website.

Check Conda environments#

While it is not required, we recommend installing idtracker.ai inside a Conda environment. You can check if you have a Conda installation by running

conda

If you get conda: command not found, you do not have Conda installed. Its installation is easy, follow the Conda installation instructions.

Tip

When deciding whether to install Anaconda or Miniconda, read their section about their differences. If you are not sure, we recommend Miniconda.

Install idtracker.ai#

Assuming you have NVIDIA Cuda >= 11.7 and Anaconda (or Miniconda) on your system, idtracker.ai can be now installed by following the commands below (to be run in a Linux terminal or in an Anaconda Prompt in Windows):

  1. Create a Conda environment called idtrackerai with Python 3.10 (modify the name of the environment if desired):

    conda create -n idtrackerai python=3.10

  2. Activate the environment:

    conda activate idtrackerai

  3. Install idtracker.ai from PyPI:

    python -m pip install idtrackerai

  4. Go to PyTorch site to get the command to install Pytorch and Torchvision with the parameters Pytorch Build: Stable, your operating system, Package: Conda, Language: Python and your Cuda version (for Cuda > 11.8, select CUDA 11.8). The command will appear as:

    conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

    This command depends on your computer specifications, don’t copy-paste it, visit PyTorch site.

If you are unfamiliar with Conda environments, keep in mind that idtracker.ai has been installed inside a Conda environment. As long as the environment is inactive, your computer will have no idea about any idtrackerai installation. To run any idtracker.ai command in the future you will have to activate first the environment with:

conda activate idtrackerai

Test the installation#

Open a terminal (Anaconda Prompt in Windows) and activate the Conda environment where your idtracker.ai installation is:

conda activate idtrackerai

Test your idtracker.ai installation by running:

idtrackerai_test

Manual downloads

test_A.avi test_B.avi

This command will copy a 18 seconds test video called test_B.avi into you current working directory and idtracker.ai will track it generating the respective session_test output folder.

Not recognized command

If just installed idtracker.ai and this test gets a very short error like No such file or directory, try reactivating the Conda environment:

conda deactivate
conda activate idtrackerai

Could not load library libcudnn_cnn_infer.so.8

If the test starts but after some seconds you get something like Could not load library libcudnn_cnn_infer.so.8. Install the Cuda toolkit dependency:

conda install cudatoolkit=11.8 -c conda-forge

qt.qpa.plugin: Could not load the Qt platform plugin “xcb”

Read this thread. Alternatively, in Ubuntu sudo apt install libxcb-cursor0 solves the problem.

Any other error

Send us your error to idtrackerai@gmail.com and we will assist you.

With GPU support, the test takes from 2 to 6 minutes. Without it (Install Pytorch for CPU), it takes up to 20-60 minutes. At the end of the test, the console should display the following line:

INFO     Test passed successfully in ? min with version 5.1.3

meaning a successful installation!

See also

A 4K resolution and 1 minute long video with 100 zebrafish are also available in Google Drive for users to test idtracker.ai’s capabilities on a more demanding video.

Install without a NVIDIA GPU#

Use idtrackerai without Pytorch#

The Segmentation app, the Validator and the Video generators do not require Pytorch and, hence, they do not need a dedicated Nvidia GPU. You can use these tools by installing only the steps 1 to 3 of Install idtracker.ai.

This kind of installation can be useful to control a full installation located in a remote computer. You can prepare your input parameters on your local machine, run the tracking on remote and validate and process the output in your local machine again.

Install Pytorch with AMD GPU#

While we don’t give support for it, you still can install Pytorch (and therefore idtracker.ai) with an AMD GPU with their API ROCm (Ubuntu, Linux, Red Hat, and CentOS only). Follow the steps 1 to 3 of Install idtracker.ai and then install Pytorch by selecting Compute Platform: ROCm in their site.

Install Pytorch with MacOS#

We are working on that

Install Pytorch for CPU#

While it will only be useful for tracking without identities and very short videos, we are working on that.

Update idtracker.ai#

From 5.x#

To update idtracker.ai from version 5.x to current version 5.1.3, run (inside the environment):

python -m pip install --upgrade idtrackerai

From 4.x or below#

To update idtracker.ai from version 4.x (or below) to current version 5.1.3, you will have to Uninstall the old conda environment and install the new version from scratch as version 4.x and 5.x use different Python versions.

Uninstall#

To remove everything inside a Conda environment and the environment itself, from outside the environment run:

conda remove -n idtrackerai --all