Deep dive · The pipeline
Follow one target, stage by stage
Eight steps a shooter would name, eleven stages in the pipeline's specification. Each stage has a defined input and output, a way to fail, and a record of what it decided and what it threw away, so every number can be traced back to the pixels it came from.
8
steps a shooter would name
11
stages in the pipeline's specification
25 of 25
shots found and assigned in the real run at the foot of this page
0.232 in
that group's mean radius
Step 1 · before S0
The sheet is born from a GLTD definition, and everything GroupLab will later need to read it is printed on it.
Step 1: print.
- 38
- markers on GL-CF25-LTR, on the corners of its cell lattice
- 6.0 mm
- per marker with its quiet zone
GLTD
The definition
Bulls, rings, markers and QR codes, all in page units.
Exclusion zones that can never hold a shot: the data block a shooter writes a load in, the codes with their quiet zones, the marker footprints and the identifier text.
The render
AprilTag 36h11 markers of 0.5 mm squares, 4.0 mm across, where the cell lines cross and nothing else is in the way; 9 on a 300 yard tile.
A GLTD-B frame in every QR code: the whole definition, a CRC-32 over it and a tile index; the sheet's identifier is computed from the definition.
Markers in the family's official orientation, whatever OpenCV's dictionary holds.
Step 2 · no stage
Shoot
Nothing runs, but the physics decides what GroupLab will see. Paper stretches ahead of the bullet and closes behind it, so the hole is narrower than the bullet, by a roughly constant amount rather than a proportion.
Step 2: shoot.
- 0.919
- hole over caliber, .264, 189 holes
- 0.920
- hole over caliber, .308, 42 holes
Survey
What holes measure
About 0.020 in narrower than the bullet, with a spread of 0.051 in: modeled as a fixed allowance, not a scale factor.
.338 holes measured 0.981 of caliber; a .22 LR hole as little as 0.49.
On printed ink a hole's rim is shallower and less even (its darkest point V 48 against 34 on paper), its dark band about 29 percent thicker, and it measures about 7 percent smaller; the inside of the hole is unchanged.
Step 3 · S0
Capture
A scan or a photograph becomes one image with a record of where it came from, and the sheet names its own definition.
Step 3: capture.
- 1920 × 1440
- live analysis stream on the phone
- 0 wrong
- sheet names on any platform
S0
Decode
The file is decoded as the camera or scanner stored it. PNG and JPEG are read.
The EXIF orientation is recorded, not applied, because the markers do not care which way up the sheet is.
S0
Identify
QR codes tried at full, double, half and quarter size, stopping at the first size that gives a GLTD-B frame passing its CRC; a size that would exceed 8000 px is skipped.
When no size gives a code, each code is cut out where the markers put it and read enlarged 2, 3 and 4 times.
Codes naming two definitions, or one not available, are refused with the reason. Nothing is guessed from the markers, which the built-in sheets share.
35 of 37 Phase 0 images named, on Windows, Linux and macOS alike, and none named wrongly.
Phone
The camera
One instruction at a time, in order: move back, move closer, less angle, hold steadier, more or less light.
Guided mode fires once every frame for 0.6 seconds has been judged ready; every picture is then checked and scored.
Step 4 · S1 to S4
Register
The markers turn pixels into page coordinates. This is where a photo's angle, a lens's bulge and a curled sheet are taken out.
Step 4: register.
- 0.00319 in
- worst bull, ten printed sheets, gate 0.005 in
- 0 → 26
- of 28 holes found once detection was kept inside the sheet
S1
Scale
In order of authority: the markers, then the file's DPI tag, then the content, then the person.
The tag was accurate to better than 0.1 percent on all fifteen files that carry one; a messaging-app picture with no tag was derived twice, at 93.0 and 93.05 dpi.
A provisional scale seeds the marker search, and is replaced once markers are found.
S2
Markers
Sub-pixel corners, refined in GroupLab's own code; threshold window sized for the marker; area and side-ratio gates as separate reasons.
If markers are lost: any four or more still register the sheet, fitted with RANSAC; with fewer, GroupLab stops and says how many it found.
S3
Register
Scans: a homography. On a crumpled, taped sheet it left 0.0027 in rms, where a similarity left 0.0040, and a more complex surface gained only 0.0002.
Never less than affine: scanners shear rows against columns by 0.12 to 0.17 degrees.
Photographs: a homography with two radial lens terms, fitted by Levenberg-Marquardt from the markers alone, with no camera data.
Bent paper: a thin-plate spline through every corner, and developable surfaces kept only when an F test says the bend is real.
S4
Verify
Print scale reported on each axis, not silently corrected.
From here on only pixels inside the registered sheet can become a candidate: on one photo the dark mat around the sheet merged into a blob a foot across, and 0 of 28 holes were found until it was masked.
Step 5 · S5 to S8
Detect
Render the sheet as printed, lay it over the photo, subtract, and judge what is left.
Step 5: detect.
- 0.012 / 0.055 in
- opening and closing radii
- 0.15
- threshold, a fraction of paper-to-ink range
S5
Render
The definition rasterized and resampled through the registration, on a grid and interpolated between.
Paper: the 95th percentile of paper pixels in eighth-inch blocks, smoothed. Ink: the median ratio of observed to paper where the render calls ink.
Each bull cell aligned by phase correlation, up to 0.1 in; the rest of the page by the median of those shifts. Exclusion zones masked hard.
S6
Difference
The absolute difference of observed and expected, both normalized by paper, as a fraction of the paper-to-ink range.
Counted in both directions, because a hole in a solid black bull makes the page lighter, not darker.
S7
Candidates
Open with a disk of radius 0.012 in, threshold at 0.15, close with a disk of radius 0.055 in, fill, take each blob's convex hull.
Every radius in inches, converted with the scale S1 settled.
S8
Classify
Size against the stated caliber, floor 0.45 of it; solidity and aspect, with the torn-hole rescue.
Position: outside every cell is refused, except within one cell width of the grid, kept and marked.
Elongation of 1.80 or more is split into two holes, both flagged; a mark with the area of 1.35 single holes or more is flagged as oversized, a single hole being the caliber's or the sheet's own typical mark.
Center: weighted by the residual, over the whole disturbed area, not a fitted circle.
Step 6 · S9
Assign
Nearest bull is not the rule. The rule is the matching of shots to bulls, one each, that minimizes the total distance, because one shot per bull is what the sheet was designed around.
Step 6: assign.
- 0 to 3
- shots per surveyed target outside their own cell
- 1
- shot nearest bull got wrong in the survey; matching gets it right
S9
Three cases
As many shots as bulls, or fewer: optimal one-to-one matching.
More shots than bulls: never forced, because forcing manufactures confident wrong answers. Nearest bull within a distance, every shot flagged, and the person told the counts disagree.
A margin under 0.15 in between the best and second-best bull is flagged either way.
Real
The case that proves it
On one commercial scan, a hole 0.627 in from bull 4 and 1.043 in from bull 9. Nearest bull gives it to 4, which already has a shot 0.289 in away; bull 9 has none. Matching gets it right.
Step 7 · S10
Combine
Sheets of one load, or the tiles of one large target, become one group. Only bookkeeping, never geometry, joins them.
Step 7: combine.
- 0
- effect of tile alignment on the group
- per shot
- confidence survives pooling
S10
Pool
Each tile runs S0 to S9 on its own and every shot is an offset from its own bull, so tape gaps and sheets stapled out of square add nothing.
The tile index in each frame maps local bulls to the assembly. Every tile present once; a missing tile is reported as missing bulls, not dropped.
A sheet read twice counts once, and GroupLab says so.
A contested assignment on one tile stays contested in the composite.
Step 8 · after S10
Report
The figures, each with a range for how sure it is, from a statistics library compared with R's shotGroups on every build.
Step 8: report.
- 45,476
- values compared with R shotGroups
- 490 of 490
- Monte Carlo cells within tolerance
Stats
What is reported
Mean radius, estimated as sigma times the square root of pi over two; CEP 50 and 90; extreme spread; each with its interval.
A shot left out is out of every figure, and shown as left out.
The offsets for a zero from the statistics, and the drop, wind and hit chance at distance from the ballistics.
Watch it think
Every stage writes down what it did
Each stage writes a record: the settings it actually used (in inches and in the pixels they became), the decisions it made with the alternatives it turned down, and every candidate it rejected with the reason. The rejections are the interesting half: they turn "no shot here" into "a mark 0.058 in across, under the 0.150 in floor". Below is a real run of grouplab analyze on a sample in the repository, a 600 dpi scan of GL-CF25-LTR-D with 25 shots. In code, S5 to S8 are recorded as one stage and S10 is called group.
[S0.decode ] ok PNG 4958x6458
[S0.identify ] ok GL-R0T0-384Z-HRBE-M0EW, from 2 codes at 1 times full resolution
at 1 times full resolution: 2 codes read, 2 valid frames
candidates: 44 definitions
resolutions: 1, 2, 0.5, 0.25
definition: GL-R0T0-384Z-HRBE-M0EW
[S1.scale ] ok 600.0 DPI from PNG metadata; provisional
decided provisional scale: 600.0 DPI, because PNG metadata states it, and the fiducials check it after S3; not bootstrap from the markers
[S2.fiducials ] degraded 34 markers sought, 33 decoded, 1 not found
markerSide: 4.0 mm = 94.5 px
refinement: Subpixel, window OpenCvSharpBackend default
thresholdWindowMax: sized from the marker
downsample: 1x
rejected marker 28 at (0.512, 9.142) in: printed, not found
[S3.register ] ok homography, 33 markers, 132 of 132 corners inliers
residual rms 0.00260 in, max 0.00735 in
decided model: homography, because a flatbed scan (DETECTION-PIPELINE.md stage S3); not homography with radial distortion
ransacThreshold: 2.54 dmm = 6.0 px
rejected marker 28 at (0.512, 9.142) in: not found: no candidate quad at its position
[S1.scale ] ok 600.2 DPI x, 600.3 DPI y from fiducials at the page center; the file stated 600.0
[S4.verify ] ok printed at 100.04% of intended size, x 100.03%, y 100.06%
[P0.bulls ] ok 25 of 25 bulls located, mean 0.00148 in, worst 0.00251 in at 19
edge points per located bull: fewest 758 at bull 5, median 851, most 900
locator: edge fit to the declared disc radii
edges[std]: 5 edges, 180 rays, up to 3.0 dmm = 7.1 px each side
[S5-S8.holes ] ok 25 holes inside the registered sheet, 9 candidates rejected, 0 of them hole-sized inside exclusion zones
resolution: 600.2 px per inch, from the registration
hole size: a hole is taken as 0.247 in, the quarter-point of 25 round marks
caliber: none named, so a single hole is the sheet's own 25th percentile mark once it has five, and shape alone decides before that
rejected blob 0.058 in across at (5.925, 0.559) in: too small, 0.058 in, under 0.150 in
rejected blob 1.610 in across at (1.523, 9.958) in: too large, 1.610 in
rejected blob 0.897 in across at (6.029, 9.748) in: too large, 0.897 in
rejected blob 0.023 in across at (2.708, 9.397) in: too small, 0.023 in, under 0.150 in
rejected blob 0.846 in across at (5.178, 9.833) in: too large, 0.846 in
rejected blob 1.415 in across at (3.518, 9.997) in: too large, 1.415 in
rejected blob 0.043 in across at (7.513, 9.915) in: too small, 0.043 in, under 0.150 in
rejected blob 0.058 in across at (4.640, 10.635) in: too small, 0.058 in, under 0.150 in
rejected blob 0.023 in across at (0.728, 10.630) in: too small, 0.023 in, under 0.150 in
[S9.assign ] ok 25 shots to 25 bulls by one-to-one matching
decided assignment: one-to-one matching, because as many shots as bulls
[S10.group ] ok 25 shots pooled about their own bulls, mean radius 0.232 in
mean radius 0.232 in 94.9% interval 0.193 to 0.290 in
sigma 0.185 in 94.9% interval 0.154 to 0.231 in
extreme spread 0.849 in 95.0% interval 0.652 to 1.125 inA real run: grouplab analyze samples/gl-cf25-ltr-d-25-shots-600-dpi.png -v 3, 28 September 2026. The time each stage took is left out, because it came from a development build and says nothing about speed.
→ Designing a target GroupLab can read→ A bullet hole is not the bullet→ Scans against phone photos→ Choosing the markers→ Curled, angled and wrinkled paper→ How GroupLab reads a target→ One hole or two?→ Pooling groups→ The sample on GitHub→ The pipeline specification→ How the hole detector was built→ How GroupLab uses OpenCV→ Every feature