Crate calib_targets_chessboard

Expand description

Invariant-first chessboard detector.

Takes a slice of ChESS X-junction corners and returns an integer-labelled chessboard grid. The crate’s only output contract is: every labelled corner has been proven to sit at a real grid intersection. Missing corners are acceptable; wrong corners are not.

High detection rate on our private regression set with zero wrong (i, j) labels (non-negligible lens distortion and motion blur).

Algorithm reference: see book/src/chessboard.md.

§Pipeline

The detector builds its (i, j) labelling with the topological grid finder in projective_grid (a Delaunay triangulation + an axis-driven cell test), then runs a chessboard-specific recovery + precision pass over the labelled components:

Stage	Name	Responsibility
1	`prefilter`	Drop corners failing strength / fit-quality / axes-validity gates.
2	`cluster_axes`	Recover the two global grid-direction centres `{Θ₀, Θ₁}` via histogram + 2-means; label each corner as canonical or swapped.
3	`topological_grid`	Delaunay + axis-driven cell test → merged labelled `(i, j)` components (`projective_grid::expert::square::assemble_oriented2_components`).
4	`recover_components`	Per-component recall boosters (interior gap fill + line extrapolation with a directional edge scale) + shared component merge.
5	`final_geometry_check`	Mandatory precision gate: line collinearity + local-H residual + direct wrong-label check + largest cardinal component. Can only drop corners; never adds.
6	`output`	Labelled grid → canonicalised, non-negative-rebased `ChessboardDetection`.

Each stage is its own module or function; see the submodules.

§Quickstart

use calib_targets_chessboard::{ChessCorner, ChessboardDetector, ChessboardParams};
use calib_targets_core::AxisEstimate;
use nalgebra::Point2;

// A synthetic 7×7 chessboard corner cloud at 20 px pitch. Adjacent
// corners carry opposite axis-slot orderings (the parity invariant).
let mut corners: Vec<ChessCorner> = Vec::new();
for j in 0..7 {
    for i in 0..7 {
        let swapped = (i + j) % 2 == 1;
        let (a0, a1) = if swapped {
            (std::f32::consts::FRAC_PI_2, 0.0)
        } else {
            (0.0, std::f32::consts::FRAC_PI_2)
        };
        corners.push(ChessCorner::new(
            Point2::new(i as f32 * 20.0 + 50.0, j as f32 * 20.0 + 50.0),
            [
                AxisEstimate { angle: a0, sigma: 0.01 },
                AxisEstimate { angle: a1, sigma: 0.01 },
            ],
            // Above the default `min_corner_strength` floor (33.0).
            100.0,
        ));
    }
}

let det = ChessboardDetector::new(ChessboardParams::default()).expect("default params are valid");
let detection = det.detect(&corners).expect("clean 7×7 grid detects");
assert_eq!(detection.corners.len(), 49);

§Rectification helpers

Two rectifiers are exposed: rectify_from_chessboard_result (RectifiedBoardView) and rectify_mesh_from_grid (RectifiedMeshView). The former takes a ChessboardDetection directly; the latter is pattern-agnostic and takes a &[LabeledCorner] plus an inlier index list. Both produce a rectified view and can be used with any consistent (i, j) labelling.

Structs§

ChessCorner: Canonical 2D corner consumed by the chessboard detector.
ChessboardAdvancedTuning: Advanced, unstable per-stage tuning knobs for the chessboard detector.
ChessboardCorner: A single labelled chessboard corner.
ChessboardDetection: Result of chessboard detection: the labelled corner set.
ChessboardDetector: Top-level detector.
ChessboardFeatureTrace: Exact chessboard admission and clustering state for one input corner.
ChessboardLabelTrace: One exact label at a chessboard-specific diagnostics checkpoint.
ChessboardParams: Top-level detector configuration.
ChessboardStageTrace: Net chessboard-specific changes after generic projective-grid detection.
ChessboardTopologicalTrace: Exact generic trace and the chessboard-specific continuation from one run.
DetectorConfig: High-level detection configuration.
GrayImageView: Borrowed view over an 8-bit grayscale image.
RectifiedBoardView: A rectified, fronto-parallel view of a detected chessboard.
RectifiedMeshView: A fronto-parallel mesh rectification of a labelled chessboard grid.

Enums§

ChessboardClusterTrace: Axis-cluster outcome for one ChESS corner at the input checkpoint.
ChessboardParamsError: A ChessboardParams configuration the chessboard detector cannot honour.
MeshWarpError: Reason rectify_mesh_from_grid could not build a RectifiedMeshView.
RectifyError: Error returned by rectify_from_chessboard_result.

Functions§

default_chess_config: Reasonable default settings for the chess-corners ChESS detector.
detect_corners: Run the ChESS corner front-end over image and adapt the result into ChessCorners.
rectify_from_chessboard_result: Rectify a chessboard from a ChessboardDetection.
rectify_mesh_from_grid: Build a rectified “board view” by piecewise homographies per grid cell. This is robust to lens distortion because it does not assume a single global H.
trace_topological: Run the same topological input adaptation as detect_all_topological (the crate-internal production orchestrator), but return a compact topological trace instead of detections.
trace_topological_detection: Run one exact generic-grid trace and continue that same result through the chessboard recovery and final geometry gate.