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
use crateDistMode;
use crateAlign3;
use crateGAPParams;
use crategenerate_alignment_points;
use crate::;
/// Perform an iterative alignment of one mesh to another. Each iteration is a full
/// Levenberg-Marquardt optimization of the alignment of a set of specific points sampled from the
/// moving mesh, with the set of points being updated each iteration based on where the previous
/// alignment ended.
///
/// The alignment points are chosen using the `sample_alignment_candidates` method of the `Mesh`
/// struct, which performs an extremely selective sampling of points on the surface of the moving
/// mesh at areas of low curvature, away from corners and edges, and with projections onto the
/// reference mesh that have the same restrictive properties. Lastly, points with a distance more
/// than 3 standard deviations from the mean deviation from the reference mesh are pruned from the
/// sample set.
///
/// This results in a set of alignment points that are selectively distributed in areas of the
/// moving mesh that are most likely to match closely to the reference mesh as the two move, in an
/// attempt to pre-select away areas which are most likely to not overlap between the two meshes.
///
/// With each iteration, the two meshes should become more and more aligned, and the alignment
/// candidates will better reflect the areas of overlap between the two meshes. As this process
/// continues, the average residual distance between the moving mesh and the reference mesh will
/// converge and then slightly increase as more and more points are included in the comparison.
/// This plateau/climb in average residual is the condition used to terminate the iterations.
///
/// # Arguments
///
/// * `moving`: the mesh which will be moved into alignment
/// * `reference`: the mesh which is stationary
/// * `sample_spacing`: a Poisson disk sampling spacing used to pick the initial candidates for the
/// alignment points. The spacing will then be used to derive a set of physical limits for the
/// quality of the alignment candidates. See the `sample_alignment_candidates` method of the
/// `Mesh` struct for more details.
/// * `initial`: an initial guess for the alignment transform
/// * `mode`: the distance mode to use for the alignment. This can be either `DistMode::ToPoint` or
/// `DistMode::ToPlane`. The two are identical except for cases where an alignment point drifts
/// off the edge of the closest triangle on the reference mesh.
/// * `max_iter`: if the alignment does not converge after this many iterations, the function will
/// return an error. This is to prevent infinite loops in case the alignment never converges.
///
/// returns: Result<Alignment<Unit<Quaternion<f64>>, 3>, Box<dyn Error, Global>>