insightsoftwareconsortium / itksoftwareguide

Sources for the ITKSoftwareGuide.

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

Contribution Details

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.

1. Download and install Docker.
2. From a shell, run

docker run --name software-guide -p 8888:8888 insighttoolkit/itksoftwareguide-edit:latest

3. Open the URL provided in the ternmial output in a web browser. In the web interface, open a Terminal
4. 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

6. To view the built PDF's, navigate to /ITKSoftwareGuide-build/ITKSoftwareGuide-build/SoftwareGuide/Latex/, and double click on the PDF.
7. Contribute as described in CONTRIBUTING.md.
8. To restart the container, run docker start 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.

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 😊.

itksoftwareguide's Issues

Update References to Gerrit to point to GitHub

Table 2.1 exceeds the page/paragraph width

Table 2.1 about the compiler support timeline (page 11) seems to exceed the page/paragraph width.

Missing link in Filtering.tex

The lines

ITKSoftwareGuide/SoftwareGuide/Latex/DesignAndFunctionality/Filtering.tex

Lines 118 to 119 in 6cae7a9

	advantage of this construction. (See the Iterators chapter
	in Book 1 for more information.)

refer to a section in the SW Guide without using the \ref command.

I'm wondering whether it was not used because linking to the first book from the second book would not work, or else, it was just a simple oversight.

In the Coding Style chapter (which is part of Book 1), I've used links to sections in only Book 1, so I ignore whether links across books would work well.

Describe the use of strongly typed enums

Following ITK issue 1049 and the corresponding PRs, ITK uses strongly typed enums. The ITK v5 migration guide provides details about the current practice in ITK:
https://github.com/InsightSoftwareConsortium/ITK/blob/master/Documentation/ITK5MigrationGuide.md#strongly-typed-enumerations

This practice should be reflected by the ITK SW guide, including how printing those types is being tested and the potential changes required in CMakeLists.txt files. Section Naming Enums (section C.6.8, p.321) is a possible candidate to cover the topic.

A quick search shows that the file ModelBasedSegmentation.cxx makes use of enums, so it will require adapting it to modern ITK practice.

Update Section `3.2.7 Multi-Threading` to account for new ITK multi-threading

I think there have been some important changes to ITK's multi-threading classes lately, or that there is an important effort ongoing.

The section in \SoftwareGuide\Latex\Architecture\SystemOverview.tex is quite short, so may be some class name or some other minor addition may be required

@dzenanz ?

Update Ch.1-1 mailing list to discourse

In chapter 1, section 1 of the software guide, it describes how you can ask questions and get involved by interacting with the mailing list.

Update this section to link to discourse and explain that the mailing list is being replaced by discourse.

Section is found here: https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Latex/Introduction/Introduction.tex#L179

Broken link in Appendix B Coding Style Guide

Link to itkTestDriver is broken in Appendix B under section "Naming Tests"

Here is the link that I am referring to:
https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch12.html#x52-210000B.6.4
I did a basic google search to see if I could find what it is supposed to link to but I am not sure.

In Github, here is the link to the code:
https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex#L616

The link is apparently referencing TestDriver

Add a Python style guide

Add a Python style guide.

The System Overview Wrapping section contains some example code of what an ITK Python code looks like, but we are lacking some guidelines on how to write proper ITK software using Python.

Besides, ITK supports more than one syntax or interface, and the ITKExamples seem not to have converged to one yet.

We should may be provide an overview and encourage using one.

Also, given the importance of the Python wrappers, the Python section may need further refactoring.

Main PDF out of date

The document at https://itk.org/ItkSoftwareGuide.pdf shows version 5.2.0 from April 16, 2021. It should be updated.

Nightly build failed to clone ITK

CDash error shows failure to clone ITK with git protocol:

