Provided by: mrgingham_1.20-5_amd64 
NAME
mrgingham - Extract chessboard corners from a set of images
SYNOPSIS
$ mrgingham /tmp/image*.jpg
# filename x y level
/tmp/image1.jpg - -
/tmp/image2.jpg 1385.433000 1471.719000 0
/tmp/image2.jpg 1483.597000 1469.825000 0
/tmp/image2.jpg 1582.086000 1467.561000 1
...
$ mrgingham /tmp/image.jpg |
vnl-filter -p x,y |
feedgnuplot --domain --lines --points --image /tmp/image.jpg
[ image pops up with the detected grid plotted on top ]
$ mrgingham /tmp/image.jpg |
vnl-filter -p x,y,level |
feedgnuplot --domain
--with 'linespoints pt 7 ps 2 palette'
--tuplesizeall 3 --image /tmp/image.jpg
[ fancy image pops up with the detected grid plotted on top, detections
colored by their decimation level ]
DESCRIPTION
This tool uses the "mrgingham" library to detect chessboard corners from images stored on disk. Images
are given on the commandline, as globs. Each glob is expanded, and each image is processed (possibly in
parallel if "-j" was given). The output is a vnlog <https://www.github.com/dkogan/vnlog> containing the
filename, coordinates of the chessboard corners and the decimation level used to compute each corner. For
diagnostics, pass in "--debug". This produces a number of self-plotting files that describe the results
of the intermediate steps. Each diagnostic file is reported on the console when it is written.
Both chessboard and a non-offset grid of circles are supported. Chessboard are the strongly preferred
choice; the circle detector is mostly here for compatibility. Both are nominally supported by OpenCV, but
those implementations are slow and not at all robust, in my experience. The implementations here are much
faster and work much better. I do use OpenCV here, but only for some core functionality.
Currently mrgingham looks for a square grid of points, with some user-requestable width. The default is a
10x10 grid.
Approach
This tool works in two passes:
• Look for "interesting" points in the image. The goal is to find all the points we care about, in any
order. It is assumed that
• there will be many outliers
• there will be no outliers interspersed throughout the points we do care about (this isn't an
unreasonable requirement: areas between chessboard corners have a solid color)
• Run a geometric analysis to find a grid in this set of "interesting" points. This will throw out the
outliers and it will order the output
If we return any data, that means we found a full grid. The geometric search is fairly anal, so if we
found a full grid, it's extremely likely that it is "right".
Chessboards
This is based on the feature detector described in this paper: <https://arxiv.org/abs/1301.5491>
The authors provide a simple MIT-licensed implementation here:
<http://www-sigproc.eng.cam.ac.uk/Main/SB476Chess>
This produces an image of detector response. This library then aggregates these responses by looking at
local neighborhoods of high responses, and computing the mean of the position of the points in each
candidate neighborhood, weighted by the detector response.
As noted earlier, I look for a square grid, 10x10 points by default. Here that means 10x10 internal
corners, meaning a chessboard with 11 squares per side. A recommended pattern is available in
"chessboard.10x10.pdf" and "chessboard.14fx14.pdf" in the "mrgingham" sources.
Circles
This isn't recommended, and exists for legacy compatibility only*
The circle finder does mostly what the first stage of the OpenCV circle detector does:
• Find a reasonable intensity threshold
• Threshold the image
• Find blobs
• Return centroid of the blobs
This is relatively slow, can get confused by uneven lighting (although CLAHE can take care of that), and
is inaccurate: nothing says that the centroid of a blob came from the center of the circle on the
calibration board.
ARGUMENTS
The general usage is
mrgingham [--debug] [--jobs N] [--noclahe] [--blur radius]
[--level l] [--blobs] imageglobs imageglobs ...
By default we look for a chessboard. By default we apply adaptive histogram equalization, then blur with
a radius of 1. We then use an adaptive level of downsampling when looking for the chessboard.
The arguments are
"--noclahe"
Optional argument to control image preprocessing. Unless given we will apply adaptive histogram
equalization (CLAHE algorithm) to the images. This is extremely helpful if the images aren't lit
evenly; which is most of them.
"--blur RADIUS"
Optional argument to control image preprocessing. This will apply a gaussian blur to the image (after
the histogram equalization). A light blurring is very helpful with CLAHE, since that makes noisy
images. By default we will blur with radius = 1. Set to <= 0 to disable
"--level L"
Optional argument to control image preprocessing. Applies a downsampling to the image (after CLAHE
and "--blur", if those are given). Level 0 means 'use the original image'. Level > 0 means downsample
by 2**level. Level < 0 means 'try several different levels until we find one that works. This is the
default.
"--jobs N"
Parallelizes the processing N-ways. "-j" is a synonym. This is just like GNU make, except you're
required to explicitly specify a job count.
The images are given as (multiple) globs. The output is a vnlog with columns "filename","x","y". All
filenames matched in the glob will appear in the output. Images for which no chessboard pattern was
found appear as a single record with null "x" and "y".
"--debug"
If given, "mrgingham" will dump various intermediate results into "/tmp" and it will report more
stuff on the console. The output is self-documenting
"--blobs"
Find circle centers instead of chessboard corners. Not recommended
REPOSITORY
<https://github.com/dkogan/mrgingham>
AUTHOR
Dima Kogan, "<dima@secretsauce.net>"
LICENSE AND COPYRIGHT
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser
General Public License as published by the Free Software Foundation; either version 2.1 of the License,
or (at your option) any later version.
Copyright 2017-2018 California Institute of Technology
Copyright 2017-2018 Dima Kogan ("dima@secretsauce.net")
mrgingham 1.20 2022-04-02 MRGINGHAM(1)