Assignment 2
Methods In Medical Image Analysis (BioE 2630 : 16-725 : 18-791 : 42-735) - Spring 2012

Creative Commons License ITK Development Environment Setup Assignment by John Galeotti, ©Carnegie Mellon University, is licensed under a Creative Commons Attribution 3.0 Unported License. Permissions beyond the scope of this license may be available by sending email to itk ATgaleotti.net. This assignment was made possible in part by NIH NLM contract# HHSN276201000580P.

TA: Vikas R.S.:  vir16+miia ATpitt.edu
Grader: "Jackie" Chen:  kuanchic+miia ATandrew.cmu.edu

20 points total

Due Date: Email your submission to your Grader by midnight (~11:59 PM EST) on Thursday night, Feb. 2. Big problems may not show up until the end, so finish early!

Acknowledgement: This assignment is based on the work of others from previous sessions of this class.

E-mail your TA or instructor with questions or problems.

Before doing any ITK development, you will need to setup a working environment in which to compile your code. This includes

  1. Installing Support Programs: CMake, ITK-SNAP, ImageJ, and a full Python environment
  2. Installing SimpleITK for Python
  3. Compiling & Testing VTK
  4. Compiling & Testing ITK
  5. Compiling SimpleITK

For further guidance on these procedures and how to test your build environment, you may wish to consult the slides from Lecture 4.

Note: Your life will be easiest if you use windows for this class, but we will try to work with you on Mac as well.

0. Directory Structure (0 points)

Before you begin, create a new directory for this class, such as C:\MIIA\ in a Windows environment or ~/MIIA/ under Linux or OS X. You will probably find it convenient to keep all of your downloaded libraries (i.e., ITK, VTK, etc.) in this same root directory. For the rest of this class, C:\MIIA\ should be taken to mean whichever directory you created in this step, e.g. if you use a Mac, then when assignments say C:\MIIA\ then you should presumably use either ~/MIIA/ or ~/Documents/MIIA/ instead.

1. Installing Support Programs (0 points)

Compiler

On Windows, if you do not already have Visual Studio 2008 or 2010 installed, you will probably want to do so now. If you are a student, you can probably download Visual Studio 2010 Professional 32-bit for free (after being certified as a student) from Microsoft's DreamSpark student program. Failing that, anyone can freely download Visual Studio C++ Express 2010, but it can only compile 32-bit code (which does work on a 64-bit operating system as long as you have 32-bit versions of all the 3rd-party libraries listed below).

On OS X, if you do not already have XCode installed, you should do so now, either by installing it from your OS X install DVD, or if you're running Lion you can download it for free from Apple's App Store.

On Linux you hopefully already have gcc installed.

CMake

CMake can be downloaded from http://www.cmake.org/ on the Download page (available via the Resources menu). The most recent version is 2.8.7. Use the binary distribution appropriate for your operating system (note: 32 bit CMake binaries should run fine on 64 bit operating systems). Installing CMake is relatively painless and you probably won't run into any problems here. I do, however, recommend letting the Windows installer add CMake to your system path (or, equivalently, letting the Mac installer "Install Command Line Tools").

Note: When using newer versions of CMake with pre-existing software, feel free to ignore any warnings about either "cmake_minimum_required" or "Policy CMP0003".

ITK-SNAP

ITK-SNAP is a 3D medical image segmentation/viewer program, which internally uses ITK+VTK+FLTK. It can be downloaded from http://www.itksnap.org/ on the Downloads page. The most recent version is 2.1.4-RC1. Use the binary distribution appropriate for your operating system. Installing ITK-SNAP is relatively painless and you probably won't run into any problems here.

ImageJ

