Installation

Basic

python3 -m venv env
source env/bin/activate
pip install poetry
poetry install

Sometimes the nnUZoo can be problematic to install over GitHub, so as a default it is commented out in pyproject.toml. In this case the installation should be performed like this:

python3 -m venv env
source env/bin/activate
pip install poetry
poetry install
poetry run pip install git+https://github.com/AI-in-Cardiovascular-Medicine/nnUZoo@main

For developers download additionally the dev dependencies:

poetry install --with dev

If you plan on using GPU acceleration for model training and inference, make sure to install the required tools (NVIDIA toolkit, etc.) and the corresponding version of PyTorch/TensorFlow.

The program was tested on Ubuntu 22.04.5 with Python 3.10.12. We tested it on different hardware; NVIDIA drivers and CUDA tended to cause problems cross-platform. Make sure to download the corresponding drivers and CUDA toolkit, e.g.:

sudo apt update
sudo apt upgrade
sudo apt install build-essential dkms
sudo ubuntu-drivers autoinstall
sudo reboot
# verify the installation of the driver
nvidia-smi
sudo apt install nvidia-cuda-toolkit

Potentially extra steps are needed.

Windows

Windows requires several manual fixes after installation due to packaging issues with PyTorch and library conflicts.

1. Install Visual C++ Redistributable

Download and install the Visual C++ Redistributable 2022 (x64) if not already present.

2. Fix missing LLVM OpenMP runtime (libomp140.x86_64.dll)

PyTorch 2.4.0 on Windows depends on libomp140.x86_64.dll which is not bundled in the pip wheel. Run this once after installation:

import urllib.request, tarfile, io, os, sys

url = 'https://conda.anaconda.org/conda-forge/win-64/llvm-openmp-14.0.0-h2d74725_0.tar.bz2'
data = urllib.request.urlopen(url).read()
dest = os.path.join(sys.prefix, 'Lib', 'site-packages', 'torch', 'lib', 'libomp140.x86_64.dll')

with tarfile.open(fileobj=io.BytesIO(data), mode='r:bz2') as t:
    f = t.extractfile('Library/bin/libomp.dll')
    with open(dest, 'wb') as out:
        out.write(f.read())
print('Done:', dest)

Note

This file will be lost if torch is reinstalled — re-run the script afterwards.

3. Fix optree version incompatibility

optree >= 0.14 is incompatible with torch 2.4.0 and causes a C-level access violation. Downgrade it:

pip install "optree==0.13.1"

4. Fix torch + TensorFlow DLL conflict

When both torch and TensorFlow are loaded in the same process, their OpenMP runtimes conflict on Windows. The fix is already applied in src/main.py via:

os.environ['KMP_DUPLICATE_LIB_OK'] = 'TRUE'

This must appear before any torch or TensorFlow imports.

5. GPU acceleration (CUDA)

Install the CUDA-enabled torch build matching your driver. With CUDA driver ≤ 12.0 (check with nvidia-smi), use the CUDA 11.8 build:

pip install "torch==2.4.0+cu118" "torchvision==0.19.0+cu118" --index-url https://download.pytorch.org/whl/cu118

After installing the CUDA build, re-run the libomp140.x86_64.dll script from step 2. Also uncomment the torch and torchvision entries in pyproject.toml (default is CPU only).

Precompiled version

A precompiled version is pinned to the release (compiled with nuitka). To compile the project yourself:

python -m nuitka --standalone --plugin-enable=pyqt6 --include-package=pydicom --include-package=scipy --include-package=numpy --follow-imports --show-progress main.py

Running the program

After installation, run the main program with:

python3 src/main.py

The graphical user interface (GUI) should appear. If you encounter issues, review the README or submit an issue on GitHub.