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 the shipped baseline 893-codeword profile (with an opt-in extended profile available for advanced use), 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.

Re-exports

pub use proposal::find_ellipse_centers;

pub use proposal::find_ellipse_centers_with_heatmap;

pub use proposal::Proposal;

pub use proposal::ProposalConfig;

pub use proposal::ProposalResult;

Modules

proposal

Gradient-voting radial symmetry for ellipse center detection.

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.

PngTargetOptions

PNG target-generation options.

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.

ScaleTier

One scale band for multi-scale adaptive detection.

ScaleTiers

An ordered set of scale tiers for multi-scale adaptive detection.

SeedProposalParams

Seed-injection controls for proposal generation.

SelfUndistortConfig

Configuration for self-undistort estimation.

SelfUndistortResult

Result of self-undistort estimation.

SvgTargetOptions

SVG target-generation options.

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.

CodebookProfile

Explicit embedded codebook profile selector.

DetectionFrame

Coordinate frame used by serialized detection outputs.

DetectionSource

Indicates which pipeline stage produced a DetectedMarker.

InnerFitReason

Stable reject/failure code for inner fit.

InnerFitStatus

Outcome category for robust inner ellipse fitting.

ProposalDownscale

Controls optional image downscaling before proposal generation.

TargetGenerationError

Target-generation failures.

Traits

PixelMapper

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

Functions

propose_with_heatmap_and_marker_diameter

Generate pass-1 proposals with heatmap using board geometry and a fixed marker diameter hint.

propose_with_heatmap_and_marker_scale

Generate pass-1 proposals with heatmap using board geometry and an explicit marker-scale prior.

propose_with_marker_diameter

Generate pass-1 center proposals using board geometry and a fixed marker diameter hint.

propose_with_marker_scale

Generate pass-1 center proposals using board geometry and an explicit marker-scale prior.