Crate ringgrid 

ringgrid

Pure-Rust detector for dense coded ring calibration targets on a hex lattice.

ringgrid detects ring markers in grayscale images, decodes their 16-sector binary IDs from a 893-codeword codebook, fits subpixel ellipses via Fitzgibbon’s direct method with RANSAC, and estimates a board-to-image homography. No OpenCV dependency — all image processing is in Rust.

Detection Modes

• Simple — Detector::detect: single-pass detection in image coordinates. Use when the camera has negligible distortion.
• External mapper — Detector::detect_with_mapper: two-pass pipeline with a PixelMapper (e.g. CameraModel) for distortion-aware detection.
• Self-undistort — Detector::detect with SelfUndistortConfig::enable set to true: estimates a 1-parameter division-model distortion from detected markers and optionally re-runs detection with the estimated correction.

Quick Start

use ringgrid::{BoardLayout, Detector};
use std::path::Path;

let board = BoardLayout::from_json_file(Path::new("target.json")).unwrap();
let image = image::open("photo.png").unwrap().to_luma8();

let detector = Detector::new(board);
let result = detector.detect(&image);

for marker in &result.detected_markers {
    if let Some(id) = marker.id {
        println!("Marker {id} at ({:.1}, {:.1})", marker.center[0], marker.center[1]);
    }
}

Coordinate Frames

Marker centers (DetectedMarker::center) are always in image-pixel coordinates, regardless of mapper usage. When a PixelMapper is active, DetectedMarker::center_mapped provides the working-frame (undistorted) coordinates, and the homography maps board coordinates to the working frame. DetectedMarker::board_xy_mm provides board-space marker coordinates in millimeters when a valid decoded ID is available on the active board.

See DetectionResult::center_frame and DetectionResult::homography_frame for the frame metadata on each result.

Structs

BoardLayout

Runtime board layout used by the detector.

BoardMarker

A single marker’s position on the calibration board.

CameraIntrinsics

Pinhole camera intrinsics.

CameraModel

Complete camera model (intrinsics + radial-tangential distortion).

CompletionParams

Configuration for homography-guided completion: attempt local fits for missing IDs at H-projected board locations.

DecodeConfig

Configuration for sector decoding.

DecodeMetrics

Decode quality metrics for a detected marker.

DetectConfig

Top-level detection configuration.

DetectedMarker

A detected marker with its refined center and optional ID.

DetectionResult

Full detection result for a single image.

Detector

Primary detection interface.

DivisionModel

Single-parameter division distortion model.

EdgeSampleConfig

Configuration for radial edge sampling.

Ellipse

Geometric ellipse parameters fitted to a ring marker boundary.

FitMetrics

Fit quality metrics for a detected marker.

IdCorrectionConfig

Structural ID verification and correction using hex neighborhood consensus.

InnerAsOuterRecoveryConfig

Configuration for automatic recovery of markers where the inner edge was incorrectly fitted as the outer ellipse.

InnerFitConfig

Configuration for robust inner ellipse fitting from outer-fit hints.

MarkerScalePrior

Scale prior for marker diameter in detector working pixels.

MarkerSpec

Marker spec in outer-normalized radius units.

OuterEstimationConfig

Configuration for outer-radius estimation around a center prior.

OuterFitConfig

Configuration for robust outer ellipse fitting from sampled edge points.

ProjectiveCenterParams

Projective-only unbiased center recovery from inner/outer conics.

Proposal

A proposed marker center with its vote score.

ProposalConfig

Configuration for center proposal detection.

RadialTangentialDistortion

Brown-Conrady radial-tangential distortion coefficients.

RansacHomographyConfig

RANSAC configuration for homography fitting.

RansacStats

RANSAC statistics for homography fitting.

SeedProposalParams

Seed-injection controls for proposal generation.

SelfUndistortConfig

Configuration for self-undistort estimation.

SelfUndistortResult

Result of self-undistort estimation.

Enums

BoardLayoutLoadError

Load-time failures for board layout JSON.

BoardLayoutValidationError

Validation failures for a board layout specification.

CircleRefinementMethod

Center-correction strategy used after local fits are accepted.

DetectionFrame

Coordinate frame used by serialized detection outputs.

InnerFitReason

Stable reject/failure code for inner fit.

InnerFitStatus

Outcome category for robust inner ellipse fitting.

Traits

PixelMapper

Mapping between raw image pixels and detector working-frame pixels.