Assignment 2
Methods In Medical Image Analysis (16-725 : BioE 2630) - Spring 2023

Creative Commons License ITK Development Environment Setup Assignment by John Galeotti (among others) © 2012-2019 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.

20 points total

Due Date: 11:59 Tuesday Feb. 21. Try to get parts 0, 1, and 2 done before next class.  Big problems may not show up until the end, so finish early! Do not expect help from TA or instructor after 5pm on the day due 

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

E-mail the TA and instructor with questions or problems.

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

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

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 Mac OS X or Windows 7/8/10 for this class, or possibly a recent version of either RHEL/CentOS or Ubuntu/Debian. But, we will try to work with you on other platforms as well.

WARNING: You may need up to 20 GB of free space for this assignment. If you are short on local disk space, then one possibility is to mount your BOX online storage space and compile SimpleITK into it. Both CMU and Pitt students have access to at least 1 TB of personal space on Box. See the course website for instructions on using BOX or GDrive as a network drive.  When using Box this way, be sure to have the fastest internet connection you can while compiling VTK and SimpleITK (I suggest using a cable to direclty connect to the campus network). If space is still a problem for you, please send the instructor & TA an email.


Submission checklist: 

1. Screenshot from Step-2(a). Save the screenshot as 'Step2-Notebook.jpg'. 

2. Screenshot from Step-2(b). Save the screenshot as 'Step2-SITK.jpg'. 

3. Screenshot from Step-3. Save the screenshot as 'Step3-VTK.jpg'.

4. Screenshot from Step-4. Save the screenshot as 'Step4-SITK-Libs.jpg'. 

5. Screenshot from Step-5. Save the screenshot as 'Step5-ITKTest.jpg'. 

Instructions: Please submit everything on Canvas.  If you have any special instructions, please submit them in an optional ReadMe.txt file as part of your submission.

0. Directory Structure (0 points)

Before you begin, create a new directory for this class to hold your (Simple)ITK and VTK libraries, etc., such as C:\MIMIA\ in a Windows environment or such as ~/MIMIA/ under Linux or OS X (Linux and Mac both recognize ~ as a shortcut for your home directory). You will probably find it convenient to keep all of your downloaded libraries (i.e., ITK, VTK, etc.) in this same MIMIA directory. (Note for 2023:  You may have already created your mimia directory in the prior homework.)            

WARNING: If your username on your computer is longer than 8 characters, then do NOT put your MIMIA directory inside your standard "Documents" folder. Instead, you are strongly encouraged to put your MIMIA directory either in the top (root) folder of your hard drive (c:\MIMIA on Windows), or else maybe in the top of your user's home directory (i.e., the folder that contains your Documents folder, e.g. c:\Users\{your user name}\MIMIA).

WARNING: Do not include any special characters (such as - $ @ : ; / \ [ ] ( ) { }) in the directory path to your MIMIA folder. For example, do not do something like "Documents/16725 - Med Image Analysis/MIMIA". Such special characters can easily interfere with shell scripts such as those used by CMake.

For the rest of this class, C:\MIMIA\ should be taken to mean whichever directory you created in this step, e.g. if you use a Mac, then when assignments say C:\MIMIA\ then you should presumably use either ~/MIMIA/ or ~/Documents/MIMIA/ instead.

Additional directories for this assignment:

Now, also create a directory for iPython Notebooks, such as C:\MIMIA\Notebooks\.

Also, create a submission directory 'hw_Install':

1. Installing Support Programs (0 points)

Environment

