robert/PedalPebble
Watch
1
0
Fork
You've already forked PedalPebble
 0
Code Issues 43 Pull requests Projects Releases 1 Packages Wiki Activity Actions

Navigation engine: windowed snapping to the route polyline #31

New issue
Closed
opened 2026-08-31 17:14:47 +02:00 by robert · 1 comment
robert commented 2026-08-31 17:14:47 +02:00 (Migrated from git.butzei.de)
Copy link

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.

## 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-09-05 17:47:38 +02:00
Owner
Copy link

Closed by PR #114 (area/navigation-snapping).

New RouteSnapper/RouteSnap in companion/core/.../route/nav/RouteSnapper.kt, reusing RouteGeodesy.locateAlongPolyline (#26) directly rather than reimplementing point-to-segment projection — the only change needed was calling it with maxOffsetMeters = Double.MAX_VALUE, since a live snapper wants the honest (possibly large) offset reported, not discarded the way tier-0 cue matching wants it discarded.

Windowing: forward-only search cursor persisting across snap() calls, 150 m normal horizon (NFR-B2's ~1 Hz fix rate at plausible speed), widening to elapsedSeconds x 20 m/s after a >5 s GPS gap, and to a flat 500 m after the previous fix was >50 m off-route (a re-acquisition case, not #32's own off-route determination — that threshold is purely internal to this class's own window sizing).

Output type RouteSnap(segmentStartIndex, distanceAlongRouteMeters, offsetMeters) carries offsetMeters unfiltered specifically for #32's future hysteresis logic to consume.

Real test coverage (6 tests, ./gradlew :companion:core:test, genuinely re-run not cached): a real ~119km komoot GPX fixture confirming monotonic distance-along-route across a long real polyline; an out-and-back route proving the forward-only cursor doesn't jump to the geometric twin ~3000m away on the return leg; a genuinely off-route case (two geometrically-close "lanes" far apart in route order) proving a large honest offset is reported instead of a wrong nearest-order match; and two widening-specific tests (GPS gap, off-route excursion) with tight distance tolerances that would catch a regression to the normal 150m horizon.

This unblocks #39 and #40.

Closed by PR #114 (`area/navigation-snapping`). New `RouteSnapper`/`RouteSnap` in `companion/core/.../route/nav/RouteSnapper.kt`, reusing `RouteGeodesy.locateAlongPolyline` (#26) directly rather than reimplementing point-to-segment projection — the only change needed was calling it with `maxOffsetMeters = Double.MAX_VALUE`, since a live snapper wants the honest (possibly large) offset reported, not discarded the way tier-0 cue matching wants it discarded. Windowing: forward-only search cursor persisting across `snap()` calls, 150 m normal horizon (NFR-B2's ~1 Hz fix rate at plausible speed), widening to `elapsedSeconds x 20 m/s` after a >5 s GPS gap, and to a flat 500 m after the previous fix was >50 m off-route (a re-acquisition case, not #32's own off-route determination — that threshold is purely internal to this class's own window sizing). Output type `RouteSnap(segmentStartIndex, distanceAlongRouteMeters, offsetMeters)` carries `offsetMeters` unfiltered specifically for #32's future hysteresis logic to consume. Real test coverage (6 tests, `./gradlew :companion:core:test`, genuinely re-run not cached): a real ~119km komoot GPX fixture confirming monotonic distance-along-route across a long real polyline; an out-and-back route proving the forward-only cursor doesn't jump to the geometric twin ~3000m away on the return leg; a genuinely off-route case (two geometrically-close "lanes" far apart in route order) proving a large honest offset is reported instead of a wrong nearest-order match; and two widening-specific tests (GPS gap, off-route excursion) with tight distance tolerances that would catch a regression to the normal 150m horizon. This unblocks #39 and #40.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
area/gpx-cue-enricher-d59
area/round-display-support
area/rejoin-point-selection
area/digit-height-content-aware
area/geometry-enricher
area/page-template-hero1-grid6
area/nav-engine
area/cue-sheet-review
area/map-viewport-geometry
area/navigation-snapping-test-audit
area/lap-function
area/navigation-snapping
area/ble-power-meter
area/gpx-export
area/gpx-recording
area/pkjs-speed-feed
tooling/watchapp-distribution
area/csc-cadence
area/about-screen
area/backlight-policy
tooling/gpx-replay
area/derived-metrics
area/speed-pipeline-coverage-audit
area/speed-source-arbitration
area/speed-pipeline
area/stop-detector
area/ble-csc-sensor
area/persist-ride-state
area/foreground-location-service
area/protocol-version-handshake
area/real-komoot-fixture
tooling/message-keys-codegen
tooling/fix-android-platform-doc
area/settings-screen
tooling/first-real-android-build
tooling/fix-runner-label
area/cue-sheet-cache
area/route-library
area/page-template-renderer
area/colour-palette
area/page-carousel
area/ride-state-machine
area/watchapp-skeleton
tooling/host-test-harness
area/field-store-page-descriptors
tooling/ci-pipeline
area/cue-sheet-enricher-interface
area/gpx-share-import
process/security-persona
area/android-companion-skeleton
tooling/pebble-sdk-emulators
process/team-and-pipeline
dev-latest
v0.5.0
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
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#32 Off-route detection with hysteresis and auto-recovery
robert/PedalPebble
#33 Next turn, then-turn, remaining distance and ETA
robert/PedalPebble
#39 Unit tests: snapping on out-and-back routes, off-route hysteresis
robert/PedalPebble
#40 Viewport selection, polyline clip, project and simplify
robert/PedalPebble
#57 Off-route re-routing back to the course
robert/PedalPebble
Depends on
#24 GPX share-sheet import intent, parser and simplification
robert/PedalPebble
Reference
robert/PedalPebble#31
No description provided.