1.Background and Introduction

The Insight Toolkit (ITK) was officially modularized in version 4.0.0, released in Dec. 2011 [1,2,7]. Developers have been testing and improving the modular structure since then. At present, the toolkit contains 137 regular/internal modules [5] and four Remote modules [3].

Here we will provide step-by-step instructions for ITK community members to take advantage of the modular structure when building a customized ITK library or using it as a third party library in ITK applications. Finally, we will introduce the External and Remote module support, which makes extending the toolkit easier.

*The following instructions apply to ITK 4.5.0 and later.

2. Build ITK via CMake GUI

The most common way to build ITK is via the CMake GUI. There are three main approaches to selecting the modules for building the library: the default mode, the group mode, and the advanced module mode.

2.1 Default Mode

By default, most internal ITK modules, except those that depend on external third party libraries (such as ITKVtkGlue, ITKBridgeOpenCV, ITKBridgeVXL, etc. ) and those with legacy code (ITKReview, ITKDeprecated and ITKv3Compatibility), will be built into the ITK library. All non-default modules, which includes the remote modules, have “EXCLUDE_FROM_DEFAULT ” tags in their module definition files (itk-module.cmake). ITK_BUILD_DEFAULT_MODULES  is the CMake option to request that all of these default modules be built, and by default this option is ON  (see Figure 1).

In the advanced mode of the CMake GUI, you can manually toggle the non-default modules via the Module_{module name} options. The Module_{module name}  options of the default modules are not available for toggle since they are already requested and enabled via ITK_BUILD_DEFAULT_MODULES=ON  (see Figure 2).

When ITK_BUILD_DEFAULT_MODULES  is toggled to be OFF , users can then customize the list of default modules to be included in the ITK library, using the the Group  (section 2.2) and Module  (section 2.3) options.

2.2 Group Mode

The CMake variables ITKGroup_{group name}  are visible to toggle when ITK_BUILD_DEFAULT_MODULES=OFF . ITK is organized so that groups of modules that have close relationships or similar functionalities reside in the same directory. Presently, there are 11 groups (not including the External and Remote groups). The CMake ITKGroup_{group name}  option is created for the convenience of enabling or disabling multiple modules at once. The Core group is turned on by default (see Figure 3).

When a group is ON , all the modules in that group and their (recursively) module dependencies are enabled. When a group is turned OFF , the modules in the group, except the ones that are required by other enabled modules, default to be OFF .

2.3 Advanced Module Mode

If you are not sure about which groups to turn on, but you do have a list of specific modules to be included in your ITK library, you can certainly skip the Group options and use the Module_{module name}  options only. For whichever modules are selected, their (recursively) dependent modules are automatically enabled.

However, not all the modules will show up in the CMake GUI for toggling, due to the various levels of controls in the previous two modes. If they are already enabled by other options or other modules, they will be hidden from the GUI. For example, Module_{ITKFoo}  option is hidden for toggle when the module ITKFoo itself is enabled either by 1) module dependencies: ITKBar depends on ITKFoo, or by 2) the ITKGroup_{FooAndBar}  option: ITKFoo belongs to the group, or by 3) ITK_BUILD_DEFAULT_MODULES=ON  and ITKFoo is a default module.

To find out why a particular module is enabled, check the CMake configuration messages where the module enablement information is displayed (Figure 1). The enablement messages are sorted in alphabetical order by module names.

3. Build ITK via Command Line

For those who prefer to build ITK via the command line syntax, here are some usage examples:

• Example 1: All default modules

  The default is ITK_BUILD_DEFULT_MODULES=ON , so it is optional to have this -D  argument.

• Example 2: Enable specific group(s) of modules

  BUILD_EXAMPLES=ON  requires ITK_BUILD_DEFAULT_MODULES=ON , therefore it is necessary to add -DBUILD_EXAMPLES=OFF  to the command line.

• Example 3: Enable specific modules

4. ITK Applications and Superbuild

For a project that uses ITK as an external library, it is recommended to specify the individual desired ITK modules in the COMPONENTS  argument of the find_package  CMake command:

If you would like to use the CMake ExternalProject module to download ITK source code when building your ITK application (a.k.a. superbuild ITK), here is a basic CMake snippet for setting up a superbuild in an ITKv4 application project using CMake 2.8.7+:

More exemple configurations for superbuild ITK projects can be found in Slicer, BrainsTools, ITK Wiki Examples, and ITK Sphinx Examples.

5. Extend ITK with External and Remote modules

The modularization effort has significantly improved the extensibility of the toolkit and lowered the barrier for contributions. An External module [4] is distributed outside the ITK main repository, but it could be built into ITK as a module once downloaded into the local copy of ITK source tree. When developing a new ITK module, place it into the Modules/External directory in a local ITK source tree to include it into your ITK library.

The next step in the module contribution process is to submit the External module to Insight Journal for review. Once the External module passes dashboard testing and peer review,  it can be made into a Remote module [3], which will be disseminated  from ITK itself while allowing its source code to be distributed independently of the main ITK repository. To be more specific, the source code of a Remote module can be downloaded by CMake (with a CMake variable switch) at ITK CMake configuration time, making it a convenient way to distribute modular source code without increasing the size of the main repository. After the Remote Module has experienced sufficient testing, and community members express broad interests in the contribution, the submitter can then move the contribution into the ITK repository via Gerrit code review.

It is possible but not recommended to directly submit a module to Gerrit for review without submitting to Insight Journal first. There are no established rules on whether a module should be directly merged into the main repository or not. But a nice IJ article describing the functionalities and the designs behind the module  is a great way to provide extra documentations on the code and could serve as good ITK Software Guide material in the future.  Figure 4 illustrates the module contribution channels.

6. Summary and Discussion

For most ITK consumers/users, the modularization of the toolkit is relatively transparent. The default configuration includes all the (default) modules into the ITK library, which is used to build their own ITK applications; For ITK developers and more advanced users, the modular structure has changed the rules for organizing the source code, building the library and contributing to ITK community. The Remote Module infrastructure enables fast dissemination of research code through ITK without increasing the size of the main repository. The Insight Journal also added supports for ITK module submissions with automatic dashboard testing. The VTK community had followed closely with the modularization progress in ITK, and VTK had been equipped with the same internal modular architecture with slightly different configuration options [6].

The adaptation to the new modular architecture takes time. Hopefully this blog provides some useful guidance to assist this transition for our community members. Please let us know if you find problems with the instructions, or if you have questions or suggestions. Your comments are always  welcomed.

References:

[1] Wiki page for ITK modularization: http://www.itk.org/Wiki/ITK/Release_4/Modularization

[2] How to organize your ITK code into a ITK module: http://insightsoftwareconsortium.github.io/ITKBarCamp-doc/ITK/ConstructITKModule/index.html

[3] ITK remote modules: http://www.itk.org/Wiki/ITK/Policy_and_Procedures_for_Adding_Remote_Modules

[4] ITK external modules: http://www.itk.org/Wiki/ITK/Release_4/Modularization/Add_an_external_module_(external_module)

[5] Doxygen page for ITK modules: http://www.itk.org/Doxygen/html/modules.html

[6] VTK Modularization and Modernization: http://www.kitware.com/blog/home/post/496

[7] ITK modularization: Divide and Conquer: http://www.kitware.com/source/home/post/34