GROUPLAB DOWNLOAD
More

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.

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
  • PDF

Where it lives

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

How GroupLab uses OpenCV ↓

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

Print

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

Every stage in full ↓

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

Every stage in full ↓

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

Every stage in full ↓

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

Every stage in full ↓

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

Every stage in full ↓

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

Every stage in full ↓

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

Every stage in full ↓

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

Every stage in full ↓