Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added assets/navigation/arrowhead-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/arrowhead-dark@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/arrowhead-dark@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/arrowhead-light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/arrowhead-light@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/arrowhead-light@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-arrive-left.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-arrive-left@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-arrive-left@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-arrive.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-arrive@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-arrive@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-fork-left.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-fork-left@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-fork-left@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-left.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-left@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-left@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-merge-left.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-merge-left@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-merge-left@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-ramp-left.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-ramp-left@2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-ramp-left@3x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-roundabout-left.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/navigation/maneuver-roundabout-left@2x.png
Binary file added assets/navigation/maneuver-roundabout-left@3x.png
Binary file added assets/navigation/maneuver-roundabout-right.png
Binary file added assets/navigation/maneuver-roundabout-sharp-left.png
Binary file added assets/navigation/maneuver-roundabout-straight.png
Binary file added assets/navigation/maneuver-roundabout-uturn.png
Binary file added assets/navigation/maneuver-sharp-left.png
Binary file added assets/navigation/maneuver-sharp-left@2x.png
Binary file added assets/navigation/maneuver-sharp-left@3x.png
Binary file added assets/navigation/maneuver-slight-left.png
Binary file added assets/navigation/maneuver-slight-left@2x.png
Binary file added assets/navigation/maneuver-slight-left@3x.png
Binary file added assets/navigation/maneuver-straight.png
Binary file added assets/navigation/maneuver-straight@2x.png
Binary file added assets/navigation/maneuver-straight@3x.png
Binary file added assets/navigation/maneuver-unknown.png
Binary file added assets/navigation/maneuver-unknown@2x.png
Binary file added assets/navigation/maneuver-unknown@3x.png
Binary file added assets/navigation/maneuver-uturn-left.png
Binary file added assets/navigation/maneuver-uturn-left@2x.png
Binary file added assets/navigation/maneuver-uturn-left@3x.png
Binary file added assets/navigation/oneway-dark.png
Binary file added assets/navigation/oneway-dark@2x.png
Binary file added assets/navigation/oneway-dark@3x.png
Binary file added assets/navigation/oneway-light.png
Binary file added assets/navigation/oneway-light@2x.png
Binary file added assets/navigation/oneway-light@3x.png
Binary file added assets/navigation/puck-dot-dark.png
Binary file added assets/navigation/puck-dot-dark@2x.png
Binary file added assets/navigation/puck-dot-dark@3x.png
Binary file added assets/navigation/puck-dot-light.png
Binary file added assets/navigation/puck-dot-light@2x.png
Binary file added assets/navigation/puck-dot-light@3x.png
Binary file added assets/navigation/puck-retained-dark.png
Binary file added assets/navigation/puck-retained-dark@2x.png
Binary file added assets/navigation/puck-retained-dark@3x.png
Binary file added assets/navigation/puck-retained-light.png
Binary file added assets/navigation/puck-retained-light@2x.png
Binary file added assets/navigation/puck-retained-light@3x.png
Binary file added assets/navigation/puck-wedge-dark.png
Binary file added assets/navigation/puck-wedge-dark@2x.png
Binary file added assets/navigation/puck-wedge-dark@3x.png
Binary file added assets/navigation/puck-wedge-light.png
Binary file added assets/navigation/puck-wedge-light@2x.png
Binary file added assets/navigation/puck-wedge-light@3x.png
4 changes: 4 additions & 0 deletions docs/development/delivery.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ Version **0.2.0-beta.1 / Android code 12** is a GitHub **pre-release** for a phy

Emulator evidence (Android 16 AOSP, no Google services) covers launch, theme switching, sheets, search, stop boards, road navigation start at 30–45 m accuracy, replayed walking with reroute, transit following by confirmations with device location off, the date/time dialogs and the Organic Maps hand-off. Physical GPS, screen-off guidance, real boarding/transfers, audible voice and battery remain field-test checks; the release notes carry the checklist.

## Unreleased: first-person guidance

Development-client evidence on the Android 16 AOSP emulator (no Google services, software ANGLE rendering) with 1 Hz test-provider replays of FOSSGIS walking, cycling and driving routes in Turin: the puck stays on its anchor (median error 0.08–0.19% of the screen height, p95 ≤ 0.66% during steady segments), the planner's projection matches MapLibre's own `project()` within about 1–2 px median, turn framing begins within one fix of the 8/10/12 s window, a 30 s stop holds bearing and zoom, a pan enters free at gesture start (about 60–75 ms to the free intent) and reroutes leave a free camera untouched, Ricentra issues one 500 ms move, degraded fixes stop the lead and keep the labelled last instruction, a live light/dark switch keeps the route, puck and basemap adjustments, and a transit access walk uses the walking camera. Emulator frame times (median 57 ms under screen recording) qualify the emulator only; physical-device smoothness, GPS course and speed quality, screen-off guidance and battery use remain field checks.

## Current release line: 0.1.9