You should be able to do this assignment on Windows, Mac, or Linux/UNIX. If for some reason you do not want to install software into your normal environment (most users can skip the rest of this paragraph), then one option is to create a virtual machine for this assignment. Both VMWare and Parallels are fast virtual machines from commercial providers, but VMWare is currently available to CMU students under a campus license. VirtualBox is a free, open source virtual machine that can also be used, but your code may compile and/or run slower inside of a VirtualBox virtual machine. SimpleITK has a nice tutorial on setup up an appropriate enviroment in Linux, including steps to create a VirtualBox virtual machine and to install Ubuntu Linux on it. You can find the tutorial here, but only follow the first steps of installing Linux and build tools (the rest of the tutorial's instructions should be ignored and this assignment used instead). Also, after installing the build tools, be sure to install OpenGL developer libraries so that you can compile VTK too. Do this by using Ubuntu's command line to enter the command: sudo apt-get install freeglut3-dev

Compiler

On Windows, if you do not already have Visual Studio installed, you will probably want to do so now. (On Windows, I currently recommend Visual Studio 2019. University students should download Visual Studio 2019 from Microsoft's Azure Dev Tools for Teaching (CMU students should follow CMU's specific login instructions.) If possible, get a key for the Enterprise version of Visual Studio, otherwise try to get the Professional version. Pitt students may also be able to get physical installation media from Pitt's campus. When you run the (current, i.e. early 2020) Visual studio installer, you should check the workload boxes like this.

(For older versions of visual studio or other instalation methods, if asked for your preferred development workloads/settings/environment, I recommend choosing "Visual C++" In all cases, be sure to choose a custom install and choose to install the C++ components.)

After Visual Studio is installed, you will need to login (use the same university email address you used to download it), and then you will be asked to choose your development settings.  Chose "Visual C++" like this.  Install all available online updates, especially the service packs, e.g. sp1 (Windows update should be able to do this for you, but you can also download Visual Studio service packs directly from Microsoft at http://msdn.microsoft.com/). Note that service packs can take several hours to install.

Most users can skip the rest of this box: If you instead already had Visual Studio installed and skipped the above instuctions: Since Visual Studio 2015, C++ is no longer installed by default. This is why we suggest you do a custom installation above. Alternateivly, if you already have Visual Studio 2015 or newer installed, you can tell it to add the C++ tools by running Visual Studio and then clicking on "File" -> "New" -> "Project" -> "C++", after which you will be prompted to install the necessary C++ components if they are not already installed. Windows 7 and 8 Important Note: Visual Studio since 2015 also requires Microsoft's C Runtime Library (CRT). This used to be included in Visual Studio, but is now included instead with Windows 10 (details here). If you are using Windows 7 or 8 (or earlier), then you will need to install the CRT manually by installing the Visual C++ Redistributable Package for VS 2015 or for 2017 or 2019.

On OS X, if you do not already have XCode installed, you should do so now by downloading the latest version 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 (top-right menu option). You must have a version ≥ 3.10. The most recent (and recommended) binary distribution is 3.16.3. Use the binary distribution appropriate for your operating system ( e.g. Windows x64 users should choose Windows win64-x64 Installer).

On OS X, you will download a .dmg disk image. Open the .dmg file (if it doesn't open automatically), and then drag CMake.app to the provided link to your Applications folder. Depending on your version of OS X, you may need to open your applications folder, and then inside your Applications folder right-click on CMake.app, and choose open from this menu. OS X will complain that CMake.app is from an unidentified developer, and you then need to click the Open button. Fortunately, you only have to do this once; hereafter you can open CMake normally.

Mac users will also need to manually install the command-line interface for CMake, by entering this command in a terminal (Terminal is in your Applications/Utilities folder; you will need to enter your user password when prompted):

sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install

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.

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+Qt. It can be downloaded from http://www.itksnap.org/ on the Downloads page. I suggest getting that latest 3.8.x version. 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. (Don't worry about any so-called errors you may get stating "A newer version of Microsoft Visual C++ 2010 Redistributable has been detected on the machine." ITK-SNAP will still work fine.)

Fiji / 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. ImageJ can be downloaded as part of Fiji from https://fiji.sc. Download the version of Fiji appropriate for your operating system. Windows users should unzip Fiji into their desktop, so that the Fiji.app folder is directly on their desktop (alternatively, you can place the Fiji.app folder into your "c:\Program Files\" directory). Installing Fiji/ImageJ is relatively painless and you probably won't run into any problems here.

At some point, Windows Defender Firewall may pop up telling you it has blocked imagej-win6, in which case I suggest  allowing it to communicate on all networks.

On OS X You may need to open Fiji "normally" once, using the icon in your Applications folder once, so that Fiji can configure itself and/or get permission to run from OS X. After that, then SimpleITK should be able to launch Fiji using the Show command.

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

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.

SimpleITK is available prepackaged for the Anaconda distribution of Python, which is by far the simplest cross-platform SimpleITK python installation. More information is available about Anaconda, including help and tutorials.

If you do not yet have 64-bit Anaconda installed

Download the latest Anaconda version for Python 3.9 from https://www.anaconda.com/distribution/. 64-bit is recommend (Assuming you have a modern 64-bit operating system). (Warning, Google Chrome on Windows may have issues downloading this file, so I recommend using a different browser for this download.)

Install the verion of Anaconda you just downloaded. Don't worry about warnings about being from an unknown publisher. If prompted, select to install for "Just Me" (in your home directory\anaconda). If asked, select to "Add Anaconda to my PATH..." and don't worry about the warning. If asked about registering Anaconda as your default Python 3.x:  If you are using Windows and you are sure you haven't installed another version of python 3.x, then you may choose to check the box.  Otherwise, or if you are unsure, I recommend to not make Anaconda your "default" Python.

Now open a command line (i.e., Terminal) window:

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. You can do this really quickly without using a mouse by just pressing the "Windows" key and then typing cmd and hitting 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 iTerm2 program.)

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


On OS X 10.15 (Catalina) Because Catalina now uses the zsh shell in your terminal instead of the bash shell used by all previous versions of OS X, you will need to do a couple of extra steps to finish installing Anaconda. Enter the following two commands into your terminal:

~/opt/anaconda3/bin/activate
~/opt/anaconda3/condabin/conda init zsh

Close your terminal, and then open a new terminal window to use for the following instructions.


Setup an isolated Conda (Python) environment for use in this class, then install VTK and SimpleITK in it

We will use conda from a command line to create an isolated conda environment for this class, so we don't interfere with any other anaconda or python installations on your computer.  Enter these commands one at a time (they may prompt you with questions, so don't copy and paste the entire block of commands at once):

conda update conda
conda create --name bmia python=3.9 ipython jupyter matplotlib scipy
conda activate bmia
pip install vtk
pip install simpleitk

Note: For this class, each time you open a new command prompt you may need to re-activate your bmia environment with the command conda activate bmia. If you ever need to tell a command line to stop using your bmia environment, you can do so with the command conda deactivate.

Note:  If (and only if) you get an "UnsatisfiableError" involving freetype and libpng, then do conda update freetype and then try installing simpleitk again.

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

Lastly, download ImageLoadingAndViewing_Basics.ipynb and place it in C:\MIMIA\Notebooks\  (Note: you might have to right-click on the link and choose Download or Save As).

Note: It is highly recommend to use some form of iPython instead of "regular" python for interactive python usage. In addition to command-line iPython, iPython's QtConsole provides some additional tools, iPython's Spyder provides a "normal" MATLAB-like interface, where you can edit a python source-code file on the left and also directly run commands in iPython console(s) on the lower-right, and iPython's Jupyter Notebook mode allows for a web-browser-based mathematica-like interface with inline images and inline graphing. You can easily launch most (if not all) of these iPython environments from inside of the Anaconda-Navigator application. You can also launch Spyder from the command line with the spyder command and Jupyter's Notebook interface using the jupyter-notebook command.

Testing Notebooks

Now try running iPython Notebook. (On mac/unix, dchange to your ~/MIMIA/Notebooks/ directory then enter the jupyter-notebook command.) Your webbrowser should open a webpage containing a list of folders, from which you should navigate to your Notebooks folder, and then you should click on the notebook you just downloaded (ImageLoadingAndViewing_Basics). Click on the "Cell" menu, and then click on "Run All". It's okay if the notebook seems to freeze up for several seconds when it first runs the sitk.Show() command, but if it stays stuck for more than a minute, you should replace the line sitk.Show(image) with sitk.ImageViewer().Execute(image) and try to run your notebook again after going to the kernel menu and telling the notebook to restart the kernel and clear all outputs. It's also okay if the notebook freezes for a couple of minutes for matplotlib to build its font cache for the first time (it will display a message inside the notebook if/when it builds the font cache). Now, scroll to the bottom where you should see a mostly blue or purple image plot. Take a screenshot (on windows, you can press Alt-PrtScn on your keyboard; on Mac, you can either use the included Grab program or the Command-Shift-4 shortcut). You can now close your iPython Notebook.

***Place the screenshot (with the rest of your submission) in your hw_Install folder.  (Be sure to use the filename mentioned at submisison checklist at the top of this page.)

Note:   If you get a runtime error about an exception thrown in sitkShow.cxx because it can't find a file or directory for the child process, then this probably means that SimpleITK can't find ImageJ. Email your TA or instructor, copying the exact error from your notebook, and also telling them exactly where/how you installed ImageJ and which version of Mac/Windows/Linux you are using.

SimpleITK

Open an ipython prompt (see above), and then enter the following two lines (note:  the first time you import SimpleITK it might take a minute, but thereafer should import very quickly):

import SimpleITK as sitk
print(sitk.Version_ExtendedVersionString())

***Place the screenshot (with the rest of your submission) in your hw_Install folder.  (Be sure to use the filename mentioned at submisison checklist at the top of this page.)

3. Compiling & Installing C++ VTK (5 points)

The VTK source code can be downloaded from http://www.vtk.org/ on the Download page source release (VTK-8.2.0.zip) and extract it into C:\MIMIA\ (this is not the latest release, but is compatible with the class' materials). This will create the folder C:\MIMIA\VTK-8.2.0, after which you should manually create the build folder C:\MIMIA\VTKBin.

**** WARNING: Do not put the downloaded source code or build directories for VTK or ITK into   c:\MIMIA\{Your_SVN_User_Name}\hw_Install. Only your submitted screenshots (and possibly a ReadMe.txt file) go into your hw_Install submission directory.

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 16 2019 (typically choose x64 platform for generator).
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:\MIMIA\VTK-8.2.0), and the binary directory is the directory in which you want to build (e.g. C:\MIMIA\VTKBin).

