chess-corners 0.3.2

High-level chessboard / ChESS corner detection API
Documentation

chess-corners

Ergonomic ChESS (Chess-board Extraction by Subtraction and Summation) detector on top of chess-corners-core.

This crate:

  • Re-exports the main types from chess-corners-core (ChessParams, CornerDescriptor, ResponseMap).
  • Provides a unified ChessConfig for single-scale and multiscale detection.
  • Exposes PyramidParams for tuning pyramid construction via CoarseToFineParams.
  • Adds optional image::GrayImage integration and a small CLI binary for batch runs.
  • Exposes pluggable subpixel refiners (RefinerKind via ChessParams::refiner) so you can choose between center-of-mass (default), Förstner, or saddle-point refinement.

Examples

By default the image feature is enabled so you can work directly with GrayImage:

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let img = ImageReader::open("board.png")?
        .decode()?
        .to_luma8();

    let mut cfg = ChessConfig::single_scale();
    cfg.params = ChessParams::default();

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

Selecting a refiner

The default refiner matches the legacy center-of-mass behavior. To opt into the Förstner or saddle-point refiners on image intensities:

use chess_corners::{ChessConfig, ChessParams, RefinerKind, find_chess_corners_image};

let mut cfg = ChessConfig::single_scale();
cfg.params = ChessParams::default();

let refiner = RefinerKind::Forstner(Default::default());
cfg.params.refiner = refiner;
let corners = find_chess_corners_image(&img, &cfg);

You can also override the refiner per call without mutating your config via find_chess_corners_image_with_refiner.

ML refiner (feature ml-refiner)

Enable the ML-backed refiner (feature ml-refiner) to run the exported ONNX model in Rust:

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

let mut cfg = ChessConfig::single_scale();
cfg.params = ChessParams::default();

let img = GrayImage::new(1, 1);
let corners = find_chess_corners_image_with_ml(&img, &cfg);

The ML refiner runs an ONNX model on normalized patches (uint8 / 255.0) centered on each candidate and predicts [dx, dy, conf_logit]. The current version ignores conf_logit and applies the offsets directly, using the embedded model defaults (patch size and batch size are fixed to match the model). Current evaluation is synthetic; real-world performance still needs validation. It is also slower (about 23.5 ms vs 0.6 ms for 77 corners on testimages/mid.png).

You can also try the bundled examples on sample images in testimages/:

  • Single-scale: cargo run -p chess-corners --example single_scale_image -- testimages/mid.png
  • Multiscale: cargo run -p chess-corners --example multiscale_image -- testimages/large.png

Both examples require the image feature, which is enabled by default. If you build with --no-default-features, re-enable it when running examples: --features image.

Feature flags:

  • image (default) – enable find_chess_corners_image for image::GrayImage.
  • rayon – parallelize response computation and multiscale refinement.
  • ml-refiner – enable ML entry points and ONNX inference via chess-corners-ml.
  • simd – enable portable-SIMD acceleration in the core response kernel (nightly only).
  • par_pyramid – opt into SIMD/rayon in the pyramid builder.
  • tracing – emit structured spans from multiscale detection and the CLI when enabled.

The full guide-style documentation and API docs are published at:

Python bindings are available in this workspace under crates/chess-corners-py and are published as the chess_corners package on PyPI.