Frequently Asked Questions¶
This page hosts frequently asked questions about SimpleITK, and their answers.
Does SimpleITK offer all the functionality as the C++ ITK?¶
SimpleITK supports most ITK image filters (see list) and the IO and registration frameworks. It exposes fewer settings than ITK, hence the Simple in the name. The main ITK elements omitted from SimpleITK are the pipeline architecture, spatial objects framework, point sets, and the mesh framework.
I am using the binary distribution of SimpleITK for Anaconda, why do I get an error about libpng?¶
ImportError: dlopen(./_SimpleITK.so, 2): Library not loaded: @rpath/libpng15.15.dylib Referenced from: …/lib/python2.7/site-packages/SimpleITK/_SimpleITK.so Reason: image not found
This type of error can occur if a library SimpleITK depends on can not be found. It may be that the version of the dependent library has changed in the Python environment and is no longer compatible. One solution is to create a environment.yml file with all the packages required for a project, then create a new environment:
conda env create -f environment.yml
Why am I getting “ModuleNotFoundError: No module named ‘_SimpleITK’” when importing SimpleITK on Windows?¶
- Traceback (most recent call last):
- File “C:Python37libsite-packagesSimpleITKSimpleITK.py”, line 14, in swig_import_helper
return importlib.import_module(mname) … File “<frozen importlib._bootstrap>”, line 219, in _call_with_frames_removed ImportError: DLL load failed: The specified module could not be found.
The above error occurs on Microsoft windows when system libraries SimpleITK depends on are not available on the system. This issue can be resolved by installing the appropriate Redistributable for Visual Studio package.
Why am I getting “DllNotFoundException: Unable to load DLL ‘SimpleITKCSharpNative’” when running a CSharp application on Windows?¶
This error message can be the result of an incomplete installation of SimpleITK in the CSharp application. Below is the complete error message that can result:
System.TypeInitializationException: 'The type initializer for 'itk.simple.SimpleITKPINVOKE' threw an exception.' TypeInitializationException: The type initializer for 'SWIGExceptionHelper' threw an exception. DllNotFoundException: Unable to load DLL 'SimpleITKCSharpNative': The specified module could not be found. (Exception from HRESULT: 0x8007007E)
The application is missing the SimpleITK dynamically loaded library (DLL). To fix this problem, follow the instructions in the Add Native Library section of the SimpleITK Visual Studio/C# build instructions.
How to Use¶
What filters are currently available in SimpleITK?¶
There are nearly 300 ITK image filters wrapped in SimpleITK. We have a list of filters accompanied by a brief description. Additionally the Doxygen can be examined to determine the availability of a filter.
What image file formats can SimpleITK read?¶
How do I read a RAW image into SimpleITK?¶
In general raw image files are missing information. They do not contain the necessary 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)
An example implementing this approach is available here here.
Why does my image appear to be empty / all black / blank when visualized?¶
There are two possible reasons for this:
The image is indeed empty. This is rarely the case, and indicates that there is something incorrect with the code, will require debugging.
The image contains very low values (1, 2, 3…). This is very common with segmentation and binary mask images. What you are experiencing is an issue with data visualization, not with the data itself. The code below illustrates the difference, and shows how to quickly visualize such images using the existing SimpleITK functionality.
import SimpleITK as sitk # Create segmentation image segmentation_image = sitk.Image([128,128], sitk.sitkUInt8) segmentation_image[40:50,20:120] = 1 segmentation_image[50:60,20:120] = 2 segmentation_image[60:70,20:120] = 3 # When visualized with Fiji, image looks all black. To see the data # change the display settings Image->Adjust->Brightness/Contrast. sitk.Show(segmentation_image) # For quick visualization, convert to float and add # 255 so that the data is immediately visible in Fiji. sitk.Show(sitk.Cast(segmentation_image,sitk.sitkFloat32) + 255)
Why isn’t Fiji or ImageJ found by the Show function (RuntimeError: Exception thrown…)?¶
Show function expects the Fiji or ImageJ application to be
installed in specific locations. The recommended installation locations are:
On Windows: in your user directory (e.g. C:\Users\your_user_name\Fiji.app).
On Linux: in ~/bin.
On Mac: in /Applications or ~/Applications.
To see the locations where the function is searching set Show’s debugOn flag.
Show(image, "file_name", TRUE)
Show is a functional interface to the ImageViewer class. Other viewing applications can be configured using an ImageViewer object, as described in the next section.
Can I use another image file viewer beside Fiji?¶
The ImageViewer class allows a user to configure what application SimpleITK uses to display images. An ImageViewer object displays an image via the Execute method.
The default display application for all image types is Fiji.
To override Fiji with some other application, use the
ImageViewer::SetCommand method. For example in Python on Linux
systems, using ImageMagick’s display program would look like this:
import SimpleITK as sitk viewer = sitk.ImageViewer() viewer.SetFileExtension('.png') viewer.SetCommand('/usr/bin/display')
By default when
ImageViewer::Execute is called, it writes out a temporary
image in Nifti format then launches Fiji. If
the viewing application has been changed to one that does not support Nifti,
the file format of the temporary file can be overridden using the
ImageViewer::SetFileExtension method. In the above example, we use PNG, a
format ImageMagick does support, unlike Nifti.
Use of an file extension unsupported by ITK results in an error message. For the supported image formats, see the ITK Image IO Filters.
More details into ImageViewer configuration can be found in the ImageViewer class documentation.
How can I use 3D Slicer to view my images?¶
3D Slicer is a very powerful and popular application for visualization and medical image computing. An ImageViewer object can be configured to use Slicer instead of SimpleITK’s default viewer, Fiji. The following are examples of how to configure an ImageViewer object in Python for Mac OS X, Linux and Windows to use Slicer.
Mac OS X
import SimpleITK as sitk viewer = sitk.ImageViewer() viewer.SetCommand('/Applications/Slicer.app/Contents/MacOS/Slicer')
import SimpleITK as sitk viewer = sitk.ImageViewer() viewer.SetCommand('Slicer')
import SimpleITK as sitk viewer = sitk.ImageViewer() viewer.SetCommand( 'c:\Program Files\Slicer 4.10.2\Slicer' )
The call to SetCommand should be modified to point to wherever the Slicer executable is installed.
Why should I use a virtual environment?¶
Before installing SimpleITK we highly recommend creating a virtual environment into which the package can be installed. Note that different Python versions and distributions have different programs for creating and managing virtual environments.
The use of a virtual environment allows a user to elegantly deal with package compatibility issues, to quote The Hitchhiker’s Guide to Python!:
A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the “Project X depends on version 1.x but, Project Y needs 4.x” dilemma, and keeps your global site-packages directory clean and manageable.
Are the Python Wheels compatible with Enthought Canopy Distribution?¶
The Generic Python Wheels frequently seem to work with the Enthought Canopy Python distribution. However, we recommend compiling SimpleITK explicitly against this Python distribution to ensure compatibility.
Is my compiler supported?¶
SimpleITK uses advanced C++ meta-programming to instantiate ITK’s Images and Filters. SimpleITK is developed to require the C++11 standard.
In practice the list of compilers actively supported are those that are used for continuous testing and integration. These can be seen on the SimpleITK dashboard. We welcome user contributions to the nightly dashboard to expand the list of these compilers and contributions to fix additional compilation problems.
Microsoft compilers before Visual Studio 14 (2015) have had memory limitation issues.
Are 32-bits architectures supported?¶
While 32-bit binaries are no longer pre-compiled, the intel 32-architecture are still tested to help ensure robustness of the toolkit. Contributions and bug reports to support additional architectures are welcomed.
Why does the Superbuild fail compiling PCRE on Mac OS X?¶
If the Xcode command line tools are not properly set up on OS X, PCRE could fail to build in the Superbuild process with messages such as:
checking whether we are cross compiling... configure: error: in `/your/build/path/SimpleITK/PCRE-prefix/src/PCRE-build': configure: error: cannot run C compiled programs. If you meant to cross compile, use `--host'. See `config.log' for more details [10/13] Performing build step for 'PCRE'
To install the command line developer tools enter the following:
To reset the default command line tools path:
What Configurations on Windows are Supported For Building?¶
We recommend using at least Microsoft Visual Studio 15 (2017) with MSVC v140 toolset.
Path Length Issues on Windows¶
The location of the build and source directories on Windows can cause the build to fail. By default, Windows does not allow path lengths longer than 260 characters.
See Windows Path Length for more information.
Where is the Test Data?¶
The testing data is not stored in the SimpleITK repository or as part of the source code. It is mirrored on several data repositories on the web.
If the source code was obtained from the git repository, the test data should be downloaded as part of the build process via the CMake ExternalData module.
A tar-ball of the “SimpleITKData” can be downloaded for a release from the GitHub Assets, which contains the external data. It should populate the .ExternalData subdirectory of the SimpleITK source code directory when extracted.
Why is CMake unable to download ExternalData?¶
When compiling SimpleITK an error like the following may occur:
Object MD5=2e115fe26e435e33b0d5c022e4490567 not found at: https://placid.nlm.nih.gov/api/rest?method=midas.bitstream.download&checksum=2e115fe26e435e33b0d5c022e4490567&algorithm=MD5 ("Unsupported protocol") https://simpleitk.org/SimpleITKExternalData/MD5/2e115fe26e435e33b0d5c022e4490567 ("Unsupported protocol") https://midas3.kitware.com/midas/api/rest?method=midas.bitstream.download&checksum=2e115fe26e435e33b0d5c022e4490567&algorithm=MD5 ("Unsupported protocol") https://insightsoftwareconsortium.github.io/ITKTestingData/MD5/2e115fe26e435e33b0d5c022e4490567 ("Unsupported protocol") https://itk.org/files/ExternalData/MD5/2e115fe26e435e33b0d5c022e4490567 ("Unsupported protocol")
This indicates that CMake was not compiles with SSL support. The “Unsupported protocol” message indicate that CMake can not communicate via “https”.
The solution is to use a compiled version of CMake which supports SSL. To re-build CMake with OpenSSL support, simply reconfigure CMake with the “CMAKE_USE_OPENSSL” option enabled.