
     README for the Examples Directory of the Watershed Distribution
     ---------------------------------------------------------------


This directory illustrates the different ways in which you can use this
module.  If you just want to play with dilate-erode methods of the module,
execute the script

    dilate_erode.py

This script assumes a disk structuring element whose radius in pixels is
supplied as the first argument to the methods 'dilate()' and 'erode()'.
The second argument lets you choose between a "square" and a "circular"
structuring element. As currently programmed, this script produces results
on a binary image called "triangle1.jpg".  You can change the filename
supplied through the constructor parameter 'data_image' to compute the
dilations and erosions for any binary image of your choice.  To demonstrate
the usefulness of these operations for "repairing" breaks in edges, execute
the script

    edge_repair.py

See the comment block at the beginning of the above script as to when
dilation followed by erosion can be expected to repair breakds in shape
boundaries.


                           -----------------



If you want to play with the distance mapping code in the module, execute
the script:            

    distance_mapping.py

This script will ask you to place a mark with a mouse click in one of the
blobs in your binary image.  Subsequently, it presents a distance map of
the blob with respect to that mark.  For a demonstration that involves more
complex blobs --- these being blobs with holes in them --- execute the
script

    distance_mapping2.py


                           -----------------



For a demonstration of the calculation of the influence zones (IZ) in a
binary blob, execute the script

    influence_zones.py

For a visually interesting demonstration, you must place at least two marks
inside a blob.  Each mark is dilated into its IZ and the boundaries between
the IZs constitute the geodesic skeleton of the binary blob.



                           -----------------



All of the scripts mentioned above run on binary image files.  As a first
demonstration involving grayscale or color images, execute the script

    LoG.py

that calculates the Laplacian-of-Gaussian of an image.  The LoG is
calculated by taking a difference of two Gaussian-smoothed images with
two different values of sigma.  The first Gaussian smoothed image is
calculated with the sigma as set in the constructor and the second with
a sigma that 20% larger.


                           -----------------



To see an automatic watershed segmentation that does NOT involve any user
interaction, execute the script:

    segment_automatic_and_show_watershed.py

As you will notice, when there is no help from the user, the watershed
algorithm over-segments the image.  For an example of the segmentation
produced by this script, for the following image

    orchid0001.jpg

of an orchid, the script produced the segmentation shown in

    automatic_output_segmentation_for_orchid.jpg

To see the individual blobs extracted from your input image through the
watershed contours, execute the following script:

    segment_automatic_and_use_contours_to_extract_blobs.py

This script finds the blobs by using the logic that a pixel belongs to the
region bounded by a contour if a line through the pixel intersects the
contour an even number of times. For a totally different approach to blob
extraction, you may wish to try the script:

    segment_automatic_and_use_region_growing_to_extract_blobs.py

This script uses region-growing logic to pull out the individual blobs.



                           -----------------



That brings us to marker based watershed segmentation in which a user is
asked to place marker points in an image in order to manually modify the
gradient map. To see how this works, execute the script:

    segment_with_markers_and_show_watershed.py

In order to interact with the module for this segmentation exercise, pay
careful attention to the titles of the image frames that are displayed.
When it asks you to click on the "save" and then "exit" buttons that appear
at the bottom of the image window, you must do exactly do that (as opposed
to just closing the window).  To see all the markers I placed in the image
in one of my own attempts at segmenting the orchid image, view the image
file:

    composite_image_with_all_marks_orchid.jpg

The watersheds produced by this marker-assisted segmentation can be seen in
the output image:

    marker_assisted_segmentation_for_orchid.jpg

To see the individual blobs extracted for the case of marker-based
watershed segmentation, execute the following script:

    segment_with_markers_and_use_contours_to_extract_blobs.py

As for the "automatic" version of this script, this script finds the blobs
by using the logic that a pixel belongs to the region bounded by a contour
if a line through the pixel intersects the contour an even number of
times. For a totally different approach to blob extraction, you may wish to
try the script:

    segment_with_markers_and_use_region_growing_to_extract_blobs.py

This script uses region-growing logic to pull out the individual blobs.



                           -----------------
             


Finally, if you want to create your own binary images for some of the
scripts mentioned above, execute the script

    data_gen.py


                           -----------------


Do not forget to execute the script

    cleanup.py

in the Examples directory after running the scripts mentioned above to
cleanup the intermediate images created by the scripts.  Ordinarily, the
destructor of the class would take care of such cleanup.  But depending on
how you exit the module, that may not always happen.

