Installation

Note

Quick note on ways of installation

Requirements:

Installation:

pip install niftypet

This will install all relevant packages, including nipet and nimpa.

Tip

Installation (advanced):

git clone https://github.com/NiftyPET/NIMPA.git
git clone https://github.com/NiftyPET/NIPET.git

export PATHTOOLS=$HOME/NiftyPET_tools
export HMUDIR=$HOME/mmr_hardwareumaps

conda install -c conda-forge python=3 \
    numpy scipy scikit-image matplotlib ipykernel ipywidgets
pip install --verbose -e ./NIMPA
pip install --verbose -e ./NIPET

This will install an "editable" distribution at the source locations for both nimpa and nipet (allowing easy modification and/or updating using git pull).

Detailed steps for installation are given below.

NiftyPET is a Python namespace package, primarily encompassing the two packages nimpa and nipet. Currently, these are available for Python 3.6 or greater for Linux and Windows systems. It has been deployed and tested on CentOS 6.8 and 7, Ubuntu 14.04, 16.04, 18.04 and 20.04, as well as Windows 10 (limited) – including Python C extensions for the core CUDA routines. Linux systems are recommended due to their robustness and stability (support for Windows is comparatively limited).

Dependencies

Hardware

  • GPU device: One or more GPU devices from NVIDIA with a CUDA compute capability of at least 3.5. It is also recommended to have at least 5 GB of GPU memory. The following devices have been tested with NiftyPET:

    • NVIDIA Tesla K20/K40/V100

    • NVIDIA Titan Xp/RTX

    • NVIDIA Quadro P4000/P6000

    • NVIDIA GeForce GTX 1060/1080/1080 Ti/1080 Max-Q

  • CPU host: The GPU device can be accessed by a CPU host, with a reasonable computing power for some other image processing routines (e.g. image registration, etc.). It is recommended to have at least 16 GB of RAM, although we have managed to run dynamic reconstruction using old PC workstations with as little as 11 GB of RAM.

Software

NitfyPET installation needs the following software pre-installed:

  • C/C++ compiler

    GCC and Clang are commonly using on Linux systems, and Visual Studio on Windows.

    • Ubuntu Linux:

      apt-get install build-essential

    • CentOS Linux:

      yum group install "Development Tools"

    • Windows: Visual Studio

  • CUDA GPU & Software

    The CUDA SDK/Toolkit (click the link to download) is a parallel computing platform and programming model. This includes the CUDA compiler (nvcc) and runtime API. For extra guidance, consult the CUDA documentation.

    Tip

    In CentOS, it is necessary to install DKMS (Dynamic Kernel Module Support). Download from here and install as follows:

    rpm -ivh epel-release-latest-7.noarch.rpm
yum -y install dkms

    Tip

    Make sure that CUDA is installed with appropriate paths to CUDA resources setup, e.g. on Linux systems:

    export PATH="/usr/local/cuda/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/cuda/lib64:$LD_LIBRARY_PATH"

    This can be added to ~/.profile or ~/.bashrc files. For more details see http://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#post-installation-actions.

  • Git

    Git is a version control system used for downloading NiftyPET and other necessary tools, i.e. NiftyReg and dcm2niix. For more details on installing git see https://git-scm.com/book/en/v2/Getting-Started-Installing-Git.

    On Linux systems it can be installed as follows:

    • Ubuntu Linux:

      apt-get install git

    • CentOS Linux:

      yum install git

    • Windows: Git

  • Python 3.6 or greater

    A free high-level programming language, through which all the GPU routines are available for the user. The easiest way to run NiftyPET in Python is by using the Anaconda or Miniconda distributions.

    Tip

    Optional Python packages

    Jupyter Notebook (notebook) is a useful development interface.

    Additionally, when using Anacoda or Minconda, it is recommended to use conda to install some dependencies rather than rely on NiftyPET to automatically install them via pip.

    # useful mathematical & plotting libraries
conda install -c conda-forge python=3 numpy scipy scikit-image matplotlib nibabel pydicom
# jupyter noebook support
conda install -c conda-forge python=3 ipykernel ipywidgets

NiftyPET installation

Tip

To avoid prompts during installation, specify configuration directories in advance:

export PATHTOOLS=$HOME/NiftyPET_tools
export HMUDIR=$HOME/mmr_hardwareumaps

Using pip

To install the entire suite of packages, use:

pip install niftypet

Tip

Instead of installing everything, follow these steps to install individual components separately.

  • nimpa

    pip install --verbose nimpa

  • nipet

    The core of NiftyPET image reconstruction.

    pip install --verbose nipet

    This will also install nimpa if not already present.

