MRGINGHAM(1)

📦
version 1.27 · 7 versions
, in ubuntu stonking

💖 MRGINGHAM(1) 💖

okay bestie, welcome to mrgingham — the chessboard corner finder. it's a manual page, it's giving extremely useful, we're gonna get through it together. no cap. 🎀

✨ NAME ✨

mrgingham — extract chessboard corners from a set of images 🦋

✨ SYNOPSIS ✨

so the whole vibe is: you hand it some images, it hands you corners.

$ mrgingham image*.jpg

# filename x y level
image1.jpg - -
image2.jpg 1385.433000 1471.719000 0
image2.jpg 1483.597000 1469.825000 0
image2.jpg 1582.086000 1467.561000 1
...

and look, you can pipe it straight into plotting, main character energy:

$ mrgingham image.jpg |
  vnl-filter -p x,y,level |
  feedgnuplot --domain \
              --with 'linespoints pt 7 ps 2 palette' \
              --tuplesizeall 3 \
              --image image.jpg

[ image pops up with the detected grid plotted on top, detections color-coded
  by their decimation level ]

🌸

✨ DESCRIPTION ✨

okay so mrgingham detects chessboard corners from images that live on your disk. the images come in on the commandline as globs. each glob gets expanded, and each image gets processed — possibly in parallel, if you passed -j. parallel besties. 💅

the output is a vnlog text table (https://www.github.com/dkogan/vnlog) with these columns:

  • filename: the path to the image on disk
  • x, y: the detected pixel coordinates of the chessboard corner
  • level: the image level that was used to detect this corner. level 0 means "full-resolution". level 1 means "half-resolution", and honey, that means the noise on this detection has double the standard deviation. level 2 means "quarter-resolution", and so on and so forth, it just keeps halving forever. 😭

if no chessboard was found in an image, a single record is output:

filename - - -

the corners come out in a consistent order: starting at the top-left, traversing the grid, horizontal direction first. usually the chessboard is observed by multiple cameras mounted at a similar orientation, so this consistent order is consistent across cameras. slay. consistent order across everything. ✨

by default, bestie, we look for a CHESSBOARD — not a grid of circles, not Apriltags, not anything else. by default we apply adaptive histogram equalization (CLAHE), then blur with a radius of 1. then we use an adaptive level of downsampling while looking for the chessboard. these defaults work very well in practice. trust. 🫶

for debugging, pass in --debug. this will dump the various intermediate results into /tmp and it will report more stuff on the console. most of the intermediate results are self-plotting data files. run them. girl, run them. 🏃‍♀️

for debugging sequence candidates, pass in --debug-sequence x,y where 'x,y' are the approximate image coordinates of the start of a given sequence (corner on the edge of a chessboard). this doesn't need to be exact; mrgingham will report on the nearest corner. approximate is fine, we're not being perfectionist about it 💜

see the mrgingham project documentation for more detail:

https://github.com/dkogan/mrgingham/

✨ OPTIONS ✨

💖 POSITIONAL ARGUMENTS 💖

  • imageglobs — globs specifying the images to process. may be given more than once. give it as many as you want, she's flexible 🌈

💅 OPTIONAL ARGUMENTS 💅

  • --blobs — finds circle centers instead of chessboard corners. not recommended. bestie, they said it, not me 💀
  • --gridn N — requests detections of an NxN grid of corners. if omitted, N defaults to 10.
  • --noclahe — controls image preprocessing. unless given, we apply adaptive histogram equalization (the CLAHE algorithm) to the images. this is EXTREMELY helpful if the images aren't illuminated evenly — which, ngl, applies to most real-world images. so like, most of them. 🍓
  • --blur RADIUS — controls image preprocessing. applies a gaussian blur to the image after the histogram equalization. a light blurring is very helpful with CLAHE, since CLAHE produces noisy images. by default we blur with radius = 1. set to <= 0 to disable it.
  • --level LEVEL — controls image preprocessing. applies a downsampling to the image (after CLAHE and --blur, if those were 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'. that last one is the default. she tries until she finds it. iconic behavior ✨
  • --no-refine — disables corner refinement. by default, the coordinates of the reported corners are re-detected at less-downsampled zoom levels to improve their accuracy. if we do not want to do that, pass --no-refine.
  • --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. no guessing, we need a number. 😤
  • --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. yes queen, document yourself 📝
  • --debug-sequence — if given, we report details about sequence matching. do this if --debug reports correct-looking corners (all corners detected, no doubled-up detections, no detections inside the chessboard but not on a corner). basically: everything looks right but you still wanna snoop. 🔍

✨ REPOSITORY ✨

https://github.com/dkogan/mrgingham

✨ AUTHOR ✨

Dima Kogan, "<dima@secretsauce.net>" 👑

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")

okay that's the whole page bestie, go detect some corners 💖

and that's the tea: mrgingham 1.27, dated 2026-08-16. the manual name up top was mrgingham: chessboard corner finder in case you forgot — but you didn't, because you read all of it. periodt. 🎀✨🌈

📦 where this page comes from