GROUPLAB DOWNLOAD
More

Deep dive · Imaging

How GroupLab uses OpenCV

OpenCV is a widely used open-source computer vision library. GroupLab uses a small, deliberate slice of it: seven operations, reached through one interface, and one of the seven, the warp, has since become GroupLab's own code. OpenCV finds things in pixels. Deciding what a hole is, fitting the paper, and every number you are shown is GroupLab's own code.

4.13.0

the OpenCV release on every platform, built for each

7

operations the Core may ask for, and no others

10

OpenCV modules compiled into the Android build

4

floating-point steps moved into GroupLab's own code

1 · Where OpenCV sits

Four layers between the Core and the pixels

GroupLab.Core has no reference to OpenCV at all. It talks to an interface, IImagingBackend, and each app plugs in an implementation. That keeps the measuring code identical on every device, lets tests swap the backend, and means a future library change touches one file rather than the engine.

C#, no OpenCV reference

GroupLab.Core

Registration, render-and-difference, classification, assignment, statistics. Asks for pixel work only through the interface below.

↓ calls

IImagingBackend

DetectMarkers · FindHomography · WarpPerspective · Morphology · FilledBlobs · PhaseCorrelate · ReadCodes

src/GroupLab.Core/Imaging

↓ implemented with

OpenCvSharp

A thin C# layer over OpenCV's C++ API, under the Apache-2.0 license. The managed half is one package; the native half must come from the same release.

↓ calls native code

Desktop and command line

OpenCvSharp's published native runtimes at 4.13.0, for Windows, Linux x64 and macOS, Intel and Apple silicon.

src/GroupLab.Cli/GroupLab.Cli.csproj

↓ calls native code

Android

Nobody publishes this, so GroupLab builds it: OpenCV and opencv_contrib 4.13.0 compiled with the Android NDK for arm64-v8a, API 24, static C++ runtime, linked into one libOpenCvSharpExtern.so. The only community build carried four modules; GroupLab needs 10.

android/opencv/build-extern.sh

The Android modules. core, imgproc, imgcodecs, calib3d for the homography, features2d, flann, objdetect for the QR decoder, dnn, aruco for the markers and wechat_qrcode for the QR finder. dnn is compiled in only because the WeChat finder needs it; no neural network is ever loaded, and no model file ships with GroupLab.

2 · The seven operations

Everything GroupLab asks of OpenCV

OperationOpenCVStageWhat GroupLab sets, and why
Find markersaruco::ArucoDetector, DICT_APRILTAG_36h11S2OpenCV's own corner refinement left off and every corner refined to a fraction of a pixel in GroupLab's code; threshold window and minimum perimeter sized from the expected marker; corner order turned back 180 degrees; a side-ratio gate of 2.0 applied after decoding.
Fit a homographycalib3d findHomography, RANSACS3Threshold in page units. Correspondences sorted by marker identifier first, because RANSAC samples by list position. Final refinement done in managed code.
Warpnone now: GroupLab's own resampler, in place of imgproc warpPerspectiveregistration checkResampling an image through a transform, as OpenCV's warpPerspective does with linear interpolation. Through the interface it builds only the synthetic scans of the registration check, and it runs in managed code so they match on every platform. The expected image in S5 has a resampler of its own.
Open or closeimgproc morphologyEx, elliptical elementS7Radii given in inches and converted with the measured scale: open radius 0.012 in, close radius 0.055 in.
Filled blobsfindContours (external), fill, 8-connected components, convexHullS7Each outline filled, then each blob with its pixel count, box and convex hull, the hull being what is measured.
Phase correlationimgproc phaseCorrelate, Hann windowS5Aligns each bull cell of the expected image to the photo, up to 0.1 in, so a small registration error does not leave slivers.
Read QR codeswechat_qrcode detector, objdetect QRCodeDetectorS0WeChat finds, the plain decoder reads the bytes. Tried at full, double, half and quarter size, with the corners of the page tried when the whole finds nothing; then each code is cut out where the markers put it and read enlarged 2, 3 and 4 times.

3 · Inside marker detection

How one AprilTag becomes four precise corners

Today's GroupLab Letter sheet, GL-CF25-LTR, carries 38 markers: 34 where the cell lines of its 5 by 5 grid cross, and 4 below its row of three sighter bulls. Each is an AprilTag from the 36h11 family: an 8 by 8 grid of 0.5 mm squares, a black border around 36 data bits. What GroupLab needs from them is not their identity so much as their corners, measured to a fraction of a pixel.

1. The photo. Gray, soft, turned and at an angle.

2. Adaptive threshold. Black or white against the local average, so shadows do not matter. Window sized for the marker.

3. A quad. Outlines become four-sided shapes. Too small, or sides more than 2 to 1, and it is refused.

4. Straightened and sampled. The perspective is removed and each data cell is read at its center.

5. Decoded. Matched against every code of the family, so a few misread bits are corrected and one marker is never taken for another.

6. Corners refined. Edges fitted through the gray pixels place each corner to a fraction of a pixel, in GroupLab's own code.

Each marker's 36 data bits are matched against the family's 587 codes, any two of which differ in at least 11 bits. The family could correct up to 5 misread bits; GroupLab corrects at most 3 and refuses the rest.

Why 36h11

587 identifiers, a minimum distance of 11 bits between any two, and the only strong family that both OpenCV and the BSD-licensed AprilTag reference code can read. The first draft chose ArUco 6x6. Checking the claims it rested on reversed it: the AprilTag library cannot read any ArUco dictionary, and OpenCV draws 36h11 in the same 8 by 8 footprint. On the real scans both families scored zero false markers.

Why 0.5 mm squares

