Building SimpleITK

Pre-built binaries (see Downloading the binaries) are available in many cases so users do not need to build SimpleITK. However, there are several reasons a user might prefer to build SimpleITK from source code:

  • The binary files for your programming language of choice are not (yet) distributed

  • You want the live on the bleeding edge by using the latest-and-greatest version of SimpleITK

  • You want to wrap your own filters using the SimpleITK infrastructure

  • You want to contribute to the development of SimpleITK

  • To use the SimpleITK’s C++ interface and/or use ITK directly

Prerequisites

To build SimpleITK you need:

  • A recent version of CMake >= 3.16.3 with SSL support for https.

  • A supported compiler.

  • To use the latest developmental version, source code can be downloaded with git >= 1.65

    • Git is required if building SimpleITK using SuperBuild to automatically download the matching version of ITK, SWIG, etc…

    • Windows users may prefer msysGit

  • The Python interface requires Python version 3.5 or greater.

  • It is recommended to have numpy installed when testing Python bindings.

  • The R interface requires R version 3.3 or greater.

System Requirements

Building SimpleITK requires a significant amount of compute power, and we recommend a reasonably powerful, modern computer. We suggest at least 4 gigabytes (GB) of RAM plus an additional 2 GB per thread when building with multiple threads. We also suggest a system with at least 4 cores for multithreaded compilation.

Building a SuperBuild of SimpleITK’s C++ core including all the testing and example code requires approximately 10 GB of disk space. Enabling the wrapping of Python or R can add 2 GB per language, and enabling the wrapping of all the languages SimpleITK supports, can bring the entire build folder to 16 GB.

Recipes / Formulas / Short cuts

Before you start please make sure you have the required Prerequisites installed.

For some environments we have short cuts, scripts, for automated building of SimpleITK (see their repository for more details):

Source code

If one of the above language specific front-ends are not used then SimpleITK must be built directly.

Before you start please make sure you have the required Prerequisites installed.

All of the instructions assume you are working on the command line.

Words of caution for building on the Windows operating system:

  • Windows has issues with long directory paths. We recommend cloning the source code near the root (e.g. C:\src).

  • To avoid potential issues do not clone the source into a path which has spaces in the directory name (e.g. C:\Users\SimpleITK Source).

First obtain the SimpleITK source code:

  1. Download the latest development version using git

git clone https://github.com/SimpleITK/SimpleITK.git

Building using SuperBuild

After downloading SimpleITK’s source code we STRONGLY recommend running cmake on the SuperBuild subdirectory of SimpleITK. Execute the following commands in the parent of the SimpleITK source directory to configure the SuperBuild:

mkdir SimpleITK-build
cd SimpleITK-build
cmake ../SimpleITK/SuperBuild

The SuperBuild will automatically download and build the matching versions of ITK, SWIG, Lua, and GTest (if testing is enabled) needed to compile SimpleITK.

If you get an error message saying that ITK_DIR is not set then, you did not correctly point cmake to the SuperBuild sub-directory. Please erase your binary directory, and point cmake to the SimpleITK/SuperBuild sub-directory.

The CMake configuration process should automatically find supported languages and enable SimpleITK wrapping for them. To manually enable a language toggle the appropriate WRAP_LANGUAGE cmake variable to ON. Verify and correct the advanced cmake variables for the language specific executable, libraries and include directories. For example if you have multiple Python installations ensure that all related Python variables refer to the same versions.

Then use your make utility or your cmake chosen build utility to build SimpleITK. As the SimpleITK build process may take a while, it is important to use the appropriate flags to enable multi-process compilation i.e. “-j” for make, “/MP” for Visual Studio, or use the CMake Ninja generator.

For building SimpleITK on Windows using the CMake GUI see:

Building Manually

By not using the superbuild, you must manually specify all dependencies used during the building of SimpleITK instead of using the known working versions provided by the superbuild as external projects. This may be useful if you are providing a system package of SimpleITK or tightly integrating it into another build system. The versions of external projects used and tested by SimpleITK can be found by examining the External CMake files in the Superbuild sub-directory.

Additional Prerequisites

The following are dependencies you will need when not using the SuperBuild:

  1. Setup the prerequisites as described above (i.e. CMake and supported compiler)

  2. Insight Toolkit (ITK) the version specified in the External_ITK.cmake file is the version of ITK used for the binary release. This can be seen as the minimum version of ITK to be used with SimpleITK, as future ITK versions are generally backwards compatible.

  3. Lua 5.3.5

  4. SWIG >= 4.0

  5. GTest or Google Test >= 1.10 is needed if testing is enabled.

