Struct Detector 

pub struct Detector { /* private fields */ }

High-level chessboard-corner detector.

Owns the pyramid and detector-specific scratch buffers so the caller can reuse them across successive frames.

Implementations

impl Detector

pub fn new(cfg: DetectorConfig) -> Result<Self, ChessError>

Build a detector with the given config.

Errors

Returns ChessError::Upscale when the DetectorConfig::upscale configuration is invalid.

pub fn with_default() -> Self

Build a detector with the default config.

pub fn config(&self) -> &DetectorConfig

Borrow the active config.

pub fn set_config(&mut self, cfg: DetectorConfig) -> Result<(), ChessError>

Replace the active config.

Errors

Returns ChessError::Upscale when the new config’s upscale section is invalid.

pub fn detect_u8( &mut self, img: &[u8], width: u32, height: u32, ) -> Result<Vec<CornerDescriptor>, ChessError>

Detect chessboard corners from a raw 8-bit grayscale buffer.

Errors

Returns ChessError::DimensionMismatch if img.len() != width * height. Returns ChessError::Upscale if the upscale configuration becomes invalid (this should not normally happen — Detector::new / Detector::set_config validate up-front).

pub fn detect( &mut self, img: &GrayImage, ) -> Result<Vec<CornerDescriptor>, ChessError>

Detect chessboard corners from an [image::GrayImage].

Errors

Returns ChessError::Upscale if the upscale configuration becomes invalid.

pub fn detect_u8_roi( &mut self, img: &[u8], width: u32, height: u32, roi: Roi, ) -> Result<Vec<CornerDescriptor>, ChessError>

Detect chessboard corners inside a rectangular region roi of a raw 8-bit grayscale image.

Returns the corners whose detected peak lies inside roi, each refined and described exactly as Detector::detect_u8 would: the same configured refiner and the same orientation/descriptor stage. Coordinates are in the full input-image pixel frame. Both detection strategies (ChESS and Radon) are supported.

Single-scale only

ROI detection is single-scale local detection by definition: the multiscale and upscale sections of the active config do not apply on this path. For whole-image detection — including the coarse-to-fine pyramid and the pre-pipeline upscaling stage — use Detector::detect_u8 / Detector::detect.

ROI clamping

A roi extending past the image is clamped to the image bounds (matching the multiscale ROI-carving behaviour). A fully out-of-range or degenerate post-clamp roi returns Ok(vec![]), not an error.

Parity with detect_u8

Parity is defined against a single-scale, non-upscaled Detector::detect_u8 run — multiscale set to SingleScale and upscale disabled, as in the DetectorConfig::chess and DetectorConfig::radon presets. When a pyramid or upscale section is active, detect_u8 detects on resampled images that this path never builds, so its output is not comparable corner-for-corner.

Against that run, every ChESS corner whose peak lies more than ring_radius + nms_radius pixels inside the clamped roi (on every side) is returned here with a bit-identical response and a position that agrees to within floating-point rounding (well under 1e-3 px). The integer peak detection is exact; only the sub-pixel refinement rounds differently, because it runs in the ROI-local coordinate frame — the same numerical relationship a coarse-to-fine multiscale run has to a full-frame single-scale run. The Radon strategy recomputes its response over the carved patch (prefix-sum accumulation restarts at the patch origin), so its parity is approximate: interior corners reappear, but response values and subpixel positions carry a small floating-point drift rather than being bit-exact. Corners nearer the ROI edge — or nearer than the detector support to the image border — may differ or be absent under either strategy.

Errors

Returns ChessError::DimensionMismatch if img.len() != width * height. With the ml-refiner feature, returns ChessError::RoiRefinerUnsupported when the configuration selects the ML refiner: the ML refiner runs a whole-frame model pipeline this path does not carry, and the refiner selection is never silently downgraded — use Detector::detect_u8 for ML refinement.

pub fn detect_roi( &mut self, img: &GrayImage, roi: Roi, ) -> Result<Vec<CornerDescriptor>, ChessError>

Detect chessboard corners inside a rectangular region roi of an [image::GrayImage].

See Detector::detect_u8_roi for the ROI contract, the single-scale caveat, the clamping behaviour, and the parity guarantee.

Errors

Same as Detector::detect_u8_roi.

pub fn diagnostics(&self) -> DetectorDiagnostics<'_>

Borrow a detector-bound diagnostics accessor.

The returned DetectorDiagnostics exposes intermediate detector outputs — the dense ChESS response map and the Radon heatmap — sourced from this detector’s already-configured DetectorConfig, so a caller holding a configured Detector need not re-supply a config to obtain diagnostic data.

This is the detector-bound half of the diagnostics channel; the free functions in crate::diagnostics serve stateless callers. Both share the same opt-in, looser-stability contract: diagnostic outputs are advisory and may change as the detector internals evolve, independently of the Detector::detect result contract.