Detection needs about 3 pixels a square. The printer is the real limit: under about 5 printer dots a square, ink spread shifts the edges, and the corner is the measurement. 0.5 mm gives 11.8 pixels a square on a 600 dpi scan and 7.2 on a 12 MP photo.

Why so many

Four markers are enough for a flat scan. The 38 on GL-CF25-LTR survive a torn corner, sample a lens's distortion at many distances from the center, and give 152 corners for 8 unknowns, so the fit is far more precise than any one corner. The load-block sheet GL-CF25-LTR-D carries 34.

4 · Where the defaults were wrong

Five things that would have failed silently

OpenCV's defaults are tuned for cameras, where a marker is a small part of the picture. GroupLab wants many corners on a flat sheet held still. None of these would have stopped a marker decoding. Each would have quietly made every measurement worse. Three are OpenCV settings and two are corrections to what OpenCV hands back, and GroupLab changes other defaults besides, such as how finely each cell of a marker is sampled.

CORNER_REFINE_NONE

Corner refinement is off

The accuracy target is a thousandth of an inch, 0.6 pixels at 600 dpi. Unrefined corners would not come close. GroupLab refines every corner to a fraction of a pixel in its own code, which also gives the same corner on every platform.

adaptiveThreshWinSizeMax = 23

The threshold window is sized for webcams

At 600 dpi a 4.0 mm marker is 94 pixels across, far larger than the default window expects. The window is sized from the expected marker.

first corner = printed bottom-right

OpenCV's 36h11 codes are turned 180 degrees

Identifiers still decode, so nothing looks wrong, but the corner order is reversed. It would have shown up as a target that registers slightly badly, blamed on the printer. GroupLab prints the official orientation and turns OpenCV's corners back, tested against all 587 codes.

sorted by identifier

Results come back in any order

The macOS runner returned markers in a different order, and RANSAC samples by position in the list, so one image could give two answers. Every detection is sorted by identifier before anything is measured.

side ratio > 2.0 refused

Shape can only be checked after decoding

Every false marker seen on the real scans was a sliver. The size gate is given to OpenCV in advance as a minimum perimeter; the side-ratio gate cannot be, so it runs on what decoded. Both are recorded as reasons of their own.

5 · Morphology

Finding holes by their size, in inches

After the printed artwork has been subtracted, what is left is a residual image. OpenCV's morphology then cleans it by shape and size. Every radius is written in inches and converted with the scale the markers measured, so the same numbers run unchanged on a 300 dpi and a 600 dpi scan, and are meant to hold down to a 93 dpi picture from a messaging app.

Residual. Observed minus expected, as a fraction of the paper-to-ink range. A hole's rim, a registration sliver along a printed ring, a speck.

Open. A disk of the opening radius: anything thinner disappears, the slivers and the speck.

Threshold. A fraction of the local range, never a gray level.

Close and fill. A disk of the closing radius bridges the gap in a C-shaped rim, and the inside is filled.

Convex hull. Its size is judged against the caliber; the center is weighted by the residual.

0.012 in
the opening's radius
0.15
the threshold, a fraction of the local paper-to-ink range
0.055 in
the closing's radius

Why not a gray level

An absolute gray threshold was measured needing 28 at 600 dpi, 12 at 300 dpi and 18 at 93 dpi on the same physical targets, because a rim averaged over fewer, larger pixels looks paler. A relative threshold and radii in inches need none of that tuning. How these numbers were chosen is on the hole detector's page.

6 · The same answer everywhere

Why four steps left OpenCV

The accuracy record is rerun on Windows, Linux and macOS. Linux matched to the precision reported; macOS gave different figures in two measurements. The differences were traced to four native floating-point steps: a perspective warp, sub-pixel corner refinement, the homography's final refinement, and the contour refinement, which fits lines in single precision. Turning OpenCV's optimized paths off did not help, so the cause was the native arithmetic itself.

Those four now run in GroupLab's own code using only addition, subtraction, multiplication, division and square root in a fixed order, which every processor rounds identically. The one exponential is a series; no sum is vectorized. OpenCV keeps the integer work, finding and decoding candidates and choosing RANSAC's inliers, which was already identical everywhere. Since then macOS prints the same figures as the other two.

The four steps, in GroupLab's code

Perspective warp · sub-pixel corner refinement · the homography's final refinement · contour refinement

src/GroupLab.Core/Imaging/PortableImaging.cs

7 · Reading the QR codes

Two detectors, because neither is enough

OpenCV's plain QR detector missed the codes on a 600 dpi scan, a tile and a photograph. The WeChat detector, used without its neural network models, found all three, but hands back text through UTF-8, so every byte above 0x7F in the binary frame became a replacement character and no frame passed its CRC.

So WeChat finds each code and the plain decoder reads it at those corners; its one-byte-per-character text turns back into the exact bytes. Codes are tried at several sizes, then in each corner third of the page, then in smaller corner squares, because every sheet keeps its codes near its corners; and, where that fails, each code is cut out where the markers say it is and read enlarged, two to four times.

Where it lives

The same source file reads the codes on the desktop, on the command line and on Android.

src/GroupLab.Cli/Imaging/OpenCvSharpBackend.cs

8 · What OpenCV does not do

The parts that are GroupLab's own

Drawing the target

The sheet you print, and the expected image it is compared with.

Fitting the paper

The lens model by Levenberg-Marquardt, the bending surfaces and the thin-plate spline.

Deciding what is a hole

The size gate from the caliber, torn and partial holes, splits, flags. No learned model decides.

Assigning shots

Shots go to bulls by optimal one-to-one matching.

Every statistic

Checked key by key against the shotGroups R package on nine reference datasets wherever it computes the same thing, and against the specification's own tables otherwise.

The picture check

And its score, from focus, exposure, angle, resolution, the markers read, the evenness of the light and the fit's own error.