Configuration and Building

After the source code is obtained, SimpleITK can be configured on Unix-like systems like so:

mkdir SimpleITK-build
cd SimpleITK-build
cmake ../SimpleITK

If all the dependencies are installed in standard places, then the CMake configuration should detect them properly. Otherwise, if there are configuration errors, the proper CMake variable should be set. CMake variables can be either set with a CMake interactive GUI such as ccmake or cmake-qt, as arguments on the command line by using the following format: -D<var>=<value>, or by editing the CMakeCache.txt file.

After proper configuration, SimpleITK can be built:

make -j$(nproc)

Advanced Build Options

SimpleITK is aware of the modularity of ITK and automatically enables and disables filters based on which modules are available from the ITK build which SimpleITK is compiled against. This makes it possible to customize SimpleITK to be a small library or to wrap additional ITK remote modules simply by configuring ITK with the desired modules enabled.

For example, the CoherenceEnhancingDiffusionImageFilter is an optional filter in SimpleITK as it’s part of the ITK remote module AnisotropicDiffusionLBR. This remote module is not enabled by default when building ITK and SimpleITK. To enable it when using SimpleITK’s Superbuild add -DModule_AnisotropicDiffusionLBR:BOOL=ON to the command line or in the CMake GUI press the “Add Entry” button to define the variable as above.

SimpleITK has a very flexible and robust build system utilizing CMake. It enables packagers to build SimpleITK in a variety of ways to suit their requirements and minimize recompilation of SimpleITK so that it can be wrapped for many different languages. Each of the language wrapping sub-directories e.g. “Wrapping/Python” can be configured and built as an independent project which is dependent on SimpleITK as an installed package of its libraries and header filers.

Testing

After compilation the prudent thing to do is to test SimpleITK to ensure that the build is stable and suitable for installation and use. To enable testing the cmake BUILD_TESTING variable must be enabled during the build process. Then the following commands execute the SimpleITK tests.

cd SimpleITK-build/SimpleITK-build
ctest .

On Windows you will need to specify configuration. Typically that would be the Release configuration, as such:

cd SimpleITK-build/SimpleITK-build
ctest -C Release

Installation from Build Tree

Python Installation

To install a built python package into the system Python, as root run:

python -m pip install SimpleITK-build/Wrapping/Python

Preferably, a Python virtual environment is created and the distribution installed there.

A Python Wheel file (.whl) is built by the “dist” target and produced in the “Wrapping/Python/dist” directory. If you use the Superbuild with the “make” generator then issue the following command:

make -C SimpleITK-build dist

R Installation

To install a built R package:

cd SimpleITK-build/Wrapping/R/Packaging
R CMD INSTALL SimpleITK

This installs the R package “SimpleITK” in /usr/local as root or your local R installation directory.

If you work in a multi-user environment, and are considerate of your fellow users you can install the package in a local directory:

  1. Create a local directory to install your R packages

mkdir my_R_libs
  1. In your home directory create a file named .Renviron with the following line

R_LIBS_USER="/path_to/my_R_libs"
  1. Check that the R library paths include this directory, in an R shell or from RStudio:

.libPaths()
  1. install

cd SimpleITK-build/Wrapping/R/Packaging
R CMD INSTALL -l /path_to/my_R_libs SimpleITK

Building SimpleITK Sphinx based documentation

SimpleITK uses Sphinx to create the documentation hosted on read-the-docs. To build this documentation we set up a Python environment with the appropriate packages.

Set up Sphinx Python virtual environment

The following are steps for setting up Sphinx:

  1. Create a Python virtual environment (“sitkenv” is the name for the new virtual environment and its directory in this example).

python -m venv sitkenv
  1. Activate the virtual environment

$ source sitkenv/bin/activate
(sitkenv) $
  1. Install Sphinx and packages using the requirements.txt (found in SimpleITK/docs directory).

(sitkenv) $ pip install -r SimpleITK/docs/requirements.txt

Build documentation

Once the Sphinx environment is configured, build the SimpleITK documentation. From the SimpleITK/docs directory (on OSX/Linux):

(sitkenv) $ make html

Results are in the SimpleITK/docs/build/html directory.