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.
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
For more detailed instructions, see the CONTRIBUTING.md file.
Building with Docker
All the dependencies described belowe are available pre-installed in a Docker image. This is the easiest way to build and contribute to The Software Guide.
- Download and install Docker.
- From a shell, run
docker run --name software-guide -p 8888:8888 insighttoolkit/itksoftwareguide-edit:latest
- Open the URL provided in the ternmial output in a web browser. In the web interface, open a Terminal
- To setup the repository for develop and build the project, run:
ssh-keygen cat ~/.ssh/id_rsa.pub # Paste this value into https://github.com/settings/keys cd /ITKSoftwareGuide ./Utilities/SetupForDevelopment.sh cd /ITKSoftwareGuide-build/ITKSoftwareGuide-build ninja
- To view the built PDF's, navigate to
/ITKSoftwareGuide-build/ITKSoftwareGuide-build/SoftwareGuide/Latex/, and double click on the PDF.
- Contribute as described in CONTRIBUTING.md.
- To restart the container, run
docker start 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:
- ImageMagick: Windows installer can be found here.
- LaTeX and BibTeX. See the preamble of the
./SoftwareGuide/Latex/00-Preamble-Common.texfile 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:
- LaTeX files found in
- JPEG, PNG and EPS files in
- PNG files generated as the result of compiling and running the examples included in the ITK source code.
- ITK examples source code
.cxxfiles where the comments delimited with
EndCodeSnippethave been written specifically to be included in the ITK Software Guide; the regular LaTeX files in
./SoftwareGuide/Latexinclude the LaTeX files generated from the ITK examples source code.
Following is a brief description of the build process:
- The source code of
ITKis downloaded and built (including ITK examples) in the binary output directory.
- JPEG and PNG files in the
./SoftwareGuide/Artdirectory are converted to EPS using ImageMagick tools; the resulting EPS files are saved in the
Artdirectory in the binary output directory.
- PNG files are generated by running ITK examples and converted to EPS using
ImageMagick; the resulting EPS files are saved in
Art/Generateddirectory of the binary output directory.
- A Python script
./SoftwareGuide/Examples/ParseCxxExamples.pyis invoked to extract the comments in the ITK examples source file delimited with
EndCodeSnippetand generate LaTeX files which are copied into the
Examplessubdirectory of the binary output directory.
- The top-level LaTeX file
./SoftwareGuide/LaTeX/ITKSoftwareGuide-Book1.texis compiled with a series of calls to
ps2pdfto generate the PDF file.
Configuring and Building with CMake
Following is the description how to configure and build ITK Software Guide using CMake:
- 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
2. Configure and generate the project for the target platform.
SuperBuild\_ITKSoftwareGuide project as appropriate for the target
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.
Frustrated by the build taking a long time to complete ... no solution here