ITK/FAQ: Difference between revisions

From KitwarePublic
< ITK
Jump to navigationJump to search
 
(103 intermediate revisions by 22 users not shown)
Line 1: Line 1:
== General information and availability ==
== General information and availability ==
=== Do I need FLTK to build ITK ? ===
No,
ITK does not require FLTK. FLTK is only used in particular demo applications in the InsightApplications directory.
ITK does not provide any GUI functionality. When building full applications, the GUI is provided by other libraries such as Qt (http://www.trolltech.com/products/qt/index.html), FLTK (http://www.fltk.org/) Gtk+ (http://www.gtk.org/) or wxWidgets (http://www.wxwidgets.org/, which used to be called wxWindows).
If you want to build the demo applications that require FLTK, you must install FLTK in your system. The recommended version is 1.1.6 that can be obtained from ftp.fltk.org and from the "RelatedSoftware" page in www.itk.org.
Once FLTK is installed in your system, you will have to enable the USE_FLTK option when you run CMake to configure InsightApplications.


=== Do I need VTK to build ITK ? ===
=== Do I need VTK to build ITK ? ===
No,
With the default configuration, ITK does not require VTK. However, some optional modules (ITKVTKGlue) do require VTK.
 
ITK does not require VTK.
 
VTK is only used by specific demo applications in the Insight/Applications directory. These applications will simply not be build if VTK is not available in your system.


ITK does not provide any visualization functionalities. Applications requiring visualization should implement those functionalities from internal code or libraries like OpenGL, GLUT or 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.
In order to use ITK with VTK you must build VTK from sources and make sure that it is configured with the flag USE_ANSI_STDLIB enabled.
Then you have to reconfigure ITK making sure that the option USE_VTK is enabled.
=== Do I need GLUT/OpenGL to build ITK ===
No,
ITK does not depend on GLUT not OpenGL.
GLUT and OpenGL are only used by specific demo applications in the Insight/Applications directory.
ITK does not provide any visualization functionalities. Applications requiring visualization should obtain these services from external libraries like OpenGL, GLUT or VTK.
=== Do I need Tcl to build ITK ===
No,
ITK does not depend on Tcl.
However, there are three ways in which ITK is related to Tcl:
# The testing system used by ITK dashboard is managed by Dart which is writen mostly in Tcl. If you want to configure experimental, continuous or nightly builds in your system using Dart. You will need Tcl installed.
# ITK can be wrapped in order to be used from Tcl.<br />This is done using "Cable". That gives ITK the versatility needed for developing rapid prototyping, and facilitating interactive teaching and experimentaion with ITK classes.
# Some demo applications in the Insight/Applications directory have configured their visualization by using VTK. These demo-applications have packaged ITK filters inside VTK filters and then wrapped those into Tcl using the traditional Tcl wrapping mechanism of VTK.
=== What version of FLTK is required by ITK demo applications ===
The recommended version of fltk is 1.1.6.
The sources can be obtained from ftp.fltk.org
        ftp://ftp.fltk.org/pub/fltk/1.1.6/
or from the "Related Software" page in www.itk.org.
FLTK is not needed for building ITK itself. FLTK is only used by
some of the demo applications distributed in InsightApplications
FLTK is in continuous development and it has been quite difficult to keep track of its configuration changes.
Also note that InsightApplications is not any more part of the core Insight Toolkit but is a standalone package.
=== What additional packages are required by each demo-application ===
The following list rapidly summarizes the additional pacakges required by demo applications in the Insight/Applications directory.
The following applications require VTK wrapped for Tcl. These applications insert ITK filters into VTK objects and then wrapp them to be used from Tcl.
* MRIRegistration
* SegmentationEditor
* vtkITK
This wrapping is done with the traditional VTK wrapping mechanism which is totally independdent of ITK mechanism based on Cable.
FLTK is used in the following demo applications to implement their GUI. The recommended version can be downloaded from http://www.itk.org/HTML/DownloadRelatedSoftware.htm
* DistanceMapFilter
* DicomImageViewer
* GaussianFilter
* GradientRecursiveGaussianFilter
* Curves2DExtractor
* Morphogenesis
* MutualInformationEuler2DRegistration
* ImageRegistration
* ImageRegistration2D
* RawImageReaderViewer
* RegionGrowingSegmentation
* ThresholdSegmentationLevelSet
* FastMarchingLevelSet
* ShapeDetectionLevelSet
* MetaImageViewer
* MetaImageColorViewer
* SurfaceGenerator
Among the applications using FLTK for GUI, the following applications also require VTK for visualizing segmented images in 3D:
* RegionGrowingSegmentation
* ThresholdSegmentationLevelSet
* FastMarchingLevelSet
* ShapeDetectionLevelSet
There is also an example of how to use Qt for GUI along with ITK:
* QtITK


=== What 3D file formats can ITK import and export? ===
=== What 3D file formats can ITK import and export? ===
Line 106: Line 10:
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.
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 InsightApplication package (fltk is required).
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"
{| border="1" cellpadding="2" cellspacing="0"
Line 118: Line 22:
| BMP  &dagger; || BMPImageIO ||
| BMP  &dagger; || BMPImageIO ||
|-
|-
| Dicom || || DicomImageIO
| DICOM || GDCMImageIO || Using DicomImageIO is backward compatible, but user should prefer GDCMImageIO
|-
|-
| GE 4x || || GE4ImageIO
| GE 4x || || GE4ImageIO
Line 131: Line 35:
|-
|-
| JPEG &dagger; || JPEGImageIO ||
| JPEG &dagger; || JPEGImageIO ||
|-
| NRRD (.nhdr/.nrrd) || NrrdImageIO ||
|-
| Nifti (.nii) || NiftiImageIO ||
|-
|-
| MetaImage (.mha/.mhd) || MetaImageIO ||
| MetaImage (.mha/.mhd) || MetaImageIO ||
Line 151: Line 59:
&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.
&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 ? ===
=== What if my file format is not supported by ITK? ===
If ITK doesn't have a specific file format reader at this point.
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.
 
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/
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/
Line 162: Line 68:
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]]
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 to read a volume from a DICOM series ===
=== 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.
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.


