DetectConfig

DetectConfig is the top-level configuration struct for the ringgrid detection pipeline. It aggregates all sub-configurations – from proposal generation and edge sampling through homography RANSAC and self-undistort – into a single value that drives every stage of detection.

Construction

DetectConfig is designed to be built from a TargetLayout (target geometry) and an optional scale prior. Three recommended constructors cover the common cases:

#![allow(unused)]
fn main() {
use ringgrid::{TargetLayout, DetectConfig, MarkerScalePrior};
use std::path::Path;

let target = TargetLayout::from_json_file(Path::new("target_spec.json")).unwrap();

// 1. Default scale prior (14--66 px diameter range)
let cfg = DetectConfig::from_target(target.clone());

// 2. Explicit scale range
let scale = MarkerScalePrior::new(24.0, 48.0);
let cfg = DetectConfig::from_target_and_scale_prior(target.clone(), scale);

// 3. Fixed marker diameter hint (min == max)
let cfg = DetectConfig::from_target_and_marker_diameter(target.clone(), 32.0);
}

All three constructors call two internal derivation functions:

• apply_target_geometry_priors – derives marker_spec.r_inner_expected and decode.code_band_ratio from the target’s inner/outer radius ratio (accounting for the ring stroke on coded targets; plain annuli expose the radii directly).
• apply_marker_scale_prior – derives proposal radii, edge sampling range, ellipse validation bounds, and completion ROI from the scale prior. See MarkerScalePrior for the full derivation rules.

The Detector wrapper

Most users interact with DetectConfig through the Detector struct, which wraps a config and exposes detection methods:

#![allow(unused)]
fn main() {
use ringgrid::{TargetLayout, Detector, MarkerScalePrior};
use std::path::Path;

let target = TargetLayout::from_json_file(Path::new("target_spec.json")).unwrap();

// Convenience constructors mirror DetectConfig
let det = Detector::new(target.clone());                           // default scale
let det = Detector::with_marker_scale(target.clone(),
              MarkerScalePrior::new(24.0, 48.0));                  // explicit range
let det = Detector::with_marker_diameter_hint(target.clone(), 32.0); // fixed size

// One-step from JSON file
let det = Detector::from_target_json_file(Path::new("target_spec.json")).unwrap();

// Full config control
let cfg = DetectConfig::from_target(target);
let det = Detector::with_config(cfg);

// Detect (0.8: detect* return Result<_, DetectError>)
let result = det.detect(&image).unwrap();

// Adaptive multi-scale APIs (wide size variation scenes)
let result = det.detect_adaptive(&image).unwrap();
let result = det.detect_adaptive_with_hint(&image, Some(32.0)).unwrap();
}

Stable vs advanced fields

DetectConfig keeps only the durable user choices at the top level:

• target — target geometry (TargetLayout)
• marker_scale — expected marker diameter range
• circle_refinement — post-fit center-correction method
• self_undistort — division-model self-undistort policy
• advanced — an AdvancedDetectConfig holding every per-stage tuning knob

All stage tuning (proposal, edge sampling, fitting, decode, completion, homography RANSAC, ID correction, global-filter toggles, …) lives under the nested advanced field. The config dump/overlay JSON nests these under an "advanced" object.

Post-construction tuning

After building a Detector, use config_mut() to override individual fields. Top-level fields are set directly; per-stage knobs go through advanced:

#![allow(unused)]
fn main() {
let mut det = Detector::new(target);
det.config_mut().self_undistort.enable = true;
det.config_mut().advanced.completion.enable = false;
det.config_mut().advanced.use_global_filter = false;
}

Calling set_marker_scale_prior() or set_marker_diameter_hint_px() on DetectConfig re-derives all scale-coupled parameters automatically.

Field reference

The Field column shows the access path from a DetectConfig value. Per-stage knobs are reached through the advanced sub-config.

Fields marked “auto-derived” are overwritten by the constructors. If you modify marker_scale after construction, call set_marker_scale_prior() to re-derive them.

Source

crates/ringgrid/src/detector/config/, crates/ringgrid/src/api.rs