Crate chess_corners

Expand description

Ergonomic ChESS detector facade over chess-corners-core.

§Overview

This crate is the high-level entry point for the ChESS (Chess-board Extraction by Subtraction and Summation) corner detector. It re-exports the main configuration/result types from chess_corners_core and adds:

single-scale detection on raw grayscale buffers via find_chess_corners,
optional image::GrayImage helpers (see find_chess_corners_image) when the image feature is enabled,
a coarse-to-fine multiscale detector configured through ChessConfig and CoarseToFineParams.

The detector returns subpixel CornerDescriptor values in full-resolution image coordinates. In most applications you construct a ChessConfig, optionally tweak its fields, and call find_chess_corners or find_chess_corners_image.

§Quick start

§Using `image` (default)

The default feature set includes integration with the image crate:

use chess_corners::{ChessConfig, ChessParams, find_chess_corners_image};
use image::io::Reader as ImageReader;

// Load a grayscale chessboard image.
let img = ImageReader::open("board.png")?
    .decode()?
    .to_luma8();

// Start from the recommended coarse-to-fine preset.
let mut cfg = ChessConfig::multiscale();
cfg.params = ChessParams::default();

let corners = find_chess_corners_image(&img, &cfg);
println!("found {} corners", corners.len());

for c in &corners {
    println!(
        "corner at ({:.2}, {:.2}), response {:.1}, theta {:.2} rad",
        c.x, c.y, c.response, c.orientation,
    );
}

§Raw grayscale buffer

If you already have an 8-bit grayscale buffer, you can call the detector directly without depending on image:

use chess_corners::{ChessConfig, ChessParams, find_chess_corners_u8};

// Single-scale convenience configuration.
let mut cfg = ChessConfig::single_scale();
cfg.params = ChessParams::default();

let corners = find_chess_corners_u8(img, width, height, &cfg);
println!("found {} corners", corners.len());

§ML refiner (feature `ml-refiner`)

use chess_corners::{ChessConfig, ChessParams, find_chess_corners_image_with_ml};
use image::GrayImage;

let img = GrayImage::new(1, 1);
let mut cfg = ChessConfig::single_scale();
cfg.params = ChessParams::default();

let corners = find_chess_corners_image_with_ml(&img, &cfg);

The ML refiner runs a small ONNX model on normalized intensity patches (uint8 / 255.0) centered at each candidate. The model predicts [dx, dy, conf_logit], but the confidence output is currently ignored; the offsets are applied directly. Current benchmarks are synthetic; real-world accuracy still needs validation. It is also slower (about 23.5 ms vs 0.6 ms for 77 corners on testimages/mid.png).

§Python bindings

The workspace includes a PyO3-based Python extension crate at crates/chess-corners-py. It exposes chess_corners.find_chess_corners, which accepts a 2D uint8 NumPy array and returns a float32 (N, 4) array with columns [x, y, response, orientation]. See crates/chess-corners-py/README.md for usage and configuration details.

For tight processing loops you can also reuse pyramid storage explicitly via find_chess_corners_buff and the internal pyramid module; this avoids reallocating intermediate pyramid levels across frames. Most users should stick to find_chess_corners / find_chess_corners_image unless they need fine-grained control over allocations.

§Configuration

ChessConfig combines the low-level ChESS parameters with multiscale tuning:

ChessParams (re-exported from chess-corners-core) controls the response kernel and detector behavior: ring radius, relative or absolute threshold, non-maximum suppression radius, and the minimum cluster size for accepting a corner.
CoarseToFineParams describes how the multiscale detector behaves: number of pyramid levels, minimum level size, coarse ROI radius (at the smallest level) and merge radius for deduplicating refined corners.
RefinerKind (via ChessParams::refiner) selects the classic subpixel refinement backend (center-of-mass default, Förstner, saddle-point) and exposes per-refiner tuning knobs.
ML refinement is exposed via explicit find_chess_corners_*_with_ml entry points when the ml-refiner feature is enabled.

