View source for ITK/FAQ

== General information and availability ==

=== Do I need VTK to build ITK ? ===
With the default configuration, ITK does not require VTK. However, some optional modules (ITKVTKGlue) do require VTK.

ITK does not provide any visualization functionalities. Applications requiring visualization should implement those functionalities from internal code or libraries like OpenGL, GLUT or VTK.

=== What 3D file formats can ITK import and export? ===

The following table identifies the file formats that ITK can read/write via a factory mechanism based on the file extension (itk::ImageIOFactory). Some proprietary files format are only imported.  More information on [[ITK File Formats]] is available, including data types supported.

A very nice tool for viewing all of these images is ImageViewer which can be found in the ITKApps repository.

{| border="1" cellpadding="2" cellspacing="0"
|- bgcolor="#abcdef"
! File Format
! Read/Write
! Import
|-
| Analyze 7.5 || AnalyzeImageIO ||
|-
| BMP  &dagger; || BMPImageIO ||
|-
| DICOM || GDCMImageIO || Using DicomImageIO is backward compatible, but user should prefer GDCMImageIO
|-
| GE 4x || || GE4ImageIO
|-
| GE 5x || || GE5ImageIO
|-
| GE Advantage Windows || || GEAdwImageIO
|-
| Gipl (.gipl) || GiplImageIO ||
|-
| IPLCommon || || IPLCommonImageIO
|-
| JPEG &dagger; || JPEGImageIO ||
|-
| NRRD (.nhdr/.nrrd) || NrrdImageIO ||
|-
| Nifti (.nii) || NiftiImageIO ||
|-
| MetaImage (.mha/.mhd) || MetaImageIO ||
|-
| PNG &dagger; || PNGImageIO ||
|-
| Raw &Dagger; || RawImageIO ||
|-
| Siemens Vision || || SiemensVisionImageIO
|-
| Stimulate (spr/sdt) || StimulateImageIO ||
|-
| TIFF || TIFFImageIO ||
|-
| VTK Structured Points || VTKImageIO ||
|}

&dagger; BMP, PNG and JPEG are not very good formats for 3D medical images. They only support 2D images and a limited set of pixel types such as unsigned char, and unsigned short. The great advantage of BMP, PNG and JPEG is that you can view them with almost any image viewer. It is possible to read/write 3D datasets as collections of 2D slices each one in an independent BMP, PNG or JPEG file by using the ImageSerierReader and ImageSeriesWriter.

&Dagger; It is higly recommended not using this format. RAW is not a format, it is insufficient, inconsistent and simply dangerous. A RAW file without a header is useless, and once you add a header, it is not RAW anymore.

=== What if my file format is not supported by ITK? ===
If ITK doesn't have a specific file format reader at this point, you may try converting this specific file format image to a format like PNG, for which ITK has readers.

A good set of tools for performing such conversions is available in ImageMagick. It can be downloaded it for free from: http://www.imagemagick.org/

You can also take advantage of the VTK readers/importers. All you need is then use the VTKImageToImage adaptor in order to convert the vtkImageData into an itk::Image.

