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
//! Clamping the solved tangents until every control hull is in the free space.
//!
//! The solver produces tangents that minimise curvature, with no knowledge of the geometry. This
//! module brings them back inside it, and the order of operations is forced by two facts:
//!
//! * Projection is on the **tangent**, never on an individual control point. `$T_i$` is one value
//! shared by two segments, so clamping a control point would break `$C^1$`; clamping the tangent
//! cannot, because both segments read the same number afterwards.
//! * The loop therefore runs over the whole spline, not per segment, and it **cannot fail**. The
//! zero tangents are always admissible — that is what "do nothing" means — and they make every
//! segment the straight chord between its knots, which is inside the free space because the taut
//! path is (L2). So the worst case is a piecewise-linear route, not a collision or an error.
use crateAdmissibleTangents;
use crateClearance;
use cratePoint2D;
/// Clamps `tangents` until every segment's control hull is in the free space.
///
/// Returns `true` if the result is a valid spline, `false` if it fell back to the taut polyline.
///
/// # Why damping is not enough on its own
///
/// The obvious repair is to damp the tangents towards zero and re-check. It does not converge: a
/// tangent whose control point pokes a *positive* amount into an obstacle shrinks that amount
/// geometrically but never to zero, so the hull stays obstructed however many iterations run, and
/// the route ends up fully flattened when only one knot was at fault.
///
/// So the repair is targeted. When a segment's hull is not clear, the tangents at *its* two ends are
/// zeroed — that makes the segment the straight chord, which is in the free space because the taut
/// path is (L2) — and the rest of the spline is re-checked. Straight runs between two such corners
/// keep their smoothing, which is the whole point of the solve.
///
/// The loop is bounded, and the bound does not affect correctness: zeroing every remaining tangent
/// is always valid, and is the documented outcome when the bound is reached.
/// Clamps every tangent into its knot's admissible set.