TA: Vikas R.S.: vir16+miia ATpitt.edu
Grader: "Jackie" Chen: kuanchic+miia ATandrew.cmu.edu
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
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.
Before you begin, create a new directory for this class, such as
C:\MIIA\ in a Windows environment
~/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
|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 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 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 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 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
|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
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
|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
You should then add both
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).
|On Windows use your newly opened command prompt to enter the command "
On OS X and Linux use a command prompt to enter the command "
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
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.
Both Matplotlib and iPython should be installed from the command line, e.g.
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.|
Open a python prompt, and then enter the following two lines:
import SimpleITK as sitk
*** Email the resulting text (with the rest of your submission) to your grader.
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 (
You also need the
(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\VTKData-5.8.0) and extract both of these archives into them.
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.
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.
On Linux (and OS X) you can use CMake's command-line "GUI"/TUI tool
IMPORTANT: Note that "../
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.,
|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
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.
Create a new directory, e.g.
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
|Mac users should now enhance the CMakeLists.txt file they just copied by changing the
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 "
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.
The ITK source code is at
http://www.itk.org/, on the
Download page (available via the Resources menu). You want to grab both
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.
Now run the CMake GUI, as you did for VTK, but using your newly created
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.
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.
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:
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
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.
Before we can custom compile SimpleITK, we must first install a couple more support programs:
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 is also required to compile SimpleITK.
|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
On Linux you hopefully already have the
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
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
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.
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.
...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.