Team Eclipse
------------

   Corey Tripp <crt17@columbia.edu>
   Naveed Hasan <naveed@cs.columbia.edu>
   Paul Blaer <psb15@columbia.edu>
   Lenny Volchok <lv71@columbia.edu>


Program
-------

   ccalib is the camera calibration program.  It makes use of the
     Tsai camera calibration code.


Usage
-----

   ccalib <image> <len mm> [data] [param]

   image -- the image is a single camara shot of the checker board
            pattern that will be used for the camera calibration.

   len mm -- is the length of a single square on the checker board
             in mm.  In all of our experiments we used a checker
             board size of 23mm.

   data -- the name of the file that the mappings between and the
           world coordinates are stored.  This is part of the Tsai
           procedure, and can be used for sanity checking.  We 
           do not make use of the parameters.

   param -- the name of the file in which the intrinsic and extrinsic 
            parameters of the camera are stored.
   

Notes
-----

    The main goal of ccalib is to automatically find the corner
features within the calibration image.  After these pixel locations
are found they are then associated with some 3D point and given to the
Tsai camera calibration routes for the actual camera calibration
calculations.

    The steps for automatically finding corner features are as follows:
        1) Edge Detection
        2) Hough Transform
        3) Get lines from Hough Transform
        4) Find intersections of those lines
        5) Refine the intersections

    The Edge Detection step is a simple neighborhood averaging with
the pixel values at the edges of the image set to zero.  Also in this
step a histogram of the edge image is constructed so that a threshold
value can be computed for the Hough Transform.  This histogram has a
know structure, looking at it from the left to the right ( dark pixel
values to bright pixel values ), the histogram starts will high values
for the dark pixel values.  Then as you move to the right this slopes
down very quickly until a local minimum is reach.  >From here the
histogram values increase as the pixel intensity increases until a
local maximum is reach.  From here the histogram values drop down to
zero.  The threshold value that the Hough transform step is interested
in is at the local maximum that appears after the local minimum.  This
value is found by knowing the structure of the histogram and looking
from both the left and the right.

    The edge image found in the Edge Detection step along with the
threshold value are then sent to the Hough Transform step.  The Hough
Transform is the basic Hough Transform algorithm and in fact the code
is from Naveed's Computer Vision homework.  After the first part of
the Hough Transform is computed a image in the Hough space is created.
The bright spots in the Hough image represent lines that exist in edge
image.

    After the Hough image is computed and labeled it then is given to
the step were these regions are transformed back into lines in the
image space.  The centers of mass of each labeled region in the Hough
image is computed and the end points of the corresponding lines are
found.  These endpoints are then checked to make sure that they are
indeed real lines and if they are, they are added to the list of lines
found.  After all of the end points are found they are checked again
so that they are nice lines for the rest of the processing.  Nice
lines are ones that go from left-to-right or top-to-bottom.

    Now that we have a list of lines within the image we need to find
possible corners in the image.  The first step is to split the list of
lines into horizontal and vertical lines.  Then sort the lines so that
horizontal lines go from top-to-bottom and vertical lines go from
left-to-right.  After this the intersections of all of the horizontal
and vertical lines are found.  These intersections are the possible
corners of the calibration pattern.

    However, these possible corners are very noisy and need to be
refine, which is the next step in the processing.  Since we know that
these points are close to the true corner point we just want to move
then a round so that they are closer to the true corner point.
Following Paul's suggestion, we first try to move the point up and
down to find the place were neighbor pixels switch colors between
black and white.  Then the point is moved left and right again looking
for a change in color.  If the point was successfully moved to a
"better" location it is kept; otherwise the point is thrown away.
After all of the points have been moved, they are then refined more to
get rid of points that close to each other so that only one point is
at a corner.

    These refined corner points are the points that get sent to the
Tsai camera calibration code a the feature points with in the
calibration image.  Since we sorted the lines and computed the
intersections in a certain order we know that in the "best" situation
that these points are in a square pattern.

Situations that are bad for the program are:
  1) When one (or more) outlier points still exist after the corners,
     This misses up the very last step when corner points are match
     with a computed 3D point.
  2) The corners point found to not make a square, again this
     causes problems when matching corner points to 3D points
  3) All of the lines (or most of the lines) are thrown out because
     they don't meet the "nice" line qualities (going from left-to-right
     top-to-bottom).  This causes lots of difficulties in the steps
     after because of the lack of data.
  4) A situation that does not conform to the assumptions made,
     outcome .... very bad
