docs(navigator): list how the route planner checks vehicle segments

The fence checks of the route planner treat a segment from the vehicle
in three ways: with the contingency margin, against the fence itself
when the vehicle is already inside the margin, and not at all when the
vehicle is outside the fence and has to recover.

The class comment said so in one paragraph. It now lists the three
cases, and says that the altitude and Home limits never block a
segment.

Assisted-by: Claude:claude-fable-5-2
Signed-off-by: jonas <jonspero@me.com>
This commit is contained in:
jonas committed 2026-11-20 11:06:10 +01:00
1 parent 922b046757
commit 640b73d670
1 file changed
+14 -9
+14 -9
View File
@@ -41,17 +41,22 @@ namespace mission_route
{
/**
* Checks route segments against the loaded Navigator geofence.
* Checks route segments against the polygons and circles of the loaded Navigator geofence.
*
* A segment that starts at the vehicle is checked by where the vehicle is:
* - Inside the fence and further from it than GF_CONT_H_MARGIN: the segment keeps the margin, like a mission leg.
* - Inside the fence but closer to it than the margin: the segment is checked against the fence itself, over its
* whole length. Example: the Return that GF_CONT_ACTION starts there may fly back through the margin, but not
* across the fence.
* - Outside the fence (outside an inclusion area or inside an exclusion area): the segment is not checked, so
* that the vehicle can fly back in. This is the recovery. It applies to every checkPath() segment.
* A segment that starts at a safe point always keeps the margin, also while the vehicle recovers.
*
* The altitude and Home limits are not checked on segments, and a vehicle that only breaches these is not in
* recovery. Mission legs passed them in the mission check and the limits are convex, so points on the legs are
* inside them: plan only on a checked mission. Safe points are checked against every limit.
*
* Calls must not overlap because they reuse the same scratch buffer; Navigator calls it from a single task.
* Segments are checked against the polygons and circles and keep GF_CONT_H_MARGIN from them, like the legs of a
* mission. Mission legs passed the altitude and Home limits in the mission check, and these limits are convex, so
* points on the legs are not checked again: plan only on a checked mission. Safe points are checked against every
* limit.
* When the vehicle breaches a polygon or circle, segments from the vehicle, including every
* checkPath() segment, are not checked so it can recover. Safe point segments still are.
* A vehicle closer to a polygon or circle than the margin cannot keep it: its segments are checked against the
* fence itself over their whole length, for every polygon and circle.
* Planning must still wait for the fence to finish loading.
*/
class GeofencePathChecker final : public PathChecker