Crate projective_grid 

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:

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.

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	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

Re-exports

pub use affine::AffineTransform2D;

pub use global_step::estimate_global_cell_size;

pub use global_step::GlobalStepEstimate;

pub use global_step::GlobalStepParams;

pub use homography::estimate_homography;

pub use homography::estimate_homography_with_quality;

pub use homography::homography_from_4pt;

pub use homography::homography_from_4pt_with_quality;

pub use homography::Homography;

pub use homography::HomographyQuality;

pub use local_step::estimate_local_steps;

pub use local_step::LocalStep;

pub use local_step::LocalStepParams;

pub use local_step::LocalStepPointData;

pub use square::alignment::GridAlignment;

pub use square::alignment::GridTransform;

pub use square::alignment::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;

pub use square::smoothness::square_find_inconsistent_corners_step_aware;

pub use square::smoothness::square_predict_grid_position;

pub use square::regular::detect_regular_grid;

pub use square::regular::DetectedGridPoint;

pub use square::regular::RegularGridDetection;

pub use square::regular::RegularGridDetector;

pub use square::regular::RegularGridError;

pub use square::regular::RegularGridParams;

pub use square::regular::RegularGridStats;

pub use square::detect::detect_square_grid;

pub use square::detect::detect_square_grid_all;

pub use square::detect::ExtensionStrategy;

pub use square::detect::MultiComponentParams;

pub use square::detect::SquareGridDetection;

pub use square::detect::SquareGridParams;

pub use square::detect::SquareGridStats;

pub use topological::build_grid_topological;

pub use topological::detect_topological_grid;

pub use topological::recover_topological_grid;

pub use topological::AxisClusterCenters;

pub use topological::AxisEstimate;

pub use topological::TopologicalComponent;

pub use topological::TopologicalError;

pub use topological::TopologicalGrid;

pub use topological::TopologicalInputCorner;

pub use topological::TopologicalParams;

pub use topological::TopologicalStats;

pub use topological::TriangleClass;

pub use component_merge::merge_components_local;

pub use component_merge::ComponentInput;

pub use component_merge::ComponentMergeResult;

pub use component_merge::ComponentMergeStats;

pub use component_merge::LocalMergeParams;

Modules

affine

Generic 2D affine transform.

circular_stats

Circular-histogram + plateau-aware peak picking + double-angle 2-means helpers.

component_merge

Local-geometry-only component merge for square grids.

global_step

Automatic global cell-size estimation for a 2D corner cloud.

hex

Hexagonal grid support for pointy-top axial coordinates.

homography

Projective homography type and estimators.

local_step

Generic per-corner local grid-step estimation.

square

Square (4-connected) grid support.

topological

Topological grid construction (axis-driven variant of SBF09; see References below).

Traits

Float

Trait alias for floating-point types supported by this crate.