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::{Detector, TargetLayout};
use std::path::Path;

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

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

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

Targets can also be built in code (no files needed):

use ringgrid::{Detector, TargetLayout};

let target = TargetLayout::default_hex();
let detector = Detector::new(target);

// An empty image yields a valid result with no detections.
let image = image::GrayImage::new(64, 48);
let result = detector.detect(&image).unwrap();
assert!(result.detected_markers.is_empty());

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.

Modules

codebook

Inspection helpers for the embedded 16-sector codebook profiles.

diagnostics

Opt-in diagnostics channel returned by Detector::detect_with_diagnostics: per-marker fit and decode metrics, homography RANSAC statistics, and pipeline stage timings.

Structs

AdvancedDetectConfig

Advanced per-stage tuning parameters for the detection pipeline.

CameraIntrinsics

Pinhole camera intrinsics.

CameraModel

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

CodedRingSpec

Parameters of the 16-sector coded ring style.

CompletionConfig

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

DecodeConfig

Configuration for sector decoding.

DetectConfig

Top-level detection configuration.

DetectedMarker

A detected marker: refined geometry plus the decoded ID.

DetectionResult

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.

HexGeometry

Hex-lattice geometry: axial rows alternating between long and short rows.

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.

MarkerSpecConfig

Marker spec in outer-normalized radius units.

OriginFiducials

Filled circular dots that define the target’s origin and orientation.

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.

ProjectiveCenterConfig

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

Proposal

A proposed ellipse center with its vote score.

ProposalConfig

Configuration for ellipse center detection via gradient-based radial symmetry voting.

ProposalResult

Proposals together with the vote heatmap for visualization or custom processing.

RadialTangentialDistortion

Brown-Conrady radial-tangential distortion coefficients.

RansacConfig

Configuration for RANSAC fitting (ellipse and homography).

RectGeometry

Rectangular (square-lattice) geometry: rows × cols cells at uniform pitch.

RingGeometry

Ring radii shared by every marker on the target, in millimeters.

ScaleTier

One scale band for multi-scale adaptive detection.

ScaleTiers

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

SeedProposalConfig

Seed-injection controls for proposal generation.

SelfUndistortConfig

Configuration for self-undistort estimation.

SelfUndistortResult

Result of self-undistort estimation.

SvgTargetOptions

SVG target-generation options.

TargetCell

One marker cell of a target: lattice coordinate, board position, and (for coded targets) the assigned codebook ID.

TargetLayout

Compositional target layout: lattice × ring geometry × coding × fiducials.

UndistortConfig

Distortion inversion settings used by iterative undistortion.

Enums

AngularAggregator

Aggregation method across theta samples.

BoardFrame

Reference frame of grid-labeled outputs (grid_coord, board_xy_mm, and the homography’s source plane).

CircleRefinementMethod

Center-correction strategy used after local fits are accepted.

CodebookProfile

Explicit embedded codebook profile selector.

DetectError

Detection-time failures reported by Detector methods.

DetectionFrame

Coordinate frame used by serialized detection outputs.

GradPolarity

Expected polarity of the radial intensity derivative dI/dr at an edge.

LatticeGeometry

Lattice arrangement of marker cells.

MarkerCoding

Marker coding style: how (and whether) markers encode their identity.

ProposalDownscale

Controls optional image downscaling before proposal generation.

TargetGenerationError

Target-generation failures.

TargetLoadError

Load-time failures for target layout JSON.

TargetValidationError

Validation failures for a target layout specification.

Traits

PixelMapper

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

Functions

find_ellipse_centers

Detect candidate ellipse centers via radial symmetry voting.

find_ellipse_centers_with_heatmap

Detect candidate ellipse centers and return the vote heatmap.

propose_with_heatmap_and_marker_scale

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

propose_with_marker_scale

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