Line 170: Line 76:
# 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/
# 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 to write a volume as DICOM series ===
=== How do I write a volume as DICOM series? ===
Use ITK in combination with gdcm  
Use ITK in combination with gdcm  


http://www.creatis.insa-lyon.fr/Public/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.
GDCM is an open source package developed by the Creatis team at INSA-Lyon. It is distributed under a license similar to ITK.


http://www.creatis.insa-lyon.fr/Public/Gdcm/License.html
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.   
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.   
Line 185: Line 91:
Insight/Examples/IO/DicomSeriesReadImageWrite2.cxx
Insight/Examples/IO/DicomSeriesReadImageWrite2.cxx


=== Interpreted languages supported by ITK ===
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:
Currently ITK supports the following language bindings:


* Tcl
* Python  
* Python  
* Java
* Java
Java was added in February 2004, it will not be found in the ITK release 1.6. You will need a CVS checkout with a data posterior to February 25 2004.


=== How do I cite the use of ITK in a publication? ===
=== 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.
The Insight software may be cited by referencing the paper, the books, and/or the web site.


A) The paper:
A) '''The papers'''


T.S. Yoo, M. J. Ackerman, W. E. Lorensen, W. Schroeder, V. Chalana, S. Aylward, D. Metaxes, 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).
McCormick M, Liu X, Jomier J, Marion C, Ibanez L. ITK: enabling reproducible research and open science. Front Neuroinform. 2014;8:13. Published 2014 Feb 20. doi:10.3389/fninf.2014.00013


B) The books:
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"
  "Insight into Images"
Line 228: Line 149:
   ISBN:  1-930934-09-2
   ISBN:  1-930934-09-2


