Assignment 4: Segmentation and Preprocessing
Methods In Medical Image Analysis (BioE 2630 : 18-791 : 42-735) - Spring 2020

Creative Commons License ITK Segmentation and Preprocessing Assignment by Vikas Revanna Shivaprabhu and John Galeotti, © 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.

70 points total

Due Date: Your final submission must be committed to svn by 11:59 pm EST on Thursday April 2 (1-week extension due to COVID-19  (remember that help "stops" at 5pm on due date). Big problems may not show up until the end, so finish early!

Please add (and committ) your .mha segmentations to your svn repository. No need to submit 2D segmentations.

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

This is your first real programming assignment. Upon completing this assignment, you should feel comfortable using ITK and working with differnt pixel types and dimensionality. This assignment requires that you have ITK or SimpleITK installed and working. This assignment includes:

  1. Setting up SVN
  2. Region-Growing Threshold Segmentation
  3. Global Threshold Segmentation
  4. Fast Marching
  5. Creative Experimentation

For further guidance you should consult the ITK software guide and the lecture slides, especially those from the background lectures on programming and ITK basic usage, and the segmentation lectures on Overview and Thresholding, Active Contours, and Level Sets.

0. Setting up SVN for this Assignment (0 points, apx. 5 minutes)

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:\MIMIA\{Your_SVN_User_Name}
mkdir hwSeg
svn add hwSeg
svn ci hwSeg -m "Setting up module for hwSeg"

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!

Now, create a new svn directory structure for this assignment, following the pattern below exactly. Assuming you are currently in the directory c:\MIMIA\{Your_SVN_User_Name}\hwSeg, 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 several images and a text file named ReadMe.txt, which explains the files and also give seed points for initializing/starting segmentations. Be sure you understand everything this file says.

Run the ITK-SNAP program (which you installed in HW2, Part 1). From the initial dialog, choose "Open Image ..." and then choose "Browse...". Browse to the SegmentationAssignment_Images directory, and choose the file ChestCT_VascularContrast.mha. Choose "Next >" and then choose "Finish" (don't worry about the "Loss of Precision" warning). Now on the top menu bar go to "Segmentation" -> "Open Segmentation ...". As you just did, browse to the SegmentationAssignment_Images directory again, but this time choose the file ChestCT_VascularSeg.mha. Once the segmentation is loaded, click the "update" 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.png. Spend a little time using SNAP to look through the volumetric data, to get a feel for it. (There is also a similar SNAP screenshot for the cropped ascending aorta volume, named SegHW-crop-SNAP.png.)

1. Region-Growing Threshold Segmentation (10 points)

Begin by copying c:\MIMIA\SimpleITK\Examples\Python\ConnectedThresholdImageFilter.py from your SimpleITK source directory to Part1\threshold.py. Note that this program is made to be directly executable from the normal command line, by entering something like ipython Part1\threshold.py. When you run the program without any command line arguments, it will tell you what arguments you should use.

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 (or similar) 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, but keep in mind that you may need content from future lectures (try looking at last year's course website). You should be able to find equivalent "full ITK" example files in ITK's Examples directory.

Reminder: Remember that matched indentation is very important in Python, and you should always uses spaces (not tabs, since they are treated differently).

Test the code using 2-dimensional image AscendingAorta_2D.png with the provided seed point (from ReadMe.txt) and compare your result with AscendingAorta_2DSeg.png.

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 and submitted images to svn as soon as you create them (fore example, use svn add threshold.py or svn add Result_Part1_3D.mha), 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. Fast Marching LevelSet (15 points)

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

3. Creative Experimentation on Big Volume (40 points)

You have previously tried some of the SimpleITK iPython tutorial notebooks, and now you should read through (and I suggest experiment a little with) the Level Set tutorial notebooks.

Now, find your best combination of preprocessing and segmentation algorithms for the full-size image volume. In addition to the seedpoint provided, you may optionally choose up to 4 additional seedpoints for the large volume (5 seedpoints total). Carefully distributing your seed points can substantially speed up your segmentation, and potentially increase its accuracy as well. (You are free to use segmentation algorithms other than level sets if you want.)

To find appropriate algorithms for vasculature segmentation, as well as example code to use, I highly recommend using the ITK Software Guide, Google, and/or the ITK mailing list archives (please do not ask the mailing list how to do this--search the list archives instead; if you still have questions, then it is appropriate to ask the list). I also highly recommend starting with the small (64x64x64) volume for initial experimentation, and then only trying things that seem promising on the larger data set.

Scoring for this part is as follows:

Since this part is a competition to see who can get the best segmentation, you are on your own. Neither the TA nor myself will help you choose or implement your segmentation algorithm (but feel free to ask your TA for help with "non competitive" issues such as compiler problems, etc.). Feel free to use all other sources of help at your disposal, including internet mailing lists (but please be polite and only ask specific questions on the itk mailing list). Place your well-commented code in Part3\best_segmentation.py (or for C++ use an .cxx extension and include an appropriate CMakeLists.txt file).

Be sure to comment in your code about any areas where you believe your segmentation does a better job than the expert segmentation. (If you're not sure about a piece of vasculature that you believe should be segmented, but was not in the expert segmentation, then feel free to ask your TA or instructor for clarificaiton.)

*** Also, be sure to include a comment at the top of best_segmentation.py indicating how long it takes your code to run on your machine, so that the TA has some idea how long he should wait for your code to finish executing.

Please note that I strongly discourage trying to use really complex segmention methods for this part. On such a large, branching data set they almost certainly will not work. If, contrary to my advice and in the spirit of competition, you feel compelled to try anyway, then I would suggest (1) lots of cafine, and (2) a 2-stage segmentation, where you only use an advanced segmentation method to refine the output of some other simpler and more robust method.

Final Check

Finally, be sure all of your files are committed correctly, either by pointing your web browser to your svn URL and logging in with your svn name and password, or else by using the command "svn list -R --verbose --username {Your_SVN_User_Name} https://biglab.ri.cmu.edu/svn/mimia19/{Your_SVN_User_Name}". If these methods do not show all your submitted files present and with appropriate timestamps, then you have not properly committed them. In this case, the first thing to check is to make sure you've added the files to svn before comitting. Otherwise, email your TA and instructor for help.