Supported VTK file formats can be found here: [[VTK_FAQ#What_image_file_formats_can_VTK_read_and_write.3F|What image file formats can VTK read and write?]] and [[VTK_FAQ#What_3D_file_formats_can_VTK_import_and_export.3F|What 3D file formats can VTK import and export]]

=== How do I read a volume from a DICOM series? ===
The following are alternative options for reading DICOM series. The first one in the list is the recommended option. The others are provided in case of desperation.

# Use the itk::ImageSeriesReader<> in combination with the DicomSeriesFileNames<>. For a full example on how to do this, please look at the source code under Insight/Code/Examples/IO/DicomSeriesReadImageWrite.cxx.
# Write a MetaImageHeader<br>This is a small text file holding information about the image: spacing, dimensions, pixelt type... This header can hold the list of dicom files you want to read. The only restriction is that the files must be uncompressed.<br>The easy way to create a MetaImage header is to use the application: MetaImageImporter that is available in: InsightApplications/MetaImageImporter. you can also take an existing metaimage reader and modify it in order to fit your needs. Please find attached one file that you can edit it with your favorite text editor.
# Use MRIConvert<br>Jolinda Smith from the Lewis Center for Neuroimaging at the University of Oregon has developed a nice application that allows you to load DICOM series and export them in MetaImage and Analyze format (among others).<br>She graciously has made this application publicly available at: http://lcni.uoregon.edu/~jolinda/MRIConvert There is a fresh version updated in april 14th.
# Jeff Brubaker and Stephen R. Aylward, at the UNC<br>CADDLab developed a DICOM query/move application called "MIND" (whit the motto: "MIND is not DICOM"). This application loads DICOM files over the network and export them in MetaImage format. This application is open source and it is available at: http://www.jeffro.net/mind/ and http://caddlab.rad.unc.edu/software/MIND/

=== How do I write a volume as DICOM series? ===
Use ITK in combination with gdcm 

http://gdcm.sourceforge.net/

GDCM is an open source package developed by the Creatis team at INSA-Lyon. It is distributed under a license similar to ITK.

http://gdcm.sourceforge.net/Copyright.html

GCDM uses CMake in order to configure its build process, so you will find a familiar setup. Once you download, configure and buid GDCM, you can reconfigure ITK by running CMake in your ITK build, going into the Advanced options and enabling USE_GDCM.  

For a code example on how to use GDCM for reading and writing DICOM series, please refer to the source code in

Insight/Examples/IO/DicomSeriesReadImageWrite2.cxx

You can always use the latest and greatest of GDCM, simply use an installed version of GDCM and link ITK to it using ITK_USE_SYSTEM_GDCM

=== Which interpreted languages are supported by ITK? ===
Currently ITK supports the following language bindings:

* Python 
* Java

=== How do I cite the use of ITK in a publication? ===
The Insight software may be cited by referencing the paper, the books, and/or the web site.

A) '''The paper'''

T.S. Yoo, M. J. Ackerman, W. E. Lorensen, W. Schroeder, V. Chalana, S. Aylward, D. Metaxas, R. Whitaker. Engineering and Algorithm Design for an Image Processing API: A Technical Report on ITK - The Insight Toolkit. In Proc. of Medicine Meets Virtual Reality, J. Westwood, ed., IOS Press Amsterdam pp 586-592 (2002).

B) '''The books'''

 "The ITK Software Guide: Design and Functionality"
  Fourth Edition
  Johnson, McCormick, Ibanez.
  published by Kitware Inc.
  2015
  ISBN: 9781-930934-28-3

 "The ITK Software Guide: Introduction and Development Guidelines"
  Fourth Edition
  Johnson, McCormick, Ibanez.
  published by Kitware Inc.
  2015
  ISBN: 9781-930934-27-6

 "Insight into Images"
  edited by Terry Yoo
  published by A.K. Peters 2004
  ISBN: 1-56881-217-5

 "The ITK Software Guide"
  Second Edition
  Ibanez, Schroeder, Ng, Cates.
  published by Kitware Inc.
  2005
  ISBN: 1-930934-15-7

 "The ITK Software Guide"
  First Edition
  Ibanez, Schroeder, Ng, Cates.
  published by Kitware Inc.
  2003
  ISBN: 1-930934-10-6

 "Mastering CMake,
  A Cross-Platform Build System"
  K. Martin and B. Hoffman
  published by Kitware Inc.
  ISBN:  1-930934-09-2

