SimpleITK/GettingStarted: Difference between revisions
Line 38: | Line 38: | ||
==C# binary files== | ==C# binary files== | ||
Binaries for select C# platform can be found on [http://sourceforge.net/projects/simpleitk/files/SimpleITK/0.8.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 [http://sourceforge.net/projects/simpleitk/files/SimpleITK/0.8.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. |
Revision as of 14:42, 7 April 2014
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 Windows, Linux and Mac OS X. C# and Java binaries are available for Windows. We are also working towards supporting R packaging.
Python binary files
The list of the binary Python packages available is maintained here.
Your versions of python, operating system, and architecture must be available to use a 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 the setuptools package to obtain it. Please go to the setuptools home page for detailed installation instructions.
Once you have installed setuptools, and easy_install is in your path, then run the following command as root to install the SimpleITK package in system's site-packages:
$ sudo easy_install -U SimpleITK
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.
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
$ export http_proxy=http://someproxy.somewhere.com:8080 $ sudo -E easy_install -U SimpleITK
Advanced users may prefer to install SimpleITK in a virtual python environment, so that it does not modify the global python environment.
Please Note: "pip" does not work with our built eggs. We do have Python wheels available for manual download on SourceForge.
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-0.8.0-CSharp-win32-x86.zip SimpleITK-0.8.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: 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 it is not required to build SimpleITK. The easiest way is to use the pre-compiled binary files (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 >= 2.8.4, for testing >= 2.8.11
- 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 and SWIG
- Windows users may prefer msysGit
- It is recommended to have numpy installed when testing Python bindings
Source code
There are two options to obtain the SimpleITK source code:
- Download a released version from the SimpleITK SourceForge page
- 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 and/or SWIG, or if you do not want to (or can not) use git (due to firewall, etc).
- Setup the prerequisites as described above (i.e. CMake and supported compiler)
- Install the matching version of SWIG >= 2.0.12
- e.g. Windows users may install swigwin-2.0.12
- Download the SimpleITK source code from the SourceForge page
- Download the matching version of ITK
- e.g. SimpleITK 0.8.0 uses ITK 4.5.1 (tag v4.5.1)
- Configure ITK using CMake
- BUILD_EXAMPLES=OFF, BUILD_TESTING=OFF, BUILD_SHARED_LIBS=OFF, ITK_USE_REVIEW=ON, ITK_WRAP_*=OFF
- Build ITK
- Be sure to note the build settings e.g. Release x64
- Configure SimpleITK using CMake
- Set ITK_DIR to the location of the ITK build location from the previous steps
- Build SimpleITK
- Be sure to configure the build settings exactly the same as ITK e.g. Release x64
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 use and installation. 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
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
To install a built python package into the system Python, as root run:
cd SimpleITK-build/Wrapping python PythonPackage/setup.py install
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.
R installation
To install a built R package:
cd SimpleITK-build/Wrapping/Rpackaging R CMD INSTALL SimpleITK
This will install the R package "SimpleITK" in /usr/local as root or your local R installation directory.
Recommended Software
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 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 ImageJ from the official home page. 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" 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.
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 terrific environment to perform interactive commands for image processing. With the addition of numpy and scipy, you'll have a powerful interactive environment.
We have instructional SimpleITK Notebooks which can help you get started.