Version **0.1.9 / Android code 11** combines compact map-first UI, stable task/navigation geometry, foreground location acquisition and read-only provider diagnostics. Navigation still uses its existing GPS source and 20 m / 10 s acceptance policy. The production launcher exclusion keeps Google barcode-scanner dependencies out of the runtime graph while the separate development client remains available.
Expand Down
14 changes: 14 additions & 0 deletions docs/development/navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,20 @@ Road guidance consumes one [packaged policy](../../modules/avoid-navigation/andr

The [host trajectory harness](../../tests/navigation-core/README.md) executes the real Ferrostar 0.57.0 Rust controller against that policy. It covers sparse turn samples, sidewalk offset, progress/deviation at accepted accuracy and a short final step. It does not execute the Android library or UniFFI/JNA bridge; Android runtime and physical-route acceptance remain separate.

## First-person guidance presentation

Road guidance uses an app-controlled MapLibre camera fed only by accepted native navigation state: no second location stream and no MapLibre user tracking. The native snapshot exposes, besides the Italian text, structured maneuvers and kinematics (`src/domain/navigation.ts`):

- `upcomingManeuver` (Ferrostar's `remainingSteps[1]`, whose text is `instruction`) and `followingManeuver` (`nextInstruction`) carry the raw OSRM type, modifier, roundabout exit, street name/ref, bearings, driving side, maneuver coordinate and its index in the route geometry. Ids are `<routeRevision>:<step>` and change on every reroute. `followingManeuver` adds the distance/time between the two maneuvers. Raw facts are kept beside Ferrostar's parsed steps because the adapter empties its visual instructions; Italian prose is never parsed back into types.
- `routeProgress.traveledMeters` is the snapped position measured with the native haversine on the bridged route geometry, so the interface can split travelled and remaining route on exactly what it draws. `snappedLocation` and `alignment` (`aligned`, `deviating`, `unknown` when the fix was too coarse to judge deviation) tell the camera whether the snapped position is credible.
- `location` adds speed, course and their accuracies when the platform supplies finite values, plus the monotonic `elapsedMs` sample time used for fix intervals and duplicate detection.

The camera planner (`src/features/navigation/guidance-camera.ts`) produces one frame per distinct fix. The map eases linearly to it over the measured fix interval, so the puck (drawn at the camera anchor while following) and the map move on one clock with React rendering at 1 Hz. It is course-up with circular filtering (the short way across north) and holds its bearing when slow; pitch, zoom and the puck anchor are per mode (walking 34°, zoom 18.3, 67% of the map left between banner and strip; cycling 42°, 17.1–18, 71.5%; driving 48°, 15.7–17.7 by smoothed speed, 73.5%). The anchor is placed with top padding: MapLibre centres the padded rectangle, so bottom padding alone would raise the puck. Turn framing starts 8/10/12 s before the maneuver (walking/cycling/driving), keeps the junction and a short outgoing path (and a second turn that follows within about ten seconds) inside the visible map, and releases over 2–3 s. Cycling and driving draw at the route-snapped position only while `alignment` is `aligned`; walking keeps the real offset. Cycling and driving add a presentation-only lead of at most one fix interval that never passes the upcoming maneuver and stops on degraded, late or recovering fixes; it never feeds navigation state. When a provider omits speed or course, the planner estimates them for presentation only: a displacement counts only beyond the combined horizontal accuracy of the two fixes (at least 3 m, within 10 s), entering motion needs two consecutive consistent estimates, the course accuracy reports the geometric uncertainty, and stationary jitter yields no speed, course or lead.

Camera intent is follow, free or overview. A gesture enters free at gesture start (`onRegionWillChange` with user interaction) and blocks every pending move; **Ricentra** restores the follow pose in one 500 ms transition (in a transit ride or wait it fits the current leg again); overview frames the remaining route north-up and flat once. Fixes and reroutes never take the camera back from free or overview. The visible map is a rectangle: below the banner, above the strip and, in a landscape layout, left of the side panel; anchoring, projection and fits use it. Leaving guidance returns the browsing map to north-up and flat with whichever browse camera command is issued next.

Development builds log `[nav-cam]` rows comparing MapLibre's own `project()` of the camera centre and the next junction with the planner (anchor error, projection error, commanded versus native zoom/bearing). Emulator replays (`adb shell cmd location providers set-test-provider-location` at 1 Hz) exercise this path; physical-device GPS, frame pacing and battery use remain separate acceptance.

## Android acceptance

Build and install following [android.md](android.md). Record version/code, Android version, permissions, installed voice and network state using public routes/stops. Each row above needs an observed result for its affected mode; provider failure is an explicit outcome, and an install alone is not runtime acceptance.
Expand Down
8 changes: 7 additions & 1 deletion docs/development/ux.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ The app belongs to the avoid.quest family. Launcher name: **avoid maps** (develo

Keep one map mounted across browsing, sheet expansion and navigation. Small inset task cards overlay that viewport at a compact height or an explicitly expanded height; keyboard resizing may reduce the sheet's available space while preserving the map. Status, loading and error updates change content inside reserved regions. Anchor route actions outside scrolling details, and keep navigation instruction, trip summary, Retry and Stop geometry independent of position quality.

Frame a planning route once for the requested origin, destination and mode, or when the user selects an alternative or requests the full route. Refreshes update its line without reframing. Panning consumes any pending frame so a late response respects the chosen view. Camera padding must leave visible map space on narrow, expanded and side-sheet layouts. Navigation follows accepted positions until the user pans; Locate deliberately resumes following.
Frame a planning route once for the requested origin, destination and mode, or when the user selects an alternative or requests the full route. Refreshes update its line without reframing. Panning consumes any pending frame so a late response respects the chosen view. Camera padding must leave visible map space on narrow, expanded and side-sheet layouts. Road guidance uses the first-person camera described in [navigation](navigation.md#first-person-guidance-presentation): a gesture enters free at its start, **Ricentra** restores following in one move, and the overview button frames the remaining route once. Fixes and reroutes never take the camera back.

Keep current quality separate from retained coordinates. The native snapshot supplies the last accepted accuracy and current usability/problem, not the accuracy of rejected samples. Label retained numbers **Ultima posizione accettata** and paused maneuvers **Ultima indicazione**; keep their geometry while guidance is suspended. Provider selection and accuracy/age policy are separate concerns.

Expand All @@ -65,6 +65,12 @@ Trasporti lists the nearest pilot rail stations above the GTT stops; a station o

## Active guidance

Road guidance is first-person: a flush banner in the chrome colour on top, the map with the puck low in the space between banner and strip, and a compact bottom strip.

- **Banner:** a maneuver glyph drawn from the OSRM type and modifier (straight, slight/normal/sharp turns, U-turn, fork, merge, ramps, roundabout with exit number and circulation, arrival; an unknown maneuver shows a neutral glyph with the supplied text, never a guessed turn), the distance in heavy Mona Sans with a smaller unit, then the street and the action in Geist with two lines reserved. A reserved row shows **Poi …** only when the following maneuver comes within about ten seconds of travel after the upcoming one; a roundabout exit number sits beside its glyph. Status (**Ricalcolo del percorso…**, **Fuori percorso**, reduced precision, **Guida in pausa · Ultima indicazione**, the search signal) floats in its own pill just below the banner, so a warning is never hidden by **Poi**; both are also in the banner's spoken label. Each banner row has a fixed height measured for the current font scale (text capped at 2×), so no instruction or status changes the banner height.
- **Strip:** arrival time labelled **arrivo stimato**, remaining time and distance **senza traffico**, the voice toggle (active, muted and unavailable are distinct icons and labels), overview and **Interrompi**. On narrow screens or with large text the summary takes its own row above the controls, so no label or number is truncated. Tapping the summary opens details. **Riprova** appears only beside an active problem, floating above the strip with Ricentra. A paused position never advances an apparently current arrival time: the strip shows **Stima sospesa** and labels the remaining values as the last estimate.
- **Map:** the remaining route in the brand ink with a contrasting casing, the travelled part thinner and muted, one cased arrow through the next junction from the real geometry, and the puck (a wedge with a live green centre, a disc when the direction is unknown, a subdued ring for a retained position). Driving and cycling hide generic business dots and labels but keep street names; driving shows one-way chevrons.

Prioritize the next instruction, map, current problem and Stop action. Present recovery beside the problem. Keep voice status and setup in navigation details. Anchor the active transit confirmation beside Stop. Transit following has its own screen, not the road panel: the stage and instruction on top, the next boarding with its live provenance (or **Corsa non confermata**), the stop to get off at, journey age and passed/missed warnings, then the remaining timeline; the large confirmation sits beside Stop. Preserve transit confirmation controls and uncertainty when simplifying the layout. Route previews remain planning; native voice, position and background behavior require the separate [navigation acceptance checks](navigation.md).

## Task model and modules
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,17 @@ import uniffi.ferrostar.createNavigationSession
/** Pure navigation core; Android owns lifecycle, fixes, network and speech. No SDK auto-rerouting. */
internal class FerrostarNavigationEngine(responseJson: String, mode: String, firstFix: Location) : AutoCloseable {
val route: Route
/** Raw OSRM maneuver facts aligned with [route] steps (Ferrostar's public steps drop them). */
val facts: List<ManeuverFacts>
val index: RouteGuideIndex
private val config: NavigationControllerConfig
private val session: NavigationSession
private var state: NavState
init {
route = FerrostarRouteParser.parse(responseJson, mode)
facts = try { ManeuverFacts.parse(responseJson) } catch (_: org.json.JSONException) { throw NavigationFailure("invalid") }
if (facts.size != route.steps.size) throw NavigationFailure("invalid")
index = RouteGuideIndex(route.geometry, route.steps, facts)
config = RoadGuidancePolicy.controllerConfig(mode)
try {
session = createNavigationSession(route, config, emptyList())
Expand Down
Loading
Loading