Navigation engine: windowed snapping to the route polyline (issue #31) #114

Merged

robert merged 1 commit from area/navigation-snapping into main 2026-09-05 17:47:21 +02:00

Conversation 0 Commits 1 Files changed 2 +447

robert commented 2026-09-05 17:45:28 +02:00

Owner

Copy link

Closes #31.

What this adds

RouteSnapper (companion/core/.../route/nav/RouteSnapper.kt), which locates a live GPS fix along an imported GpxRoute's polyline.

Reuse, not reimplementation

This reuses route.enrich.locateAlongPolyline (#26/PR #79) directly - no changes to that function. It is already a forward-only, bounded-horizon point-to-segment projection with a monotonically advancing search cursor, built for #63's tier-0 cue placement, and its own KDoc already documents the exact out-and-back/lollipop disambiguation problem this issue is about.

The one behavioural difference a live snapper needs versus a cue-matcher - reporting a genuinely large offset instead of discarding a bad match - comes for free by calling it with maxOffsetMeters = Double.MAX_VALUE. locateAlongPolyline only rejects a match past that threshold; a live snapper wants the opposite (the large offset is the useful signal for #32), so nothing in that function needed to change.

RouteSnapper supplies the two things a live-GPS caller has that a one-shot cue-import pass doesn't:

• A search cursor that persists fix-to-fix (searchCursorIndex), starting at the route's own start and advancing to wherever the previous fix matched.
• A search horizon that widens dynamically instead of being one fixed value:
  • NORMAL_SEARCH_HORIZON_METERS (150 m) at ordinary 1 Hz cadence.
  • Widens to elapsed seconds x MAX_PLAUSIBLE_SPEED_METERS_PER_SECOND (20 m/s) after a GPS gap longer than GAP_THRESHOLD_SECONDS (5 s).
  • Widens to a fixed OFF_ROUTE_REACQUISITION_HORIZON_METERS (500 m) when the previous fix's offset exceeded REACQUISITION_OFFSET_THRESHOLD_METERS (50 m) - this internal threshold is purely a window-sizing decision, not #32's off-route determination.

RouteSnap (the output type) carries segmentStartIndex, distanceAlongRouteMeters, and offsetMeters - the last one deliberately unfiltered and unclamped, so #32's off-route detection has a real number to run its own hysteresis against. Deciding "is the rider off-route" is explicitly out of scope here.

Monotonicity (per the issue's 2026-09-02 update)

D42 removed mid-ride re-routing from Phase 3, so there is no route swap this engine has to survive. Distance-along-route is non-decreasing across on-route fixes by construction: the search cursor never looks behind its own previous result. RouteSnapperTest asserts this directly over a sampled real GPX route, per the issue's "asserted in tests, not merely intended" wording.

Tests (./gradlew :companion:core:test, all passing, 287 tests total in the module)

• A real komoot export (real-komoot-havelchaussee-glienicker-bruecke.gpx), sampled every 20th point, confirming exact matches and non-decreasing distance-along-route.
• An out-and-back route that does not jump from the outbound leg to its geometrically coincident return leg (the outbound leg is deliberately much longer than the search horizon, so exclusion is by distance, not by tie-breaking luck), and correctly transitions onto the return leg once actually there.
• A genuinely off-route fix that reports a large offset instead of snapping onto a spatially closer segment that is far away in route order (two parallel "lanes" of a big loop, connected by a long filler stretch).
• Window widening after a GPS gap, and after an off-route excursion - each asserted with a tight distance tolerance so the test actually catches a regression back to the un-widened horizon, not just "some progress was made".

https://claude.ai/code/session_01DAoXbRmJUf2uxNYBfdAXPt

Closes #31. ## What this adds `RouteSnapper` (`companion/core/.../route/nav/RouteSnapper.kt`), which locates a live GPS fix along an imported `GpxRoute`'s polyline. ## Reuse, not reimplementation This reuses `route.enrich.locateAlongPolyline` (#26/PR #79) directly - no changes to that function. It is already a forward-only, bounded-horizon point-to-segment projection with a monotonically advancing search cursor, built for #63's tier-0 cue placement, and its own KDoc already documents the exact out-and-back/lollipop disambiguation problem this issue is about. The one behavioural difference a live snapper needs versus a cue-matcher - reporting a genuinely large offset instead of discarding a bad match - comes for free by calling it with `maxOffsetMeters = Double.MAX_VALUE`. `locateAlongPolyline` only rejects a match past that threshold; a live snapper wants the opposite (the large offset **is** the useful signal for #32), so nothing in that function needed to change. `RouteSnapper` supplies the two things a live-GPS caller has that a one-shot cue-import pass doesn't: - **A search cursor that persists fix-to-fix** (`searchCursorIndex`), starting at the route's own start and advancing to wherever the previous fix matched. - **A search horizon that widens dynamically** instead of being one fixed value: - `NORMAL_SEARCH_HORIZON_METERS` (150 m) at ordinary 1 Hz cadence. - Widens to `elapsed seconds x MAX_PLAUSIBLE_SPEED_METERS_PER_SECOND` (20 m/s) after a GPS gap longer than `GAP_THRESHOLD_SECONDS` (5 s). - Widens to a fixed `OFF_ROUTE_REACQUISITION_HORIZON_METERS` (500 m) when the previous fix's offset exceeded `REACQUISITION_OFFSET_THRESHOLD_METERS` (50 m) - this internal threshold is purely a window-sizing decision, **not** #32's off-route determination. `RouteSnap` (the output type) carries `segmentStartIndex`, `distanceAlongRouteMeters`, and `offsetMeters` - the last one deliberately unfiltered and unclamped, so #32's off-route detection has a real number to run its own hysteresis against. Deciding "is the rider off-route" is explicitly out of scope here. ## Monotonicity (per the issue's 2026-09-02 update) D42 removed mid-ride re-routing from Phase 3, so there is no route swap this engine has to survive. Distance-along-route is non-decreasing across on-route fixes *by construction*: the search cursor never looks behind its own previous result. `RouteSnapperTest` asserts this directly over a sampled real GPX route, per the issue's "asserted in tests, not merely intended" wording. ## Tests (`./gradlew :companion:core:test`, all passing, 287 tests total in the module) - A real komoot export (`real-komoot-havelchaussee-glienicker-bruecke.gpx`), sampled every 20th point, confirming exact matches and non-decreasing distance-along-route. - An out-and-back route that does **not** jump from the outbound leg to its geometrically coincident return leg (the outbound leg is deliberately much longer than the search horizon, so exclusion is by distance, not by tie-breaking luck), and correctly transitions onto the return leg once actually there. - A genuinely off-route fix that reports a large offset instead of snapping onto a spatially closer segment that is far away in route order (two parallel "lanes" of a big loop, connected by a long filler stretch). - Window widening after a GPS gap, and after an off-route excursion - each asserted with a tight distance tolerance so the test actually catches a regression back to the un-widened horizon, not just "some progress was made". https://claude.ai/code/session_01DAoXbRmJUf2uxNYBfdAXPt

robert added 1 commit 2026-09-05 17:45:28 +02:00

Navigation engine: windowed snapping to the route polyline (issue #31) ... 191131fd99

Adds RouteSnapper, which locates a live GPS fix along an imported
GpxRoute's polyline for turn-by-turn navigation.

Reuses route.enrich.locateAlongPolyline directly rather than
reimplementing point-to-segment projection - that function is already
a forward-only, bounded-horizon projection with a monotonically
advancing search cursor, built for #63's tier-0 cue placement but
documented as solving exactly this out-and-back/lollipop disambiguation
problem. The one behavioural difference a live snapper needs -
reporting a genuinely large offset instead of discarding the match -
comes for free by calling it with maxOffsetMeters = Double.MAX_VALUE;
no changes to that function were needed.

RouteSnapper adds the two things a live GPS caller needs on top:
a search cursor that persists fix-to-fix (searchCursorIndex), and a
search horizon that widens on GPS gaps (elapsed time x a generous
plausible-speed bound) or after an off-route excursion (a large fixed
re-acquisition window), rather than a single fixed horizon.

RouteSnap carries segmentStartIndex, distanceAlongRouteMeters and
offsetMeters - the last one deliberately unfiltered, so #32's
off-route detection has the real, honest offset to run its own
hysteresis against; that decision is explicitly out of scope here.

Tests (./gradlew :companion:core:test, all passing):
- a real komoot export, sampled and monotonicity-checked
- an out-and-back route that does not jump from the outbound leg to
  its geometrically coincident return leg, and correctly transitions
  onto the return leg once actually there
- a genuinely off-route fix reporting a large offset rather than
  snapping onto a spatially closer segment far away in route order
- window widening after a GPS gap and after an off-route excursion,
  each with a tight distance tolerance so the test actually catches a
  regression to the un-widened horizon

Claude-Session: https://claude.ai/code/session_01DAoXbRmJUf2uxNYBfdAXPt

robert merged commit ceb255b3da into main 2026-09-05 17:47:21 +02:00

robert referenced this pull request from a commit 2026-09-05 17:47:23 +02:00

Merge pull request 'Navigation engine: windowed snapping to the route polyline (issue #31)' (#114) from area/navigation-snapping into main

robert referenced this pull request 2026-09-05 17:47:38 +02:00

Navigation engine: windowed snapping to the route polyline #31

robert referenced this pull request from a commit 2026-09-05 22:39:11 +02:00

Test audit of #39: lollipop/self-crossing snapping, fix a real self-crossing bug

robert referenced this pull request 2026-09-05 22:39:37 +02:00

Test audit of #39: lollipop/self-crossing snapping, fix a real self-crossing bug #116

robert referenced this pull request 2026-09-05 22:40:01 +02:00

Unit tests: snapping on out-and-back routes, off-route hysteresis #39

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:companion

Android companion app

  

area:docs

Documentation

  

area:shared

Message contract shared by both sides

  

area:tooling

Build tooling, SDK, dev scripts

  

area:watchapp

Pebble C watchapp

  

blocker

Blocks a large part of the project until resolved

  

kind:chore

Setup, scaffolding, maintenance

  

kind:feature

New functionality

  

kind:spike

Time-boxed investigation to de-risk a decision

  

kind:test

Tests and fixtures

No labels

area:companion

area:docs

area:shared

area:tooling

area:watchapp

blocker

kind:chore

kind:feature

kind:spike

kind:test

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

robert/PedalPebble!114

No description provided.