From source

The source code of full version of nimpa and nipet packages can be downloaded to a specific folder using git as follows:

git clone https://github.com/NiftyPET/NIMPA.git
git clone https://github.com/NiftyPET/NIPET.git

After a successful download, navigate to folder nimpa and run inside one of the following:

  1. pip install --verbose .

  2. pip install --verbose -e .

The last option with the -e makes the installation "editable", allowing the user to modify the source code themselves or by pulling newer versions from git using git pull.

Identically for nipet, run one of the following:

  1. pip install --verbose .

  2. pip install --verbose -e .

The installation will download and call on cmake, which will run automatically and generate Ninja files, and then run ninja to build all the CUDA C routines and Python C extensions. Following this, the compiled Python modules will be installed into the specific Python package location.

Third party software installed with NiftyPET

NiftyPET will automatically install additional third party software (used for capabilities such as image registration and conversion). NiftyReg and dcm2niix will be installed in the NiftyPET_tools folder specified during the installation process:

Conda environments

One of the advantages of using conda is the possibility of having separate environments for different versions of Python and/or packages installed in them. Thus conda environments enable the user to set up NiftyPET differently for various applications (e.g., different image resolution, radio-pharmaceutical-optimised attenuation and/or scatter correction, etc.). Below is an example of installation of NiftyPET into environment called niftypet.

Create environment called, for example, niftypet, by running this command:

conda create --name niftypet

Activate the conda environment:

conda activate niftypet

Note

On Windows, this may be simply activate niftypet, and on Linux source activate niftypet.

Tip

It may be quicker to also install additional required packages with conda (rather than relying on pip to automatically do this during installation of niftypet):

# useful mathematical & plotting libraries
conda install -c conda-forge python=3 numpy scipy scikit-image matplotlib nibabel pydicom
# jupyter noebook support
conda install -c conda-forge python=3 ipykernel ipywidgets

NiftyPET can now be installed as described above in NiftyPET installation, while making sure that the conda environment is active.

Warning

Make sure to conda activate niftypet whenever opening a new terminal to ensure the correct environment is active.

Jupyter Notebook

Jupyter Notebooks are useful for sharing and replicating image reconstruction methods written in Python. They allow introspection, plotting and sharing of any intermediate results (e.g. sinograms and images generated during the reconstruction pipeline) or any end results. It is easiest to use conda to install Jupyter in the base environment in order to automatically pick up kernels for all other enviroments (conda install --name base notebook). See http://jupyter.readthedocs.io/en/latest/tryjupyter.html for more details and http://jupyter.readthedocs.io/en/latest/install.html for a manual installation.

Warning

When using Jupyter, make sure to select the correct kernel (corresponding to the desired conda environment name) within the notebook.

Post-installation checks

Configuration

A .niftypet folder is created during the installation (in $HOME or %APPDATA%). Additional subfolders may be present corresponding to the conda environment name. Configuration information is stored in resources.py within this folder.

Warning

It is recommended to rerun pip install rather than manually editing paths and device properties in resources.py.

Default CUDA device

The default CUDA device used for GPU calculations is chosen during the installation together with the corresponding optimal nvcc (CUDA compiler) flags. For example, for the NVIDIA Titan Xp with compute capability of 6.1, resources.py will have a section showing:

# DO NOT MODIFY BELOW--DONE AUTOMATICALLY
### start GPU properties ###
DEV_ID = 0
CC_ARCH = '-gencode=arch=compute_61,code=compute_61;'
### stop GPU properties ###

Any available (installed) CUDA device can be chosen within Python for any image reconstruction or part of the reconstruction pipeline.

Search paths for third-party software

Paths to tools for image registration, resampling, and conversion (DICOM -> NIfTI) can also be found in resources.py:

# paths to apps and tools needed by NiftyPET
### start NiftyPET tools ###
PATHTOOLS = '/path/to/NiftyPET_tools/'
RESPATH = '/path/to/NiftyPET_tools/niftyreg/bin/reg_resample'
REGPATH = '/path/to/NiftyPET_tools/niftyreg/bin/reg_aladin'
DCM2NIIX = '/path/to/NiftyPET_tools/dcm2niix/bin/dcm2niix'
HMUDIR = '/path/to/mmr_hardware_mumaps'
### end NiftyPET tools ###

Note that the proprietary hardware \(\mu\)-maps (HMUDIR) are not distributed with this software, and have to be obtained from the Siemens Biograph mMR scanner.