BiBtex citations
'''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,
   @Manual{ITKSoftwareGuide,
     Title          = {The {ITK} {S}oftware {G}uide},
     Title          = {The {ITK} {S}oftware {G}uide},
     Author        = {Ibanez, L. and Schroeder, W. and Ng, L. and Cates, J.},
     Author        = {Ibanez, L. and Schroeder, W. and Ng, L. and Cates, J.},
     Organization  = "Kitware, Inc. ISBN 1-930934-10-6",
     Organization  = "Kitware, Inc.",
    Address        = {http://www.itk.org/ItkSoftwareGuide.pdf},
     Edition        = {First},
     Edition        = {First},
     year          = {2003}
     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,
   @Manual{ITKSoftwareGuideSecondEdition,
     Title          = {The {ITK} {S}oftware {G}uide},
     Title          = {The {ITK} {S}oftware {G}uide},
     Author        = {Ibanez, L. and Schroeder, W. and Ng, L. and Cates, J.},
     Author        = {Ibanez, L. and Schroeder, W. and Ng, L. and Cates, J.},
     Organization  = "Kitware, Inc. ISBN 1-930934-15-7",
     Organization  = "Kitware, Inc.",
    Address        = {http://www.itk.org/ItkSoftwareGuide.pdf},
     Edition        = {Second},
     Edition        = {Second},
     year          = {2005}
     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) '''A specific software version'''


See:


  https://zenodo.org/record/3592082


If you have a publication that used ITK, please create a pull request to add it to ITKBibliography.bib:


C) The Web sites:
  https://github.com/InsightSoftwareConsortium/insightsoftwareconsortium.org/blob/insightsoftwareconsortium-org/citations/ITKBibliography.bib


"The Insight Segmentation and Registration Toolkit"
If you want to include ITK in an acknowledgment section, a phrase similar to the following may be used:
  www.itk.org
 
"CMake: Cross Platform Make"
  www.cmake.org
 
If you want to include ITK in an acknowledment section, a phrase similar to the following may be used:


  "This work benefited from the use of the Insight Segmentation
  "This work benefited from the use of the Insight Segmentation
Line 279: Line 220:
   open source system and it is freely available at www.cmake.org."
   open source system and it is freely available at www.cmake.org."


=== I got the message: "Could not create IO object for file" ===
=== Is ITK FDA-Approved? ===
Question:
 
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.txx
Line: 101
Description: Could not create IO object for file c:\t1.mnc
 
What is going wrong ?
 
Answer:
 
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. You must make sure that you use one of the filename extensions recognized by ITK. Please look at FAQ entry 1.7 for a full list of those extensions and associated fileformats.
 
Additional details on the ITK Input/Output architecture are available in the ITK Software Guide: http://www.itk.org/ItkSoftwareGuide.pdf.
 
 
 
=== Is ITK FDA-Approved ? ===
 
Question:
 
  Has the Insight Toolkit been FDA approved?
 
Answer:


Given the fact that ITK is a software toolkit, it cannot be the
Given the fact that ITK is a software toolkit, it cannot be the
Line 323: Line 237:


== Language bindings ==
== Language bindings ==
=== Error opening hint file NOTFOUND ===
=== 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.
When you enable "USE_VTK" in the CMake configuration of ITK, and VTK was built with wrapping, CMake looks for a "hints" file.


Line 335: Line 249:
  VTK_WRAP_HINTS:FILEPATH=/home/johndoe/src/VTK/Wrapping/hints
  VTK_WRAP_HINTS:FILEPATH=/home/johndoe/src/VTK/Wrapping/hints


== Using Insight ==
=== 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 to combine ITK and VTK in my application ===
=== 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
A full tutorial on how to combine ITK and VTK is available at
Line 346: Line 281:
You will need the auxiliary classes available at
You will need the auxiliary classes available at


   InsightApplications/Auxiliary/vtk
   ITKApps


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


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


Simply copy those files into the source code directory of your project.
=== How do I configure Emacs for ITK coding style? ===
 
For the full list of tutorials please look at
 
    http://www.itk.org/HTML/Tutorials.htm
 
 
=== Compile/Link errors involving C++ streams library ===
 
Compile and link errors involving the C++ streams library (ostream, istream, ifstream, ofstream, etc.) are usually the result of collisions between the old and new streams library. The C++ streams library in the Standard Library is different and usually imcompatible with the original C++ streams library. The new streams library is share the same class names as the old streams library but has a very different implementation (templates, thread safety, etc.). ITK can only be built using the Standard Library streams library.
 
If the compile/link error is in an ITK file, the solution is usually to include the proper stream header file, i.e. <fstream> before any other include file. The forces the streams library used by all subsequent headers to be the Standard Library version.
 
If the compile/link error is in an application that is trying to use ITK, the solution is usually to include an ITK header file before any other include file. This forces whatever include files that the application may use to use the Standard Library streams library.
 
=== What is the difference between the CMake options ITK_WRAP_TCL and VTKITK_WRAP_TCL ? ===
 
ITK_WRAP_TCL enables the official method of wrapping ITK into Tcl. This wrapping requires the installation of two external packages: Cable and GCC_XML. Information about these packages can be found at http://public.kitware.com/Cable/HTML/Index.html and http://www.gccxml.org/HTML/Index.html
 
VTKITK_WRAP_TCL is not really part of ITK. It is only required to enable the build of some demo-applications in the Insight/Applications directory. These applications use VTK for visualization. ITK filter are packaged here inside VTK classes that are subsequently wrapped for Tcl using the traditional VTK wrapping mechanism (not Cable).
 
=== EMACS configuration file : ITK coding style ===
You can add the following codes into your .emacs file
You can add the following codes into your .emacs file


Line 394: Line 308:
  ;;;;;;;;;;;
  ;;;;;;;;;;;


=== VIM configuration file : ITK coding style ===
=== How do I configure VIM for ITK coding style? ===
for all of you who use VIM, here are just couple of things:


  set tabstop=2 " Tabs are two characters
  set tabstop=2 " Tabs are two characters
Line 403: Line 316:
  set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1 " ITK/VTK style indenting
  set cinoptions={1s,:0,l1,g0,c0,(0,(s,m1 " ITK/VTK style indenting


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


This was contributed by Andy Cedilnik @kitware.com
This was contributed by Andy Cedilnik @kitware.com


=== FLTK_WRAP_UI called with FLTK_WARP_UI undefined ===
If you'd like to enable c++ style syntax highlight for *.txx files, put the following lines in your .vimrc file:
I use CMake to build the InsightApplications and the following error appears:
  syntax on
 
  au BufNewFile,BufRead *.txx set filetype=cpp
CMake Error: Error in cmake code at
../../CMakeLists.txt:20:
FLTK_WRAP_UI called with FLTK_WARP_UI undefined
 
I wonder where and how to define it.
 
This error message
 
"...FLTK_WARP_UI undefined"
 
appears when you have missed to specify some of the FTLK components.
 
Please run Cmake again, pass to "Advanced" mode and double check that you provided the right paths for the following components
 
* FLTK_BASE_LIBRARY
* FLTK_FLUID_EXECUTABLE
* FLTK_FORMS_LIBRARY
* FLTK_GL_LIBRARY
* FLTK_INCLUDE_DIR
 
Here is for example how they look in a typical Windows installation:
 
FLTK_BASE_LIBRARY      C:/cygwin/home/ibanez/src/fltk-1.1.4/lib/fltkd.lib
FLTK_FLUID_EXECUTABLE  C:/cygwin/home/ibanez/src/fltk-1.1.4/fluid/fluidd.exe
  FLTK_FORMS_LIBRARY      C:/cygwin/home/ibanez/src/fltk-1.1.4/lib/fltkformsd.lib
  FLTK_GL_LIBRARY        C:/cygwin/home/ibanez/src/fltk-1.1.4/lib/fltkgld.lib
FLTK_IMAGES_LIBRARY    C:/cygwin/home/ibanez/src/fltk-1.1.4/lib/fltkimagesd.lib
FLTK_INCLUDE_DIR        C:/cygwin/home/ibanez/src/fltk-1.1.4
 


Here is an example for a Linux installation


FLTK_BASE_LIBRARY      /home/ibanez/local/lib/fltk.a
=== What is the "ITK_TEMPLATE_VISIBILITY_DEFAULT" CMake option? ===
FLTK_FLUID_EXECUTABLE  /home/ibanez/local/bin/fluid
FLTK_FORMS_LIBRARY      /home/ibanez/local/lib/fltk_forms.a
FLTK_GL_LIBRARY        /home/ibanez/local/lib/fltk_gl.a
FLTK_IMAGES_LIBRARY    /home/ibanez/local/lib/fltk_images.a
FLTK_INCLUDE_DIR        /home/ibanez/local/include
 
Note that FLTK on Unix/Linux *MUST* be installed. The reason is that FLTK
has an inconsitent convention for the use of upper/lower case in file names
and resolved this inconsistency by duplicating *ALL* the headers' filenames
with symbolic links. These links are created during the installation process.
If you don't install FLTK, you will not be able to find the headers because
the case will not match the #includes in ITK.
 
 
=== Find library for a given class ===
 
Assume you are using some class in your program and would like to know which library you have to link to your program... Unfortunately there is not a direct way of finding in what library you will find a class. The rule of thumb is that ITK creates a library per each one of the directories in
 
                        Insight/Code/
 
and the library name matches the directory name, like ITKCommon, ITKAlgorithms, ITKBasicFilter...
 
Let the symbol that you are looking for be itk::NumericTraits<float>::One, the itkNumericTraits.cxx file is located in Insight/Code/Common, so you will find the symbol in ITKCommon.lib.
 
              find . -name "*NumericTraits*"
 
would have led you to the "Insight/Code/Common" directory, and therefore gave you the hint of using the ITKCommon library.


== Platform-specific questions ==
== Platform-specific questions ==
=== Build->Rebuild All in MS VC++ reloads all projects ===
=== How do I avoid multiple prompts to reload all projects in Microsoft Visual Studio? ===
When performing a "Rebuild All" from Microsoft Visual C++, every project prompts the user for a reload (and there are hundreds of projects).
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.
DO NOT USE "Rebuild All" or "Batch Build". Use the following recommended procedure.
Line 481: Line 337:
This can also be done from the command line like this: msdev ITK.dsw /MAKE "ALL_BUILD - Debug" /REBUILD
This can also be done from the command line like this: msdev ITK.dsw /MAKE "ALL_BUILD - Debug" /REBUILD


=== Highlighting .txx files in Visual Studio ===
== Contribute ==
 
=== How do I make code contributions to ITK? ===
How can I get Visual Studio to do syntax hightlighting in the files with extension .txx ?
Please see this page: [[ITKContribute]].
 
There are four ways to do this:
 
# The <b>WRONG</b> way
# The <b>DANGEROUS</b> way
# The <b>NICE</b> way
# The <b>OPEN SOURCE</b> way
 
==== The WRONG way ====
 
The <b>WRONG</b> is to mark the .txx files as "Compilable". This is WRONG because the .txx files are only intended to be compiled when they are invoked from a .cxx file. Doing this will result in errors such as the ones reported in.
 
  http://public.kitware.com/pipermail/insight-users/2005-December/015847.html
 
which after many email exchanges were identified
 
  http://public.kitware.com/pipermail/insight-users/2005-December/015905.html
 
==== The DANGEROUS way ====
 
The <b>DANGEROUS</b> way is to make changes in the Windows Registry entries of Visual Studio.
 
http://public.kitware.com/pipermail/insight-users/2005-November/015785.html
 
You should avoid doing this since it brings *Bad Karma*. Once you touch the Windows Registry, the consequences will follow you in the afterlife (regardless of whether you believe in the afterlife or not).
 
==== The NICE way ====
 
This thread for VS8 does not work:
 
http://public.kitware.com/pipermail/insight-users/2005-November/015786.html
 
Go the OPEN SOURCE way.
 
==== The OPEN SOURCE way ====
 
STOP Using the Visual Studio editor, behave as a real programmer and use a decent source code editor such as VIM or EMACS. You can configure these editors to be the default editor used by the Visual Studio IDE.
 
=== Borland 5.5 Compiler Issues ===
To build Insight using the (free) Borland 5.5 compiler:
 
# Get the Borland compiler from http://www.borland.com and install it
# Run cmakesetup and select the Borland Makefiles in the "Build For:" drop down.
# Set the CMAKE_BUIlD_TYPE to MinSizeRel. This is required so that the Borland linker will stay below its size limit which is arounbd 35 meg for a tds file.
 
=== Borland 5.6 Compiler Issues ===
Well ITK simply does not support this compiler at all.
 
=== Windows + FLTK: unresolved external symbol TrackMouseEvent ===
This error is due to changes in FLTK and it is totally unrelated to ITK. The error only appears in ITK demo applications that are using FLTK for GUI.
 
The library "comctl32" must be added to the link command line.
 
You can solve this by editing the CMake file: CMake/Modules/FindFLTK.cmake and around line 39 add the comctl32 library.
 
After the change the lines should look like:
 
IF(WIN32)
  SET( FLTK_PLATFORM_DEPENDENT_LIBS wsock32 comctl32 )
ENDIF(WIN32)
 
This is already fixed in the CVS version of CMake FindFLTK.cmake.
 
The CMake version 1.6 will have this issue solved.
 
===Mac OS X ===
 
====Getting Shared Libraries to work====
There is a problem with the Mac OSX tool chain that prevents shared libraries
from working.  Fortunately, the Mac folks have fixed the problem.  You have to
update xcode, the compiler and as much stuff as possible, and it will work
again, after you start from a clean build.
 
If gcc -version reports any thing less than 3.3 build 1671, then you should update the compiler.
From the apple developers download http://developer.apple.com/macosx/download/ you have to login to get the November2004GCCUpdater.   
 
 
====Under Mac OS X, when I try to run a program that builds successfully, the window is displayed but I can't interact with it.====
 
This is caused by the fact that the application needs to be registered with the window manager for correct operation.  There is an additional step that needs to be performed ''after'' the link step, in order to add the required resources to the binary.  This can be done with a simple:
 
% /Developer/Tools/Rez Carbon.r -o myapp
 
For apps built with FLTK, you can use:
 
% /Developer/Tools/Rez /usr/local/include/FL/mac.r -o myapp
 
Here is an example of adding a custom command to do this automagically in your `CMakeList.txt` file:
 
IF(APPLE)
  FIND_PROGRAM(APPLE_REZ Rez /Developer/Tools)
  ADD_CUSTOM_COMMAND(TARGET MyApplication
    POST_BUILD
    COMMAND ${APPLE_REZ}
    ARGS ${FLTK_INCLUDE_DIR}/mac.r -o MyApplication)
ENDIF(APPLE)
 
'''Note:''' This is ''not'' required for applications build against X libraries; only for Carbon-based applications.  If you have built FLTK for X rather than Carbon, the above does not apply.
 
(Gavin Baker, 7-May-2004)
 
=== How to set Windows DLL's on the Path ===
 
==== In Windows 95 and 98 ====
 
# Click on the "Start" button on the task bar.
# Click on the "Run..." button
# Type "sysedit".  This is the editor of the system files, including the "autoexec.bat"
# If you have already a PATH variable, then add the directory where the ITK DLLs are to that list. Use ";" as separators
# If you don't have a PATH variable.... well... add one and put your directory there. It should look like
 
  PATH=C:\itkbin\bin\Release\
 
==== In Windows XP Method A ====
 
# Go to "Control Panel"
# Select "System",
# Take the "Advanced" tab
# Click on the button "Environment Variables" on the bottom,
# Select "PATH"
# Add the full directory where you have your ITK .dlls. Pay attention to whether they are in the Release or Debug subdirectories.
 
==== In Windows XP Method B ====
 
# Right-Click on "My Computer" ( a popup menu should appear, the last option on it is "properties")
#Select "properties" a new popup window appears with some tabs on it.
# Select the tab "Advanced"
# At the bottom you will se a button called "Environment Variables". Click on it.
# A new popup window appears with a small browser with the list of environment variables. In this browser you will see the list of environment variables.
# Select "path" and click on the "edit" button. A small new popup appears with two text fields: "Variable name" and "Variable value".
# Go to the "Variable value" field, move to the end, add a ";" separator and type the directory where you have the VTK or ITK Dlls.
# Add another ";" separator and type the directory where you have the ITK Dlls.
# Click on "OK" to close the "Edit User Variable" window.
# Click on "Ok" on the "Environment Variables" window.
# Click on "Ok" on the "System Properties window".
# Take a deep breath, cross you fingers and try to execute your program again.
 
==== Maximum Path Length ====
http://support.microsoft.com/default.aspx?scid=kb;en-us;830473
 
maximum path length:
Windows XP:            8191 characters
Windows 2000 or NT 4.0: 2047 characters.
 
description:
This limitation applies to the command line, individual environment variables (such as the PATH variable) that are inherited by other processes, and all environment variable expansions. If you use Command Prompt to run batch files, this limitation also applies to batch file processing.
 
solutions:
  • Modify programs that require long command lines so that they use a file that contains the parameter information, and then include the name of the file in the command line.
 
  For example, instead of using the ExecutableFile.exe Parameter1 Parameter2 ...ParameterN command line in a batch file, modify the program to use a command line that is similar to the following command line, where ParameterFile is a file that contains the required parameters (parameter1 parameter2 ...ParameterN):
ExecutableFile.exe c:\temp\ParameterFile.txt
  • Modify programs that use large environment variables so that the environment variables contain less than either 2047 or 8191 characters (as appropriate to your operating system).
 
  For example, if the PATH environment variable contains more than either 2047 or 8191 characters (as appropriate to your operating system), use one or more of the following methods to reduce the number of characters:
  • Use shorter names for folders and files.
  • Reduce the depth of folder trees.
  • Store files in fewer folders so that fewer folders are required in the PATH environment variable.
  • Investigate possible methods that you can use to reduce the dependency of PATH for locating .dll files.
 
work around for a given executable:
  copy the dlls into the executable directory
 
=== Visual Studio 6 Compiler Issues ===
 
ITK requires service pack 5 or higher to build with Visual Studio 6.  However, there are still some code patterns occasionally encountered when using ITK code that cause an INTERNAL COMPILER ERROR.  Here is a minimal example of code that reproduces the ICE:
 
<pre><nowiki>
namespace N { template <class T> struct C {}; }
template <class T> struct A
{
  // Inside this template we refer to another template in another namespace.
  void m(const N::C<int>&);
};
 
// Now declare a class template using a non-type template parameter.
template <unsigned int V> struct B;
</nowiki></pre>
 
The above code results in an ICE reported from line 1794 of msc1.cpp.
The work-around is to use a typedef to refer to the other template:
 
<pre><nowiki>
namespace N { template <class T> struct C {}; }
template <class T> struct A
{
  typedef N::C<int> NCint;
  void m(const NCint&);
};
template <unsigned int V> struct B;
</nowiki></pre>
 
Here is another example causing a crash in the same place:
 
<pre><nowiki>
// Create a class template that has type and non-type arguments with defaults.
template <class T=int, int N=1> class A {};
 
// Require the compiler to deduce the arguments for a specific instantiation.
template <class T, int N> void f(A<T,N>) {}
void g() { f(A<int,1>()); }
</nowiki></pre>
 
The work-around is unforunately to not have the first default template argument:
 
<pre><nowiki>
template <class T, int N=1> class A {};
template <class T, int N> void f(A<T,N>) {}
void g() { f(A<int,1>()); }
</nowiki></pre>
 
There are other code patterns that cause the same error.  If you find one please try to produce a minimal example and add it to this page.
 
==== Visual Studio 6 Compiler : Why you should not use it ====
 
Visual Studio 6 is becoming a really old compiler if you are thinking of using it for your project be ready to bang your head against the wall.
Anyway if you have to use it, here are some fixes to the compiler include file (mostly STL related):
 
* [http://www.dinkumware.com/vc_fixes.html Fixes for Library Bugs in VC++ V5.0/V6.0]
* [http://www.acceleratedcpp.com/details/msbugs.html Known problems in using the Microsoft Visual C++ compiler, version 6.0]
 
=== Visual Studio 7 .NET 2002 Compiler Issues ===
 
The Visual Studio 7.0 compiler is more similar to the version 6 compiler than the version 7.1 compiler from the C++ conformance perspective.  While it does not crash as frequently as version 6, there are some code patterns that still cause an INTERNAL COMPILER ERROR.  Here is one example:
 
<pre><nowiki>
// Define a class template that has a data member of the template type.
template <class T> struct A { T v; };
 
// Define a primary template with no members.
template <class T> struct B {};
 
// Define a specialization that defines a type.
// This line is not actually necessary to cause the ICE but will be present when this problem is encountered in practice.
//template <> struct B<int> { typedef int Type; };
 
template <class T> struct C
{
  // Lookup the "Type" member of B<T>.  In practice this will reference a specialization.
  typedef typename B<T>::Type Type;
 
  // Use the result of the lookup to instantiate A<> and its data member.
  typedef typename A<Type>::A AType;
};
</nowiki></pre>
 
This will cause an ICE in msc1.cpp, line 2844.  The work-around is to define the "Type" member in the primary template of B even though it will not be used:
 
<pre><nowiki>
template <class T> struct A { T v; };
template <class T> struct B { typedef T Type; };
template <class T> struct C
{
  typedef typename B<T>::Type Type;
  typedef typename A<Type>::A AType;
};
</nowiki></pre>
 
=== MipsPro Compilers (7.3.3.1m and 7.4.2m) on IRIX ===
 
There have been reports of problems building ITK on IRIX platform.  Here are the compiler flags that are used to build ITK and submit nightly dashboard results.  SGI Flags for both 7.3.3.1m and 7.4.2m compilers that are working for the kraepelin.uiowa nightly builds.
 
DEBUG BUILD:
//No help, variable specified on the command line.
CMAKE_CXX_FLAGS:STRING= -n32 -g -DUDEBUG -G0 -multigot  -no_auto_include  -xansi -LANG:std -LANG:ansi-for-init-scope=ON -woff  15,84,1110,1209,1424,1468,3102,3210,3439
 
//No help, variable specified on the command line.
CMAKE_C_FLAGS:STRING= -n32 -g -DUDEBUG -G0 -multigot  -xansi -woff  15,84,1110,1209,1424,1468,3102,3210,3439
 
OPTIMIZED BUILD:
CMAKE_CXX_FLAGS:STRING= -n32 -O3 -DNDEBUG -G0 -multigot  -no_auto_include  -xansi -LANG:std -LANG:ansi-for-init-scope=ON  -woff  15,84,1110,1209,1424,1468,3102,3210,3439
 
//No help, variable specified on the command line.
CMAKE_C_FLAGS:STRING= -n32 -O3 -DNDEBUG -G0 -multigot  -xansi -woff 15,84,1110,1209,1424,1468,3102,3210,3439


== Testing ==
== Testing ==
=== Is ITK tested regularly? ===
=== Is ITK tested? ===
ITK is tested throughout the day on machines distributed around the world. You can view the results at: http://public.kitware.com/Insight/Testing/HTML/TestingResults/Dashboard/MostRecentResults-Nightly/Dashboard.html
Please see this page: [[ITK/Testing]]


ITK uses Dart to perform builds, run tests and generate dashboards. You can find more information about Dart at http://www.itk.org/Dart/
== Working with Image Data ==


=== What is the testing schedule? ===
===How do I iterate through all the pixels in an image?===
Dart opens a daily dashboard at 1:00AM Eastern Daylight Time and keeps that dashbooard open for 24 hours. Build/Test results submitted as "nightlies" will appear on the currently opened dashboard. Each test site can select a convenient time to run tests.


Fresh dashboards are generated every hour, on the hour. They can also be generated on demand using the Rollup button on the dashboard. This button should be used sparingly since dashboard rollups can be time consuming.
Please see this example: http://www.itk.org/Wiki/ITK/Examples/Iterators/ImageRegionIterator of itkImageRegionIterator.


In addition to nightly testing, several sites run Continuous build/tests. These sites monitor cvs repository activity and begin a build/test sequence if there are updates to the repository. If a compile error is detected, the Dashboard server sends email to the "offending" party.
===What are Hounsfield Units?===


=== What kind of testing is performed? ===
Hounsfield units were defined by Sir Godfrey N. Hounsfield, on of the pioneers of Computer Tomography for clinical applications.
ITK has three types of tests:


# Unit Tests. Also called white box tests. These tests reside in the Testing/Code/XXX directories. There are meant to exercise a class's methods and verify that the code compiles, links and produces expected results. These tests do not need to produce results that are useful to a user. If a test returns a 0 status, it passes. A test fails if it returns a non-zero status.
The units represent the linear attenuation of X-Rays for a particular material.  
# Blackbox Tests. These tests are automatically (or semi-automatically) generated. For example, each Code directory has a test called itkXXXHeaderTest. This test is automatically created and has a "#include" for each file in the directory.
# Regression Tests. These tests generate results and compare them with a known result. The purpose of regression testing is to detect changes in the output of the system.  


=== How Do I Add a Test? ===
The units scale is defined in such a way that level for Water is 0 and the level for Air is -1000.


=== What is a continuous build and how can I contribute one? ===
The attenuation of any other material is mapped linearly into this range.
Continuous builds run throughout the day and report their output in the Continuous Builds portion of the dashboard. The most recent build is at the top of the list. The builds run periodically and check the status of the repository. If a file is added or changed since the last build, the working repository of the continuous build is updated, the code compiled and tests executed. Optional e-mail norifications can be sent if there are errors, warmings or test failures.


You can set up a continuous build. This entails writing some small shell scripts and setting up a scheduler (Scheduler for Windows, cron for Linux/Unix). You will also need to install tcl, checkout Dart and configure your build for testing.
A table of Hounsfield units for common human tissues is avalable in the following link [[ITK Hounsfield Units]]
 
For Windows 2000, here are three batch files that can be modified for your own environment.
 
AllowInsightContinuous.bat
BuildInsightContinuous.bat
PreventInsightContinuous.bat


The batch files use a lock to prevent/allow the continuous
===What are MRI T1 / T2 Units?===


rem ************* AllowInsightContinuous.bat
MRI images measure two types of relaxation times.  
rem Allow the Continuous to run
rem
c:
cd c:\lorensen\InsightContinuous\Insight-VC6
if EXIST continuous.lock (
  del continuous.lock
)
cd ..
rem ************* BuildInsightContinuous.bat
rem DO a C++ Build Continuously
rem
c:
rem Setup proxy it behind a firewall
set HTTP_PROXY=webcache
set HTTP_PROXY_PORT=8080
rem
rem Setup the path
rem
set PATH=c:/lorensen/InsightContinuous/Insight-VC6/bin/Release;%PATH%
rem
rem Tell cvs where .cvspass resides
set HOME=c:/lorensen
cd c:\lorensen\InsightContinuous\Insight-VC6
if EXIST continuous.lock (
  exit /B
) else (
  date /T > continuous.lock
  time /T >> continuous.lock
  cd c:\lorensen\InsightContinuous\Insight-VC6
  tclsh83 c:/lorensen/Dart/Source/Client/DashboardManager.tcl DartConfiguration.tcl Continuous Start Update Configure Build Test Submit
  cd c:\lorensen\InsightContinuous\Insight-VC6
  del continuous.lock
  cd ..
)
rem ***************** PreventInsightContinuous.bat
rem Prevent the Continuous
rem
c:
cd c:\lorensen\InsightContinuous\Insight-VC6
if EXIST continuous.lock (
  exit /B
) else (
  echo "Prevent continuous for nightly" > continuous.lock
)
cd ..


Now you need to establish a schedule for the three batch jobs. Use the "Scheduled Tasks" on the "Control Panel" to access the Schedule Task Wizard. The following schedule runs the continuous every 10 minutes from 6:05AM until 12:00AM. The Allow and Prevent scripts turn the build ON/OFF at the appropriate time. Schedule each batch file as follows:
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.
 
AllowInsightContinuous.bat - Daily, Start 6:00AM
BuildInsightContinuous.bat - Daily, Start 6:05AM, Advanced: Repeat Task every 10 minutes, duration 17 hours and 55 minutes
PreventContinuous.bat - Daily, Start 12:00AM
 
 
== Working with Image Data ==


===How do I iterate through all the pixels in an image?===
Details on the MRI units are available in the Wikipedia:


This requires the use of image iterators, which is explained in detail in the SoftwareGuide in Chapter 11, pdf-page 481.
[http://en.wikipedia.org/wiki/Relaxation_%28NMR%29 Relaxation (NMR)]


Examples are available in `Insight/Examples/Iterators`.  You probably want to use the [http://www.itk.org/Insight/Doxygen/html/classitk_1_1ImageSliceIteratorWithIndex.html ImageSliceIterator].
=== DICOM: Bits Allocated, Bits Stored and High Bit ===


(Luis Ibanez, 7-Jun-2004)
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.


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


Hounsfield units were defined by Sir Godfrey N. Hounsfield, on of the pioneers of Computer Tomography for clinical applications.
                          |<------------------ pixel ----------------->|
            ______________ ______________ ______________ ______________
          |XXXXXXXXXXXXXX|              |              |              |
          |______________|______________|______________|______________|
            15          12 11          8 7            4 3            0
</pre>


The units represent the linear attenuation of X-Rays for a particular material.
Here is what you generally get after writing by GDCM:
<pre>
        Bits Allocated = 16
        Bits Stored    = 16
        High Bit      = 15


The units scale is defined in such a way that level for Water is 0 and the level for Air is -1000.
            |<------------------------- pixel ------------------------>|
            ______________ ______________ ______________ ______________
          |              |              |              |              |
          |______________|______________|______________|______________|
            15          12 11          8 7            4 3            0
</pre>


The attenuation of any other material is mapped linearly into this range.
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.


A table of Hounsfield units for common human tissues is avalable in the following link [[ITK Hounsfield Units]]
=== I'm working with DICOM images, where can I find more information? ===
[[ITK/DICOM]]


== Data Display ==
== Data Display ==
Line 874: Line 415:
===What imaging software is available for displaying medical image files?===
===What imaging software is available for displaying medical image files?===


Here are some viewing options for the image fileformats supported in ITK:                                                 
Please see the [[ITK/Third_Party_Applications | third party applications]] page for visualization applications that used ITK to perform Image reading/writing.
 
1. Scalar images:
 
* InsightApplications/ImageViewer
* [http://www.paraview.org ParaView]
* For 3D images: [http://www.kitware.com/products/volview.html VolView]
* [http://rsb.info.nih.gov/ij/ ImageJ]
 
2. Color Images:
 
* InsightApplications/ColorImageViewer
* [http://www.paraview.org ParaView]
* For 3D images: [http://www.kitware.com/products/volview.html VolView]
 
3. Vector Images:
 
* [http://www.paraview.org ParaView] (glyphs, streamlines, composites).


===When I view the output of my program, all I see is a black image. What went wrong?===
===When I view the output of my program, all I see is a black image. What went wrong?===
Line 911: Line 435:
Examples on multimodality registration are available in `Insight/Examples/Registration`.  A demo application using Mutual Information is available under `InsightApplications/LandmarkInitializedMutualInformationRegistration`.
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 before you get involved with image
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.
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].
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)
(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}}
{{ITK/Template/Footer}}

Latest revision as of 21:42, 6 February 2020

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.

File Format Read/Write Import
Analyze 7.5 AnalyzeImageIO
BMP † 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 † JPEGImageIO
NRRD (.nhdr/.nrrd) NrrdImageIO
Nifti (.nii) NiftiImageIO
MetaImage (.mha/.mhd) MetaImageIO
PNG † PNGImageIO
Raw ‡ RawImageIO
Siemens Vision SiemensVisionImageIO
Stimulate (spr/sdt) StimulateImageIO
TIFF TIFFImageIO
VTK Structured Points VTKImageIO

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

‡ 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: What image file formats can VTK read and write? and 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.

  1. 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.
  2. Write a MetaImageHeader
    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.
    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.
  3. Use MRIConvert
    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).
    She graciously has made this application publicly available at: http://lcni.uoregon.edu/~jolinda/MRIConvert There is a fresh version updated in april 14th.
  4. Jeff Brubaker and Stephen R. Aylward, at the UNC
    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 papers

McCormick M, Liu X, Jomier J, Marion C, Ibanez L. ITK: enabling reproducible research and open science. Front Neuroinform. 2014;8:13. Published 2014 Feb 20. doi:10.3389/fninf.2014.00013

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 = Template: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 = Template: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},
   }
 @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},
   }
 @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},
   }

C) A specific software version

See:

 https://zenodo.org/record/3592082

If you have a publication that used ITK, please create a pull request to add it to ITKBibliography.bib:

 https://github.com/InsightSoftwareConsortium/insightsoftwareconsortium.org/blob/insightsoftwareconsortium-org/citations/ITKBibliography.bib

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, ...)

How do I use ITK from C# .NET?

There are currently three options:

  1. Use ManagedITK
    • NOTE: This option is not recommended as the project is no longer supported
  2. Use the 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 here (valid Sept 2012)
  3. 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 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


What is the "ITK_TEMPLATE_VISIBILITY_DEFAULT" CMake option?

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:

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:

        Bits Allocated = 16
        Bits Stored    = 12
        High Bit       = 11

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

Here is what you generally get after writing by GDCM:

        Bits Allocated = 16
        Bits Stored    = 16
        High Bit       = 15

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

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

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 the overview.

(Luis Ibanez, 7-June-2004)

Common Problems

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: [Welcome | Site Map]