RTK installation¶
Configuration, compilation and installation with ITK¶
RTK is a module of ITK, the Insight Toolkit. Follow the instructions of the ITK software guide (chapter 2 mainly) for configuring and compiling ITK. The following CMake options are RTK specific:
Module_RTK: Activates RTK download and compilation. Default isOFF. Turn itONto activate RTK or compile RTK independently (see below).Module_RTK_GIT_TAG: Git tag for the RTK download. By default, the RTK version which is downloaded and compiled is the one given in the RTK.remote.cmake. Change this option to build another version. For example, you can change it tomainto build the latest RTK version. RTK is only maintained to be backward compatible with the latest ITK release and ITK main branch.RTK_BUILD_APPLICATIONS: Activates the compilation of RTK’s command line tools. Although RTK is mainly a toolkit, we also provide several command line tools for doing most of the available processing. These command line tools use gengetopt. Several examples are available in the documentation.RTK_USE_CUDA: Activates CUDA computation. Default isONif CMake has automatically found the CUDA package and a CUDA-compatible GPU, andOFFotherwise.RTK_CUDA_VERSION: Specifies an exact version of the CUDA toolkit which must be used. If unspecified, RTK only checks if the found version is recent enough.RTK_CUDA_PROJECTIONS_SLAB_SIZE: Set the number of projections processed at once in CUDA processing. Default is 16.RTK_PROBE_EACH_FILTER: Activates the timing, CPU and CUDA memory consumption of each filter. Defaults isOFF. When activated, each filter processing is probed and a summary can be displayed. All command line applications display the result with--verbose.
RTK will automatically be installed when installing ITK.
CUDA GPU architectures¶
RTK requires CUDA 10 or later. The default CUDA architecture is 75 (Turing). Builds using this default target Turing and newer GPUs only. To build from source for an older GPU (Maxwell, Pascal or Volta), explicitly set CMAKE_CUDA_ARCHITECTURES to its compute capability (for example, -DCMAKE_CUDA_ARCHITECTURES=52 for compute capability 5.2) and use a compatible CUDA toolkit. CUDA 13 no longer supports compilation for architectures below 75. Use CUDA 11 or 12 for those GPUs.
Independent configuration and compilation¶
For RTK developpers, it may be useful to compile RTK independently from ITK. This is possible, simply:
Compile ITK with
Module_RTK=OFF.If you want to use CUDA, also activate
Module_CudaCommonor compile it separately as RTK in the following two bullet points (cloning its GitHub repository or downloading it as a zip package).Manually download RTK’s source repository from GitHub with
git(recommended) or as a zip package.Configure the project with CMake pointing to RTK’s source directory and setting the CMake option
ITK_DIRto ITK’s compilation directory. All CMake options above can be set exceptModule_RTK.
Installing the Python wrapping into a Python environment¶
The recommended way is to create a self-contained Python packages folder holding ITK’s compiled Python extensions and install ITK’s Python package into it, built with -DITK_WRAP_PYTHON=ON -DPY_SITE_PACKAGES_PATH=/path/to/python_packages_folder and installed with cmake --install <itk-build-dir> --component RuntimeLibraries. The extensions are built for a specific Python ABI and platform, so the folder is portable across environments that support that ABI/platform; using a different Python version or OS requires rebuilding ITK (and RTK).
utilities/rtk_install_python_packages.sh automates the RTK side: it validates that the itk package is in place (and CudaCommon’s wrapping when RTK_USE_CUDA=ON), then configures, builds and installs RTK into the same folder with CMake (-DPY_SITE_PACKAGES_PATH=$DEST_DIR, cmake --install --component RuntimeLibraries), makes the folder importable with a .pth file, and symlinks RTK’s Python modules to the source tree so their edits are taken into account without reinstalling. Run it from the RTK source directory, with DEST_DIR set to the same folder given by -DPY_SITE_PACKAGES_PATH above:
ITK_DIR=<itk-build-dir> DEST_DIR=/path/to/python_packages_folder utilities/rtk_install_python_packages.sh
With CUDA, set RTK_USE_CUDA=ON and make sure CudaCommon’s wrapping is also in the folder (built inside ITK with -DModule_CudaCommon=ON, or standalone):
ITK_DIR=<itk-build-dir> DEST_DIR=/path/to/python_packages RTK_USE_CUDA=ON utilities/rtk_install_python_packages.sh
The packages folder holds compiled extensions for a specific Python ABI/platform, but the .pth file that makes it importable is added by the script to the site-packages of the Python interpreter it runs with (the one given by PYTHON, python3 by default), or to its user site-packages if the former is not writable, e.g. for a system Python outside a virtual environment. To use it in another environment, run the script with PYTHON=/path/to/other/env/bin/python ... or export PYTHONPATH=$DEST_DIR. The script also generates rtk<app> wrapper scripts in that interpreter’s scripts directory (its user scripts directory, e.g. ~/.local/bin, in the latter case), so the applications can be run directly (e.g. rtkfdk --help) in addition to as Python modules (e.g. python -m itk.rtkfdk --help).
RTK is built in the Release configuration. Set CMAKE_BUILD_TYPE (e.g. CMAKE_BUILD_TYPE=Debug) to match another configuration of ITK.
Python pre-compiled binaries¶
We only provide pre-compiled binaries for the Python package which depends on ITK. Use the following commands to install the RTK module with pip.
python -m pip install --upgrade pip
python -m pip install itk-rtk
The same operating systems and Python versions are supported as ITK’s packages, see the list on Pypi.
We also provide pre-compiled CUDA packages for Windows and Linux. They require an installed version of CUDA compatible with the package. Currently, RTK is available for CUDA 12.4 on Windows and Linux via:
python -m pip install itk-rtk-cuda124
Note: the official PyPI packages are built from the latest RTK release and may not include features described in the latest documentation. If you install from PyPI, consult the corresponding stable documentation.
To try the newest features before they are published on PyPI, download the most recent wheels produced by our CI workflows:
Each workflow shows a list of Artifacts at the bottom of its front page if you are logged in on GitHub. Just select the version corresponding to your operating system and Python version, unzip the wheel and pip install wheel_filename.
GUI tools¶
Some RTK command-line tools, such as rtkshowgeometry, require graphical visualization capabilities. To use these tools, install the GUI optional dependencies:
python -m pip install itk-rtk[gui]
This installs:
pyvista- for 3D visualizationmatplotlib- for additional graphics support
Testing¶
To run RTK Python tests with pytest, install the test dependencies from the directory containing pyproject.toml:
pip install --group test itk-rtk
This installs:
pytest>=7.0- for running Python unit testsmatplotlib- for visualization in testsspekpy- for generating x-ray spectraxraylib- for retrieving tabulated x-ray attenuation coefficients
After installing, run the tests with:
pytest test/*.py
Documentation¶
To build the RTK documentation, install the documentation dependencies from the directory containing pyproject.toml:
pip install --group doc
This installs Sphinx and related tools for documentation generation.
Getting started¶
See GettingStarted.md. Your CMakeLists.txt can now use RTK when importing ITK as shown in the FirstReconstruction’s CMakeLists.txt.