Completion & Final Refit

The completion stage attempts to detect markers that the initial pipeline missed — typically markers at the image periphery, under heavy blur, or with low contrast. It runs after projective-center correction, structural ID correction, and global homography filtering. It uses the homography to predict where missing markers should be and attempts conservative local fits at those locations.

Completion Algorithm

For each marker ID in the BoardLayout that was not detected in the initial pipeline:

Project: use the homography to map the board position to image coordinates
Boundary check: skip if the projected position is too close to the image edge (within image_margin_px)
Local fit: run edge sampling and RANSAC ellipse fitting within a limited ROI (roi_radius_px) around the projected center
Decode: attempt code decoding at the fitted position
Gate: accept the detection only if it passes conservative quality gates

Conservative Gates

Completion uses stricter acceptance criteria than the initial detection to avoid false positives:

Parameter	Default	Purpose
`reproj_gate_px`	3.0 px	Max distance between fitted center and H-projected position
`min_fit_confidence`	0.45	Minimum fit quality score
`min_arc_coverage`	0.35	Minimum fraction of rays with valid edge detections
`roi_radius_px`	24.0 px (derived from scale prior)	Edge sampling extent
`image_margin_px`	10.0 px	Skip attempts near image boundary
`max_attempts`	`None` (unlimited)	Optional cap on completion attempts

The reproj_gate_px is the most important gate — it ensures that completed markers are geometrically consistent with the homography. A tight gate (default 3.0 px) prevents false detections from being added.

Seed Strategy

The completion stage uses a three-level fallback chain to predict each missing marker’s image position:

Hex-neighbor midpoint (via projective-grid): predicts the position from axial midpoints of detected hex neighbors along three hex axes. This is the most geometrically principled seed for hex lattices and handles local perspective distortion well.
Local affine: fits a local affine transform from the 3–4 nearest decoded neighbors in board space and projects the missing position. Requires at least 3 nearby decoded markers.
Global homography: projects the board position through the global H matrix. Least accurate under lens distortion at image periphery.

The hex-neighbor seed was added via the projective-grid crate integration. On the rtv3d validation dataset it provides +5–6 additional decoded markers across strategies.

Projective Center for Completion Markers

After completion, projective center correction is applied to the newly completed markers only. Previously corrected markers retain their corrections. Each marker is corrected exactly once.

Final Homography Refit

With the expanded marker set (original + completed), the homography is refit from all corrected centers. This final refit:

Uses all available markers for maximum accuracy
Accepts the refit only if the mean reprojection error improves
Updates DetectionResult.homography and DetectionResult.ransac

Disabling Completion

Set completion.enable = false in DetectConfig or use --no-complete in the CLI to skip completion entirely. This is useful when:

You only want high-confidence initial detections
Processing speed is more important than recall
The homography is unreliable (few decoded markers)

Completion also requires a valid homography — if the global filter did not produce one (fewer than 4 decoded markers), completion is automatically skipped.

Source: detector/completion.rs, pipeline/finalize.rs

Keyboard shortcuts