Compile
-------

Install opencv libs and cmake:

    apt-get install build-essential libopencv-dev cmake

Build:

    make


Use
---

When you have a chessboard pattern with 9 x 7 squares, it has 8 x 6 
*inner* corners. That is what the program will look for. There are no 
4-edge corners on the outer edge of the board, so these will not be 
used.

    ./opencv-findcorners 8 6 image.png  > output.json

This will open a display window to show the detected corners: do check 
them for correctness! Especially when the image has some visible noise, 
there is some tendency to misdetect the corner location. When this 
occurs, fix the output file manually.

The output file is suitable for pasting into a multi-image combined 
input file for `camcalibplanes`.


In case it doesn't work
-----------------------

In case too few points are detected, first try specifying a smaller grid 
size; so instead of 8 6, specify 7 6 or 8 5. If this works, then either 
forget about the points that are missing, or add that row or column 
manually using e.g. hugin.


Also by editing the image, you can try to make detection work in some 
more cases, but this is usually more trouble than it is worth: using 
hugin will often be quicker.

Some things you need to know:

The image always gets converted into greyscale, so no need to do 
external editing in color.

The first detection step converts the image into binary black-and-white, 
and the intention is to have all squares still present then. With 
`CALIB_CB_ADAPTIVE_THRESH` active, the black-and-white threshold is not 
the same for the entire image, but taken as average over neighboring 
pixels. This will allow some gradient in lighting, but not too much.

Some editing possibilities:

- Increase image contrast, so that white squares are almost white and 
  black squares are almost black; use "gamma" or "levels" tool in an 
  image editor. When squares are unclean due to reflections or uneven 
  lighting, fix them up -- without touching the edges. (Edges should 
  remain somewhat "blurry" to have better subpixel detection.)

- Remove everything except the chessboard. No problem to cut off a 
  little from the board's edge squares -- as long as they remain 
  approximately rectangular with 4 neat corners. Make the outer space 
  approximately as white as the white squares, which works best with the 
  neighbor-average for the adaptive threshold.

- For fisheye cameras that have the actual lens edge visible inside the 
  picture, it makes much sense to have some pictures with chessboard 
  very close to the edge. That way, the distortion near the edge can be 
  accurately determined. But squares tend to get very compressed near 
  the edge. It may help somewhat to "fix" the outer squares by 
  stretching them a bit *over* the edge and painting neat white color 
  around them. As long as the inner corners stay the same, results will 
  be perfectly usable. But detection may still fail, and adding a few 
  pixels manually using hugin is quick and easy too.

Detection will find *all* "contours" = edges in the black-and-white 
image after thresholding; and it will keep all square contours.

Then it will use the *grayscale* image to fine-tune the corners to 
subpixel precision. Therefore you should not use a black-and-white input 
image unless really necessary.

In some cases, the program will stubbornly refuse to detect some of the 
clearly visible inner corners. This may be due to the detection 
algorithm, and appears generally unfixable. In these cases, doing manual 
detection using hugin is much faster than trying to convince openCV.