Cloning into 'ITK'... fatal: remote error:    The unauthenticated git protocol on port 9418 is no longer supported. Please see https://github.blog/2021-09-01-improving-git-protocol-security-github/ for more information. Cloning into 'ITK'... fatal: remote error:    The unauthenticated git protocol on port 9418 is no longer supported. Please see https://github.blog/2021-09-01-improving-git-protocol-security-github/ for more information. -- Had to git clone more than once:           3 times.
--
CMake Error at ITK-prefix/tmp/ITK-gitclone.cmake:66 (message):
  Failed to clone repository:
  'git://github.com/InsightSoftwareConsortium/ITK.git'


ninja: build stopped: subcommand failed.

Similar to InsightSoftwareConsortium/ITKSphinxExamples#328

CI Build is failing

Update to newer CMake and ITK 5.

Provide an index of terms

It may be useful to add an index to the SW guide. It may ease looking up any term of interest, especially in the printed edition.

More information:
https://en.wikibooks.org/wiki/LaTeX/Indexing

Remove Gerrit-specific Git client hooks

STYLE: Update Python string formatting syntax

Replace the likes of old-style "My file is {file}".format(file=my_file) with new-style f"My file is {my_file}".

Error in itkSoftwareGuide: Chapter 2.7.3 BilateralFilter Equation 2.18 and 2.19

Description

In the current itkSoftwareGuide, formulas 2.18 and 2.19 each lack the minus in the exponent so that they are Gaussian kernels.
In addition, equation 2.19 is missing bracket.

Expected information

As I understand it, this file must be corrected.
https://github.com/InsightSoftwareConsortium/ITK/blob/master/Examples/Filtering/BilateralImageFilter.cxx

Versions

May 25, 2020

Screenshot

Broken URL in book 2 for `GeodesicActiveContourShapePriorLevelSetImageFilter`

In section 4.3.7 of the second book, the second link (with text itk::GeodesicActiveContourShapePriorLevelSetFilter) is presented, but appears to be broken:

https://itk.org/Doxygen/html/classitk_1_1GeodesicActiveContourShapePriorLevelSetFilter.html

I believe the link and the corresponding text should be changed to:

https://itk.org/Doxygen/html/classitk_1_1GeodesicActiveContourShapePriorLevelSetImageFilter.html
and
itk::GeodesicActiveContourShapePriorLevelSetImageFilter,

respectively. The only difference being the addition of the word Image to the end of the filter name.

Remove unsupported compiler

In book 1, page 9, Cygwin is listed as a supported compiler. It should be removed or eventually replaced by MinGW.

Appendices bookmarks not being generated

For some reason, the Appendices chapter bookmarks are not generated in the PDF file, although the sections are available in the table of contents.

For an easier navigation, it would be desirable if the bookmarks were generated for the appendices as well.

Malformed tables

In book 1, tables 9.2, 9.3 and 9.4 are missing a left side.

External Data for Build

Where can I download the external data to build the software guide? I have checked the USE_SYSTEM_ITK option instead of cloning the repository.

RGBPixel doesn't include subtraction or addition operators

In Book 1, Chapter 4, it says the following (here)

ITK introduces the itk::RGBPixel type as a support for representing the values of an RGB color space. As such, the RGBPixel class embodies a different concept from the one of an itk::Vector in space. For this reason, the RGBPixel lacks many of the operators that may be naively expected from it. In particular, there are no defined operations for subtraction or addition.

According to the Doxygen for RGBPixel, there are addition and subtraction operators for the RGBPixel class. I'm not sure the information is correct. Maybe in the past this was not the case however.

Here is what to edit: https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Latex/Architecture/DataRepresentation.tex#L101

Update links in CONTRIBUTING.md to ITK CONTRIBUTING documentation

After ITK has migrated to GitHub, uncomment lines in CONTRIBUTING.md added in #51 to point to ITK's CONTRIBUTING.md and the ITK Git Cheat Sheet.

Create CONTRIBUTING.md with details on how to contribute to the GitHub repository

Create GitHub client side hooks

git review-push, etc.

Update Figure 2.1

