SimpleITK/GettingStarted

From KitwarePublic
Jump to navigationJump to search

SimpleITK provides a simplified interface to ITK in a variety of languages. You can either download binaries, if they are available for your platform and prefered language, or you can build SimpleITK yourself.

Additionally, there are several recommended third-party software packages.

After you have installed SimpleITK, please look to the Tutorial or the Doxygen pages for more information.

Binaries

One of the great advantages of SimpleITK is that (typically) you do not have to build it — you can simply download the binaries and get started right away!

Currently, the following systems have binaries which you can easily download: python. We are currently (Feb 2012) working on creating binaries for the following systems: C#, Java. We are also working towards R packaging as well.

Python binary files

The list of the binary python packages available is maintained here.

Both your version of python and operating system must be available to be able to use the binary distribution. The package does not need to be downloaded from above, as SimpleITK is registered on the Python Packaging Index. The binary built packages are distributed as python eggs. They can be installed with the "easy_install" utility from the setuptools python package.

If your system does not already have easy_install you will need to install this python package. Please go to the setuptools setuptools home page for detailed instructions.

Once you have installed setuptools and easy_install is in your path then run the following command as root to install the package in system's site-packages:

$ sudo easy_install SimpleITK

This command will check the available packages, and choose the one that is most recent and matches your system.

For advanced users you may be able to install SimpleITK in a virtual python environment, so that it does not modify the global python environment.

C# binary files

Binaries for select C# platform can be found on SimpleITK's SourceForge page. Installation of library should involve only importing the unzip files into you C# environment.

More information about getting started with a sample C# program can be found in A visual guide to building SimpleITK on Linux

Java binary files

Binaries for select Java platforms can be found on SimpleITK's SourceForge page. Installation instructions are at a visual guide to SimpleITK in Java.

Build It Yourself

In many cases it is not required to build SimpleITK. The easiest way is to use the pre-compiled binary files (see here). Some reasons why you might want to build SimpleITK from source are:

  • The binary files for your programming language of choice are not (yet) distributed
  • You want the live on the bleeding edge by using the latest-and-greatest version of SimpleITK
  • You want to wrap your own filters using the SimpleITK infrastructure
  • You want to contribute to the development of SimpleITK

Prerequisites

To build SimpleITK you need:

  • A recent version of cmake.
  • A supported compiler.
  • Source code
    • Released source code can be found on SimpleITK's SourceForge Page
    • Alternatively, the latest developmental version can be download with git.
git clone --recursive  http://itk.org/SimpleITK.git

After SimpleITK's souce code is obtained it is STRONGLY recommended to run cmake on the SuperBuild subdirectory of SimpleITK:

mkdir SimpleITK-build
cd SimpleITK-build
cmake ../SimpleITK/SuperBuild

The SuperBuild will automatically download and build the matching version of ITK and SWIG needed to compile SimpleITK. This is the recommended way to build SimpleITK and is easiest.

If you get an error message saying that ITK_DIR is not set then, you did not correctly point cmake to the SuperBuild sub-directory. Please erase your binary directory, and point cmake to the SimpleITK/SuperBuild sub-directory.

The cmake configuration process should automatically find supported languages and enable SimpleITK wrapping for them. To manually enable a language toggle the appropriate WRAP_LANGUAGE cmake variable to ON. Verify and/or correct the advanced cmake variables to the language specific executable, libraries and include directories.

Then use your make utility or your cmake choosen build utility to build SimpleITK. After completion, add the SimpleITK-build/lib directory to you LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac) environment.

SimpleITK takes a while to build. Some tips and tricks to speed up development time are listed here.

Testing

cd SimpleITK-build/SimpleITK-build
ctest

If all tests fail, verify that you have the testing data in your source tree (the reason for the "--recursive" flag in the git command) AND that you've added the correct path to your *_LIBRARY_PATH.

Python installation

To install a built python package, as root:

 cd SimpleITK-build/Wrapping
 python PythonPackage/setup.py install

A visual guide to building SimpleITK on Linux

A visual guide to building SimpleITK on Linux

Recommended Software

ImageJ

SimpleITK has a build in function to called "itk::simple::Show()", which can be used for quick viewing of images while using SimpleITK, in an interactive fashion. Currently, this function is hard coded to use ImageJ. This was chosen because it has the ability to load images of all the types that SimpleITK supports. Even 3D vector images with n components. We recommend downloading a recent version of ImageJ from the official home page. The recent versions come with support for the Nifti ( *.nii ) file format which SimpleITK uses to export to ImageJ. The Show function first searches the "PATH" environmental variable, then additional standard locations, for most platforms are examined, if problems are encountered the correct path can be added to this environmental variable.


Note: Linux installation requires an additional step. The Show function searches for an executable named ImageJ or imagej, however the default tarball does not come with this file. Instead it comes with a file names script. This file contains the installation instructions. In short the file should be renamed to "imagej" and the site specific variables for the installation location, and java must be set. Also consider the "newwindow" variable... Do you really want a new instance of ImageJ launched each time you use Show? Lastly, as the installation instructions indicate, the imagej wrapper should be in your path.


ipython

If you are using python, ipython is great environment to perform interactive commands for image processing. With the addition of numpy and scipy, you'll have a very powerful interactive environment.