SimpleITK/FAQ
This page hosts frequently asked questions about SimpleITK, and their answers.
Download
Where is the Input Data? or Why is my Testing/Data directory empty?
The testing data should reside in the source directory under the "Testing/Data" directories. If this directory is empty you likely downloaded the source code with "git clone". The data is stored as a git submodule . There are two common methods to download this submodule repository.
The first method is to download the data at the same time as you are downloading the source directory. When you are initially cloning the SimpleITK repository, you can recursively clone the submodules with the following command:
git clone --recursive http://itk.org/SimpleITK.git
If you forgot to include the "--recursive" argument when you cloned SimpleITK, or if your git version is so old that it doesn't support the "--recursive" option, then the following two commands should download that data:
$ git submodule init Submodule 'Testing/Data' (git://itk.org/SimpleITKData.git) registered for path 'Testing/Data' $ git submodule update Initialized empty Git repository in /Volumes/Home/Users/blowekamp/temp/SimpleITK/Testing/Data/.git/ remote: Counting objects: 290, done. remote: Compressing objects: 100% (182/182), done. remote: Total 290 (delta 106), reused 290 (delta 106) Receiving objects: 100% (290/290), 19.89 MiB | 2.76 MiB/s, done. Resolving deltas: 100% (106/106), done. Submodule path 'Testing/Data': checked out 'f4f1faf6e60696bed8282758e49a95779ad15e0d'
Why are so many tests failing?
The most common cause of a large number of failures is that the data submodule has not been downloaded or updated.
If the subdirectory "Testing/Data" is empty, then the data submodule has not been initialized and downloaded. Please follow the instructions to rectify the situation.
To check if the data submodule is out of date the following command can be run:
$ git status # On branch master # Changed but not updated: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: Testing/Data (new commits) #
The git suggestion is unfortunately not too helpful here. This message indicates that the data submodule needs to be updated with the following command:
$ git submodule update
If you have your data submodule up to date and the tests are still failing, it is likely there is a more complicated configuration problem.
Compilation
Is my compiler supported?
SimpleITK uses advanced C++ meta-programming to instantiate ITK's Images and Filters. Addtionally, we use some headers which are included in the C99 and C++ TR1 extension. Therefore SimpleITK places additional requirements on the compiler beyond what is required for ITK. In principle we require C++x03 with C99's "stdint.h" and TR1's "functional". If your compiler has those features it is likely able to be supported.
The additional requirement for a supported compiler is that it is on the nightly dashboard. With this regard, the list of supported compilers is on the SimpleITK SimpleITK dashboard. We welcome user contributions to the nightly dashboard to expand the list of supported compilers.
Committed to Support
- GCC 4.0
- GCC 4.2
- GCC 4.5
- Visual Studio 10 ( including Express )
- Visual Studio 9 with Service Pack 1
Prior Release Problems
- Please note that with SimpleITK release 0.4.0, Visual Studio 2008 was not compiling. This problem has since been remedied in the development branch on April 18th, 2012.
Do I need to download an option package for TR1 support?
Visual Studio 2008 requires an additional download for TR1 support. This support is best provided with the Service Pack 1. There is a separate TR1 feature pack which can be downloaded, but it is no longer recommended since Service Pack 1 includes TR1 and numerous bug and performance improvements.
Do I need to download an optional package for C99?
Visual Studio 2008 requires an additional download for C99 stdint support.
How do I build with Visual Studio 2008?
Visual Studio 2008 is the oldest supported Microsoft development environment that SimpleITK supports. To build SimpleITK, certain features of C++TR1 are required. These features are best provided by the "Microsoft Visual Studio 2008 Service Pack 1". Alternatively just the Visual C++ 2008 Feature Pack Release can be installed. Please note that all our dashboard machines now use SP1.
Visual Studio also requires an implementation of stdint.h, which can be downloaded here. For 64-bit Microsoft Windows it should be dragged with the gui to thone of the following locations in a 64-bit system:
C:\Program Files\Microsoft Visual Studio 9.0 (x86)\VC\include
While on 32-bit operating systems it should be install here:
C:\Program Files\Microsoft Visual Studio 9.0\VC\include
Please note that some times a web browser will automatically add a ".txt" extension. After the file is saved it would be wise to check the file's properties to verify that the it has the correct ".h" file extension along with the file permissions.
What Configurations on Windows are Supported For Building?
There are quite a large number of configuration options available for the Windows platform. The following table is a guide line of what is regularly tested and confirmed to work or fail.
| Architecture | Library Type | Visual Studio 2008 SP1 VS9 ) | Visual Studio 2010 ( VS10 ) | |||
|---|---|---|---|---|---|---|
| Release | Debug | Release | Debug | |||
| 32-bit Window OS | Only Intel 32-bit | Static | Nightly | FAIL | Nightly | FAIL |
| Shared | Nightly | Nightly | Nightly | |||
| 64-bit Window OS | Intel 32-bit | Static | Nightly | Nightly | ||
| Shared | ||||||
| Intel 64-bit | Static | Nightly | FAIL | Nightly | Nightly | |
| Shared | ||||||
| Legend | |
|---|---|
| Nightly | This combination of options is nightly tested, and known to work. |
| This combinations has been manually tested, and is expected to work. | |
| It is not known if this combinations of options will work. | |
| FAIL | These options are known not to work. |
This table has been updated for the stable development branch, master, as of April 18th 2012.
Why are all of the configurations not supported on Windows?
One of the following errors frequently occur when the set of configuration options fail:
LINK : fatal error LNK1102: out of memory
LINK : fatal error LNK1248: image size (80000010) exceeds maximum allowable size (80000000)
These errors occur because of limitations in the compiler's linker or the operating system. For 64-bit architectures the linker is still only 32-bits. In certain configurations the linker can run out of memory. Also the Windows operating systems have a hard limit of 2GB for the size of libraries. For certain Debug mode configurations this limit is encountered.
In general building in Debug mode should not be necessary, unless you are trying to debug SimpleITK or ITK. This configuration produces libraries that are very large because the compiler must maintain symbols for all instantiated ITK classes and member functions for each template parameters that a class is instantiating.
Installation
Why do I get an error about a missing Dynamic Library when running SimpleITK with Python on windows?
This error has been resolved with SimpleITK version 0.5.1 and should no longer occur.
This error occurs after you have downloaded the Windows SimpleITK binaries when you are running python and try to import SimpleITK. There is an error about a missing DLL on Windows when you don't have Visual Studio 10 and no other application has installed certain libraries before. You will need to download the Visual Studio 10 redistribution libraries. The libraries are available for download here.
How to Use
What filters are currently available in SimpleITK?
As of September 2012 we have approximately 225 ITK image filters wrapped for SimpleITK. The filter coverage table shows the current set of ITK filters in SimpleITK. Additionally the Doxygen can be looked at to determine if a filter is available.
How do I read a RAW image into SimpleITK?
In general raw image files are missing information. They do not contain the nessesary header information to describe the basic size and type for the data, so this format is intrinsically deficient. The RawImageIO class is not available in SimpleITK so there is no direct way to programmatically hard code this header information. The suggested way is to create a Meta image header file (*.mhd) which references the raw data file and describes the size and type of the data. The documentation on how to write a Meta image header can be found here.
The following is a sample Meta image header file, perhaps of name sample.mhd:
ObjectType = Image NDims = 3 DimSize = 256 256 64 ElementType = MET_USHORT ElementDataFile = image.raw (this tag must be last in a MetaImageHeader)
Can I use another image file viewer beside ImageJ?
By default when the Show function is called, SimpleITK writes out a temporary image in Nifti format then launches ImageJ. The user can override the file format of the temporary file and/or the application used to handle that file.
The temporary file format can be specified via the SITK_SHOW_EXTENTION environment variable. For example, if the user wanted to export a PNG file, on Linux it might look like this:
SITK_SHOW_EXTENSION=".png" export SITK_SHOW_EXTENSION
Use of an extension unsupported by ITK results in an error message. For the supported image formats, here is the ITK Image IO Filters.
The default display application for all image types is ImageJ. To override ImageJ with some other application, use the SITK_SHOW_COMMAND environment variable. For instance, on Unix systems, using GNOME's image viewer eog would be:
SITK_SHOW_EXTENSION=".png" export SITK_SHOW_EXTENSION SITK_SHOW_COMMAND="eog" export SITK_SHOW_COMMAND
To override the default display applications for only color or 3d images, there are the SITK_SHOW_COLOR_COMMAND and SITK_SHOW_3D_COMMAND environment variables.
More details on the Show function, including use of the "%a" and "%f" tokens, is at the Show function Doxygen page.
How can I use Slicer to view my images?
Slicer is a very powerful and popular application for visualization and medical image computing. The SITK_SHOW_COMMAND environment variable may be used to display images in Slicer rather than ImageJ. The following are examples of what settings for SITK_SHOW_COMMAND might look like for Mac OS X, Linux and Windows to use Slicer.
Mac OS X
export SITK_SHOW_COMMAND=/Applications/Slicer.app/Contents/MacOS/Slicer
Linux
export SITK_SHOW_COMMAND=Slicer
Windows
set SITK_SHOW_COMMAND=:"c:\Program Files\Slicer 4.2.2-1\Slicer"
The value of SITK_SHOW_COMMAND should be modified to point to wherever Slicer is installed. If you only want to use Slicer for volumetric 3D images, use the SITK_SHOW_3D_COMMAND environment variable instead of SITK_SHOW_COMMAND.
