Struct Detector 

pub struct Detector { /* private fields */ }

Primary detection interface.

Encapsulates board layout and detection configuration. Create once, detect on many images. Board ownership is single-source: it is stored inside DetectConfig.

Examples

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

let board = BoardLayout::from_json_file(Path::new("target.json")).unwrap();
let detector = Detector::new(board);
let image = GrayImage::new(640, 480);
let result = detector.detect(&image);
println!("Found {} markers", result.detected_markers.len());

Implementations

impl Detector

pub fn new(board: BoardLayout) -> Self

Create a detector with a board layout and default marker-scale search prior.

pub fn with_marker_scale( board: BoardLayout, marker_scale: MarkerScalePrior, ) -> Self

Create a detector with an explicit marker-scale prior.

pub fn with_marker_diameter_hint( board: BoardLayout, marker_diameter_px: f32, ) -> Self

Create a detector with a fixed marker-diameter hint.

pub fn from_target_json_file(path: &Path) -> Result<Self, BoardLayoutLoadError>

Load target JSON and create a detector in one step using default marker-scale search prior.

pub fn from_target_json_file_with_scale( path: &Path, marker_scale: MarkerScalePrior, ) -> Result<Self, BoardLayoutLoadError>

Load target JSON and create a detector with explicit marker-scale prior.

pub fn from_target_json_file_with_marker_diameter( path: &Path, marker_diameter_px: f32, ) -> Result<Self, BoardLayoutLoadError>

Load target JSON and create a detector with fixed marker-diameter hint.

pub fn with_config(config: DetectConfig) -> Self

Create with full config control.

pub fn config(&self) -> &DetectConfig

Access the current configuration.

pub fn config_mut(&mut self) -> &mut DetectConfig

Mutable access to configuration for post-construction tuning.

pub fn detect(&self, image: &GrayImage) -> DetectionResult

Detect markers in a grayscale image.

When config.self_undistort.enable is false, runs single-pass detection in image coordinates.

When config.self_undistort.enable is true, runs baseline detection, estimates a self-undistort model, and optionally runs a second seeded pass with the estimated mapper.

pub fn propose(&self, image: &GrayImage) -> Vec<Proposal>

Generate pass-1 center proposals in image coordinates.

This exposes the detector-backed proposal seeds used by single-pass detection after spacing-aware post-NMS suppression.

pub fn propose_with_heatmap(&self, image: &GrayImage) -> ProposalResult

Generate pass-1 proposals with the vote heatmap in image coordinates.

The returned heatmap is the post-Gaussian-smoothed vote map used for thresholding and non-maximum suppression in the proposal stage. When proposal downscaling is enabled, the heatmap is resampled back into the original image frame together with the returned proposals.

pub fn detect_adaptive(&self, image: &GrayImage) -> DetectionResult

Detect markers with robust adaptive scale selection.

Adaptive mode evaluates several scale candidates and returns the highest-scoring result. Candidates include:

• probe-selected multi-scale tiers,
• fixed two-tier / four-tier multi-scale presets,
• curated single-pass scale priors.

Candidate ranking is deterministic and prioritizes:

1. mapped markers,
2. homography availability / inlier support,
3. decoded markers,
4. geometric quality tie-breakers.

No manual scale configuration is required. Use detect_adaptive_with_hint when an approximate marker diameter is known.

pub fn adaptive_tiers( &self, image: &GrayImage, nominal_diameter_px: Option<f32>, ) -> ScaleTiers

Return the scale tiers that adaptive detection would use for this image.

This helper is useful for debugging and reproducibility:

• inspect auto-selected tiers before running detection
• persist exact tiers and replay with detect_multiscale

When nominal_diameter_px is Some, returns a hint-centered two-tier bracket. When None, returns probe-selected tiers (or ScaleTiers::four_tier_wide fallback if probing fails).

pub fn detect_adaptive_with_hint( &self, image: &GrayImage, nominal_diameter_px: Option<f32>, ) -> DetectionResult

Adaptive detection with an optional nominal-diameter hint.

When nominal_diameter_px is Some, the hint-centered two-tier bracket is included as the primary candidate while robust fallback candidates remain enabled. When None, behaves identically to detect_adaptive.

pub fn detect_multiscale( &self, image: &GrayImage, tiers: &ScaleTiers, ) -> DetectionResult

Detect markers using an explicit set of scale tiers.

Runs one detection pass per tier (fit/decode + projective centers + ID correction), merges results with size-consistency-aware dedup, then runs global filter, completion, and final H refit once on the merged pool.

Use ScaleTiers constructors to build the tier set:

• ScaleTiers::four_tier_wide — 8–220 px
• ScaleTiers::two_tier_standard — 14–100 px
• ScaleTiers::single — single-pass, no merge overhead

pub fn detect_with_mapper( &self, image: &GrayImage, mapper: &dyn PixelMapper, ) -> DetectionResult

Detect with a custom pixel mapper (two-pass pipeline).

Pass-1 runs without mapper for seed generation, pass-2 runs with mapper. Marker centers in the returned result are always image-space. Mapper-frame centers are exposed via DetectedMarker.center_mapped.

This method always uses the provided mapper and does not run self-undistort estimation from config.self_undistort.