Snake
  by Brian Potetz
  A teaching tool for 15-385 (Introduction to Computer Vision)
    with Tai Sing Lee
  at Carnegie Mellon University
  3/3/04

USAGE: add the directory that SnakesGUI is in to your Matlab path
       load an image into the matlab variable 'image'.
       type 'Snake'

USER INTERFACE
Buttons:
  Snake -               Once you have specified an initial polyline shape (by clicking in the image), press Snake to
                        fit the polyline to the image.
  Clear Shape -         Erase the current user-defined polyline shape.
  Clear User Costs -    Clear all user costs (specified by clicking the image with the 'encourage snake' or 
                        'discourage snake' tools.

'Show' Buttons:
These determine what image is being displayed. The button currently being displayed is shown in bright red.
  Show Image -          Display the original image.
  Show Image Costs -    Display the image-derived cost (used by the snake algorithm to fit the polyline to the image)
                        of traversing through each vertex. This image is computed using a derivative of gaussian edge
                        operator with a guassian whose width is specified by the 'Edge Width' slider position.
                        Dark pixels correspond to cheaper costs.
  Show Nearness Costs - Display the cost due to straying too far from the initial polyline shape. This cost makes the
                        final snake polyline more closely resemble the originaly polyline. The relative importance of
                        this cost is specified by the position of the 'Nearness Weight' slider.
  Show User Costs -     Display costs specified by the user. These costs were made by clicking on the image with the
                        'encourage snake' or 'discourage snake' tools.
  Show Total Costs -    Display the combined cost used by the snake's A* algorithm (includes image, nearness and user
                        costs).
  Show Path Costs -     Display the cost of the cheapest path from the first vertex in the original polyline to each
                        point in the image that has been considered by the snake algorithm as it tries to reach the
                        second point in the polyline.
                        Vertices shown in black were never evaluated by the algorithm.
                        This cost matrix is only updated when the user presses the Snake button.
                        Pressing 'Show Path Costs' successive times in a row causes displays the path costs for
                        different segments in the polyline.
 
  Hide Shape -          Toggles the display of the polyline. Hiding the polyline can be helpful when comparing the
                        current polyline shape with the actual edge in the image.


User Tools:
These determine what happens when you click on the image.
  Add Vertices -        Places a new vertex at the end of the polyline.
  Delete Vertices -     Removes the last vertex from the polyline.
  Encourage Snake -     Decreases the total cost function in the area clicked by the user.
  Discourage Snake -    Increases the total cost function in the area clicked by the user.


Slider Controls:
  Edge Width -          Controls the width of the gaussian used to compute the edge costs. 
                        The edge costs are computed using a derivative-of-gaussian edge operator.
                        Larger values of this width accentuate more robust, lower-frequency edges in the image.
                        However, the location of the edge is less precise than with smaller values of edge width.
  Nearness Weight -     Controls the 
  Nearness Threshold -  All points within a certain distance from the original polyline are given zero 'nearness
                        cost'. This slider sets that distance.
  Polyline Color -      Adjusts the color of the polyline. This control was initially implemented simply to
                        demonstrate the user of sliders in MATLAB.