seegoban - take a photo of a Go board and write the position in SGF.

Usage: seegoban <photo>

To use, click on the corners of the board. A grid will appear overlaying the
board. If necessary, you can adjust any of the corners by clicking near
them. When satisfied, you can press enter to write the board position in a
simple text format, or 's' to write it in SGF, or 'd' to get full information
about the board position in a format intended for debugging. If you have the
program 'cgoban' installed, you can press 'c' to open a cgoban window with the
current board position.

To see where seegoban is making mistakes, you can tell it what the correct board
position is. To do this, pass the -e switch on the command line, like:

$ seegoban -e correct.txt board.png

After placing the grid, you can press 'e' to find out which stones are being
detected incorrectly. If you have the program 'xgraph' installed, you can also
press 'v' to view a graph of the distribution of the stones. The x axis is
brightness, the y axis is saturation. Each point represents an intersection: the
brightness and saturation of the points around that intersection, and the colour
that should be detected there, regardless of what seegoban actually detects.
(Red for no stone, green for black, blue for white). You can also press 'g' to
print this data in a format suitable for input to xgraph. If you don't pass the
-e switch, 'v' and 'g' still work, but only one data set (containing a point for
every intersection) is displayed.

The grid can also be placed from the command line. For each corner, pass the
switch '-c x,y', where x and y are the coordinates on the full-sized image with
the origin in the top left. If fewer than four corners are given, the rest may
be placed from within the program. Having placed the grid, you can press 'p' to
print the locations of the corners for future use with '-c'.

If the grid is placed from the command line, you can run seegoban
noninteractively. Pass the '-a' switch with an argument specifying the output
format: 't'ext, 's'gf, 'd'ebug, 'e'xpected stones, 'g'raph, 'v'iew graph, or
open in 'c'goban.

The '-t' option can be used to set thresholds for stone-detection. It takes
three comma-separated arguments: "-t A,B,C". A is the maximum brightness of a
black stone, B is the minimum brightness of a white stone, and C is the maximum
saturation of any stone. The default values are 159,160,65, which works well for
the example board-1. 60,200,255 works for board-3. For an arbitrary photograph,
you may be able to use xgraph to find good values.

The '-s' option controls the size of the sample block used to determine the
colour at a particular point. The default is 7, for a 7x7 square. The colour at
point (x,y) is the average colour of all pixels in such a square centred on
(x,y).

Currently it doesn't get great results, but that will improve as I learn what
heuristics to use.

Heuristics:

To work out whether there is a stone at a given point, we take the average color
of a 7x7 (by default) block surrounding it. If this color has saturation greater
than 65, we assume there is no stone there. Otherwise the stone is assumed to be
black if its brightness is less than 160, or white otherwise.

Representing a color as (r,g,b), its saturation is max{r,g,b} - min{r,g,b} (as
in HSV colorspace) and its brightness is .30*r + .59*g + .11*b (which according
to wikipedia is fairly accurate in terms of how we perceive brightness).

I intend to make these thresholds editable while seegoban is running, and to
have more intelligent boundaries. My current plan, given a point of brightness B
and saturation S is: if w*B - x*S > m, there is a white stone there; if y*B +
z*S < n, there is a black stone there; otherwise, there is no stone there.
Suitable values for w, x, y, z, m, n are as-yet unknown, but I'm working on
being able to collect that data.

Todo:

* Webcam support
* Proper GUI
* Automate operation from the command line
* Preview of results
* Select an SGF editor other than cgoban

Bugs:

* The grid is assumed to be convex. If this assumption does not hold, failure is
  not graceful.

License:

seegoban is copyright 2010 Philip Hazelden <philh.net>. You can do what you like
with it. If we meet some day, and you think this stuff is worth it, you can buy
me a beer in return.

board-1.png is licensed under the Creative Commons Attribution-ShareAlike 3.0
License. I got it from
http://en.wikipedia.org/wiki/File:Go-Equipment-Narrow-Black.png
as of May 2010.

The other included example boards were photographed by myself, and are free.