ChessConfig::default and the shortcut ChessConfig::single_scale both configure a single-scale run. ChessConfig::multiscale returns the recommended coarse-to-fine starting point with a 3-level pyramid. Any pyramid.num_levels > 1 triggers the coarse-to-fine path: corners are first detected on the smallest pyramid level and then refined inside base-image regions of interest.

If you need raw response maps or more control, depend directly on chess-corners-core and use its chess_corners_core::response and chess_corners_core::detect modules alongside the re-exported ResponseMap and CornerDescriptor types.

§Features

image (default) – enables find_chess_corners_image and image::GrayImage integration.
rayon – parallelizes response computation and multiscale refinement over image rows. Combine with par_pyramid to parallelize pyramid downsampling as well.
ml-refiner – enables the ML-backed refiner entry points via the chess-corners-ml crate and embedded ONNX model.
simd – enables portable-SIMD accelerated inner loops for the response kernel (requires a nightly compiler). Combine with par_pyramid to SIMD-accelerate pyramid downsampling.
par_pyramid – opt-in gate for SIMD/rayon acceleration inside the pyramid builder.
tracing – emits structured spans for multiscale detection, suitable for use with tracing-subscriber or JSON tracing from the CLI.
cli – builds the chess-corners binary shipped with this crate; it is not required when using the library as a dependency.

The library API is stable across feature combinations; features only affect performance and observability, not numerical results.

The ChESS idea was proposed in the papaer Bennett, Lasenby, ChESS: A Fast and Accurate Chessboard Corner Detector, CVIU 2014

Re-exports§

pub use image::find_chess_corners_image_with_ml;
pub use image::find_chess_corners_image;
pub use image::find_chess_corners_image_with_refiner;

Modules§

image: Optional image::GrayImage helpers for the unified corner detector.

Structs§

CenterOfMassConfig: Legacy center-of-mass refinement on the response map.
ChessConfig: Unified detector configuration combining response/detector params and multiscale/pyramid tuning.
ChessParams: Tunable parameters for the ChESS response computation and corner detection.
CoarseToFineParams: Parameters controlling the coarse-to-fine multiscale detector.
CornerDescriptor: Describes a detected chessboard corner in full-resolution image coordinates.
ForstnerConfig: Förstner-style gradient-based refiner.
ImageBuffer: Owned grayscale image buffer (u8).
ImageView: Minimal grayscale view for refinement without taking a dependency on image.
PyramidBuffers: Reusable backing storage for pyramid construction.
PyramidParams: Parameters controlling pyramid generation.
RefineResult: Result of refining a single corner candidate.
ResponseMap: Dense response map in row-major layout.
SaddlePointConfig: Quadratic saddle-point surface refiner.

Enums§

RefineStatus: Status of a refinement attempt.
Refiner: Runtime refiner with reusable scratch buffers.
RefinerKind: User-facing enum selecting a refinement backend.

Traits§

CornerRefiner: Trait implemented by pluggable refinement backends.

Functions§

find_chess_corners: Detect corners from a base-level grayscale view, allocating pyramid storage internally.
find_chess_corners_buff: Detect corners using a caller-provided pyramid buffer.
find_chess_corners_buff_with_ml: Variant of find_chess_corners_buff that uses the ML refiner pipeline.
find_chess_corners_buff_with_refiner: Variant of find_chess_corners_buff that accepts an explicit refiner selection.
find_chess_corners_u8: Detect chessboard corners from a raw grayscale image buffer.
find_chess_corners_u8_with_ml: Detect corners from a raw grayscale buffer using the ML refiner pipeline.
find_chess_corners_u8_with_refiner: Detect corners from a raw grayscale buffer with an explicit refiner choice.
find_chess_corners_with_ml: Single-call helper that runs the ML refiner pipeline.
find_chess_corners_with_refiner: Single-call helper that lets callers pick the refiner.