ImageJ is a Java-based image processing/analysis/viewer program, which is called by SimpleITK's "show" command as a simple means to quickly view images. It can be downloaded from http://rsbweb.nih.gov/ij/ on the Downloads page. The most recent version is 1.45. (On Mac, if ImageJ.app is not located inside an ImageJ folder, then be sure to place an alias to ImageJ.app directly in your Applications folder. Hopefully future versions of SimpleITK will not require this step.) Installing ImageJ is relatively painless and you probably won't run into any problems here. (FYI, if outside of this class you need to use an older version of ImageJ, then be sure you have the Nifti image-format plugin for ImageJ installed from http://rsbweb.nih.gov/ij/plugins/nifti.html. ImageJ 1.45 already includes this plugin.)

Python

Python is an interactive python shell. By interactive, I mean python executes each line as you enter it, similar to Matlab. It makes rapid prototyping with SimpleITK very easy.

Linux and Mac systems should already have python installed, usually version 2.6 or 2.7. On Windows, you will probably have to install python yourself. You can check if your operating system already has python installed by opening a command-line window and entering the command python.

To open a command-line window (i.e., a command prompt)
On Windows one way to open a command-line window (i.e., a command prompt) is to click on the start menu, which will show either a search box or a Run... command. Using either of these, enter the text cmd then hit enter.

On OS X You can simply run the Terminal program located in your Applicaitons/Utilities folder. (Or, even better, you can install and use the free iTerm program.)

On Linux you hopefully already know how to open a command prompt (oftern called a Terminal or a Bash shell, etc.).

If the python command works, you will be told which version of python you are using and you can then enter the python command quit() to exit.

On Windows, even if the python command does not work, python may still be installed. You can try looking for Python?? in your "All Programs" menu, and you can also try looking for the directory Python?? in either C:\ or in C:\Program Files. (Note that Python?? means Python followed by some version number.)

Installing Python for Windows

Python Windows .msi installers can be downloaded from http://python.org/download/. You are strongly recommended to install Python version 2.7. If you are running a 64-bit version of Windows, you can install the 64-bit version of python, but please be aware that if you do, then you may have less luck finding binary installers for other python modules (For example, iPython, below, does not have an "official" 64-bit binary installer). Choose all the default choices when running the installer.

Once you have installed Python itself, you should also install python's distribute module (which, FYI, has replaced the old and buggy "setuptools" module) by downloading (e.g., right-click and save-as) the file distribute_setup.py from http://python-distribute.org/. You should then be able to double-click on the file to automatically download and install distribute.

You should then add both C:\Python27 and C:\Python27\Scripts to your system's path, by clicking on the start menu, right-clicking on Computer, choosing Properties, (for newer versions of Windows, then click on Advanced System Settings), in the resulting dialog box find and click on the Environment Variables button, find and edit the system entry for Path, and then at the end of that entry add, e.g.:

;C:\Python27;C:\Python27\Scripts

Be sure to enter the two semicolans above, and make sure that the directories you enter represent the actual Python directories installed on your system.

Finally, once your path has been updated, you should open a new command prompt window for use with the rest of this assignment.

You should now test your installation be installing "pip" (a newer, better python module installer).

Installing pip
On Windows use your newly opened command prompt to enter the command "easy_install pip", which should automatically download and install pip if everything is working correctly.

On OS X and Linux use a command prompt to enter the command "sudo easy_install pip", which should automatically download (if necessary) and install pip if everything is working correctly. (Note that here, and elsewhere in this assignment, the "sudo " prefix is of course unnecessary in the unlikely case that you already have root access.)

You are now ready to install several useful add-ons for python:

Installing NumPy, SciPy, Matplotlib, iPython, etc.
On Windows by far the easiest way to install well-optimized versions of these packages is to download Christoph Gohlke's "unofficial" binary installers from http://www.lfd.uci.edu/~gohlke/pythonlibs. Just be sure to download the correct version (e.g., win32-Py27 for 32-bit systems or win-amd64-Py27 for 64-bit python on AMD or Intel systems) of each of the following modules, installing them in the order listed:  NumPy, SciPy, Matplotlib, iPython, and PyReadline. Once these are installed, it is recommend that in the future you run python by clicking on the pylab icon in the IPython folder of the start->programs menu.

On OS X and Linux NumPy is hopefully already installed. You can test this by opening a python shell (at a command prompt enter the Pythoncommand) and then in the python shell entering import numpy. If there are no errors, then NumPy is already installed. (This same procedure can be used to check of the other, following modules are installed as well.)

Fairly optimized binaries of NumPy (if not already installed on your system) and SciPy can be downloaded for several Linux and Mac distributions (but not the default Python included with Mac OS 10.6 "Snow Leopard" or earlier) by following the instructions at http://www.scipy.org/Download. As an alternate method, you can try using either "pip install" or easy_install to install these packages from a command prompt (e.g. sudo pip install scipy), but beware that it may be nontrivial to get and install properly compiled versions of the libraries NumPy depends on, including LAPACK, ATLAS, and Goto BLAS. (If you can't get SciPy to install for some reason, such as being stuck with a version of NumPy that is too old, then don't worry about it for now. If you really need SciPy later, you can spend more time trying to install it then. The alternative would be to do a clean install of a separate version of Python directly into ~/MIIA/Python27.)

Both Matplotlib and iPython should be installed from the command line, e.g. sudo pip install matplotlib and sudo easy_install ipython. Note that installing Matplotlib requires that you have version 2 of the freetype library already installed, which can be an issue on Mac. (As with SciPi, if you can't get matplotlib to install for some reason, then don't worry about it for now--you can always spend more time later trying to install it if it turns out you really need it. If you can't get iPython to install, then try one of the other installation methods listed on http://ipython.org/download.html.)

2. Installing and Testing SimpleITK for Python (5 points)

If all you want to do is use SimpleITK in Python, then life is fairly easy now. SimpleITK for Python can be easily downloaded and installed from the command prompt by entering sudo easy_install SimpleITK.

On Windows note that if you do not already have Visual Studio 2010 installed, then you will also need to install the appropriate Visual C++ 2010 SP1 Redistributable Package for either Win32 or x64 systems; if you don't do this, you will get the cryptic "ImportError: DLL load failed: ..." when you try to import SimpleITK.

Testing

Open a python prompt, and then enter the following two lines:

import SimpleITK as sitk
sitk

*** Email the resulting text (with the rest of your submission) to your grader.

3. Compiling & Installing VTK (5 points)

The VTK source code can be downloaded from http://www.vtk.org/ on the Download page (available via the Resources menu). You want the latest official source release (vtk-5.8.0.zip). You also need the vtkdata-5.8.0.zip file. (Regarding the windows installer listed on the VTK website, we have no experience with it, and recommend that for consistency across platforms you use the source release instead.) Create new directories for both of these files (e.g. C:\MIIA\VTK-5.8.0 and C:\MIIA\VTKData-5.8.0) and extract both of these archives into them. C:\MIIA\VTKBin).

Now run the CMake GUI:

On Windows it might be called either CMake or CMakeSetup, and in either case it should be in your Applications folder (or Start Menu) under CMake. At some point CMake will ask what compiler system you are using, e.g. Visual Studio 2010 (32-bit). Warning: You may have issues later (compiling SimpleITK beta 0.3) if you choose Visual Studio 64-bit, so in this class always have CMake use Visual Studio 32-bit instead. At the top of the CMake GUI are two fields, one for source code and one for where to build the binaries; the source code directory is the directory where VTK has been extracted (e.g. C:\MIIA\VTK-5.8.0), and the binary directory is the directory in which you want to build (e.g. C:\MIIA\VTKBin).

On OS X I recommend using the GUI App named CMake-2.8.7, which is located in your Applications folder and is similar to the windows GUI. If you are asked to select a generator, then select the option most appropriate for the compiler you intend to use, e.g. "Xcode with default native compilers." At the top of the CMake GUI are two fields, one for source code and one for where to build the binaries; the source code directory is the directory where VTK has been extracted (e.g. ~/MIIA/VTK-5.8.0), and the binary directory is the directory in which you want to build (e.g. ~/MIIA/VTKBin).

On Linux (and OS X) you can use CMake's command-line "GUI"/TUI tool ccmake by issuing the following command within your VTKBin directory:

    ccmake (-G Xcode) ../vtk-5.8.0

    IMPORTANT: Note that "../vtk-5.8.0" should be the path to the directory where you extracted VTK. Change this if necessary.

Once your CMake GUI is running, you want to "configure" the system. This will cause cmake to establish environment settings for the build process. Once finished, you will be presented with a (nested) list of optional or unknown values for you to change as needed (these will typically be shown in red). Make sure that BUILD_SHARED_LIBS, BUILD_EXAMPLES, and BUILD_TESTING are turned off. You should turn on VTK_USE_PARALLEL and VTK_USE_RENDERING. Also set VTK_DATA_ROOT to the directory where the VTKData archive has been extracted (e.g., C:\MIIA\VTKData-5.8.0).

On a Mac, you should also turn on only one of: VTK_USE_CARBON, VTK_USE_COCOA, or VTK_USE_X; cocoa is recommended.

Once these variables have been set, Configure again. If the "Generate" button is still grayed out, click "Configure" yet again. Finally, you should be able to generate the build environment (i.e., on Windows you will eventually be able to click the "Generate" button).

On Windows, this will create a Visual Studio workspace solution that can be used for the build; you want to build the ALL_BUILD target inside it.

Under Mac OS X or other UNIX-like systems, this should generate either a Makefile or an Xcode project that can be used for the build. If using Xcode, then build the ALL_BUILD Target. If you are using a Makefile, simply issue the make command from within the VTKBin directory.

After using your compiler of choice to build the solution/project/Makefile that CMake just created in your VTKBin directory, then your VTKBin\bin\(Debug\)(or similar) directory will contain the compiled binaries necessary for linking to VTK.

Testing

Create a new directory, e.g. C:\MIIA\VTKTest-5.8.0

VTK-5.8.0 contains an Examples directory. Copy the 2 files from the Examples/Tutorial/Step6/Cxx directory out of VTK, and into the new directory C:\MIIA\VTKTest-5.8.0

Mac users should now enhance the CMakeLists.txt file they just copied by changing the ADD_EXECUTABLE line to read as follows "ADD_EXECUTABLE(Cone6 MACOSX_BUNDLE Cone6.cxx)".
Create a build directory (e.g. C:\MIIA\VTKTestBin). Run the CMake GUI with the newly created source and build directories. If CMake complains about not finding VTK, don't worry--just set VTK_DIR to point to your VTKBin directory, and then Configure/Generate. Compile the code. Inside your build directory there will now be an executable program named Cone6. Run the Cone6 program.
Mac users should run the program by double-clicking on the application bundle icon or by typing "open Cone6.app" from the command line in the same directory as the newly built app.

If all you see is white then press the "r" key on your keyboard. Take a screenshot (on windows, you can press Alt-PrtScn on your keyboard; on Mac, you can use the included Grab program or the Command-Shift-4 shortcut.) Email the screenshot (with the rest of your submission) to your grader.

If you run into problems building VTK, and your TA cannot immediately resolve them, then please subscribe to the VTK users mailing list and ask for help.

4. Compiling & Installing ITK (5 points)

The ITK source code is at http://www.itk.org/, on the Download page (available via the Resources menu). You want to grab both InsightToolkit-4.0.0.zip and InsightApplications-4.0.0.zip. If you haven't already done so, download the ITK Software Guide 2.4.0 PDF while you're at it.

Extract both archives. Create a new directory to build ITK in (e.g. C:\MIIA\InsightBin).

Now run the CMake GUI, as you did for VTK, but using your newly created InsightBin and InsightToolkit-4.0.0 directories. Make sure that ITK_BUILD_ALL_MODULES is turned on and BUILD_SHARED_LIBS, BUILD_EXAMPLES, and BUILD_TESTS are turned off. You may wish to enable advanced options and then turn on ITK_USE_PATENTED in case you have interest in using any of the patented algorithms in ITK (e.g. fuzzy connectedness).

Once these variables have been set, Configure again. Finally, you should be able to "Generate" the build environment. Build ITK (just like you built VTK); this will take a considerable amount of time.

Testing

Follow the instructions in Lecture04 to perform the ITK installation test. Because HelloWorld.exe is a command-line program, you should probably run it either from within Visual Studio, or from a command-prompt. Email the text output (with the rest of your submission) to your grader.

Build again

At this point, Visual Studio (and most other compilers) will have built ITK with debugging turned on. For most purposes in this class, you want debugging turned on, but for the segmentation assignment you will want to speed up your code once it is well-debugged, and that requires that you have ITK built both with and without debugging support.

On Windows to build a second copy of ITK without debugging support in Visual Studio:

  1. Open you already existing Visual Studio project for ITK (the one you generated from CMake, above)
  2. In top center of Visual Studio there is a drop-down menu that currently will state "Debug" mode
  3. Change drop-down menu to "Release"
  4. Build ITK in Visual Studio

Now, in addition to ITK libraries being located in the Debug folder, there will be a second copy of ITK libraries located in the Release folder of your InsightBin directory.

FYI, the chief reason that turning off debugging support makes your code faster is that it allows the compiler much more freedom to automatically optimize your code. For the segmentation assignment, this could make your code over 6 times faster.

5. Compiling & Installing SimpleITK for C++ (5 points)

Update: This should all be working now.

Before we can custom compile SimpleITK, we must first install a couple more support programs:

Git

Gitis an advanced replacement for svn, designed for masively distributed collaborative development. (This class will actually use svn rather than git for submitting assignments, since svn is simpler.) Git is, however, the way that ITK 4.x and SimpleITK are developed, and is the only way to get the source code for custom-compiling SimpleITK, which is necessary to use SimpleITK in C++. Git can be easily downloaded and installed from http://git-scm.com/.

Swig

Swig is also required to compile SimpleITK.

Installing Swig
On Windows, just download http://prdownloads.sourceforge.net/swig/swigwin-2.0.4.zip and extract to someplace where you can tell CMake to find it.

On OS X consider installing and using MacPorts to install version 2.x of swig (e.g., after installing MacPorts, then enter sudo port install swig swig-python swig-java swig-tcl at the command prompt). Otherwise, you'll have to download swig's source from http://www.swig.org/download.html and compile and install it yourself.

On Linux you hopefully already have the port command installed, so that you can just enter sudo port install swig swig-python swig-java swig-tcl at the command prompt. Otherwise, you could try using another package manager (e.g., rpm or yum) to do the equivalent, or else you'll have to download swig's source from http://www.swig.org/download.html and compile and install it yourself.

SimpleITK

SimpleITK source code can now be downloaded by using a command prompt to change to your MIIA directory and then issuing the git command:

git clone --recursive https://github.com/SimpleITK/SimpleITK

Now change into the resulting SimpleITK directory (e.g. C:\MIIA\SimpleITK), and then "checkout" the v.3 beta (to match the python version installed above):

git checkout v0.3.0b -b beta.3x

Unfortunately, SimpleITK beta.3 requires two files (itkN4MRIBiasFieldCorrectionImageFilter.h/hxx) that were removed from the final v4.0 of ITK. As a workaround for the time being, remove the file N4MRIBiasFieldCorrection.json from the directory MIIA\SimpleITK\Code\BasicFilters\json:

git rm Code/BasicFilters/json/N4MRIBiasFieldCorrection.json

Update: for those having problems getting git to work, I created a zip file of what you should have up to this point.

Create a new directory to build SimpleITK in (e.g. C:\MIIA\SimpleITKBin). Now run the CMake GUI, and give it the resulting source (e.g. C:\MIIA\SimpleITK) and build directories. When given the choice, disable BUILD_TESTING and (unless you plan on using it) disable everything in the WRAP category as well. Make sure that the Ungrouped entry ITK_DIR points to the verion of ITK you just built. (If, contrary to the above suggestion, you choose to wrap Python anyway, then be sure that CMake's options under the "Advanced" Python category all point to the correct version of python.) Generate and then build SimpleITK.

If you have linker errors (especially on Windows-64 bit) involving the SimpleITKBasicFilters library being too large, then you should probably check if you are compiling 64-bit code. If so, then the only sure way to fix things is to re-compile VTK, ITK, and SimpleITK in 32-bit mode instead of 64-bit mode. Hopefully future releases of SimpleITK won't have this problem.

(As an alternate solution, you can try changing Visual Studio's setting for Whole Program Optimizaiton--Link Time Code Generation. This has allowed some people to compile 64-bit SimpleITK in both Release and Debug mode, but for others DEBUG mode in particular still fails to compile.)

Email your grader a list of the resulting files in MIIA\SimpleITKBin\lib\Debug\

6. Build InsightApplications (optional!) (0 points)

Warning: This is not necessary for this class, but it may prove helpful to you. This can take a very long time and a lot of disk space.

Create a new directory to build InsightApplications in (e.g. C:\MIIA\ITKAppsBin).

Now run the CMake GUI using your newly created ITKAppsBin and the InsightApplications-4.0.0 directories. Turn off BUILD_SHARED_LIBS and turn on USE_VTK and BUILD_TESTING. You may have to repeatedly configure several times to get all these options turned on. Once all the variables have been set, Configure again. Finally, you should be able to "Generate" the build environment. Build InsightApplications; this will take a very long time and a lot of disk space.

7. Rejoice...

...or not. One thing you may try before contacting anyone is to ensure that your compiler system is up-to-date with the latest patches.

Microsoft publishes service packs for the Visual Studio suite that can be found at http://msdn.microsoft.com/.

Apple makes available the latest version of the Xcode Tools for download at http://developer.apple.com (may require setting up an account on the site - it's free).

If you are not using either of these systems, or you still run into compiler/linker errors after updating, please do not hesitate to copy and paste your errors to someone (preferably the TA). If he can't help you, he'll find someone who can.

Good luck!