projective_grid/
lib.rs

1//! Generic 2D projective grid graph construction, traversal, and homography tools.
2//!
3//! This crate provides reusable algorithms for building 4- or 6-connected grid
4//! graphs from detected 2D points, assigning grid coordinates via BFS traversal,
5//! and computing projective mappings (homographies) for grid rectification.
6//!
7//! It is pattern-agnostic: the [`NeighborValidator`] trait lets callers plug in
8//! pattern-specific logic (chessboard orientation checks, marker constraints,
9//! etc.) while the graph construction, traversal, and geometry remain generic.
10//!
11//! # Module layout
12//!
13//! | Module | Responsibility |
14//! |---|---|
15//! | [`square`] | Square (4-connected) grid: direction, alignment, index, mesh, rectify, smoothness, validators |
16//! | [`hex`] | Hex (6-connected) grid: mirrored submodules for axial `(q, r)` coordinates |
17//! | [`graph`] | Generic KD-tree-based graph builder + [`NeighborValidator`] trait |
18//! | [`graph_cleanup`] | Graph-level cleanup passes (symmetry, straightness, crossing pruning) |
19//! | [`global_step`] / [`local_step`] | Cell-size / local-step estimation on point clouds |
20//! | [`traverse`] | BFS / DFS on grid graphs (connected components, `(i, j)` assignment) |
21//! | [`homography`] | Projective geometry (4-point homography, DLT) |
22//!
23//! Top-level types from [`square`] are re-exported here at the crate root so
24//! existing consumers (e.g., `projective_grid::GridIndex`) continue to work
25//! unchanged.
26
27mod float_helpers;
28
29pub mod circular_stats;
30pub mod global_step;
31pub mod graph;
32pub mod graph_cleanup;
33pub mod hex;
34pub mod homography;
35pub mod local_step;
36pub mod square;
37pub mod traverse;
38
39/// Re-export of the square-grid submodule at the legacy `validators` path.
40///
41/// Kept for back-compat with doc-comment examples that wrote
42/// `projective_grid::validators::XJunctionValidator`.
43pub mod validators {
44    pub use crate::square::validators::{SpatialSquareValidator, XJunctionValidator};
45}
46
47/// Trait alias for floating-point types supported by this crate.
48///
49/// Both `f32` and `f64` satisfy this bound. All public generic types default
50/// to `f32` for backward compatibility.
51pub trait Float: nalgebra::RealField + Copy {}
52impl<T: nalgebra::RealField + Copy> Float for T {}
53
54// --- Generic building blocks (no square / hex assumption) --------------------
55pub use global_step::{estimate_global_cell_size, GlobalStepEstimate, GlobalStepParams};
56pub use graph::{GridGraph, GridGraphParams, NeighborCandidate, NeighborValidator};
57pub use graph_cleanup::{
58    enforce_symmetry, prune_by_edge_straightness, prune_crossing_edges, prune_isolated_pairs,
59    segments_properly_cross,
60};
61pub use homography::{estimate_homography, homography_from_4pt, Homography};
62pub use local_step::{estimate_local_steps, LocalStep, LocalStepParams, LocalStepPointData};
63pub use traverse::{assign_grid_coordinates, connected_components};
64
65// --- Square-grid surface re-exported at the crate root (back-compat) --------
66pub use square::alignment::{GridAlignment, GridTransform, GRID_TRANSFORMS_D4};
67pub use square::direction::{NeighborDirection, NodeNeighbor};
68pub use square::index::GridIndex;
69pub use square::mesh::GridHomographyMesh;
70pub use square::rectify::GridHomography;
71pub use square::smoothness::{
72    find_inconsistent_corners, find_inconsistent_corners_step_aware, predict_grid_position,
73};
74pub use square::validators::{SpatialSquareValidator, XJunctionValidator};
75
76// `SpatialHexValidator` stays namespaced under `hex::validators` and
77// `hex::SpatialHexValidator` — it's hex-specific and does not need a
78// crate-root re-export.
projective_grid/lib.rs

projective_grid/
lib.rs
