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.

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

Modules

codebook

Generated codebook for 16-sector ring markers.

codec

Marker ID decoding from ring sector patterns.

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.

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.

Ellipse

Geometric ellipse parameters fitted to a ring marker boundary.

FitMetrics

Fit quality metrics for a detected marker.

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.

ProjectiveCenterParams

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

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

CircleRefinementMethod

Center-correction strategy used after local fits are accepted.

DetectionFrame

Coordinate frame used by serialized detection outputs.

Traits

PixelMapper

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