ITK/FAQ

From KitwarePublic
< ITK
Revision as of 12:02, 21 July 2004 by Gavinb (talk | contribs) (Added q+a's from antonym)
Jump to navigationJump to search

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 recomended version is 1.1.3 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 ITK.

Do I need VTK to build ITK ?

No,

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.

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:

  1. 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.
  2. ITK can be wrapped in order to be used from Tcl.
    This is done using "Cable". That gives ITK the versatility needed for developing rapid prototyping, and facilitating interactive teaching and experimentaion with ITK classes.
  3. 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.3.

The sources can be obtained from ftp.fltk.org or from the "Related Software" page in www.itk.org.

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?

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

A very nice tool for viewing all of these images is ImageViewer which can be found in the InsightApplication package (fltk is required).

File Format Read/Write Import
Analyze 7.5 AnalyzeImageIO
Dicom DicomImageIO
GE 4x GE4ImageIO
GE 5x GE5ImageIO
GE Advantage Windows GEAdwImageIO
Gipl (.gipl) GiplImageIO
IPLCommon IPLCommonImageIO
JPEG JPEGImageIO
MetaImage (.mha/.mhd) MetaImageIO
PNG † PNGImageIO
Raw ‡ RawImageIO
Siemens Vision SiemensVisionImageIO
Stimulate (spr/sdt) StimulateImageIO
TIFF TIFFImageIO
VTK Structured Points VTKImageIO

† PNG is not a very good format. At this point it only supports 2D images and only pixel types unsigned char, and unsigned short. The great advantage of PNG is that you can view it with almost any image viewer.

‡ This 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 to read a volume from a DICOM series

  1. 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.
  2. 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.
  3. 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/

Interpreted languages supported by ITK

Currently ITK supports the following language bindings:

  • Tcl
  • Python
  • 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?

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

B) The books: 

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

"The ITK Software Guide"
 Ibanez, Schroeder, Ng, Cates.
 published by Kitware Inc.
 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

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

I got the message: "Could not create IO object for file"

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.

Language bindings

Error opening hint file NOTFOUND

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

Using Insight

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 

;;;;;;;;;;;;;;
(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))
;;;;;;;;;;;

VIM configuration file : ITK coding style

for all of you who use VIM, here are just couple of things: 

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

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

This was contributed by Andy Cedilnik @kitware.com

FLTK_WRAP_UI called with FLTK_WARP_UI undefined

I use CMake to build the InsightApplications and the following error appears: 

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:FILEPATH=E:/cygwin/home/ibanez/src/fltk-1.1.3/lib/fltkd.lib
FLTK_FLUID_EXECUTABLE:FILEPATH=E:/cygwin/home/ibanez/src/fltk-1.1.3/fluid/fluidd.exe
FLTK_FORMS_LIBRARY:FILEPATH=E:/cygwin/home/ibanez/src/fltk-1.1.3/lib/fltkformsd.lib
FLTK_GL_LIBRARY:FILEPATH=E:/cygwin/home/ibanez/src/fltk-1.1.3/lib/fltkgld.lib
FLTK_IMAGES_LIBRARY:FILEPATH=E:/cygwin/home/ibanez/src/fltk-1.1.3/lib/fltkimagesd.lib
FLTK_INCLUDE_DIR:PATH=E:/cygwin/home/ibanez/src/fltk-1.1.3

Platform-specific questions

Build->Rebuild All in MS VC++ reloads all projects

When performing a "Rebuild All" from Microsoft Visual C++, every project prompts the user for a reload (and their are hundreds of 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

Borland 5.5 Compiler Issues

To build Insight using the (free) Borland 5.5 compiler:

  1. Get the Borland compiler from http://www.borland.com and install it
  2. Run cmakesetup and select the Borland Makefiles in the "Build For:" drop down.
  3. 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.

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.

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 applcations 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)


Testing

Is ITK tested regularly?

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

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

What is the testing schedule?

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.

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 kind of testing is performed?

ITK has three types of tests:

  1. 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.
  2. 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.
  3. 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?

What is a continuous build and how can I contribute one?

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.

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 

rem ************* AllowInsightContinuous.bat
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: 

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?

This requires the use of image iterators, which is explained in detail in the SoftwareGuide in Chapter 11, pdf-page 481.

Examples are available in `Insight/Examples/Iterators`. You probably want to use the ImageSliceIterator.

(Luis Ibanez, 7-Jun-2004)

Data Display

What imaging software is available for displaying medical image files?

Here are some viewing options for the image fileformats supported in ITK:

1. Scalar images:

2. Color Images:

3. Vector Images:

  • ParaView (glyphs, streamlines, composites).

(Luis Ibanez, 9-Jun-2004)

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

Retrieved from "https://public.kitware.com/Wiki/index.php?title=ITK/FAQ&oldid=82"