The ITK Software Guide Reboot
Importance
For quite some time, the ITK Software Guide has been an extremely valuable resource for those adventurers that wish to delve into the exciting world of medical image analysis. At over 700 pages, the Software Guide is a tome that many graduate students have held near and dear for its broad coverage of medical image algorithms, the secret keys to create a program that gets real results, and its ability to create strong backs while lugging it around. adoption and success of the Insight Toolkit has been fueled by the Software Guide.
The book covers how to get started with the Insight Toolkit with instructions on how to obtain and build the toolkit, build examples against the toolkit, the design and architecture of the toolkit, and suggestions on other documentation sources and learning approaches. The content is approachable by scientists that are non-native programmers, with hints at programming best practices and direction on how to address programming challenges. It surveys the application of a broad range of image processing, segmentation, and registration algorithms in their mathematical and scientific context while introducing important practical concepts such as working in physical space instead of pixel space, analysis in a pipeline, and streaming. Finally, guidance is provided on how to extend the toolkit the solve problems in a better way and contribute back to the community.
Origins
With funding from the National Institutes of Health’s National Library of Medicine (NIH-NLM), the guide was written by primarily by Luis Ibanez with many important contributions from Brad King, Brian Avants, Celina Imielinska, Hans Johnson, Jisung Kim, Josh Cates, Gavin Baker, Julien Jomier, Karthik Krishnan, Lydia Ng, Mark Foskey, Mathieu Malaterre, Sebastien Barre, Stephen Aylward, Tessa Sundaram, Will Schroeder, and Yinpeng Jin according to the version control log and Contributors section. The book has been available in PDF or hard copy form.
Much of the practical value of the work is derived its creation with a literate programming methodology. A large portion of the content revolves around a set of code examples, and some of the code is interleaved with the text. By combining LaTeX, perl scripts, and CMake scripts, the text is generated from the code and the output of running the examples on real data. With text, code, and, data, the work is of high value because a reader can easily verify and extend the described methods. Also, by building and running the examples nightly on the software quality dashboard, we continue to know that the content works as-advertised.
Reboot
The last release of the Software Guide was in 2005. While much of the material has maintained relevant, eight years is a long period of time on the human-scale, even longer on the dog scale, and even longer yet on the software scale. Yet, there was great desire for updates to the guide.
How did the update finally happen? In summary, a openness towards self-initiatives, lowering the barrier-to-entry to contribution, encouraging collaboration, and applying more open-source software practices. Hans Johnson put in the effort to get the guide building again, converted the perl scripts to python scripts, and made a number of content updates. The worked was placed in a publically accessible code repository. The familiar patch contribution workflow used for the main repository was added to the Software Guide repository, and the Gerrit Code Review system was setup to make it easy to submit a patch, increase the quality of patches, and encourage interaction between community members. Brad King, Constantine Zakaroff, Jon Haitz, Kent Williams, Luis Ibanez, Matt McCormick, and Xiaoxiao Liu contributed patches, infrastructure improvements and reviews to the project. The new version of the guide was the result of efforts by a number of busy individuals whose work collectively summed to the release of the new edition.
What’s Next
The 4.5 edition of the guide contains updates to material on the build process, description of the repository layout, notes on architectural improvements such as the addition of a direction matrix to the Image data structure, and some updates to the contribution process among many other improvements.
What’s next for the guide? Whatever the community comes up with :-). Previously held confab‘s discussed ways to improve the documentation around ITK in general, improving on methods to document the API with Doxygen, more extensive, accessible, and locatable examples (a subject of upcoming blog posts), and updating and extending material in the guide. Conspicuously missing from the guide are material on the version 4 levelsets and registration frameworks. Interest has been expressed in moving the guide to a more standard and powerful literate programming system like sphinx. An open discussion will be held creation of a hard copy of the book. Regardless of any bigger changes, incremental corrections and additions can quickly and easily be make through Gerrit patches, and a new edition of the guide is likely with future releases.