Tour › Behind the curtain
How GroupLab works
Click any part for a technical summary, then open its full explanation. Or follow one target through the eleven stages of the pipeline's specification, from the file to the pooled group.
Apps you run thin shells
GroupLab.Core the engine: no user interface, no OpenCV
Imaging the Core's only door to OpenCV
Checked at build time never shipped
Online website, server and releases
Arrows of control run downward: an app calls the Core, the Core calls the imaging interface, and the Core never touches OpenCV itself; the apps use OpenCV behind that interface and to read and write image files. The build-time checks and the online parts never run on your device.
The parts
Apps you run
Desktop app
An Avalonia shell around the Core. It prints sheets, runs the printer check, reads scans and photographs, and draws every result; the figures themselves all come from GroupLab.Core. Its imaging backend is OpenCvSharp with OpenCvSharp's own native runtime packages.
Key numbers
- 1 to 4 s
- to analyze a 300 dpi Letter scan on a desktop, naming the sheet included
Built from
- .NET 10
- Avalonia
- OpenCvSharp 4.13
Where it lives
Apps you run
Android app
The same Core on the phone, with OpenCV built from source for arm64. The camera screen analyzes a 1920 × 1440 stream live (CameraX's default is 640 by 480, where a QR module is about one pixel), gives one instruction at a time, and in Guided mode fires once every frame for 0.6 seconds has been judged ready. Every picture is then checked and scored. Its screens are one shared project, mobile/GroupLab.Mobile, a plain .NET library the iPhone and iPad build links too, and only the camera, printing, sharing and updating are Android's own.
Key numbers
- 1920 × 1440
- live analysis stream
- 0.6 seconds
- judged ready before Guided fires
- < 40
- on the score bar means take it again; 70 and up is good
Built from
- .NET 10
- CameraX
- OpenCV 4.13 for arm64
Where it lives
How OpenCV was built for Android ↓
Read more
Apps you run
iPhone and iPad
Planned the same way: an Avalonia shell around the same Core, with OpenCV built as a static iOS framework and builds from GitHub's macOS runners to TestFlight.
Built from
- .NET 10
- Avalonia
- OpenCV for iOS
Where it lives
Apps you run
Command line
The engine with no windows. Its measurements are made by named commands, such as grouplab holes synthetic for the detector's scores or grouplab identify sweep for the QR reading, and the Phase 0 measurement record and the QR sweep are rerun by those commands in CI on Windows, Linux and macOS.
Key numbers
- 3 systems
- Windows, Linux and macOS, where CI reruns the Phase 0 measurement record
Built from
- .NET 10
- OpenCvSharp
Where it lives
GroupLab.Core
Target format
Every sheet is one GLTD definition: bulls, rings, markers, codes and the zones that can never hold a shot. A binary frame, GLTD-B, is printed in the QR codes: the whole definition, a CRC-32 over it and a tile index, so a sheet names its own definition. A wrong name must never happen, because it would scale every measurement by a wrong number; an unnamed sheet only costs one choice from a list.
Key numbers
- 35 of 37
- Phase 0 images named from their codes, on Windows, Linux and macOS alike
- 0
- wrong names on any platform, the number that must stay at zero
Built from
- JSON
- binary QR frame with CRC-32
Where it lives
Follow a sheet through the stages ↓
Read more
GroupLab.Core
Renderer
Draws the definition twice: as the PDF you print, and as the expected image, resampled through the registration so the printed artwork lies on the photo pixel for pixel. Paper level is estimated locally (the 95th percentile of paper pixels in eighth-inch blocks, smoothed), never as one global value.
Key numbers
- ⅛ in
- blocks for the local paper level
- 0.1 in
- most each bull cell may shift to align by phase correlation
Built from
- GLTD
Where it lives
src/GroupLab.Core/Renderingsrc/GroupLab.Core/Detection/ExpectedImage.cssrc/GroupLab.Core/Detection/RenderDifferenceHoleDetector.cs
How render-and-difference works ↓
Read more
GroupLab.Core
Registration
Maps image pixels to page coordinates from the marker corners. Scans get a homography, never less than affine because scanners shear by 0.12 to 0.17 degrees. Photographs add two radial lens terms fitted by Levenberg-Marquardt. Curled or waved paper is followed by a thin-plate spline through every corner.
Key numbers
- 152
- corners from the 38 markers on GL-CF25-LTR, for an 8-parameter homography
- 0.00319 in
- worst bull on ten printed sheets, against a 0.005 in gate
- 0.054 → 0.029
- inches, median worst bull on 12 photos, without and with the lens fit
Built from
- RANSAC
- Levenberg-Marquardt
- thin-plate spline
Where it lives
Registration, stage by stage ↓
Read more
GroupLab.Core
Hole detection
Subtracts the expected image from the photo, as a fraction of the local paper-to-ink range, so printed artwork cancels and holes remain. Then morphology sized in inches, not pixels: open with a radius of 0.012 in, threshold at 0.15, close with a radius of 0.055 in, fill, convex hull. The smallest hole allowed follows the stated caliber, one hole or two is judged against the sheet's own marks, and nothing is refused silently.
Key numbers
- 343
- real hole measurements, on 15 scans of commercial targets, before GroupLab's detector was written
- 100%
- of held-out synthetic holes found within 0.15 in, one per bull; synthetic holes are easier than real ones, so this is an upper bound
- 0.0063 in
- median center error on those holes
Built from
- OpenCV morphology
- GroupLab's own rules
Where it lives
How the hole detector was built ↓
Read more
GroupLab.Core
Statistics
Mean radius, CEP 50 and 90, extreme spread and the rest, each with an interval. Mean radius is estimated as sigma times the square root of pi over two, not a plain average. Every figure the R package shotGroups also computes is checked against its output on every build. The simulation behind Shots Needed to Zero lives here too.
Key numbers
- 45,476
- values compared with R shotGroups, none pending
- 490 of 490
- Monte Carlo table cells within tolerance
Built from
- .NET 10
- checked against R shotGroups
Where it lives
Read more
GroupLab.Core
Ballistics
Turns a group into what it means at distance: drop and wind for the load, a group carried to another distance, and the chance of a hit on a given target.
Built from
- .NET 10
Where it lives
Imaging
OpenCV, behind one interface
The Core never calls OpenCV. It asks an interface for seven things: find markers, fit a homography, warp, open or close, list filled blobs with hulls, phase-correlate, and read QR codes. Four floating-point steps, the warp among them, were moved into GroupLab's own managed code, so every platform prints the same figures.
Key numbers
- 7
- operations the Core asks of OpenCV
- 10
- OpenCV modules in the Android build
- 4
- steps rewritten in managed code so every platform prints the same figures
Built from
- OpenCV 4.13
- OpenCvSharp
- ArUco
- WeChat QR detector
Where it lives
Read more
Checked at build time
Reference checks
Never shipped. The statistics are checked against R's shotGroups, the geometry and the QR format against independent Python code, and the ballistics against two other solvers, every time GroupLab is built. Neither R nor Python runs in the build: the tests read the outputs those programs wrote once and committed.
The original hole survey was also a Python and OpenCV harness, kept so each of its numbers can be reproduced.
Built from
- R
- shotGroups
- Python
- numpy
- Node
Where it lives
Online
grouplab.org
One script builds the whole site from plain files: the features list, the tour and the research articles. It refuses to build a figure that has no dark version, and it runs each article's figure script so the charts come from the data.
Built from
- Python
- Markdown
- JSON
Where it lives
Online
Server workers
Small PHP receivers put what arrives into quarantine, and small timed jobs under systemd limits take it from there. A sent target is rebuilt from its pixels (so nothing hidden in the file survives), is copied to a private archive, and is deleted from the server.
Key numbers
- 60 days
- the longest a sent target waits on the server
- 30 days
- the longest an error report or a survey answer waits
- 7 days
- before anything refused is deleted
Built from
- Python
- PHP
- nginx
- systemd timers
Where it lives
Read more
Online
Builds and updates
Every change is built and tested on Windows, Linux and macOS. Every tested change to what ships becomes a nightly build with installers, and the app only accepts updates signed with the project's key.
Built from
- GitHub Actions
- signed updates
Where it lives
Read more
Follow a target
The eight steps a shooter would name, from printing the sheet to the report. Each lists the stages of the pipeline that run in it and the parts of the map involved.
Step 1 of 8 · before S0
The renderer draws the sheet from its GLTD definition, with AprilTag markers where the cell lines cross and the definition in its QR codes. A one-time printer check measures the printer's scale, so photographs of its sheets are corrected to real inches.
- GLTD Definition. bulls, rings, markers, codes and exclusion zones
- PDF Render. 0.5 mm marker modules, 4.0 mm markers, 38 on GL-CF25-LTR
Step 2 of 8 · no stage
Shoot
Nothing runs. The paper stretches ahead of the bullet and closes behind it, so a hole is narrower than the bullet: about 0.92 of caliber for .264 and .308 in the survey.
- Survey What holes measure. a fixed allowance narrower than the bullet, not a scale factor
Step 3 of 8 · S0
Capture
A scan or a photo is decoded into one image, and the sheet is named from its QR codes.
- S0 Decode. a JPEG or PNG decoded as the camera or scanner stored it, its orientation recorded and not applied
- S0 Identify. codes read at full, double, half and quarter size, then cut out where the markers put them and enlarged; a frame must pass its CRC, and codes that disagree are refused
Step 4 of 8 · S1 to S4
Register
The markers give scale, position and shape of the paper.
- S1 Scale. markers first, then the file's DPI tag, then content, then ask
- S2 Markers. AprilTag 36h11 with sub-pixel corners and two shape gates
- S3 Register. RANSAC homography, lens terms, or a spline through every corner
- S4 Verify. print scale reported per axis, never silently corrected
Step 5 of 8 · S5 to S8
Detect
The expected image is subtracted; morphology in inches finds candidates; each is judged.
- S5 Render. expected image, local paper level, cells aligned
- S6 Difference. residual as a fraction of paper-to-ink range
- S7 Candidates. open radius 0.012 in, threshold 0.15, close radius 0.055 in, hull
- S8 Classify. size for the caliber, position, splits, flags
Step 6 of 8 · S9
Assign
Shots are matched to bulls.
- S9 Assign. globally optimal one-to-one matching; never forced when shots outnumber bulls; margins under 0.15 in flagged
Step 7 of 8 · S10
Combine
Sheets of one load, or tiles of one big target, are pooled.
- S10 Pool. each tile registers itself, so tile alignment adds nothing; a missing tile is reported, not dropped
Step 8 of 8 · after S10
Report
Figures with intervals, checked against R shotGroups.
- Stats Figures. mean radius, CEP, extreme spread, each with how sure it is
→ How GroupLab uses OpenCV→ How the hole detector was built→ Follow one target, stage by stage→ Back to the tour→ Every feature→ The code on GitHub