ITK Software Guide

This ITK Software Guide is the handbook for developing software with ITK.

It is divided into two companion books.

The first book covers building and installation, general architecture and design, as well as the process of contributing in the ITK community.

The second book covers detailed design and functionality for reading and writing images, filtering, registration, segmentation, and performing statistical analysis.

This repository contains the source code for the Software Guide.

Build Overview

A combination of CMake Superbuild infrastructure, Python extraction scripts, and LaTeX formatting are required to render the entire ITK Software Guide.

CMakeLists.txt files are placed in the directories involved on the build process. As any other CMake-managed process, the results of the build process are put in a binary tree corresponding to the source tree.

The following dependencies are required to build ITK Software Guide on Linux or Windows platforms:

• Git
• Python
• ImageMagick: Windows installer can be found here.
• LaTeX and BibTeX. See the preamble of the ./SoftwareGuide/Latex/00-Preamble-Common.tex file for the full list of required LaTeX packages. Among these packages, the Minted package for syntax highlighting in its turn depends on a Python package Pygments. Instructions for installing Minted and Pygments packages on Windows are available here.
• dvips, ps2pdf. While on Linux platforms these tools are usually included with most distributions, on Windows platforms they are usually included in MikTex Latex distribution.

ITK Software Guide is generated with Latex by using input from a variety of source code files and images:

1. LaTeX files found in ./SoftwareGuide/Latex.
2. JPEG, PNG and EPS files in ./SoftwareGuide/Art.
3. PNG files generated as the result of compiling and running the examples included in the ITK source code.
4. ITK examples source code .cxx files where the comments delimited with BeginLaTeX, EndLaTeX and BeginCodeSnippet, EndCodeSnippet have been written specifically to be included in the ITK Software Guide; the regular LaTeX files in ./SoftwareGuide/Latex include the LaTeX files generated from the ITK examples source code.

Following is a brief description of the build process:

1. The source code of ITK is downloaded and built (including ITK examples) in the binary output directory.
2. JPEG and PNG files in the ./SoftwareGuide/Art directory are converted to EPS using ImageMagick tools; the resulting EPS files are saved in the Art directory in the binary output directory.
3. PNG files are generated by running ITK examples and converted to EPS using ImageMagick; the resulting EPS files are saved in Art/Generated directory of the binary output directory.
4. A Python script ./SoftwareGuide/Examples/ParseCxxExamples.py is invoked to extract the comments in the ITK examples source file delimited with BeginLaTeX, EndLaTeX and BeginCodeSnippet, EndCodeSnippet and generate LaTeX files which are copied into the Examples subdirectory of the binary output directory.
5. The top-level LaTeX file ./SoftwareGuide/LaTeX/ITKSoftwareGuide-Book1.tex is compiled with a series of calls to latex, bibtex, latex, makeindex,dvips, and ps2pdf to generate the PDF file.

Building with Docker

All the dependencies described above are available pre-installed in a Docker image.

1. Download and install Docker.
2. If on Mac or Windows, start a boot2docker shell.

   $ git clone https://github.com/InsightSoftwareConsortium/ITKDevelopmentEnvironment.git
   $ cd ITKDevelopmentEnvironment/Docker
   $ ./build.sh itksoftwareguide-edit && ./run.sh itksoftwareguide-edit

4. Go get a coffee and curl up with a good book -- it will take a while.
5. Connect to your system with your browser at http://host:port, where host is localhost on Linux and the output of boot2docker ip on MacOS and Windows. On Windows, make sure to run boot2docker ip from a normal Git bash shell. port is the result of docker port itksoftwareguide-edit 3000 run inside the docker environment. An example: http://192.168.59.103:49153.y Both the username and password to connect are "itk".
6. To view the built PDF's, navigate to bin/ITKSoftwareGuide/SoftwareGuide/Latex/, click on the PDF, then the download button.
7. To edit the sources, edit the files in src/ITKSoftwareGuide/SoftwareGuide/Latex/.
8. To build changes, run make from the directory /home/src/itk/bin/ITKSoftwareGuide using a terminal available from the Term button of the web interface.
9. To commit a patch and submit it to Gerrit, use the same contribution process described below in the directory /home/itk/src/ITKSoftwareGuide.

Configuring and Building with CMake

Following is the description how to configure and build ITK Software Guide using CMake:

1. Run cmake-gui and specify input and binary output directories. Alternatively, create the binary output directory and run

   $ ccmake source_dir

where source_dir is the full path of the ITKSoftwareGuide directory. 2. Configure and generate the project for the target platform. 3. Build SuperBuild\_ITKSoftwareGuide project as appropriate for the target platform.

Troubleshooting

1. Build process will fail if CMake is unable to locate any of the dependencies. In this case a close examination of the error messages might provide a clue as to which dependency is failing.

2. Frustrated by the build taking a long time to complete ... no solution here 😊.

How to Contribute to the ITK Software Guide

Contributions are welcome and appreciated!

Contribution Process Overview

The following commands illustrate patch submission to GitHub:

   $ git clone https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide.git
   $ cd ITKSoftwareGuide
   $ ./Utilities/SetupForDevelopment.sh
   $ git checkout -b my-topic
   # make changes to local file(s)
   $ git add -- changedFileName
   $ git commit
   $ git review-push

Contribution Details

For more detailed instructions, see the CONTRIBUTING.md file.