On OS X I recommend using the GUI App named CMake..., 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. ~/MIMIA/VTK-8.2.0), and the binary directory is the directory in which you want to build (e.g. ~/MIMIA/VTKBin). Note: If CMake asks you if you want to create Makefiles, you may want to choose XCode instead.

On Linux (and as an alternative on 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-8.2.0 (-DCMAKE_BUILD_TYPE=RELEASE)

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

Once your CMake GUI is running, make sure that "Grouped" is checked and that "Advanced" is not checked. You now 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_DOCUMENTATION, BUILD_SHARED_LIBS, BUILD_EXAMPLES, BUILD_TESTING and VTK_Group_Web are turned off
Turn on VTK_Group_Rendering and VTK_Group_StandAlone.  Change VTK_PYTHON_VERSION to 3.

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 click the "Generate" button).

On Windows, this will create a Visual Studio workspace solution named VTK.sln, in your 'VTKBin' folder, that can be used for the build. Open up VTK.sln and then compile/build it using the 'All Build' option for the 'ALL_BUILD' target inside it.
This will take ~10-15 minutes, maybe more depending on your system configuration. Wait for VS to finish building the solution.  

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 open up the VTK Xcode Project file and then select the ALL_BUILD Target and then compile/build it using the 'All Build' option (typically by pressing Command-B on the keyboard). [If instead 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\lib\(Debug\)(or similar) directory will contain the compiled binaries necessary for linking to VTK. WARNING: Double check the contents of your VTKBin\lib folder. If it only contains a cmake folder, then you didn't finish yet; CMake did its job, but you still need to use Visual Studio or Xcode to build VTK by following the instructions in the gray boxes above.

Testing

Create a new directory, e.g. C:\MIMIA\VTKTest

Now, VTK-8.2.0 will contain an 'Examples' directory. Copy the 2 files from the Examples\Tutorial\Step6\Cxx directory out of VTK, and into the new directory C:\MIMIA\VTKTest. Create a build directory (e.g. C:\MIMIA\VTKTestBin). Run the CMake GUI with the newly created source and build directories. If CMake complains (e.g., about an error in the configuration process or that project files may be invalid), it probably just means that CMake didn't find VTK; don't worry — we're about to fix it. Open up "Ungrouped Entries" and make sure that 'VTK_DIR' is set to your VTKBin directory.  If not, click the ... button to the right to choose your VTKBin directory. (Things might not work if it is set to a different VTK, such as one that might have been automatically installed by Anaconda.) Once you are sure that the correct VTKBin directory is being used, then hit Configure/Generate. Open up the Step6 solution file (or XCode Project file) and then compile/build it using the 'All Build' option. Check the debug folder inside your build directory for an executable program named 'Cone6.exe' (or Cone6.app). Run the Cone6 program.

If you see a white screen full of scrolling warning messages, just close that  window; you may have to click the x twice, a few seconds apart, to get it to close.  If all you see is white then press the "r" key on your keyboard. The cone should now be visable and interactive.  Take a screenshot (on windows, you can press Alt-PrtScn on your keyboard; on Mac, you can either use the included Grab program or the Command-Shift-4 shortcut). 

***Place the screenshot (with the rest of your submission) in your hw_Install folder. (Be sure to use the filename mentioned at submisison checklist at the top of this page.)

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

4. Compiling & Installing C++ ITK & C++ SimpleITK (5 points)

Before we can custom compile C++ SimpleITK, we must first install git:

Git

"Git" is an advanced replacement for svn, designed for massively distributed collaborative development. Git is 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 may already be installed (try typping "git --version" into a command prompt), but if git is not already installed then git can be easily downloaded and installed either direclty from http://git-scm.com/ (currently recommended) or else using Anaconda with conda install git

On Windows, as of Feb. 5th 2018, Anaconda git on Windows has a bug involving environment variable order that prevents cloning SimpleITK below; if you installed Anaconda git on Windows, I suggest removing it using conda remove git and then downloading git directly from the git-scm URL above.

The git installer may eventually ask you about "Adjusting your PATH environment," at which point you should choose to use "Git from the command line and also from 3rd-party software" (this is probably already the default). Everywhere else, go with the default choices.

SimpleITK

Once git is installed, we can now use an automated process to download, compile, and install C++ ITK as needed for SimpleITK. Download the latest (relatively stable) development version of SimpleITK source code by using a command prompt to change to your MIMIA directory and then issuing a couple of git commands:

cd \MIMIA
git clone --recursive https://github.com/SimpleITK/SimpleITK.git
cd SimpleITK
git checkout latest -b greatest

While we're at it, now is also a good time to also check out some SimpleITK Jupyter notebooks. Again, use git from a command prompt:

cd \MIMIA
git clone --recursive https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks
git clone --recursive https://github.com/ozan-oktay/Medical-Image-Analysis-IPython-Tutorials
git clone --recursive https://github.com/SimpleITK/SPIE2018_COURSE

After that is finished, create a place to build SimpleITK:

cd \MIMIA
mkdir SITKBin

Warning: We are deliberately using the short name of SITKBin because on Windows CMake requires us to keep the total pathname to all ITK directories to be less than 50 characters each.

Now, run CMake. For Windows, you probably want to choose "Visual Studio 16 2019" (or whatever matches your version of Visual Studio) for the generator, "x64" for the platform, and enter "host=x64" for the optional toolset, as shown here. For the source-code directory, use SimpleITK's super-build directory, e.g. c:\MIMIA\SimpleITK\SuperBuild , and use a binary directory of c:\MIMIA\SITKBin. When you press "Configure," don't worry about any potential pop-up warnings about needing to install a Java Runtime Environment--just click OK to make the dialog disappear without installing java. After configuring, you should be able to turn off each of BUILD_EXAMPLES, BUILD_TESTING, WRAP_CSHARP, WRAP_JAVA, WRAP_LUA, WRAP_PYTHON, WRAP_R, WRAP_RUBY, and WRAP_TCL (and any other WRAP_ language flag), as shown here.

On Windows, the following used to be necessary, but has probably been fixed and no longer required: Select the "Advanced" check box at the top of CMake, and then find the entry for CMAKE_EXE_LINKER_FLAGS_DEBUG and change the end of it from /INCREMENTAL to /INCREMENTAL:NO and then make the same change for both CMAKE_MODULE_LINKER_FLAGS_DEBUG and CMAKE_SHARED_LINKER_FLAGS_DEBUG.

If you are using Visual Studio 2012, you will also need to edit the entry for CMAKE_CXX_FLAGS by adding " /D_VARIADIC_MAX=10" to end end of its entry. Also note that Visual Studio 2012 must be updated to properly support variadic templates or you will get errors about std::tuple.

Configure again and then generate your build environment.

*** For the remainder of this section, you will need to maintain a reliable internet connection, possibly for hours. I recommend leaving your laptop plugged into AC power in a location with either good WiFi or an Ethernet cable. As part of the SuperBuild, CMake has configured your build environment (Visual Studio, XCode, etc.) to call other special CMake commands to automatically download and compile software as necessary to build SimpleITK. In particular, at some point ITK will be downloaded and compiled as part of SimpleITK's ALL_BUILD, and it will need a consistent internet connection for the download.

On Windows, after CMake is done, your SITKBin directory will now contain a Visual Studio solution file named SuperBuildSimpleITK.sln

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 python36_d.lib--we don't need debug-mode Python code anyway.

Warning: If your code is taking 10+ hours to compile, then you may have antivirus software slowing down Visual Studio. In this case, you may want to "pause" your antivirus software until you're done compiling.

There will be a 'Debug' folder under your c:\MIMIA\SITKBin\ITK-build\lib directory. This folder  should contain a list of ITK libraries. 

Under Mac OS X or other UNIX-like systems, CMake 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 SITKBin directory.

If you are using Makefiles, you will need to slightly modify the above instructions, creating separate Release and Debug build directories and following the lecture slides to specify which to ccmake, something like this:

cd \MIMIA
mkdir SITKBin
cd SITKBin
ccmake -DCMAKE_BUILD_TYPE=DEBUG -Module_SCIFIO=ON ../SimpleITK/SuperBuild
make (-j2)

cd ..
mkdir SITKBinRelease
cd SITKBinRelease
ccmake

-DCMAKE_BUILD_TYPE=RELEASE -Module_SCIFIO=ON ../SimpleITK/SuperBuild
make (-j2)

Note about using multiple cores for make. Make will run the fastest if you use -j to specify the number of parallel jobs to match the number of cpu cores on your machine. However, if you want to use your computer for other things during the build, then I suggest instead specifying 1 less than your cores, e.g. make -j3 on a 4 core machine, so that there will be 1 readily available core for web browsing, email, etc.

Build again in Release mode

At this point, Visual Studio (and most other compilers) will have built SimpleITK and 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 SimpleITK and/or ITK built both with and without debugging support.

On Windows to build a second, optimized copy of SimpleITK (including ITK) without debugging support in Visual Studio:

  1. Open (if necessary) your already existing Visual Studio project for SimpleITK (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 ALL_BUILD 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 c:\MIMIA\SITKBin\ITK-build\lib directory. Likewise, you should also have both debug and release libraries for SimpleITK.

Under Mac OS X Mavericks, You can build in Release mode by either pressing shift-command-i, or by going to the Product menu and then selecting Build For -> Profiling.

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 upcoming segmentation assignment, this could make your code over 6 times faster.

***Take a screenshot showing the list of resulting files in MIMIA\SITKBin\lib{\Release} or MIMIA\SITKBin\SimpleITK-Build\lib{\Release} (Please use whichever directory on your system that exists and contains the files, with or without the Release subdirectory as necessary.) Make sure to save the screenshot using the filename mentioned at submisison checklist at the top of this page.

***Place the screenshot (with the rest of your submission) in your hw_Install folder.

5. Testing C++ ITK (5 points)

At this point, from the previous super build you should already have an ITK source directory located here:

c:\MIMIA\SITKBin\ITK

and a working installation of ITK located here:

c:\MIMIA\SITKBin\ITK-build

The next instructions follow the pattern in Lecture04 to perform the ITK installation test.

Go back to the parent directory 'c:\MIMIA'. Create two new folders called 'ITKTest' and 'ITKTestBin'. Next, find the 'Installation' folder in c:\MIMIA\SITKBin\ITK\Examples and copy the two files in that folder to the new folder 'ITKTest'. 
After this step, copy this full path of this directory and paste it as the source directory in the CMake GUI. The full path to your 'ITKTestBin' folder is where you will build the binaries. Finally, click on 'Configure'.

You may have to edit the value for ITK_DIR to point to your SITKBin/ITK-build directory, e.g. c:\MIMIA\SITKBin\ITK-build or on Mac ~/Documents/MIMIA/SITKBin/ITK-build. After setting this value, you will have to click 'Configure' again.

On recent versions of OS X, you will need to change another CMake option. After successfully configuring CMake (once it has found ITK), turn on Advanced options and set CMAKE_CXX_FLAGS to contain -std=c++11 . After setting this value, you will need to run Configure again.

Clicking "Generate" or "OK" should now create 'HelloWorld.sln' in the 'ITKTestBin' folder. Open this VS solution and build it. Then, in your command prompt, change to 'ITKTestBin\Debug' (or equivalent) and run '.\HelloWorld.exe'.
'HelloWorld.exe' is a command-line program, you should probably run it either from within Visual Studio, or from a command-prompt. 

Command-prompt might be preferable if Visual Studio closes the application file before you can visualize the result (as is sometimes the case). 

On OS X, if the build fails with errors about C++11 (including errors in vnl_math.h about auto or code under a line #if VXL_FULLCXX11SUPPORT), then you may ned to close Xcode, re-run CMake, this time turning on Advanced options and setting CMAKE_CXX_FLAGS to contain -std=c++11 . After setting this value, you will need to run Configure and Generate again, and then open the XCode project and try building again.

***Take a screenshot of the text output. Make sure to save the screenshot using the filename mentioned at submisison checklist at the top of this page.

***Place the screenshot (with the rest of your submission) in your hw_Install folder.

Final Reminder: Did you follow all the instructions at the top of this assignment for how to name your files and add them to your hw_Install directory?

6. Double check your submission

Finally, be sure all requested files are in the hw_Install folder, then zip and upload to canvas.

7. Rejoice

If everything is working and if you want to "jump ahead" now, then feel free to look at the official list of SimpleITK examples for C++ and Python:

http://www.itk.org/SimpleITKDoxygen/html/examples.html

If everything is not working, and if you still run into compiler/linker errors after updating your compiler system with the latest patches, then please do not hesitate to copy and paste your errors to someone (preferably the TA). If he/she can't help you, they'll find someone who can.

Good luck!