chess_corners/

lib.rs

//! 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:
//!
//! ```no_run
//! use chess_corners::{ChessConfig, ChessParams, find_chess_corners_image};
//! use image::io::Reader as ImageReader;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // 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,
//!     );
//! }
//! # Ok(()) }
//! ```
//!
//! ## Raw grayscale buffer
//!
//! If you already have an 8-bit grayscale buffer, you can call the
//! detector directly without depending on `image`:
//!
//! ```no_run
//! use chess_corners::{ChessConfig, ChessParams, find_chess_corners_u8};
//!
//! # fn detect(img: &[u8], width: u32, height: u32) {
//! // 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());
//! # let _ = corners;
//! # }
//! ```
//!
//! ## ML refiner (feature `ml-refiner`)
//!
//! ```no_run
//! # #[cfg(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);
//! # let _ = corners;
//! # }
//! ```
//!
//! 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

#[cfg(feature = "ml-refiner")]
mod ml_refiner;
mod multiscale;

// Re-export a focused subset of core types for convenience. Consumers that
// need lower-level primitives (rings, raw response functions, etc.) are
// encouraged to depend on `chess-corners-core` directly.
pub use chess_corners_core::{
    CenterOfMassConfig, ChessParams, CornerDescriptor, CornerRefiner, ForstnerConfig, ImageView,
    RefineResult, RefineStatus, Refiner, RefinerKind, ResponseMap, SaddlePointConfig,
};

// High-level helpers on `image::GrayImage`.
#[cfg(feature = "image")]
pub mod image;
#[cfg(all(feature = "image", feature = "ml-refiner"))]
pub use image::find_chess_corners_image_with_ml;
#[cfg(feature = "image")]
pub use image::{find_chess_corners_image, find_chess_corners_image_with_refiner};

// Multiscale/coarse-to-fine API types.
pub use crate::multiscale::{
    find_chess_corners, find_chess_corners_buff, find_chess_corners_buff_with_refiner,
    find_chess_corners_with_refiner, CoarseToFineParams,
};
#[cfg(feature = "ml-refiner")]
pub use crate::multiscale::{find_chess_corners_buff_with_ml, find_chess_corners_with_ml};
pub use box_image_pyramid::{ImageBuffer, PyramidBuffers, PyramidParams};

/// Unified detector configuration combining response/detector params and
/// multiscale/pyramid tuning.
///
/// [`ChessConfig::default`] keeps the detector in the single-scale regime.
/// Use [`ChessConfig::multiscale`] for the recommended coarse-to-fine starting
/// point on high-resolution, small-board, or textured projected patterns.
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ChessConfig {
    /// Low-level ChESS response/detector parameters (ring radius, thresholds,
    /// NMS radius, minimum cluster size, and subpixel refinement backend).
    pub params: ChessParams,
    /// Coarse-to-fine multiscale configuration (pyramid shape, ROI radius,
    /// merge radius).
    pub multiscale: CoarseToFineParams,
}

impl ChessConfig {
    /// Recommended coarse-to-fine starting point.
    ///
    /// This uses the canonical r=5 ChESS ring together with:
    /// - 3 pyramid levels,
    /// - `min_size = 128`,
    /// - coarse ROI radius 3,
    /// - merge radius 3.0.
    pub fn multiscale() -> Self {
        let mut cfg = Self::default();
        cfg.multiscale.pyramid.num_levels = 3;
        cfg.multiscale.pyramid.min_size = 128;
        cfg
    }

    /// Convenience helper for single-scale detection.
    ///
    /// This is equivalent to [`ChessConfig::default`] but kept as an explicit
    /// readability helper at call sites.
    pub fn single_scale() -> Self {
        Self::default()
    }
}

/// Detect chessboard corners from a raw grayscale image buffer.
///
/// The `img` slice must be `width * height` bytes in row-major order.
///
/// # Panics
///
/// Panics if `img.len() != width * height`.
#[must_use]
pub fn find_chess_corners_u8(
    img: &[u8],
    width: u32,
    height: u32,
    cfg: &ChessConfig,
) -> Vec<CornerDescriptor> {
    let view = ImageView::from_u8_slice(width as usize, height as usize, img)
        .expect("image dimensions must match buffer length");
    multiscale::find_chess_corners(view, cfg)
}

/// Detect corners from a raw grayscale buffer with an explicit refiner choice.
#[must_use]
pub fn find_chess_corners_u8_with_refiner(
    img: &[u8],
    width: u32,
    height: u32,
    cfg: &ChessConfig,
    refiner: &RefinerKind,
) -> Vec<CornerDescriptor> {
    let view = ImageView::from_u8_slice(width as usize, height as usize, img)
        .expect("image dimensions must match buffer length");
    multiscale::find_chess_corners_with_refiner(view, cfg, refiner)
}

/// Detect corners from a raw grayscale buffer using the ML refiner pipeline.
#[must_use]
#[cfg(feature = "ml-refiner")]
pub fn find_chess_corners_u8_with_ml(
    img: &[u8],
    width: u32,
    height: u32,
    cfg: &ChessConfig,
) -> Vec<CornerDescriptor> {
    let view = ImageView::from_u8_slice(width as usize, height as usize, img)
        .expect("image dimensions must match buffer length");
    multiscale::find_chess_corners_with_ml(view, cfg)
}