'''BibTtex citations'''

  @Manual{johnson2015itk,
     author = {Johnson, Hans J and McCormick, Matthew M and Ibanez, Luis},
     publisher = {Kitware, Inc.},
     title = {{The ITK Software Guide Book 1: Introduction and Development Guidelines-Volume 1}},
     year = {2015}
    }

  @Manual{johnson2015itk,
     author = {Johnson, Hans J and McCormick, Matthew M and Ibanez, Luis},
     publisher = {Kitware, Inc.},
     title = {{The ITK Software Guide Book 2: Design and Functionality-Volume 2}},
     year = {2015}
  }

  @Manual{ITKSoftwareGuide,
    Title          = {The {ITK} {S}oftware {G}uide},
    Author         = {Ibanez, L. and Schroeder, W. and Ng, L. and Cates, J.},
    Organization   = "Kitware, Inc.",
    Edition        = {First},
    year           = {2003},
    note           = {ISBN 1-930934-10-6},
    url            = \href{[http://www.itk.org/ItkSoftwareGuide.pdf http://www.itk.org/ItkSoftwareGuide.pdf]}{<nowiki>http://www.itk.org/ItkSoftwareGuide.pdf</nowiki>},
    }

  @Manual{ITKSoftwareGuideSecondEdition,
    Title          = {The {ITK} {S}oftware {G}uide},
    Author         = {Ibanez, L. and Schroeder, W. and Ng, L. and Cates, J.},
    Organization   = "Kitware, Inc.",
    Edition        = {Second},
    year           = {2005},
    note           = {ISBN 1-930934-15-7},
    url            = \href{[http://www.itk.org/ItkSoftwareGuide.pdf http://www.itk.org/ItkSoftwareGuide.pdf]}{<nowiki>http://www.itk.org/ItkSoftwareGuide.pdf</nowiki>},
    }

  @Manual{ITKSoftwareGuideThirdEdition,
    Title          = {The {ITK} {S}oftware {G}uide},
    Author         = {Johnson, Hans J. and McCormick, M. and Ib\'{a}{\~n}ez, L. and The Insight Software Consortium},
    Organization   = "Kitware, Inc.",
    Edition        = {Third},
    year           = {2013},
    note           = {\textit{''In press''}},
    url            = \href{[http://www.itk.org/ItkSoftwareGuide.pdf http://www.itk.org/ItkSoftwareGuide.pdf]}{<nowiki>http://www.itk.org/ItkSoftwareGuide.pdf</nowiki>},
    }

C) '''The Web sites'''

 "The Insight Segmentation and Registration Toolkit"
  www.itk.org

 "CMake: Cross Platform Make"
  www.cmake.org

If you want to include ITK in an acknowledgment section, a phrase similar to the following may be used:

 "This work benefited from the use of the Insight Segmentation
  and Registration Toolkit (ITK), an open source software
  developed as an initiative of the U.S. National Library
  of Medicine and available at www.itk.org."

and

 "The multi-platform configuration tool CMake was used for
  configuring ITK and facilitating its use from our project.
  CMake was partially funded by the U.S. National Library of
  Medicine as part of the Insight Toolkit project. CMake is an 
  open source system and it is freely available at www.cmake.org."

=== Is ITK FDA-Approved? ===

Given the fact that ITK is a software toolkit, it cannot be the
subject of FDA approval as a medical device. We have discussed
this topic in several occasions and received advice from FDA
representatives, that can be summarized as follow:


  ITK is to be considered as an off-the-shelf (OTS) product that
  is used for supporting a higher level medical application/product.
  The developer of such application/product will be responsible for
  performing the validation processes described in FDA published
  guidelines for the development of software-related medical devices.

For mode details see the page [[FDA Guidelines for Software Developement]]

== Language bindings ==
=== What does "Error opening hint file NOTFOUND" mean? ===
When you enable "USE_VTK" in the CMake configuration of ITK, and VTK was built with wrapping, CMake looks for a "hints" file.

The "hints" file is on the VTK source tree under: VTK/Wrapping/hints

Please switch CMake to "advanced", look for the VTK_WRAP_HINTS variable and set it to the full path to the "hints" file including the "hints" filename itself.

here is how it looks in the CMakeCache.txt of a typical ITK installation:

 //Where can the hints file be found
 VTK_WRAP_HINTS:FILEPATH=/home/johndoe/src/VTK/Wrapping/hints

=== How do I use ITK with WrapITK? ===

WrapITK allows you to use ITK from other languages.
(Python, Java, Ruby, ...)

* [[ITK/Wrapping | See the page about ITK wrappings]]

=== How do I use ITK from C# .NET? ===

There are currently three options:
# Use [http://code.google.com/p/manageditk ManagedITK]
#* '''NOTE: This option is not recommended as the project is no longer supported'''
# Use the [http://www.simpleitk.org/ SimpleITK] [http://sourceforge.net/projects/simpleitk/files/SimpleITK C# language bindings]
#* SimpleITK is great, but it does not support all filters (e.g. no support for registration in version 0.5.1)
#* A list of available filters can be found [http://www.itk.org/SimpleITKDoxygen/html/Filter_Coverage.html here] (valid Sept 2012)
# Manually wrap the desired functionality
#* This option requires the most work, but is the most flexible, allowing you to use any ITK functionality you desire
#* An example can be found [[ITK/Using ITK from .NET|here]]

NOTE: WrapITK does not currently support C# language bindings, but could be made to do so.

== Using the Insight Toolkit ==

=== How do I combine ITK and VTK in my application? ===

A full tutorial on how to combine ITK and VTK is available at

"Getting Started with ITK and VTK"
http://www.itk.org/CourseWare/Training/GettingStarted-II.pdf

You will need the auxiliary classes available at

  ITKApps

For example, for converting ITK images into VTK images and back, you will find useful the files from the ITKVTKGlue module:

      itkImageToVTKImageFilter.h
      itkImageToVTKImageFilter.hxx
      itkVTKImageToImageFilter.h
      itkVTKImageToImageFilter.hxx

=== How do I configure Emacs for ITK coding style? ===
You can add the following codes into your .emacs file

 ;;;;;;;;;;;;;;
 (c-add-style "itk"
             '("stroustrup" 
               (c-basic-offset . 2)
               (c-offsets-alist
                 (c . c-lineup-dont-change)
                 (innamespace . 0)
                 (inline-open . 0) 
                 (substatement-open . +)
                 (statement-block-intro . 0) ) ) )
 (add-hook 'c++-mode-hook (function (lambda ()
  (c-set-style "itk")(turn-on-auto-fill))))
 (add-to-list 'auto-mode-alist '("\\.txx\\'" . c++-mode)) (add-to-list 'auto-mode-alist '("\\.h\\'" . c++-mode))
 ;;;;;;;;;;;

=== How do I configure VIM for ITK coding style? ===

 set tabstop=2 " Tabs are two characters
 set shiftwidth=2 " Indents are two charactes too
 set expandtab " Do not use tabs
 set matchpairs+=<:> " To mach arguments of templates
 set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1 " ITK/VTK style indenting

You can also use CMake indentation and syntax file which are available on www.vim.org.

This was contributed by Andy Cedilnik @kitware.com

If you'd like to enable c++ style syntax highlight for *.txx files, put the following lines in your .vimrc file:
 syntax on
 au BufNewFile,BufRead *.txx set filetype=cpp

== Platform-specific questions ==
=== How do I avoid multiple prompts to reload all projects in Microsoft Visual Studio? ===
When the CMake source changes, you may see multiple prompts to reload many projects.

DO NOT USE "Rebuild All" or "Batch Build". Use the following recommended procedure.

There is an ALL_BUILD target available in the MSVC++ workspace. The best way to build ITK is to set ALL_BUILD as the active project, then select the active configuration you want (DEBUG, etc).

This can also be done from the command line like this: msdev ITK.dsw /MAKE "ALL_BUILD - Debug" /REBUILD

== Contribute ==
=== How do I make code contributions to ITK? ===
Please see this page: [[ITKContribute]].

== Testing ==
=== Is ITK tested? ===
Please see this page: [[ITK/Testing]]

== Working with Image Data ==

===How do I iterate through all the pixels in an image?===

Please see this example: http://www.itk.org/Wiki/ITK/Examples/Iterators/ImageRegionIterator of itkImageRegionIterator.

===What are Hounsfield Units?===

Hounsfield units were defined by Sir Godfrey N. Hounsfield, on of the pioneers of Computer Tomography for clinical applications.

The units represent the linear attenuation of X-Rays for a particular material. 

The units scale is defined in such a way that level for Water is 0 and the level for Air is -1000. 

The attenuation of any other material is mapped linearly into this range.

A table of Hounsfield units for common human tissues is avalable in the following link [[ITK Hounsfield Units]]

===What are MRI T1 / T2 Units?===

MRI images measure two types of relaxation times. 

The units are millisecons and the two relaxation concepts relate to how long it takes for the molecules in the tissue to realign themselves with a magentic field after being perturbed.

Details on the MRI units are available in the Wikipedia:

[http://en.wikipedia.org/wiki/Relaxation_%28NMR%29 Relaxation (NMR)]

=== DICOM: Bits Allocated, Bits Stored and High Bit ===

A question that is often asked on insight-users is :
I am trying to read/write a DICOM image, but some of the DICOM fields have changed after I write it back on disk.

Here is what you have on disk:
<pre>
        Bits Allocated = 16
        Bits Stored    = 12
        High Bit       = 11

                          |<------------------ pixel ----------------->|
            ______________ ______________ ______________ ______________
           |XXXXXXXXXXXXXX|              |              |              |
           |______________|______________|______________|______________|
            15          12 11           8 7            4 3            0
</pre>

Here is what you generally get after writing by GDCM:
<pre>
        Bits Allocated = 16
        Bits Stored    = 16
        High Bit       = 15

            |<------------------------- pixel ------------------------>|
            ______________ ______________ ______________ ______________
           |              |              |              |              |
           |______________|______________|______________|______________|
            15          12 11           8 7            4 3            0
</pre>

Since DICOM V3, you '''cannot''' store any overlay in the unused bits of the Pixel Data (0x7fe0,0x0010), thus it imply that the unused bits are '''zeros'''.
In ITK, there is no such thing as 12bits Pixel Type, thus when instanciating your reader you declare a 16bits Pixel Type. This buffer is then passed back to GDCM which sees an array of 16bits values and then simply used the simpliest way to store this buffer back on disk: Bits Stored = 16 and High Bit = 15.
In case you have not made any change to your pixel buffer, implicitely the first 4 bits will be zero again. The only difference being that they are not as clearly declared as 12bits.

=== I'm working with DICOM images, where can I find more information? ===
[[ITK/DICOM]]

== Data Display ==

===What imaging software is available for displaying medical image files?===

Please see the [[ITK/Third_Party_Applications | third party applications]] page for visualization applications that used ITK to perform Image reading/writing.

===When I view the output of my program, all I see is a black image. What went wrong?===

ITK is capable of reading and writing data in a variety of formats and bit depths.  However many 'consumer' image programs only work with 8-bit data, so when you try to display a 16-bit data file the image will appear black.  The solution is to use an image display program that correctly handles these types of files.  A small selection is listed above.

[http://www.imagemagick.org/ ImageMagick] is a particularly useful set of tools for image display, manipulation and conversion.

The `ImageViewer` program, part of InsightApplications, is capable of correctly loading and displaying all file types supported by ITK (including anisotropic images).

(Gavin Baker, 24-Jun-2004)

== Registration ==

===Can ITK be used for multi-modal registration? For example, CT-MRI, or MRI-fMRI?===

ITK provides several method for performing Multi-Modality registration. These methods are described in detail in the SoftwareGuide Chapter 8, pdf-page 241 to 340. In particular you will find interesting Section 8.4 in pdf-page 255 where the Mutual Information metrics are described.

Examples on multimodality registration are available in `Insight/Examples/Registration`.  A demo application using Mutual Information is available under `InsightApplications/LandmarkInitializedMutualInformationRegistration`.

It is strongly recommended that you read the chapter on image resampling (Section 6.9.4 of the pdf) before you get involved with image registration methods. That will save you a lot of misunderstandings that are common in new users.

You will also find useful the tutorial sessions, in particular [http://www.itk.org/CourseWare/Training/RegistrationMethodsOverview.pdf the overview].

(Luis Ibanez, 7-June-2004)

== Common Problems ==

<!--This fragment identifier is referenced from exception messages in the ITK Reader and Writer-->
<div id="NoFactoryException"></div>

=== Why can't I read any image files? or Why am I getting the exception message: "There are no registered IO factories."? ===

When trying to read or write a file using the ImageFileReader or the ImageFileWriter I got an exception with the following message:

 itk::ImageFileReaderException (00F7F494)
 Location: "Unknown"
 File: C:\ITK\InsightToolkit-1.6.0\Code\IO\itkImageFileReader.hxx
 Line: 101
 Description: Could not create IO object for file c:\t1.mnc

This exception is thrown when ITK does not recognize the fileformat that you are trying to read or write. When reading, ITK recognize file formats by asking a set of internal readers to attempt to read your file. If none of the registered readers accept your file, then the exception above is thrown. When writing, ITK uses the extension of the filename in order to chose the fileformat to be used. Make sure that you use one of the filename extensions recognized by ITK, and that the ImageIO class for that format has been registered.

Enable all the IO modules that you wish to support in your ITK CMake configuration.

To register the IO factory:

* If you are using CMake: call ''include( ${ITK_USE_FILE} )'' before ''add_executable'' or ''add_library''.

* If you are not using CMake: the factories should be registered with ''itk::XXXImageIOFactory::RegisterOneFactory()'' where ''XXX'' is the format.

* You may need to add something to the REQUIRED list of the FIND_PACKAGE call that includes ITK from your project. For example, if you were trying to open a png file when you got this error, ensure your CMakeLists.txt contains FIND_PACKAGE(ITK REQUIRED ITKIOPNG)

{{ITK/Template/Footer}}