Crate chess_corners_core

Expand description

Core primitives for ChESS/Radon response computation, subpixel refinement, and corner descriptors.

The crate exposes a deliberate low-level contract through its crate root: response computation (chess_response_u8, chess_response_u8_patch, radon_response_u8), corner detection (find_corners_u8, detect_corners_from_response) and its individual stages — threshold + NMS via detect_peaks_from_response_with_refine_radius and image-domain refinement via refine_corners_on_image — the ChessParams configuration consumed by those stages together with its RefinerKind refiner selector, pluggable subpixel refinement (the CornerRefiner trait and built-in refiners), the two-axis orientation fit (fit_axes_at_point, describe_corners), and the ImageView borrowed-buffer type. The detector pipeline composes three orthogonal stages — detection, refinement, and orientation fit — all reachable from the crate root.

Most users should work through the chess-corners facade crate rather than depending on chess-corners-core directly. Depend on this crate only when you need raw response maps, custom refiners, or the Radon detector primitives.

§Features

std (default) – compatibility feature reserved for future use. The current detector implementation requires the Rust standard library.
rayon – parallelizes the dense response computation and Radon accumulation over image rows using the rayon crate. Does not change numerical results.
simd – enables a SIMD‑accelerated inner loop for the ChESS response kernel, based on portable_simd. Requires a nightly compiler; the scalar path remains the reference implementation.
tracing – emits structured spans around response and detector functions using the tracing ecosystem, useful for profiling and diagnostics.

Feature combinations:

no features / std only – single‑threaded scalar implementation.
rayon – same scalar math, but rows are processed in parallel.
simd – single‑threaded, but the inner ring computation is vectorized.
rayon + simd – rows are processed in parallel and each row uses the SIMD‑accelerated inner loop.

The detector is independent of rayon/simd, and tracing only adds observability; none of these features change the numerical results, only performance and instrumentation.

§Minimum supported Rust version

The default (stable) build requires Rust 1.88 or newer, as declared by rust-version in Cargo.toml. The optional simd feature uses portable_simd and therefore requires a nightly toolchain; every other feature builds on stable.

The ChESS idea is proposed in Bennett, Lasenby, ChESS: A Fast and Accurate Chessboard Corner Detector, CVIU 2014.

Structs§

AxisEstimate: Direction of one local grid axis with its 1σ angular uncertainty.
AxisFitResult: Result of a two-axis orientation fit at a single corner.
CenterOfMassConfig: Configuration for the CenterOfMassRefiner.
CenterOfMassRefiner: Center-of-mass subpixel refiner.
ChessBuffers: Reusable scratch for ChessDetector. Wraps an owned ResponseMap; the ChESS response kernel currently allocates its output, and this struct keeps the latest map alive so the trait’s Response<'a> = &'a ResponseMap can borrow it across the two stages.
ChessDetector: Zero-sized DenseDetector implementor for the ChESS kernel.
ChessParams: Low-level ChESS detection parameters consumed by the response and detection stages. The chess-corners facade lowers its DetectorConfig onto this type; depend on it directly when driving the response and detection stages without going through the facade. Tunable parameters for the ChESS response computation and corner detection.
Corner: A detected corner candidate (subpixel position with raw response strength).
CornerDescriptor: Describes a detected chessboard corner in full-resolution image coordinates.
ForstnerConfig: Configuration for the ForstnerRefiner.
ForstnerRefiner: Förstner structure-tensor subpixel refiner.
ImageView: Minimal grayscale view for refinement without taking a dependency on image.
RadonBuffers: Reusable scratch for the whole-image Radon detector. Holds the upsampled image buffer, the four summed-area tables, the response map, and the box-blur scratch. All buffers grow on demand and are reused across frames — same pattern as PyramidBuffers.
RadonDetector: Zero-sized DenseDetector implementor for the whole-image Duda-Frese Radon kernel.
RadonDetectorParams: Configuration for the whole-image Radon detector.
RadonResponseView: Borrow of the dense working-resolution response map. Cheaply convertible to a ResponseMap via Self::to_response_map when ownership is required (e.g. for the classic detect_corners_from_response).
RefineContext: Inputs shared by refinement methods.
RefineResult: Result of refining a single corner candidate.
ResponseMap: Dense response map in row-major layout.
Roi: Rectangular region of interest with half-open coordinate semantics [x0, x1) × [y0, y1).
SaddlePointConfig: Configuration for the SaddlePointRefiner.
SaddlePointRefiner: Saddle-point quadratic-surface subpixel refiner.

Enums§

OrientationMethod: Method used to fit the two grid axes at a detected corner.
PeakFitMode: Subpixel peak-fitting mode.
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 the built-in subpixel refinement backends.
DenseDetector: Two-stage dense corner detector contract.

Functions§

chess_response_u8: Compute the dense ChESS response for an 8-bit grayscale image.
chess_response_u8_patch: Compute the ChESS response only inside a rectangular ROI of the image.
describe_corners: Convert raw corner candidates into full descriptors by sampling the source image and running the chosen OrientationMethod at each corner.
detect_corners_from_response: Core detector: run NMS + refinement on an existing response map.
detect_corners_from_response_with_refiner: Detector variant that accepts a user-provided refiner implementation.
detect_peaks_from_radon: Stage 1 of Radon detection: threshold + NMS + cluster-filter + 3-point Gaussian peak-fit on the response map.
detect_peaks_from_response_with_refine_radius: Stage 1 of ChESS detection: threshold + NMS + cluster-filter on the response map.
find_corners_u8: Compute corners starting from an 8-bit grayscale image.
fit_axes_at_point: Sample the 16-point ChESS ring at (cx, cy) with radius and run the chosen orientation method.
merge_corners_simple: Merge corners within a given radius, keeping the strongest response.
radon_response_u8: Compute the dense Radon response into buffers.response and return a read-only RadonResponseView at working resolution (i.e. input_dim × image_upsample).
refine_corners_on_image: Stage 2 of detection: image-domain subpixel refinement.