************ Example: ITK ************ Introduction to ITK =================== The *Insight Toolkit*, [#]_ or ITK, is an open-source software system initially designed to support the Visible Human Project [C1]_. ITK is under continual development, being updated to employ cutting-edge segmentation and registration algorithms for multiple dimensions. For more information about ITK, please refer to [C2]_ and [C3]_. In order to facilitate the implementation of processing mechanisms specific to the medical imaging community, ITK provides a robust set of general purpose image processing tools. These image processing tools are available to users through the standard ITK Filter interface. Although ITK is implemented in C++, through the use of CMake [#]_ and CableSwig [#]_, the functionality of ITK is made available to languages such as TCL, Java, and Python. In addition, much of the functionality of ITK is also available in a |vistrails| package. The ITK package is not currently included in the binary distribution of |vistrails|, but it may be downloaded separately from the |vistrails| website. **Note:** The WrapITK library, upon which the |vistrails| ITK package depends, is well-tested on Linux and Mac OS X platforms. It is, however, known to have issues under Windows. Preparing ITK ============= At the time of this writing, the latest stable release of ITK is 3.6.0. In order to incorporate the functionality of ITK into the |vistrails| system, it first must be built and installed. In the following sections, we will describe in detail the process of downloading, building, and installing ITK and all the required components needed to use it. Downloading ITK ^^^^^^^^^^^^^^^ ITK can be downloaded in either source tarballs or via public CVS access to the ITK source repository. The following instructions take advantage of the CVS source repository; however, source tarballs can be downloaded from: http://www.itk.org/ These instructions can be found, in part, at the ITK website. To use CVS, you must have a CVS client installed on your system. To download the ITK library, issue the following commands: .. parsed-literal:: cvs -d :pserver:anonymous@www.itk.org:/cvsroot/Insight login *password: insight* cvs -d :pserver:anonymous@www.itk.org:/cvsroot/Insight co Insight Change directory into the newly created ``Insight/Utilities`` directory and issue the following command: .. parsed-literal:: cvs -d :pserver:anonymous@public.kitware.com:/cvsroot/CableSwig co CableSwig This checkout includes CableSwig in the ITK system, allowing it to be built automatically during compilation of ITK itself. Building the ITK Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^ ITK requires CMake to be installed and available on your system. As of ITK version 3.2.0, CMake version 2.4.6 or greater must be used to prevent compilation errors. In order to simplify updating ITK to later versions of the software, we perform an out-of-source build. To do this, we first create a directory outside the **Insight** directory created for us during the CVS checkout process. .. parsed-literal:: mkdir itk cd itk We now run CMake, or the GUI-based version ccmake, in this directory. If you're using Windows, you may wish to run the Windows-specific ``cmake-gui.exe`` instead. .. parsed-literal:: ccmake ../Insight Note: The above command assumes that the **Insight** directory exists at the same level as the **itk** directory that we just created. The following advanced CMake variables must be set to the appropriate values: .. csv-table:: :header: CMake Variable, Value BUILD\_SHARED\_LIBS, ON INSTALL\_WRAP\_ITK\_COMPATIBILITY, ON ITK\_CSWIG\_PYTHON, OFF ITK\_USE\_REVIEW, ON USE\_WRAP\_ITK, ON WRAP\_ITK\_PYTHON, ON WRAP\_ITK\_JAVA, OFF Note: Some CMake variables are only available based on the state of others. If a variable is missing from the list, set what is visible and re-configure, this will often allow you to see and set additional parameters. After generating the appropriate files and exiting ccmake, the standard build process can be completed. To compile (on Linux or Mac OS X), run: .. parsed-literal:: make sudo make install On Windows, the build process is governed by the type of project or Makefile generated by CMake. .. topic:: Note: It is possible to use ITK without installing it. To do this, the environment variables LD\_LIBRARY\_PATH and PYTHONPATH must be set to the appropriate build directories: | ``LD_LIBRARY_PATH=/Path_To_itk/bin`` | ``PYTHONPATH=/Path_To_itk/Wrapping/WrapITK/Python`` At this point, ITK is build and installed. To validate this, open a Python shell and issue the following commands: .. parsed-literal:: >>> import itk >>> itk.Image[itk.US,2] The above commands should both complete without error, and should produce the output: .. parsed-literal:: <class 'itkImage.itkImageUS2'> The WrapITK implementation used to wrap ITK for use in Python lazily instantiates required classes. This means that even if the import succeeds, the instantiation of the above ``itk.Image`` class may fail. This is particularly common if the environment variable LD\_LIBRARY\_PATH is incorrectly set. ITK and |vistrails| =================== When built and installed with the appropriate Python bindings included, ITK can be used from |vistrails| through the ITK package. As mentioned previously, ITK is a third-party package and is not included in the general |vistrails| distribution. However, like many third-party packages, it is available from the |vistrails| website. [#]_ The |vistrails| ITK package is under continual development with the latest versions being announced on the |vistrails| website. After downloading the package and extracting it into the ``.vistrails/userpackages`` directory, you can enable it through the ``Module Packages`` tab in the ``Preferences`` dialog. Please refer to Chapter :ref:`chap-packages` for instructions on how to do this. Upon starting |vistrails|, the ITK package modules will be made available to the Builder Window. ITK Package Organization ^^^^^^^^^^^^^^^^^^^^^^^^ The ITK |vistrails| package loosely mimics the ITK functionality hierarchy. The package's top level consists of base classes, containers, and file readers as shown in Figure :ref:`fig-structure`. Also available at the top level is the ``PixelType`` module and the specific types used to create and execute ITK-based pipelines. Currently, the ITK Image Filters are organized into functional groups. The five filter types, as show in Figure :ref:`fig-structurec`, are: * Feature Extraction Filters * Image Intensity Filters * Segmentation Filters * Image Selection Filters * Image Smoothing Filters All filter types currently have at least one representative ITK filter wrapped and usable from within the |vistrails| environment. .. _fig-structure: .. figure:: figures/example_itk/package_structure.png :align: center :width: 30% \(a\) The |vistrails| ITK Package Structure Overview .. figure:: figures/example_itk/pixeltypes.png :align: center :width: 30% \(b\) The ITK Package Supported PixelTypes .. _fig-structurec: .. figure:: figures/example_itk/filtertypes.png :align: center :width: 30% \(c\) The ITK Package Filter Structure Reading DICOM Volumes ^^^^^^^^^^^^^^^^^^^^^ DICOM is a standard format for exchanging medical images. ITK includes DICOM support through the GDCM libraries. [#]_ It is worthwhile to note that at this time these libraries are currently not a complete implementation of the DICOM standard. DICOM volumes can be integrated into |vistrails| through the use of either the ``GDCMReader`` or ``DICOMReader`` modules in the ITK package. For the rest of this example, we will use the ``GDCMReader`` module as its performace is slightly higher than the ``DICOMReader`` implementation. Figure :ref:`VisTrails workflow utilizing ITK to extract a single slice... <fig-slicer>` shows the use of the ``GDCMReader`` module. In order to properly read a DICOM volume, the ``GDCMReader`` must be supplied with the dimension of the volume to be read and the directory containing the series to read. By default, WrapITK supports two- and three-dimensional volumes. In order to include support for higher dimensions, the appropriate WrapITK variable must be set within CMake, *before* compiling ITK. Volume Processing With ITK and |vistrails| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Typically, DICOM volumes are written with no 16-bit unsigned shorts. Unfortunately, most systems allow the display of only 8-bit values. Because of the higher precision inherent in DICOM data, it is often preferable to perform any computation, segmentation, or processing on the data prior to rescaling in order to utilize as much information as possible. .. _fig-slicer: .. figure:: figures/example_itk/itk_slicingpipe.png :align: center :width: 100% |vistrails| workflow utilizing ITK to extract a single slice from a DICOM volume. The slice is chosen by first forming a Region to extract. The result is viewed through the use of standard |vistrails| Spreadsheet modules. Volume Processing With ITK and |vistrails| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ITK image filters are typically templated based on the dimensionality of the data being processed, as well as the data type being processed. In |vistrails|, these parameters are handled through the use of ``PixelType`` modules. Although any ITK Filter wrapped in \vistrails can accept any of these ``PixelType``\ s, the underlying implementation may not be compatible with the input ``PixelType``. Using ``PixelType``\ s incompatible with the underlying filter implementations is the most frequent cause of error when executing otherwise functional pipelines in |vistrails|. .. %%:ref:`fig-pixeltypes` When processing volumes, it is often necessary to extract a single slice from the volume at different stages of the processing pipeline. This is possible in |vistrails| through the use of the ``ExtractImageFilter``. Given a volume, a Region, and Dimensionality information, the ``ExtractImageFilter`` can extract a single slice from the data volume that can be used in further processing, previewing the results, or writing to disk. An example workflow that extracts a slice from a DICOM volume can be seen in Figure :ref:`VisTrails workflow utilizing ITK to extract a single slice... <fig-slicer>`. Visualizing the results ^^^^^^^^^^^^^^^^^^^^^^^ Although ITK's processing filters and the DICOM standard both support 16-bit processing and storage, many image viewers are capable of displaying in only 8-bit resolution using the unsigned char ``PixelType``. Since the output of an ITK processing workflow is an image, it makes sense to view it as such. This means that we are required to both remap the data values in the image to 8 bits as well as perform a casting operation to change the data type from unsigned shorts to unsigned chars. These operations are performed through the use of the ``RescaleIntensityImageFilter`` and the ``CastImageFilter``. Figure :ref:`VisTrails workflow utilizing ITK to extract a single slice... <fig-slicer>` demonstrates the use of the ``RescaleIntensityImageFilter`` and the ``CastImageFilter`` in conjunction with the ``ImageToFile`` and ``ImageViewerCell`` modules to view the resulting slice in the |vistrails| Spreadsheet. .. rubric:: Footnotes .. [#] The Insight Toolkit is sometimes referred to by the longer name *Insight Segmentation and Registration Toolkit*. .. [#] CMake cross-platform make system. http://www.cmake.org .. [#] CableSwig Interface generator. http://www.itk.org/HTML/CableSwig.html .. [#] Please Note: At the time of this writing, the |vistrails| ITK package is not a complete wrapping of all ITK functionality. If you would like to contact the author regarding the wrapped functionality, please do so through the e-mail address on the |vistrails| website. .. [#] Grass roots DiCoM Project. http://www.creatis.insa-lyon.fr/Public/Gdcm/ .. rubric:: Citations .. [C1] R. A. Banvard, "The visible human project image data set from inception to completion and beyond," Proceedings of CODATA, 2002. .. [C2] L. Ibanez, W. Schroeder, L. Ng, and J. Cates, The ITK Software Guide, 2nd ed., Kitware, Inc. ISBN 1-930934-15-7, http://www.itk.org/ItkSoftwareGuide.pdf, 2005. .. [C3] T. S. Yoo, M. J. Ackerman, W. E. Lorensen, W. Schroeder, V. Chalana, S. Aylward, D. Metaxes, and R. Whitaker, "Engineering and algorithm design for an image processing API: A technical report on ITK - The Insight Toolkit," Proceedings of Medicine Meets Virtual Reality, pp. 586-592, 2002.