projective-grid 0.9.0

Generic 2D projective grid graph construction, traversal, and homography tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

//! Generic 2D projective grid construction and homography tools.
//!
//! This crate turns a cloud of 2D points into a labelled grid.
//!
//! # Start here: [`detect_regular_grid`]
//!
//! [`detect_regular_grid`] is the zero-config onboarding entry point.
//! Hand it a `&[Point2<f32>]`; it returns a [`RegularGridDetection`]
//! with every recovered corner carrying its `(i, j)` label and the
//! index back into your input slice — **no caller-written validator
//! scaffolding required**:
//!
//! ```rust
//! use nalgebra::Point2;
//! use projective_grid::detect_regular_grid;
//!
//! let mut points = Vec::new();
//! for j in 0..4 {
//!     for i in 0..5 {
//!         points.push(Point2::new(i as f32 * 30.0, j as f32 * 30.0));
//!     }
//! }
//! let grid = detect_regular_grid(&points).expect("clean grid detects");
//! assert_eq!(grid.points.len(), 20);
//! ```
//!
//! For tuning, use [`RegularGridDetector`] + [`RegularGridParams`].
//! The detector internally estimates the cell size and grid axes from
//! the point cloud and drives the pipeline with a built-in open
//! regular-grid policy.
//!
//! # Advanced / specialized entry points
//!
//! When you need pattern-specific rules (parity, marker slots, colour
//! splits), reach for the validator-driven path:
//!
//! - [`detect_square_grid`] — square-lattice recovery driven by a
//!   caller-supplied [`SeedQuadValidator`] + [`GrowValidator`] pair.
//!   This is what the chessboard / ChArUco / puzzleboard detectors
//!   build on. [`detect_regular_grid`] is a thin wrapper over it with
//!   a built-in permissive policy.
//! - [`detect_topological_grid`] — Shu/Brunton/Fiala 2009 topological
//!   recovery, image-free. Requires per-corner grid axes inline on
//!   the input via [`TopologicalInputCorner`].
//!
//! [`SeedQuadValidator`]: square::seed::finder::SeedQuadValidator
//! [`GrowValidator`]: square::grow::GrowValidator
//!
//! All entry points share a common output shape: a `(i, j) →
//! corner_idx` map plus per-stage diagnostics. Use
//! [`merge_components_local`] to attempt to merge multiple
//! disjoint components into a single grid.
//!
//! The crate is pattern-agnostic — it knows nothing about chessboards,
//! ArUco markers, or images. Lower-level primitives (KD-tree,
//! circular stats, mean-shift, DLT homography, BFS grow, Delaunay
//! triangulation) are exposed under their natural modules for callers
//! who want to compose their own pipeline.
//!
//! # Module layout
//!
//! | Module | Responsibility |
//! |---|---|
//! | [`square::regular`] | Zero-config point-cloud regular-grid detection (onboarding entry point) |
//! | `square::cleanup` | Generic output cleanup (private; used internally) |
//! | [`square::grow`] | Seed-and-grow BFS over a square lattice |
//! | [`square::extension`] | Boundary extension via globally-fit or local homography |
//! | [`square::seed`] | 2×2 seed primitives (cell size, midpoint violation) |
//! | [`square::validate`](mod@square::validate) | Post-grow line / local-H residual checks |
//! | [`square::mesh`] / [`square::rectify`] | Per-cell mesh / global homography rectification |
//! | [`square::smoothness`] | Midpoint prediction + step-aware outlier detection |
//! | [`square::alignment`] | D4 transforms on integer grid coordinates |
//! | [`hex`] | Hex grid: alignment, mesh, rectify, smoothness (no grow path yet) |
//! | [`circular_stats`] | Undirected-angle helpers (smoothing, plateau peak picking, double-angle 2-means) |
//! | [`global_step`] / [`local_step`] | Cell-size estimation primitives |
//! | [`homography`] | 4-point + DLT homography with reprojection-quality diagnostics |
#![deny(missing_docs)]

mod float_helpers;

pub mod affine;
pub mod circular_stats;
pub mod component_merge;
pub mod global_step;
pub mod hex;
pub mod homography;
pub mod local_step;
pub mod square;
pub mod topological;

/// Trait alias for floating-point types supported by this crate.
///
/// Both `f32` and `f64` satisfy this bound. All public generic types default
/// to `f32` for backward compatibility.
pub trait Float: nalgebra::RealField + Copy {}
impl<T: nalgebra::RealField + Copy> Float for T {}

// --- Generic building blocks (no square / hex assumption) --------------------
pub use affine::AffineTransform2D;
pub use global_step::{estimate_global_cell_size, GlobalStepEstimate, GlobalStepParams};
pub use homography::{
    estimate_homography, estimate_homography_with_quality, homography_from_4pt,
    homography_from_4pt_with_quality, Homography, HomographyQuality,
};
pub use local_step::{estimate_local_steps, LocalStep, LocalStepParams, LocalStepPointData};

// --- Square-grid surface re-exported at the crate root --------
pub use square::alignment::{GridAlignment, GridTransform, GRID_TRANSFORMS_D4};
pub use square::index::GridCoords;
pub use square::mesh::SquareGridHomographyMesh;
pub use square::rectify::SquareGridHomography;
pub use square::smoothness::{
    square_find_inconsistent_corners, square_find_inconsistent_corners_step_aware,
    square_predict_grid_position,
};

// --- Square-grid onboarding entry point ----------------------
pub use square::regular::{
    detect_regular_grid, DetectedGridPoint, RegularGridDetection, RegularGridDetector,
    RegularGridError, RegularGridParams, RegularGridStats,
};

// --- Square-grid validator-driven (advanced) entry points ----
pub use square::detect::{
    detect_square_grid, detect_square_grid_all, ExtensionStrategy, MultiComponentParams,
    SquareGridDetection, SquareGridParams, SquareGridStats,
};

// --- Topological-grid surface --------------------------------
pub use topological::{
    build_grid_topological, detect_topological_grid, recover_topological_grid, AxisClusterCenters,
    AxisEstimate, TopologicalComponent, TopologicalError, TopologicalGrid, TopologicalInputCorner,
    TopologicalParams, TopologicalStats, TriangleClass,
};

// --- Component merge (shared by both pipelines) --------------
pub use component_merge::{
    merge_components_local, ComponentInput, ComponentMergeResult, ComponentMergeStats,
    LocalMergeParams,
};