SimpleITK/GettingStarted: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
 
(60 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Image: Simpleitk_logo.png‎|center]]
{{SimpleITKMigrationHeader}}
 
[[Image: SimpleITK-SquareTransparentLogo.png|center]]


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.
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.
Line 11: Line 13:
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!
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, '''Python''' binaries are available on Windows, Linux and Mac OS X. '''C# and Java''' binaries are available for Windows. We are also working towards supporting '''R''' packaging.
Currently, '''Python''' binaries are available on Microsoft Windows, GNU Linux and Apple OS X. '''C# and Java''' binaries are available for Windows. We are also working towards supporting '''R''' packaging.


==Python binary files==
==Python binary files==


There are currently 3 python binary package choices. Python Eggs, Wheels, and Binstar packages for the Anaconda Python distribution.
There are currently two Python binary package choices: Python Wheels, and Anaconda packages for the Anaconda Python distribution.
 
 
Your versions of python, operating system, and architecture must be available to use a binary distribution.  


SimpleITK is registered on the [http://pypi.python.org/pypi/SimpleITK/ Python Packaging Index]. The binary built packages are distributed as python eggs and wheels. While your installation tool and the Python Packaging Index may get you the correct binary, it is often best to manually download the file from [http://sourceforge.net/projects/simpleitk/files/SimpleITK/ SourceForge].
==== Use a Virtual Environment ====


Advanced users may prefer to install SimpleITK in a [http://pypi.python.org/pypi/virtualenv virtual python environment], so that it does not modify the global python environment.
Before you install SimpleITK we <b>highly recommend</b> that you create a virtual environment into which you install the package. Note that different Python versions and distributions have different programs for creating and managing virtual environments.  


=== Eggs ===
The use of a virtual environment allows you to elegantly deal with package compatability issues, to quote [http://docs.python-guide.org/en/latest/ The Hitchhiker’s Guide to Python!]:
<blockquote>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.</blockquote>


If your system does not already have easy_install you will need to install the setuptools package to obtain it. Please go to the [http://pypi.python.org/pypi/setuptools setuptools home page] for detailed installation instructions.
Programs for creating virtual environments include [https://packaging.python.org/en/latest/installing/#creating-virtual-environments virtualenv and pyvenv] for generic Python distributions, [http://conda.pydata.org/docs/using/envs.html conda] for the anaconda distribution, and [http://docs.enthought.com/canopy/configure/canopy-cli.html canopy_cli] for the canopy distribution.


Once you have installed '''setuptools''', and '''easy_install''' is in your path, then run the following command install the SimpleITK package in the current pythons system's site-packages:
=== Wheels for Generic Python Distribution ===


$ easy_install -U SimpleITK
If you are working with the [https://www.python.org/ generic Python distribution] you can install a Wheel with the lasted version of pip (>=9.0).


This command will check the available packages and choose the most recent one that matches your system.  Then it will download and install the python egg.
First thing you should do is create a virtual environment (virtualenv or pyvenv tools) and activate it.


To install through a firewall proxy, the environment variable "http_proxy" may need to be configured. To pass the environment variable down through sudo, you need to use the "-E" option
<u>Note</u>: you can always manually download the wheels for your operating system and Python version directly from [http://sourceforge.net/projects/simpleitk/files/SimpleITK/ sourceforge].
$ export http_proxy=http://someproxy.somewhere.com:8080
$ sudo -E easy_install -U SimpleITK


=== Wheels ===


You need a recent version of pip ( >= 1.4, newer is better) to install [http://pythonwheels.com wheels]. Please go to [https://pip.pypa.io/en/latest/index.html pip homepage] for more information about installation.
From the command line use the [https://pip.pypa.io/en/latest/index.html pip program] to install:


Once you have pip, the package can be installed:
$ pip install SimpleITK


$ pip install -U SimpleITK
The pip package manager should automatically find the correct package for Microsoft Windows, Apple OS X and GNU Linux if your version and architecture are supported. If no binary package is found, then a source distribution will be downloaded and attempted to be compiled and you should look into [[#Build_It_Yourself]].


However, you may need to manually download the file from SourceForge. And specify it on the command line.
:: If your pip version in the virtual environment is stale (<9.0) you need to update it (pip install -U pip).


=== Anaconda Distribution ===
=== Anaconda Distribution ===


Currently there are compiled binaries on [https://binstar.org/SimpleITK Binstar] for the Anaconda distribution, easily installed with:
First thing you should do is create a virtual environment ([https://conda.pydata.org/docs/using/envs.html conda] tool) and activate it.
 
$ conda install -c https://conda.binstar.org/simpleitk SimpleITK


The [https://github.com/conda/conda-recipes/tree/master/simpleitk recipe] for these builds are in the official [https://github.com/conda/conda-recipes conda-recipe] repository.
Currently there are compiled binaries on [https://conda.anaconda.org/simpleitk Anaconda Cloud], easily installed with:


Beta and release candidate packages are also available on Binstar on the dev channel:
$ conda install -c <nowiki>https://conda.anaconda.org/simpleitk</nowiki> SimpleITK


$conda install -c https://conda.binstar.org/simpleitk/channel/dev SimpleITK
Beta and release candidate packages are also available on Anaconda cloud under the dev label:


=== Homebrew ===
$conda install -c <nowiki>https://conda.anaconda.org/simpleitk/label/dev</nowiki> SimpleITK


SimpleITK Formula:
=== Enthought Canopy Distribution ===
https://github.com/Homebrew/homebrew-science/blob/master/simpleitk.rb


=== Enthought Distribution ===
First thing you should do is create a virtual environment (canopy_cli tool) and activate it.


Currently there are no binaries supported with this distribution. You will need to compile SimpleITK yourself. ( On Windows pip installation of the binaries may work. )
Currently there are no binaries supported with this distribution. You will need to compile SimpleITK yourself. (Using pip installation may work.)


==C# binary files==
==C# binary files==


'''Binaries for select C# platform''' can be found on [http://sourceforge.net/projects/simpleitk/files/SimpleITK/0.9.0/CSharp/ SimpleITK's SourceForge page]. Installing the library should only involve importing the unzipped files into you C# environment. The files have the following naming convention:
'''Binaries for select C# platform''' can be found on [https://sourceforge.net/projects/simpleitk/files/SimpleITK/1.0.0/CSharp/ SimpleITK's SourceForge page]. Installing the library should only involve importing the unzipped files into you C# environment. The files have the following naming convention:
  SimpleITK-version-CSharp-buildplatform-targetplatform.zip
  SimpleITK-version-CSharp-buildplatform-targetplatform.zip
eg.
eg.
  SimpleITK-0.9.0-CSharp-win32-x86.zip
  SimpleITK-1.0.0-CSharp-win32-x86.zip
  SimpleITK-0.9.0-CSharp-win64-x64.zip
  SimpleITK-1.0.0-CSharp-win64-x64.zip


Details about how to set up a C# Visual Studio project with SimpleITK can be found in the [[SimpleITK/GettingStarted/A_visual_guide_to_SimpleITK_with_CSharp|Visual Guide to SimpleITK with CSharp]].
Details about how to set up a C# Visual Studio project with SimpleITK can be found in the [[SimpleITK/GettingStarted/A_visual_guide_to_SimpleITK_with_CSharp|Visual Guide to SimpleITK with CSharp]].
Line 83: Line 77:
==Java binary files==
==Java binary files==


'''Binaries for select Java platforms''' can be found on [http://sourceforge.net/projects/simpleitk/files/SimpleITK/0.9.0/Java/ SimpleITK's SourceForge page]. Installation instructions are available at [[SimpleITK/GettingStarted/A visual guide to SimpleITK in Java|a visual guide to SimpleITK in Java]].
'''Binaries for select Java platforms''' can be found on [https://sourceforge.net/projects/simpleitk/files/SimpleITK/1.0.0/Java/ SimpleITK's SourceForge page]. Installation instructions are available at [[SimpleITK/GettingStarted/A visual guide to SimpleITK in Java|a visual guide to SimpleITK in Java]].


==Nightly binaries==
==Nightly binaries==


The '''latest binaries''' for the current development version of SimpleITK are also generally available. Binary packages are built as part of the nightly regression testing system. The download links are available from the [http://open.cdash.org/index.php?project=SimpleITK '''CDash'''] '''dashboard''' in the "Nightly Packages" section.  
The '''latest binaries''' for the current development version of SimpleITK are also generally available. Binary packages are built as part of the nightly regression testing system. The download links are available from the [https://open.cdash.org/index.php?project=SimpleITK '''CDash'''] '''dashboard''' in the "Nightly Packages" section.  


Each row on the dashboard is a SimpleITK build on a particular system, and if the build was successful there will be a '''package icon''': http://open.cdash.org/images/package.png which links to the packages build by the system. A user may directly download the built package from such a link.
Each row on the dashboard is a SimpleITK build on a particular system, and if the build was successful there will be a '''package icon''': https://open.cdash.org/img/package.png which links to the packages build by the system. A user may directly download the built package from such a link.


=Build It Yourself=
=Build It Yourself=
Line 102: Line 96:
=== Prerequisites ===
=== Prerequisites ===
To build SimpleITK you need:
To build SimpleITK you need:
* A recent version of [http://www.cmake.org/ CMake] >= 2.8.4, for testing >= 2.8.11 ( 3.0-3.2 OK )
* A recent version of [http://www.cmake.org/ CMake] >= 3.3 with SSL support for https.
* A supported [[SimpleITK/FAQ#Is_my_compiler_supported.3F|compiler]]
* A supported [[SimpleITK/FAQ#Is_my_compiler_supported.3F|compiler]]
* To use the latest developmental version, source code can be downloaded with [http://git-scm.com/ git] >= 1.65
* To use the latest developmental version, source code can be downloaded with [http://git-scm.com/ git] >= 1.65
** Git is required if building SimpleITK using "SuperBuild" (see below) to automatically download the matching version of ITK and SWIG
** Git is required if building SimpleITK using "SuperBuild" (see below) to automatically download the matching version of ITK, SWIG, etc...
** Windows users may prefer [http://msysgit.github.com/ msysGit]
** Windows users may prefer [http://msysgit.github.com/ msysGit]
* It is recommended to have numpy installed when testing Python bindings
* It is recommended to have numpy installed when testing Python bindings
=== Recipes / Formulas / Short Cuts ===
For some environments we have short cuts, scripts, for automated building of SimpleITK (see their repository for more details):
* For '''Python''': The [https://github.com/scikit-build/scikit-build scikit-build] based distutils based [https://github.com/scikit-build/scikit-build setup.py frontend] can be used to build, install, and package SimpleITK for Python.
* For the '''Anaconda Python''' distribution: The recipe and instructions for the SimpleITK build are in [https://github.com/SimpleITK/SimpleITKCondaRecipe this GitHub repository].
* For the '''R language''': A devtools installer and instructions are available from [https://github.com/SimpleITK/SimpleITKRInstaller this GitHub repository].
* '''On the Mac''', with the [http://brew.sh/ Homebrew package manager], a SimpleITK formula is available: https://github.com/Homebrew/homebrew-science/blob/master/simpleitk.rb for multiple language wrappings.
* For the '''Lua language''' with the Luarocks module deployment system, a SimpleITK rockspec is available form [https://github.com/SimpleITK/SimpleITKLuaRock this GitHub repository].


=== Source code ===
=== Source code ===
If one of the above language specific front-ends are not used then SimpleITK must be build directly.
There are two options to obtain the SimpleITK source code:
There are two options to obtain the SimpleITK source code:
# Download a released version from the SimpleITK [http://sourceforge.net/projects/simpleitk/ SourceForge] page
# Download a released version from the SimpleITK [https://sourceforge.net/projects/simpleitk/ SourceForge] page
# Download the latest development version using git
# Download the latest development version using git
  git clone http://itk.org/SimpleITK.git
  git clone http://itk.org/SimpleITK.git
Line 131: Line 142:
SimpleITK takes a while to build. Some tips and tricks to speed up development time are listed [http://www.itk.org/SimpleITKDoxygen/html/Developer.html#TandT here].
SimpleITK takes a while to build. Some tips and tricks to speed up development time are listed [http://www.itk.org/SimpleITKDoxygen/html/Developer.html#TandT here].


=== Building manually ===
=== Building Manually ===
This is '''not''' the recommended way of building SimpleITK, but it can be useful if you want to use a system version of ITK and/or SWIG, or if you do not want to (or can not) use git (due to firewall, etc).
This is '''not''' the recommended way of building SimpleITK, but it can be useful if you want to use a system version of ITK, etc. , or if you do not want to (or can not) use git.


# Setup the prerequisites as described above (i.e. CMake and supported compiler)
# Setup the prerequisites as described above (i.e. CMake and supported compiler)
# Install the matching version of [http://www.swig.org/ SWIG] >= 3.0.5
# Install the matching version of [http://www.swig.org/ SWIG] >= 3.0.11
#* e.g. Windows users may install [http://prdownloads.sourceforge.net/swig/swigwin-3.0.5.zip swigwin-3.0.5]
#* e.g. Windows users may install [http://prdownloads.sourceforge.net/swig/swigwin-3.0.11.zip swigwin-3.0.11]
# Download the SimpleITK source code from the [https://sourceforge.net/projects/simpleitk/files/SimpleITK/ SourceForge] page
# Download the SimpleITK source code from the [https://sourceforge.net/projects/simpleitk/files/SimpleITK/ SourceForge] page
# Download the matching version of ITK
# Download the matching version of ITK, found by examining the `SuperBuild/External_ITK.cmake` file.
#* e.g. [http://sourceforge.net/projects/simpleitk/files/SimpleITK/0.8.1/Source/SimpleITK-0.8.0-Source.tar.gz/download SimpleITK 0.8.1] uses [ http://sourceforge.net/projects/itk/files/itk/4.7/InsightToolkit-4.7.2.tar.gz/download ITK 4.7.2 (tag v4.7.2)]
# Configure ITK using CMake
# Configure ITK using CMake
#* BUILD_EXAMPLES=OFF, BUILD_TESTING=OFF, BUILD_SHARED_LIBS=OFF, '''ITK_USE_REVIEW=ON''', ITK_WRAP_*=OFF
#* e.g. BUILD_EXAMPLES=OFF, BUILD_TESTING=OFF, BUILD_SHARED_LIBS=OFF, '''ITK_USE_REVIEW=ON'''
# Build ITK
# Build ITK
#* Be sure to note the build settings e.g. Release x64
#* Be sure to note the build settings e.g. Release x64
Line 147: Line 157:
#* Set ITK_DIR to the location of the ITK build location from the previous steps
#* Set ITK_DIR to the location of the ITK build location from the previous steps
# Build SimpleITK
# Build SimpleITK
#* Be sure to configure the build settings exactly the same as ITK e.g. Release x64
#* Be sure to configure the build settings exactly the same as ITK e.g. Release x64 and CXX_FLAGS
 
=== Advanced Build Options ===
 
SimpleITK is aware of the enabled and disabled ITK Modules. It is possible to customize SimpleITK by disabling unneeded ITK modules or to extend SimpleITK by writing custom json file dependent an ITK Remote Modules being enabled.
 
Additionally, each of the Examples directory, and each of the Wrapping subdirectories can be configured as independent CMake project dependent on an installed SimpleITK.


===[[SimpleITK/GettingStarted/Visual_guide_to_building_on_Linux|A visual guide to building SimpleITK on Linux]]===
===[[SimpleITK/GettingStarted/Visual_guide_to_building_on_Linux|A visual guide to building SimpleITK on Linux]]===
Line 153: Line 169:
==Testing==
==Testing==


After compilation the prudent thing to due is to test SimpleITK to ensure your build is stable and suitable for use and installation. The following commands execute the SimpleITK tests.
After compilation the prudent thing to due is to test SimpleITK to ensure your build is stable and suitable for installation and use. The following commands execute the SimpleITK tests.


  cd SimpleITK-build/SimpleITK-build
  cd SimpleITK-build/SimpleITK-build
Line 161: Line 177:
  cd SimpleITK-build/SimpleITK-build
  cd SimpleITK-build/SimpleITK-build
  ctest -C Release
  ctest -C Release
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 have added the correct path to your *_LIBRARY_PATH.


==Python installation==
==Python installation==


To install a built python package into the system Python, as root run:
To install a built python package into the system Python, as root run:
   cd SimpleITK-build/Wrapping
   cd SimpleITK-build/Wrapping/Python
   python PythonPackage/setup.py install
   python Packaging/setup.py install


Alternatively, a Python virtual environment can be created and the distribution installed there.
Alternatively, a Python virtual environment can be created and the distribution installed there.


If you build the "dist" target a Python egg will be created in the "Wrapping/dist" directory. Building Python wheels can be enabled with a CMake flag.
A Python Wheel file (.whl)  can be created in the "Wrapping/Python/dist" directory, by building the "dist" target. If you have used the Superbuild with the "make" generator then issue the following command:
  make -C SimpleITK-build dist


==R installation==
==R installation==
Line 178: Line 193:
To install a built R package:
To install a built R package:


   cd SimpleITK-build/Wrapping/Rpackaging
   cd SimpleITK-build/Wrapping/R/Packaging
   R CMD INSTALL SimpleITK
   R CMD INSTALL SimpleITK


This will install the R package "SimpleITK" in /usr/local as root or your local R installation directory.
This will install the R package "SimpleITK" in /usr/local as root or your local R installation directory.
If you are working in a multi-user environment, and are considerate of your fellow users you can install the package in a local directory:
<ol> <li> Create a local directory where you will install your R packages</li></ol>
  mkdir my_R_libs
<ol start="2"> <li> Add an environment variable to your .bashrc</li></ol>
  export R_LIBS="/path_to/my_R_libs"
<ol start="3"> <li> source your .bashrc and check the R library path, in an R shell >.libPaths()</li></ol>
<ol start="4"> <li>install </li></ol>
  cd SimpleITK-build/Wrapping/R/Packaging
  R CMD INSTALL -l /path_to/my_R_libs  SimpleITK


=Recommended Software=
=Recommended Software=


===ImageJ===
== Fiji (Fiji is Just ImageJ) ==
SimpleITK has a built in function, '''"itk::simple::Show()"''', which can be used for viewing images in an interactive session. Currently, this function by default Show invokes [http://rsbweb.nih.gov/ij/ '''ImageJ'''] to display images.  ImageJ was chosen because it can handle all the image types that SimpleITK supports, even 3D vector images with n components.
 


We recommend downloading a recent version of [http://rsbweb.nih.gov/ij/download.html ImageJ] from the official home page. Recent versions come with support for the [http://nifti.nimh.nih.gov/nifti-1/ Nifti] ( *.nii ) file format, which SimpleITK uses to export to ImageJ.  
SimpleITK has a built in function, [https://itk.org/SimpleITKDoxygen/html/namespaceitk_1_1simple.html#ac8416e6e7f02dedfe8373b83dbea411d  '''"itk::simple::Show()"'''], which can be used for viewing images in an interactive session. Currently, this function by default Show invokes [https://fiji.sc '''Fiji'''] then [http://rsbweb.nih.gov/ij/ '''ImageJ'''] to display images. ImageJ was chosen because it can handle all the image types that SimpleITK supports, even 3D vector images with n components.  


The Show function first searches the "PATH" environment variable, then additional standard locations are examined, if problems are encountered the correct path can be added to this environment variable and the '''"debugOn'''" option to  '''"Show'''" flag set.


The Show function first searches the "PATH" environment variable, then additional standard locations, for most platforms are examined, if problems are encountered the correct path can be added to this environment variable.
====ImageJ====


If ImageJ is used then we recommend downloading a recent version of [http://rsbweb.nih.gov/ij/download.html ImageJ] from the official home page. Recent versions come with support for the [http://nifti.nimh.nih.gov/nifti-1/ Nifti] ( *.nii ) file format, which SimpleITK uses to export to ImageJ.


'''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 [http://imagej.nih.gov/ij/download/linux/unix-script.txt 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.
'''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 [http://imagej.nih.gov/ij/download/linux/unix-script.txt 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===
==iPython and Jupyter==


If you are using python, [http://ipython.org/ '''ipython'''] is terrific environment to perform interactive commands for image processing. With the addition of numpy and scipy, you'll have a powerful interactive environment.
If you are using python, [http://ipython.org/ '''ipython'''] with [http://jupyter.org Jupyter] is terrific environment to perform interactive computing for image processing. With the addition of numpy and scipy, you'll have a powerful interactive environment.


We have instructional [http://simpleitk.github.io/SimpleITK-Notebooks/ SimpleITK Notebooks] which can help you get started.
We have instructional [http://insightsoftwareconsortium.github.io/SimpleITK-Notebooks/ SimpleITK Jupyter Notebooks] which can help you get started.

Latest revision as of 18:57, 19 June 2017

NOTICE
This page is being migrated to Read The Docs!

For the up to date version please see this page!

SimpleITK-SquareTransparentLogo.png

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.

Downloading the 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, Python binaries are available on Microsoft Windows, GNU Linux and Apple OS X. C# and Java binaries are available for Windows. We are also working towards supporting R packaging.

Python binary files

There are currently two Python binary package choices: Python Wheels, and Anaconda packages for the Anaconda Python distribution.

Use a Virtual Environment

Before you install SimpleITK we highly recommend that you create a virtual environment into which you install the package. Note that different Python versions and distributions have different programs for creating and managing virtual environments.

The use of a virtual environment allows you to elegantly deal with package compatability 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.

Programs for creating virtual environments include virtualenv and pyvenv for generic Python distributions, conda for the anaconda distribution, and canopy_cli for the canopy distribution.

Wheels for Generic Python Distribution

If you are working with the generic Python distribution you can install a Wheel with the lasted version of pip (>=9.0).

First thing you should do is create a virtual environment (virtualenv or pyvenv tools) and activate it.

Note: you can always manually download the wheels for your operating system and Python version directly from sourceforge.


From the command line use the pip program to install:

$ pip install SimpleITK

The pip package manager should automatically find the correct package for Microsoft Windows, Apple OS X and GNU Linux if your version and architecture are supported. If no binary package is found, then a source distribution will be downloaded and attempted to be compiled and you should look into #Build_It_Yourself.

If your pip version in the virtual environment is stale (<9.0) you need to update it (pip install -U pip).

Anaconda Distribution

First thing you should do is create a virtual environment (conda tool) and activate it.

Currently there are compiled binaries on Anaconda Cloud, easily installed with:

$ conda install -c https://conda.anaconda.org/simpleitk SimpleITK

Beta and release candidate packages are also available on Anaconda cloud under the dev label:

$conda install -c https://conda.anaconda.org/simpleitk/label/dev SimpleITK

Enthought Canopy Distribution

First thing you should do is create a virtual environment (canopy_cli tool) and activate it.

Currently there are no binaries supported with this distribution. You will need to compile SimpleITK yourself. (Using pip installation may work.)

C# binary files

Binaries for select C# platform can be found on SimpleITK's SourceForge page. Installing the library should only involve importing the unzipped files into you C# environment. The files have the following naming convention:

SimpleITK-version-CSharp-buildplatform-targetplatform.zip

eg.

SimpleITK-1.0.0-CSharp-win32-x86.zip
SimpleITK-1.0.0-CSharp-win64-x64.zip

Details about how to set up a C# Visual Studio project with SimpleITK can be found in the Visual Guide to SimpleITK with CSharp.

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 available at a visual guide to SimpleITK in Java.

Nightly binaries

The latest binaries for the current development version of SimpleITK are also generally available. Binary packages are built as part of the nightly regression testing system. The download links are available from the CDash dashboard in the "Nightly Packages" section.

Each row on the dashboard is a SimpleITK build on a particular system, and if the build was successful there will be a package icon: package.png which links to the packages build by the system. A user may directly download the built package from such a link.

Build It Yourself

In many cases a user does not need to build SimpleITK because of the pre-built binaries available (see above). However there are several reasons a user might prefer to build SimpleITK from source:

  • 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
  • To use the SimpleITK's C++ interface and/or use ITK directly

Prerequisites

To build SimpleITK you need:

  • A recent version of CMake >= 3.3 with SSL support for https.
  • A supported compiler
  • To use the latest developmental version, source code can be downloaded with git >= 1.65
    • Git is required if building SimpleITK using "SuperBuild" (see below) to automatically download the matching version of ITK, SWIG, etc...
    • Windows users may prefer msysGit
  • It is recommended to have numpy installed when testing Python bindings

Recipes / Formulas / Short Cuts

For some environments we have short cuts, scripts, for automated building of SimpleITK (see their repository for more details):

  • For the Anaconda Python distribution: The recipe and instructions for the SimpleITK build are in this GitHub repository.
  • For the Lua language with the Luarocks module deployment system, a SimpleITK rockspec is available form this GitHub repository.

Source code

If one of the above language specific front-ends are not used then SimpleITK must be build directly.

There are two options to obtain the SimpleITK source code:

  1. Download a released version from the SimpleITK SourceForge page
  2. Download the latest development version using git
git clone http://itk.org/SimpleITK.git

Building using SuperBuild

After downloading SimpleITK's source code we STRONGLY recommend to run cmake on the SuperBuild subdirectory of SimpleITK. Execute the following commands in the parent of the SimpleITK source directory to configure the SuperBuild:

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. Additionally, it will set recommended compilation flags to minimize the size of the library and enable support for large libraries. 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. For example if you have multiple Python installations ensure that all related Python variable refer to the same versions.

Then use your make utility or your cmake chosen build utility to build SimpleITK.

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

Building Manually

This is not the recommended way of building SimpleITK, but it can be useful if you want to use a system version of ITK, etc. , or if you do not want to (or can not) use git.

  1. Setup the prerequisites as described above (i.e. CMake and supported compiler)
  2. Install the matching version of SWIG >= 3.0.11
  3. Download the SimpleITK source code from the SourceForge page
  4. Download the matching version of ITK, found by examining the `SuperBuild/External_ITK.cmake` file.
  5. Configure ITK using CMake
    • e.g. BUILD_EXAMPLES=OFF, BUILD_TESTING=OFF, BUILD_SHARED_LIBS=OFF, ITK_USE_REVIEW=ON
  6. Build ITK
    • Be sure to note the build settings e.g. Release x64
  7. Configure SimpleITK using CMake
    • Set ITK_DIR to the location of the ITK build location from the previous steps
  8. Build SimpleITK
    • Be sure to configure the build settings exactly the same as ITK e.g. Release x64 and CXX_FLAGS

Advanced Build Options

SimpleITK is aware of the enabled and disabled ITK Modules. It is possible to customize SimpleITK by disabling unneeded ITK modules or to extend SimpleITK by writing custom json file dependent an ITK Remote Modules being enabled.

Additionally, each of the Examples directory, and each of the Wrapping subdirectories can be configured as independent CMake project dependent on an installed SimpleITK.

A visual guide to building SimpleITK on Linux

Testing

After compilation the prudent thing to due is to test SimpleITK to ensure your build is stable and suitable for installation and use. The following commands execute the SimpleITK tests.

cd SimpleITK-build/SimpleITK-build
ctest

On Windows you will need to specify configuration. Typically that would be the Release configuration, as such:

cd SimpleITK-build/SimpleITK-build
ctest -C Release

Python installation

To install a built python package into the system Python, as root run:

 cd SimpleITK-build/Wrapping/Python
 python Packaging/setup.py install

Alternatively, a Python virtual environment can be created and the distribution installed there.

A Python Wheel file (.whl) can be created in the "Wrapping/Python/dist" directory, by building the "dist" target. If you have used the Superbuild with the "make" generator then issue the following command:

 make -C SimpleITK-build dist

R installation

To install a built R package:

 cd SimpleITK-build/Wrapping/R/Packaging
 R CMD INSTALL SimpleITK

This will install the R package "SimpleITK" in /usr/local as root or your local R installation directory.


If you are working in a multi-user environment, and are considerate of your fellow users you can install the package in a local directory:

  1. Create a local directory where you will install your R packages
 mkdir my_R_libs
  1. Add an environment variable to your .bashrc
 export R_LIBS="/path_to/my_R_libs"
  1. source your .bashrc and check the R library path, in an R shell >.libPaths()
  1. install
 cd SimpleITK-build/Wrapping/R/Packaging
 R CMD INSTALL -l /path_to/my_R_libs  SimpleITK

Recommended Software

Fiji (Fiji is Just ImageJ)

SimpleITK has a built in function, "itk::simple::Show()", which can be used for viewing images in an interactive session. Currently, this function by default Show invokes Fiji then ImageJ to display images. ImageJ was chosen because it can handle all the image types that SimpleITK supports, even 3D vector images with n components.

The Show function first searches the "PATH" environment variable, then additional standard locations are examined, if problems are encountered the correct path can be added to this environment variable and the "debugOn" option to "Show" flag set.

ImageJ

If ImageJ is used then we recommend downloading a recent version of ImageJ from the official home page. Recent versions come with support for the Nifti ( *.nii ) file format, which SimpleITK uses to export to ImageJ.

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 and Jupyter

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

We have instructional SimpleITK Jupyter Notebooks which can help you get started.