TA: Weilong Wang: weilongw+miia ATandrew.cmu.edu
Grader: "Jackie" Chen: kuanchic+miia ATandrew.cmu.edu
*** 1 Week Extension Granted ***
Due Date: Email your submission to your Grader by midnight (~11:59 PM EST) on Monday night, Feb.
11 18. 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.
WARNING: You may need up to 25 GB of free space for this assignment. If that's a problem, please send me email.
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 2010 installed (2012 may work, but is not well tested), you will probably want to do so now. CMU students should download it from CMU's Dreamspark Premium site, and Pitt students should be able to get physical installation media from Pitt's campus. Otherwise, If you are a student, you can probably download Visual Studio 2010 Professional for free (after being certified as a student) from Microsoft's DreamSpark student program. Failing that, anyone can freely download Visual Studio Express 2012 for Windows Desktop (least good choice, but may be sufficient; the older Visual Studio Express 2010 is NOT recommended due to 32-bit limitatations.). In all cases, be sure to install all available online updates (Windows update can do this for you).|
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 18.104.22.168. 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.4. 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 Download page. The most recent version is 1.46. (On Mac, if ImageJ.app is not located inside an ImageJ folder, then you may need to place an alias to ImageJ.app directly in your Applications folder. This was required for previous versions of SimpleITK, but I'm not sure about current versions.) 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 (please be aware that if you do, then you may have less luck finding binary installers for other 64-bit python modules). Later, you will need to compile your code to match your choice here of 32-bit or 64-bit. 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, PyZmq, Tornado, PyReadline, Pygments, PySide, and iPython. 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.
I highly recommend using iPython for interactive python usage. On Windows, this means going to Start->All Programs->IPython and then choosing either "IPython Qt Console (pylab mode)" or "IPython Notebook (pylab mode)". Notebook mode allows for a mathematica-like interface, but it does not work with Internet Explorer versions 9 or older.
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.10.1) and extract both of these archives into them.
Now run the CMake GUI:
|On Windows 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 10 (32-bit). Warning: if you installed a 64-bit version of Python, you must choose a 64-bit build, such as Visual Studio 10 Win64; otherwise, 32-bit Python requires telling CMake to use Visual Studio 32-bit instead. WARNING: NEVER choose IA64 (unless you are absolutely sure you are using this Microsoft-abandoned, enterprise-server architecture that is not x86-64 compatible). 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.10, 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 named
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.10.1 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.
Before we can custom compile SimpleITK, we must first install another support program:
"Git" is 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/.
|On Windows, the git installer will eventually ask you about "Adjusting your PATH environment," at which point you should choose to "Run Git from the Windows Command Prompt." Everywhere else, go with the default choices.|
Once git is installed, we can now use an automated process to download, compile, and install C++ ITK as needed for SimpleITK. Download the SimpleITK source code by using a command prompt to change to your MIIA directory and then issuing a couple of git commands:
git clone --recursive http://itk.org/SimpleITK.git
git checkout v0.6rc2 -b beta.6rc2
While we're at it, now is also a good time to also check out a set of SimpleITK iPython notebooks. Again, use git from a command prompt:
git clone --recursive https://github.com/SimpleITK/SimpleITK-Notebooks
After that is finished, create a place to build SimpleITK:
Now, run CMake and for the source-code directory use SimpleITK's super-build directory, e.g.
c:\miia\SimpleITK\SuperBuild , and use a binary directory of
c:\miia\SimpleITK-build. After configuring, you should be able to turn off BUILD_EXAMPLES, but be sure to leave BUILD_TESTING turned on (it is required to produce a Python egg file).
|On Windows, Check the "Advanced" box at the top of CMake, and then find the entry for CMAKE_EXE_LINKER_FLAGS_DEBUG and change the end of it from /
Configure again and then generate your build environment.
|On Windows, after the above finshes, your
Open this file in Visual Studio, select the ALL_BUILD target, and then build the solution. This will automatically download and compile ITK, etc. as needed. NOTE: It is okay to have 1 build error that is a link error for not finding python27_d.lib--we don't need debug-mode Python code anyway, and so we'll use the python code produced when we rebuild in release mode, below.
|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
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.
Email your grader a list of the resulting files in
MIIA\SimpleITK-Build\lib. (either a text list or a screen shot is acceptable).
If all you want to do is use SimpleITK in Python, then life is fairly easy now. Normally, I would have you download and install the latest stable version of SimpleITK for Python by simply entering
sudo easy_install SimpleITK at a command prompt. However, I want you to use the latest release candidate that you just built in step 3. To install that egg file, first go to your directory
miia\SimpleITK-build\SimpleITK-build\Wrapping\dist and look for the egg file. The egg file will start with SimpleITK- and will end with the .egg extension. You will need the full name of this file. Now, enter the following at a command prompt:
Under Mac OS X or other UNIX-like systems, you will probably need to prefex easy_install with the sudo command, like this:
sudo easy_install SimpleITK-*.egg
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.
At this point, from the previous super build you should already have an ITK source directory located here:
and a working installation of ITK located here:
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.
...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.