calib_targets_puzzleboard/
lib.rs

1//! PuzzleBoard calibration target detector.
2//!
3//! The *PuzzleBoard* is a self-identifying chessboard target introduced by
4//! Stelldinger (2024, [arXiv:2409.20127](https://arxiv.org/abs/2409.20127)):
5//! a standard checkerboard with a small binary dot placed at the midpoint of
6//! every interior edge. The dot pattern is designed so that any locally
7//! observed fragment of the board (≥ 4 × 4 squares) uniquely identifies its
8//! absolute position on a master 501 × 501 pattern — giving every detected
9//! chessboard corner an absolute `(I, J)` label, with graceful degradation
10//! under occlusion, perspective distortion, and low pixel-per-edge ratios.
11//!
12//! Encoding is the superposition of two cyclic binary sub-perfect maps:
13//! - **A**: shape `(3, 167)` with window `(3, 3)₂` — one bit per horizontal edge
14//! - **B**: shape `(167, 3)` with window `(3, 3)₂` — one bit per vertical edge
15//!
16//! The maps are generated once (see `tools/generate_code_maps.rs`) and shipped
17//! as embedded bytes (`src/data/map_a.bin` / `map_b.bin`). All runtime lookups
18//! go through [`code_maps`].
19//!
20//! ## Quickstart
21//!
22//! ```no_run
23//! use calib_targets_puzzleboard::{
24//!     PuzzleBoardDetector, PuzzleBoardParams, PuzzleBoardSpec,
25//! };
26//!
27//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
28//! let spec = PuzzleBoardSpec::new(12, 12, 1.0)?;
29//! let params = PuzzleBoardParams::for_board(&spec);
30//! let detector = PuzzleBoardDetector::new(params)?;
31//! // Feed a real greyscale image and raw ChESS corners to `detector.detect(…)`.
32//! // See `examples/detect_puzzleboard.rs` for a working end-to-end example.
33//! # Ok(()) }
34//! ```
35#![deny(missing_docs)]
36
37pub mod code_maps;
38pub mod diagnostics;
39
40mod board;
41mod detector;
42mod io;
43mod params;
44
45pub use board::{PuzzleBoardSpec, PuzzleBoardSpecError, MASTER_COLS, MASTER_ROWS};
46pub use code_maps::{EDGE_MAP_A_COLS, EDGE_MAP_A_ROWS, EDGE_MAP_B_COLS, EDGE_MAP_B_ROWS};
47pub use detector::{
48    PuzzleBoardCorner, PuzzleBoardDecodeConfig, PuzzleBoardDecodeInfo, PuzzleBoardDetectError,
49    PuzzleBoardDetectionResult, PuzzleBoardDetector, PuzzleBoardScoringMode, PuzzleBoardSearchMode,
50};
51pub use diagnostics::{
52    PuzzleBoardDecodeDiagnostics, PuzzleBoardDiagnostics, PuzzleBoardObservedEdge,
53};
54pub use io::{PuzzleBoardDetectConfig, PuzzleBoardDetectReport, PuzzleBoardIoError};
55pub use params::PuzzleBoardParams;
56
57pub use calib_targets_core::{GridAlignment, GridTransform, GRID_TRANSFORMS_D4};
calib_targets_puzzleboard/lib.rs

calib_targets_puzzleboard/
lib.rs
