ITK WATERSHED SEGMENTATION EXAMPLE

This application demonstrates the use of several Itk filters to perform
watershed segmentation of a 2D grayscale image.  The document
InsightDocuments/Web/HTML/WatershedSegmentationExample provides a
brief explanation of the segmentation algorithm and its use and is
also illustrated with some sample images.  All the information needed to build
and run the sample application is contained in this document.

-----------------------------------------------------------------------------
TO BUILD THIS APPLICATION

This application should be easy to build in one of two ways and has no
dependencies on external libraries.

1. (UNIX SYSTEMS) Write your own makefile.  Make sure to include paths to
headers in:

${BUILD_DIRECTORY}/Insight/
${SOURCE_DIRECTORY}/Insight/Code/Numerics
${SOURCE_DIRECTORY}/Insight/Code/Numerics/vxl/vcl
${SOURCE_DIRECTORY}/Insight/Code/Numerics/vxl/vxl
${SOURCE_DIRECTORY}/Insight/Code/Common
${SOURCE_DIRECTORY}/Insight/Code/Algorithms
${SOURCE_DIRECTORY}/Insight/Code/BasicFilters

Include paths to libraries in:
${BUILD_DIRECTORY}/Insight/Code/Numerics
${BUILD_DIRECTORY}/Insight/Code/Numerics/vxl/vcl
${BUILD_DIRECTORY}/Insight/Code/Numerics/vxl/vxl
${BUILD_DIRECTORY}/Insight/Code/Common
${BUILD_DIRECTORY}/Insight/Code/Algorithms
${BUILD_DIRECTORY}/Insight/Code/BasicFilters

wher SOURCE_DIRECTORY is the root of the Itk source tree and BUILD_DIRECTORY is 
the root of the Itk binaries directory.

and link against libraries:
libVXLNumerics libITKCommon libITKBasicFilters libVXLNumerics libpthread libm
libpthread libdl

OR, if you are familiar with CMake:

2. (WINDOWS or UNIX) Include this directory in a SUBDIRS tag of the root
CMakeLists.txt file before running CMake. CMake will generate a make file in
this directory (or the appropriate VC++ equivalent).  Refer to the CMake
documentation for more complete and current information on how to configure
CMake.

The CMake-generated makefile will produce a single executable
itkWatershedSegmentationExample.

-----------------------------------------------------------------------------
FILTERS USED IN THE EXAMPLE

This example uses three Itk image-to-image filters.

itkGradientAnisotropicDiffusionImageFilter diffuses the image while preserving
gradient edges.

itkGradientMagnitudeImageFilter is an edge-detection algorithm that outputs
an image of the gradient magnitudes of the input image.  This is the
"height function" that is input to the watershed segmentation algorithm.

itkWatershedImageFilter implements the watershed segmentation algorithm.  It
outputs a labeled image of integers, where each label corresponds to a 
unique segment in the image.

-----------------------------------------------------------------------------
FILE I/O

The application implements a simple PGM (ascii, grayscale) file reader.  It
uses an Itk raw image writer class to write an ascii file of labeled image
values.

-----------------------------------------------------------------------------
SETTING THE FILTER PARAMETERS

How you set the filter parameters will obviously depend on the data that you
are working with, but here are a few guidelines.  For more detailed information
about the watershed algorithm and its parameters, see the documentation contained
in itk::WatershedImageFilter.h.

conductance_term

 This term controls the sensitivity of the anisotropic diffusion stage to
 edges in the input image.  A good default value with which to start is 1.0.

diffusion_iterations 

 This is the number of iterations of the anisotropic diffusion algorithm that
 will be run on the image.  I suggest trying values between 8-20.

lower_threshold

 The watershed filter can be set to threshold low values in the input image.
 This parameter is supplied as a percentage (0.0 - 1.0) of the total range
 of values in the image.  For example, a value of .07 will threshold the 
 lowest 7 percent of values in the image.  This parameter can be used to
 control the amount of oversegmentation in the basic segmentation of the image
 (before regions are merged up to the specified level).

flood_level

 This value is a percentage of the total height of the input image (maximum
 intensity value - minimum intensity value) after thresholding.  It represents
 the level to which the hypothetical flood level of water in the catchment
 basins (regions) is raised.  In other words, it controls the extent to which
 neighboring segments will merge with one another into larger segments.  A
 minimum value of 0.0 will give the basic, typically very oversegmented
 output. The maximum value of 1.0 will give a single segment that fills the
 entire image.  Start with small percentages of 10 or 20 percent and work your
 way up.


If in doubt, start with the following command line:

itkWatershedSegmentationExample input_file.pgm output_prefix 1.0 10 0.07


-----------------------------------------------------------------------------
VIEWING THE RESULTS

The algorithm will produce labeled images in a raw, ascii format (no header).
These images have potentially many thousands of label values.  All the parameters
described above will affect the number of regions produced.  Typically, raising
the values of the parameters lowers the number of segments produced. 

One effective way to visualize the results of the segmentation is to map the
integer labels into distinct RGB colors (or grayscale levels).  Because labels
close in value tend to also be close spatially in the image, it is helpful to
spread close label values far apart in the RGB range.  A hashing scheme that
puts more weight on least-significant integer bits is a good way to accomplish
this.

The application itkWSRawToPNG uses the hashing scheme described above to convert the 
raw output of itkWatershedSegmentationExample into a color PNG image, which can be
viewed using any standard image viewer such as xv.

