Navigation engine: windowed snapping to the route polyline

## Goal Locate the rider along the route cheaply and without jumping. ## Acceptance criteria - [ ] Position snapped to the nearest point on the polyline - [ ] Search restricted to a window around the last match, not the whole route - [ ] **Out-and-back and lollipop routes do not jump to the return leg** - covered by tests - [ ] Window widens on re-acquisition after an off-route excursion or a GPS gap - [ ] Distance along route maintained monotonically while on route - [ ] Cost stays negligible at 1 Hz on a long route ## Files - `companion/.../route/nav/RouteSnapper.kt` ## Update — 2026-09-01: monotonicity and re-routing interact - [ ] The monotonic distance-along-route invariant is stated as a property the code enforces, and is **asserted in tests** (#39), not merely intended - [ ] Behaviour on a **spliced route** defined: a re-route (#57) produces a **new route object with its own monotonic distance axis**, swapped in once at the moment the detour is accepted — rather than mutating the route this engine is mid-way through reading See D30. The rejoin point is the part everyone thinks of; the splice is the part that breaks invariants. ## Update — 2026-09-02: monotonicity is now free D42 removes mid-ride re-routing from Phase 3, so **the route object never changes during a ride**. Distance-along-route is therefore monotonic by construction rather than by rule. - [ ] Drop the splice-related wording: there is no route swap to survive in Phase 3 - [ ] The windowed snapping requirement is unchanged, and still must not jump to the return leg of an out-and-back The Phase 5 re-routing issue reintroduces a route swap, and carries the monotonic-axis requirement itself.

robert commented

2026-08-31 17:14:47 +02:00

(Migrated from git.butzei.de)

Goal

Locate the rider along the route cheaply and without jumping.

Acceptance criteria

Position snapped to the nearest point on the polyline
Search restricted to a window around the last match, not the whole route
Out-and-back and lollipop routes do not jump to the return leg - covered by tests
Window widens on re-acquisition after an off-route excursion or a GPS gap
Distance along route maintained monotonically while on route
Cost stays negligible at 1 Hz on a long route

Files

companion/.../route/nav/RouteSnapper.kt

Update — 2026-09-01: monotonicity and re-routing interact

The monotonic distance-along-route invariant is stated as a property the code enforces, and is
asserted in tests (#39), not merely intended
Behaviour on a spliced route defined: a re-route (#57) produces a new route object with
its own monotonic distance axis, swapped in once at the moment the detour is accepted —
rather than mutating the route this engine is mid-way through reading

See D30. The rejoin point is the part everyone thinks of; the splice is the part that breaks
invariants.

Update — 2026-09-02: monotonicity is now free

D42 removes mid-ride re-routing from Phase 3, so the route object never changes during a ride.
Distance-along-route is therefore monotonic by construction rather than by rule.

Drop the splice-related wording: there is no route swap to survive in Phase 3
The windowed snapping requirement is unchanged, and still must not jump to the return leg of an
out-and-back

The Phase 5 re-routing issue reintroduces a route swap, and carries the monotonic-axis requirement
itself.

Rows
Columns

Navigation engine: windowed snapping to the route polyline #31

Goal

Acceptance criteria

Files

Update — 2026-09-01: monotonicity and re-routing interact

Update — 2026-09-02: monotonicity is now free