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

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: Due soon, as posted in Canvas. Try to get parts 0, 1, and 2 done before the weekend. 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 10/11 for this class, or possibly a recent version of Ubuntu. 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.

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 notes or instructions for the grader, 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:\BMIA\ in a Windows environment or such as ~/BMIA/ 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 BMIA directory. (Note:  You may have already created your bmia directory in the prior homework.)

WARNING: If your username on your computer is longer than 8 characters, then do NOT put your BMIA directory inside your standard "Documents" folder. Instead, you are strongly encouraged to put your BMIA directory either in the top (root) folder of your hard drive (c:\BMIA 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}\BMIA).

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

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

Additional directories for this assignment:

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

Also, create a submission directory C:\BMIA\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

CMake

CMake can be downloaded from http://www.cmake.org/ on the Download page (top-right menu option). You must have a version ≥ 3.18. The most recent (and recommended) binary distribution is 3.28.3. Use the binary distribution appropriate for your operating system ( e.g. Windows x64 users should choose Windows win64-x64 Installer).

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 4.0.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-win64, in which case I suggest  allowing it to communicate on all networks.

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 (and/or miniconda) distribution of Python, which is by far the simplest cross-platform SimpleITK python installation. More information is available about Anaconda, including help and tutorials.

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

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.

Now, use the same command line terminal to install PyTorch for your system using the official instuctions.  Be sure to select the "Stable" PyTorch build on the first row, select your OS on the second row, select "Conda" as your Package on the third row, and select "Python" as your Language on the fourth row. For the fifth row, choose the appropriate Compute Platform, e.g. CUDA if you have an NVidia GPU or choose Default on Mac OS. The webpage will then show you what command to enter on the command line.  Copy and paste that command to your command-line terminal to install PyTorch.

After PyTorch is installed, continue using your same command line to enter this command to install Monai:

conda install monai


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:\BMIA\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 launch Spyder from the command line with the spyder command and Jupyter's Notebook interface using the jupyter-notebook command. (For this class, always make sure you are using your bmia conda environment before you run commands on the command line.)

Testing Notebooks

Now try running iPython Notebook. (On mac/unix, change to your ~/BMIA/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). [Note: If your browser window is blank, and you are using Safari 17 or newer, the problem may be the use of separte browsing profiles. For me, notebooks only open correctly in my personal/first profile; you can open a new window with your first profile using Safari's keyboard shortcut command-option-shift-0.] 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.)

SimpleITK

Open an ipython prompt (see above), and then enter the following two lines:

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-9.3.0.zip) and extact it into C:\BMIA\. This will create the folder C:\BMIA\VTK-9.3.0, after which you should manually create the build folder C:\BMIA\VTKBin.

**** WARNING: Put the downloaded source code and build directories for VTK or ITK into C:\BMIA\; do NOT put them into your c:\BMIA\hw_Install directory. Only your submitted screenshots (and possibly a ReadMe.txt file) go into your hw_Install submission directory.

Now run the CMake GUI:

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.  If you see VTK_PYTHON_VERSION  then make sure it is set to either 3 or else to 3.11.

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).

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:\BMIA\VTKTest

Now, download and uncompress (i.e. untar) the cone example from VTK's online list of examples. Copy the 2 files from the resulting Cone directory into the new directory C:\BMIA\VTKTest. Create a build directory (e.g. C:\BMIA\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" (if necessary) 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 Cone 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 'Cone.exe' (or Cone.app). Run the Cone 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 to reset the view. The cone should now be visable and interactive.)  Once you see the cone, move it around with your mouse/trackpad and then 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)

Git

Before we can custom compile C++ SimpleITK, we must first install git. "Git" is an advanced replacement for svn, designed for masively distributed collaborative development. Git is the way that ITK 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

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 BMIA directory and then issuing a couple of git commands:

cd \BMIA
git clone --recursive https://github.com/SimpleITK/SimpleITK.git
cd SimpleITK
git checkout tags/v2.3.1 -bv2.3.1-branch


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 \BMIA
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:

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.

WARNING: Mac OS Sonoma with the latest XCode (15.2) is having build errors for me. I currently recocmmend that you use Makefiles instead of XCode to build SimpleITK. Makefile instructions are further down.

Now, run CMake. For Windows, you probably want to choose "Visual Studio 16 2019" for the generator, "x64" for the platform, and enter "host=x64" for the optional toolset. For the source-code directory, use SimpleITK's super-build directory, e.g. c:\BMIA\SimpleITK\SuperBuild , and use a binary directory of c:\BMIA\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 Mac you should also check the "Advanced" box and then make sure USE_GOLD_LINKER is not checked.

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.

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.

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 BMIA\SITKBin\lib{\Release} or BMIA\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:\BMIA\SITKBin\ITK

and a working installation of ITK located here:

c:\BMIA\SITKBin\ITK-build

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

Go back to the parent directory 'c:\BMIA'. Create two new folders called 'ITKTest' and 'ITKTestBin'. Next, find the Examples'Installation' folder which sould be in c:\BMIA\SITKBin\ITK\Examples\Installation 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'.

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). 

***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 make a .zip file of the entire folder  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!