chess_corners/config/refiner.rs
1use chess_corners_core::SaddlePointConfig;
2use serde::{Deserialize, Serialize};
3
4/// The optional image-refinement stage
5/// ([`DetectorConfig::refiner`](crate::DetectorConfig::refiner)).
6///
7/// Each detector first places its corners with its own subpixel localizer on
8/// its response map: ChESS with the center of mass
9/// ([`ChessConfig::center_of_mass`](crate::ChessConfig::center_of_mass)),
10/// Radon with the peak fit ([`RadonConfig::peak_fit`](crate::RadonConfig::peak_fit)).
11/// An image refiner reads only the input image around each corner, so every
12/// variant works with both detectors. Where it starts and what happens when
13/// it cannot refine a corner follow the detector:
14///
15/// - **ChESS**: the refiner replaces the center of mass. It starts from the
16/// integer response peak, and a corner it rejects is dropped.
17/// - **Radon**: the refiner runs on top of the peak fit. It starts from the
18/// peak-fit position, and a corner it does not refine to convergence keeps
19/// its peak-fit position. No corner is dropped.
20///
21/// Under [`Uncertainty::Propagated`](crate::Uncertainty::Propagated) a
22/// corner's position covariance comes from whichever localizer produced its
23/// final position.
24#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
25#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
26#[serde(rename_all = "snake_case")]
27#[non_exhaustive]
28pub enum ImageRefiner {
29 /// Quadratic surface fit to the image patch at the saddle point,
30 /// re-centred until it converges. Usually more accurate than the
31 /// detector's own localizer, most of all under lens blur and board
32 /// rotation; on cells of about 4 px its fit window spans the
33 /// neighbouring corners. Reports a position covariance on the corners it
34 /// refines to convergence.
35 SaddlePoint(SaddlePointConfig),
36}
37
38impl ImageRefiner {
39 /// Saddle-point refinement with default tuning.
40 pub fn saddle_point() -> Self {
41 Self::SaddlePoint(SaddlePointConfig::default())
42 }
43}