A Simple C++/CMake Example

Building a C++ SimpleITK application is supported by using CMake to configure the build process. CMake can generate project buildsystems for Unix Makefiles, Ninja, Microsoft Visual Studio, or Mac OS Xcode.

Here is a basic CMakeLists.txt configuration file for building a SimpleITK C++ example program.

cmake_minimum_required(VERSION 3.16.3)

project(sitk_example)

find_package(SimpleITK)
add_executable ( sitk_example sitk_example.cxx )
target_link_libraries ( sitk_example ${SimpleITK_LIBRARIES} )

Here is our SimpleITK C++ example file sitk_example.cxx.

// This one header will include all SimpleITK filters and external objects.
#include <SimpleITK.h>
#include <sitkImageOperators.h>

// create convenient namespace alias
namespace sitk = itk::simple;

int
main(int argc, char * argv[])
{

  sitk::PixelIDValueEnum    pixelType = sitk::sitkUInt8;
  std::vector<unsigned int> imageSize(2, 128);

  // Create a black image
  sitk::Image image(imageSize, pixelType);

  // Add a Gaussian blob to the image
  std::vector<double> blobSize(2, 64.0);
  std::vector<double> blobCenter(2, 64.0);
  image = image + sitk::GaussianSource(pixelType, imageSize, blobSize, blobCenter);

  // Write the image as a PNG file
  sitk::WriteImage(image, "blob.png");
}

Invoking cmake as below in the same directory as these files will create the project buildsystem:

cmake .

Required CMake Variables

Running CMake will produce a CMakeCache.txt file that is the CMake configuration. Within that text file there are two variables needed to build a SimpleITK program, SimpleITK_DIR and ITK_DIR. SimpleITK_DIR needs to be set to the directory that contains the file SimpleITKConfig.cmake, and ITK_DIR needs to be the directory containing the file ITKConfig.cmake.

CMake attempts to find these files automatically, but it is unlikely to find them unless SimpleITK and ITK are installed into the system.

If SimpleITK has been built using the SuperBuild process, as described in Building SimpleITK, then these required directories can be found in the SuperBuild location. The SimpleITK_DIR variable should refer to the directory SimpleITK-build within the SuperBuild location, and the ITK_DIR variable should refer to the directory ITK-build in the SuperBuild location.

Here are what the settings in a CMakeCache.txt file should look like:

//The directory containing a CMake configuration file for ITK.
ITK_DIR:PATH=path_to_simpleitk_build_dir/ITK-build

//The directory containing a CMake configuration file for SimpleITK.
SimpleITK_DIR:PATH=path_to_simpleitk_build_dir/SimpleITK-build

Compiling using CMake

A SimpleITK program can also be compiled by running CMake. Here is the command to perform the build in the current directory:

cmake --build . --config Release

The ‘config’ parameter could also be set to Debug, RelWithDebInfo or MinSizeRel. On Unix-type systems Release is the default. On Windows the config must be specified explicitly. We recommend Release or MinSizeRel, since SimpleITK compiled in Debug mode is several orders of magnitude slower.

Of course traditional methods can be used to build a SimpleITK program (e.g. make on Unix, or Visual Studio on Windows), but it is often convenient to be able to use the same build command on all system types.

Using CMake-gui on Windows

In addition to the standard command-line CMake, a graphical-user-interface (GUI) version of CMake is also available. Here is what the CMake GUI looks like building our same example:

Windows CMake GUI

We have placed the files sitk_example.cxx and CMakeLists.txt in the folder C:sitkExample, and in CMake we have set the source directory to point there. Also, in CMake, we have set the build directory to point to C:sitkExample-Build.

After the user specifies the source and build directories, CMake will ask to select which compiler generator to use. The options are determined by what versions of Visual Studio are installed on the system, in this example Visual Studio 16 2019. The user must specify x64 for the platform generator, as the default option (x86) is not supported by SimpleITK.

Setting SimpleITK_DIR Setting ITK_DIR

After clicking Configure, CMake will attempt to find the SimpleITK library. That can be set in the SimpleITK_DIR variable, as seen in the above left image. CMake is looking for the directory containing the SimpleITKConfig.cmake file, in our example C:SimpleITK-buildSimpleITK-build.

Clicking Configure again, CMake will then try to find the ITK library for the ITK_DIR variable (see above right). CMake is looking for the directory containing ITKConfig.cmake. For a SimpleITK SuperBuild, as we have done, ITK_DIR will be the ITK-build directory within the SuperBuild, in our case C:SimpleITK-buildITK-build.

Once the SimpleITK_DIR and ITK_DIR variables have been set, we can click Generate to create the Visual Studio project file, ALL_BUILD.vcxproj.

Visual Studio

After opening ALL_BUILD.vcxproj in Visual Studio, the user should select a build type in Visual Studio. We recommend choosing Release for performance reasons. Then the user should select the x64 build platform, not the unsupported default, x86. Many man-hours and cpu cycles have been wasted building SimpleITK without setting the proper platform.