Figure 2.1 shows a very outdated version of CMake. I think it would be desirable to push an updated image for the sake of consistency, and to provide a more modern look.

Update references to JIRA to point to GitHub

Update the Code Style Guide section to match the `.clang-format` tool decisions

Since the merge of PR 1191 to the ITK repository, code formatting has been automatized with .clang-format.

A number of decisions were made based on the answers on the corresponding discourse post to define the style.

Thus, the Coding Style Guide section should be adapted to the adoption of the tool.

Maintaining both may be difficult as it has been until now when some change is introduced in the style. Although it is the .clang-format tool that will ultimately dictate the style in an automatic fashion, explaining the result it produces as the code layout with real examples may be useful to contributors.

Thus, there would be at least two possibilities to update the fiel/section:

• Remove most of the contents of the file since ultimately .clang-format will take care of the formatting and explain how .clang-format takes care of the style.
• Mention that the style is automated by the .clang-format tool, but re-work the current sections with examples to match what the .clang-format file dictates.

Also, the .clang-format tool dictates the C++ style, so for the Python ITKExamples we would still be missing a similar tool and/or a section in the ITK SW Guide (see issue #118).

Switch CI to GitHub Actions

Following the progressive switch of the ITK ecosystem to Azure Pipelines CI, the Software Guide CI should also transition to Azure Pipelines CI.

Line length to long warnings

This will need to be fixed in the main ITK repository.

https://open.cdash.org/viewBuildError.php?type=1&buildid=6056900

Examples/RegistrationITKv4/DeformableRegistration5.cxx:308:80: warning: Line length too long for LaTeX printing
Examples/RegistrationITKv4/DeformableRegistration5.cxx:338:80: warning: Line length too long for LaTeX printing
Examples/RegistrationITKv4/DeformableRegistration5.cxx:339:80: warning: Line length too long for LaTeX printing
Examples/RegistrationITKv4/DeformableRegistration3.cxx:309:80: warning: Line length too long for LaTeX printing
Examples/RegistrationITKv4/DeformableRegistration3.cxx:339:80: warning: Line length too long for LaTeX printing

license of user guide and included figures

@thewtex
Is the user guide and included figures distributed under a permissive license?

I am interested in re-using (with attributes) some figures from the guide in talks and documentation, it'd be great to include a license with this repo

You know me, in particular I'm looking at Fig 4.1 " Geometrical concepts associated with the ITK image."
Thanks for the great work 😄

Provide a glossary

It may be a nice addition to add a glossary of terms at the end of each chapter that summarizes the most important terms that the chapter presented.

The terms may be those having to do with image analysis, or ITK-specific.

Add CI badges

Add the CI badges to home

Missing introduction in Chapter 1

Having a look at the ITK Software Guide PDF file, the WELCOME message in Chapter 1 is stopped after

Welcome to the

so a good fair of the Introduction file is missing.

Broken Link in Iterators

Broken link in Chapter 6 Iterators under the section Optimizing iteration speed

Link is to itk::ImageBoundaryFacesCalculator but it seems that it was moved to a new namespace: itk::NeighborhoodAlgorithm::ImageBoundaryFacesCalculator

Fix PDF file properties in Book 2

As discussed in PR #73, Book 2 PDF file properties seem not to be created as expected; taking one of the latest builds, the PDF properties show:

Title: MultiResImageRegistration1TraceMetric.eps
Author: aghayoor
Subject: gnuplot plot
Keywords: "Registration,Segmentation,Guide"

and the following is expected:

Title: ITK Software Guide
Author: Hans Johnson and Luis Ibáñez and Matthew McCormick and the Insight Software Consortium
Subject: Medical Image Segmentation and Registration Toolkit
Keywords: "Registration,Segmentation,Guide"

Update Docker image usage instructions

Update Docker image usage instructions in the README. The image has been overhauled, and it now uses JupyterLab as the interface. Also update Docker installation and run instructions, which have become much easier on macOS and Windows.