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
//! This module contains the tools for aligning 2D geometry using the Levenberg-Marquardt
//! algorithm.
//!
//! # Structure
//!
//! A single-body alignment has three pieces:
//!
//! - [`AlignParams2`] holds the parameters being optimized (`tx`, `ty`, `rz`) and expresses them
//! as a transformation about an arbitrary local origin, with an optional working offset. This
//! is what gives the caller control over the center of rotation, the directions the translation
//! parameters act along, and which degrees of freedom ([`Dof3`]) are free to move at all.
//! - [`SurfaceTarget2`] is the stationary entity being aligned to. It is implemented for
//! `Curve2`, `Boundary2`, `CurveGroup2`, and (as [`CloudTarget2`]) unordered measured points,
//! and reports an [`AlignSurfMatch2`] for any query point: the closest position, its normal,
//! whether the projection actually landed on the target's interior, and optionally the
//! target's own measurement uncertainty there.
//! - [`points_to_surface2`] runs the solver, with behavior controlled by [`AlignOptions2`].
//!
//! Beyond the single-body path:
//!
//! - [`multi_curve_adjustment`] simultaneously aligns several [`crate::geom2::CurveGroup2`]
//! bodies to each other in one combined solve, holding one static, with [`MultiParams2`]
//! carrying the concatenated per-body parameters and [`MultiOptions2`] controlling the
//! solve.
//! - [`AlignInfo2`] asks how well a set of points constrains an alignment, exposes its
//! weak directions, and chooses D-optimal correspondence subsets for pruning.
//!
//! # Reporting
//!
//! The solver returns an [`crate::geom2::AlignOutcome2`], which carries the alignment plus a
//! record of how every solve that contributed to it terminated. An `Err` is reserved for the case
//! where there is no answer at all: rejected arguments, or an initial solve that broke down.
//!
//! Everything short of that is reported rather than raised, because there is still a real
//! alignment to return. In particular, a solve that exhausts its evaluation budget leaves behind
//! the best parameters it found, which is a usable result whose convergence simply was not proven
//! (see [`crate::common::SolveQuality`]). That is a routine outcome here rather than a failure:
//! the correspondences are re-established every time the parameters change, so the objective is
//! only piecewise smooth, and near the solution a point close to a corner can flip between two
//! matches indefinitely without the convergence criteria ever being met. Similarly, a refinement
//! round that breaks down is rolled back to the previous round's result and the reason recorded on
//! the outcome, since refinement is an improvement on an alignment that was already usable.
//!
//! # Robustness
//!
//! The alignment is robust by default. An initial unweighted solve is followed by several rounds
//! of iteratively reweighted least-squares using MAGSAC++ noise-marginalized weights, with the
//! weights held fixed inside each solve so the analytic jacobian stays consistent with the
//! residual it differentiates. The noise bound can be supplied explicitly or estimated from the
//! data via the median absolute deviation.
//!
//! On the single-body path, measurement uncertainty on either the test points or the target
//! combines in quadrature and normalizes the residuals into units of sigma. The multi-curve
//! path carries no uncertainty at all, because nothing in 2D produces it: its residuals stay in
//! the units of the geometry, and so does its noise bound.
//!
//! # Relationship to `align3`
//!
//! The solver cores of this module and the 3D machinery in [`crate::geom3::align3`] are
//! deliberately structural mirrors rather than a shared generic: 2D needs only a single rotation
//! angle, whose partial derivative is a plain 90-degree turn with none of the Euler-angle gimbal
//! correction that 3D requires, and its parameter storage is half the size. The parts with no
//! dimension-specific content at all, the multi-body parameter bookkeeping, the information
//! analysis, and the static-body selection, are shared generics in [`crate::common::align`],
//! with thin per-dimension wrappers here.
//!
//! Neither module is the authority. This one was written first and the 3D module was brought
//! into line with it, but the multi-body work happened in 3D and came back the other way. A
//! change to either should be considered for the other, and the file layout is kept parallel so
//! that comparison is easy to make.
use Vector3;
/// The storage for the three parameters of a 2D alignment problem, in the order tx, ty, rz.
pub type AlignStorage2 = ;
pub use CloudTarget2;
pub use *;
pub use *;
pub use ;
pub use MultiParams2;
pub use *;
pub use *;
pub use points_to_surface2;
pub use *;
/// A struct that handles constraints on degrees of freedom in R^2 space. Each dimension is
/// represented by a bool which specifies if the degree of freedom is _active_.