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

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

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

85 points total

Due Date: Your final submission must be committed to svn by midnight (~11:59 PM EST) on Tuesday night, April 3. Big problems may not show up until the end, so finish early!

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

This is your first real programming assignment, and your first use of SVN. Upon completing this assignment, you should feel comfortable not only using ITK, but also programming for arbitrary pixel types and dimensionality. This assignment requires that you have ITK installed and working. This assignment includes:

  1. Using SVN
  2. Region-Growing Threshold Segmentation
  3. Global Threshold Segmentation
  4. Fast Marching

For further guidance you should consult the ITK software guide and the lecture slides, especially those from lectures 5 and 7. Additionally, Part 3 requires content from lecture 9.

0. Using SVN (5 points, apx. 0.5-2 hours)

Usage of SVN was discussed in Lecture 4, starting on slide 13. You will be required to submit your code for all remaining assignments using SVN. You should have received your SVN username and password either in class or via email. All of the instructions given here will be for the command line version of SVN. You may want to use a GUI instead (see lecture 3), but it is up to you to learn the interface of the GUI of your choice.

Begin by confirming access to your SVN module, by listing the current contents of your module:

svn list --verbose --username {Your_SVN_User_Name} https://svn.vialab.org/svn/miia12/{Your_SVN_User_Name}
{Provide your SVN password when prompted.}

Your password should be accepted, and you should not have any connection errors.

Change to the directory you previously created (in HW2) to contain ITK, VTK, etc. (e.g. cd c:\MIIA), and then checkout your module:

svn co --username {Your_SVN_User_Name} https://svn.vialab.org/svn/miia12/{Your_SVN_User_Name}
{SVN will probably remember your password for you, but if not then provide it again when requested.}

You should now have a new directory named C:\MIIA\{Your_SVN_User_Name}. This directory should contain all of your code for the remainder of this class (but none of your binaries unless specifically instructed otherwise).

Now add a directory to your SVN module to contain this assignment. You must first create the directory locally, then tell SVN to add it to your module, and then commit your changes to the SVN server:

cd c:\MIIA\{Your_SVN_User_Name}
mkdir hw3
svn add hw3
svn ci hw3 -m "Setting up module for hw3"

This is the general template you must follow to add any new file or directory to your SVN repository. When you change a file that already exists, you only need to run the last line above (the commit line) to update the server's copy of your file. Notice the -m option, followed by a quoted string. SVN requires that every committed change be given a brief description, and this is how to do it. (Warning: If you get strange errors when trying to commit, then make sure you are using the double-quote characters around your commit description.)

Now, to further test and exemplify things, you are going to create a directory for this part of the assignment, add a file containing the one word "Hello", commit the directory + file, change the file by adding the word "World" to the end, and then commit the change:

cd c:\MIIA\{Your_SVN_User_Name}\hw3
mkdir Part0
echo "Hello"> Part0\file.txt
svn add Part0
svn commit Part0 -m "Initializing Part 0"
echo "World">> Part0\file.txt
svn commit Part0 -m "Fixed file.txt"

In the above, if you prefer you could also use a text editor, such as Windows Notepad, instead of the echo commands. Also, as you may have noticed, running an svn command on a directory runs the command on all of the files and directories it contains. This can be nice...or not. Use with caution.

In the future, the source code for each part of each assignment should be in an appropriately numbered hw#\Part# directory structure, but...

NEVER build C++ source code inside your svn module. For C++ always do an out-of-source build!

0.1 SVN Setup for this segmentation assignment & Dataset Acquisition (0 points, apx. 5-30 minutes)

Create a new svn directory structure for this assignment, following the pattern below exactly. Assuming you are currently in the directory c:\MIIA\{Your_SVN_User_Name}\hw3, this would look like:

mkdir Part1
mkdir Part2
mkdir Part3
svn add Part1 Part2 Part3
svn ci Part1 Part2 Part3 -m "Setting up module for segmentation hw"

Now, download the image data set you will be using for this assignment, and unzip the archive somewhere convenient, but NOT in your SVN directory. (Please do NOT upload your copy of these downloaded images to SVN.)

Inside the resulting SegmentationAssignment_Images directory, you will find IM.mha, which is a small (64x64x64) piece of a much larger volumetric CT data. IM.mha has been cropped to include the ascending aorta, which will be your primary segmentation task for this assignment. In the same directory you will also find SegIM.mha, which is a coresponding expert segmentation for the ascending aorta, as visible in IM.mha. You will also find IM_2D.png and its corresponding expert segmentation SegIM_2D.png, which is a 2D image slice extracted from the 3D image IM.mha. As noted in the included seed_data.txt, your automatic segmentations of this piece of the aorta should be initialized using the seed point (x=35,y=34) for 2D and (x=35,y=17,z=28) for 3D.

Run the ITK-SNAP program (which you installed in HW2, Part 1). Go to "File" -> "Open Greyscale Image". Browse to the SegmentationAssignment_Images directory, and choose the file IM.mha. Choose the defaults through the rest of the file-opening dialogs. (If an "Insufficient Precision Warning" dialog appears, just ignore it and click "Ok" to make it go away.) Now go to "Segmentation" -> "Load From Image". Browse to the SegmentationAssignment_Images directory again, but this time choose the file SegIM.mha. Choose the defaults through the rest of the dialogs. Now click the "update mesh" button at the bottom of the main window. A screen-shot of what this should look like after you update SNAP's mesh is included in the file SegHW-SNAP.jpg. Spend a little time using SNAP to look through the volumetric data, to get a feel for it.

1. Region-Growing Threshold Segmentation (20 points)

Begin by copying SimpleITK/Examples/Segmentation/ConnectedThresholdImageFilter.py from your SimpleITK directory to Part1\threshold.py.

SimpleITK Python vs. SimpleITK C++ vs. "Full" ITK C++
From this point on, we will assume that you want to use SimpleITK in Python. However, if you prefer to use SimpleITK in C++ instead, then rather than grabbing the .py example files, look in the same directory for the corresponding .cxx example files and use those instead. If you use C++, you will of course also need to submit an appropriate CMakeLists.txt file as well. Finally, if you're really brave, then feel free to try this in "full" ITK instead of SimpleITK. You should be able to find equivalent example files in ITK's Examples directory.

Make the following changes to threshold.py, being sure to commit your changes to svn after you complete each step:

Big Hint: Be aware that 3D CT images have 12-bit data stored in 16-bit pixels, and so their intensities can be negative or exceed 1000 (unlike standard jpegs or pngs that have a maximum intensity of 255).

Reminder: When working on any part of any assignment for this class, be sure to add any new source files to svn as soon as you create them, and be sure to frequently commit you code as you make changes to it. Above all, don't forget to committ your final code to svn!

2. Global Threshold Segmentation (20 points)

Begin by copying code from part 1 of the assignment Part1\threshold.py to Part2\globalThreshold.py.
Make the following changes to globalThreshold.py, being sure to commit your changes to svn after you complete each step:

Final reminder: Don't forget about adding and committing to svn!

3. Fast Marching (40 points)

Implement a fast marching solution to a level set evolution problem by building the following pipeline:
reader -> smoothing -> gradientMagnitude -> sigmoid ->  fastMarching -> thresholder -> writer