Vela Maps - technical specification¶
The technical reference: rules, contracts, constants and thresholds, stated as what the code
does now. Where this file and the code disagree, the code is right. docs/book/ explains each
subsystem in prose; section 16 lists the other documents.
Contents
- 1. Product definition
- 2. Architecture
- 3. The Google extractor
- 4. Routing and navigation
- 5. Places
- 6. Map rendering
- 7. Offline data
- 8. Transit
- 9. Voice, dictation and language
- 10. User interface
- 11. Remote resilience
- 12. Degoogled constraints
- 13. Performance model
- 14. Privacy, diagnostics and location hygiene
- 15. Build, release and distribution
- 16. Where the rest lives
1. Product definition¶
1.1 What it is¶
Vela Maps (app.vela) is a maps and navigation app for Android phones without Google Play
services: search, places, routing, traffic-aware ETAs and turn-by-turn navigation. It targets
GrapheneOS and other ROMs with no GMS. License GPLv3. Distribution is F-Droid and Obtainium.
1.2 Non-negotiables¶
- No Vela backend. Each install talks to its sources directly from the user's own IP, like one logged-out browser. There is no shared API key and no server tier.
- No static shared Google credential. Sessions bootstrap per install (
GoogleSession). The project's legal footing rests on this. - Open data draws the map: open vector tiles, and by default Vela's own bake of open datasets for places. Section 1.4 lists what Google is asked for.
- Degoogled at runtime (section 12): AOSP location and TTS only; no FCM, Firebase, Play Integrity or fused location.
- Recalibratable without a release. Field indices, pb templates, endpoints, word tables, tuning dials and parse logic ship over a signed remote channel (section 11), because Google reshapes its endpoints.
1.3 Non-goals¶
- Account sync of any kind.
- Anything that needs a Google sign-in, such as review "helpful" counts (section 3.4).
- A Vela-hosted tile, routing or search service.
1.4 Capability and source matrix¶
| Capability | Source | Reaches Google | Works offline |
|---|---|---|---|
| Basemap | OpenFreeMap Liberty vector tiles, or a downloaded PMTiles region | No | With a downloaded region |
| Place icons while browsing | Vela data by default (Overture, AllThePlaces and OpenStreetMap, baked in this repo); Google's ambient places or both by setting (section 5.1) | Only in Google or Both mode | Vela data, with a downloaded region |
| Opening a place | Google listing, correlated to the tapped feature | Yes, unless the lookup toggle is off | Tile data, or a saved copy |
| Search | Google autocomplete per typing pause (suggest), Google search?tbm=map on submit, Photon beside them for house-number text; offline, the place packs and the downloaded places archives (PlacesArchiveSearch, ranked with the packs in OfflineRank) |
Yes | Region packs, places archives |
| Reviews, photos, popular times, About | Photos: one hspqX request. Popular times and details: the search reply or one focused search. Reviews: a hidden WebView scrape. The page walk only as fallback or for More photos |
Yes | Saved copy only |
| Driving route | Google's line with open-data steps (HybridRoute, section 4.1): FOSSGIS OSRM's where both routes share the road, else a Valhalla map match, map-tile street names, then bare turns. Without Google: the OSRM route. Without OSRM: Google's own short steps, or the on-phone router |
Yes | Downloaded .obf region |
| Traffic and live ETA | Google directions | Yes | No |
| Walking, cycling | Walk: OSRM foot; Google's walk only when 15% shorter (WALK_GOOGLE_SHORTER). Bike: safety-weighted by default, on-phone profile, else Valhalla |
Walk: to compare. Bike: not by default | Downloaded region |
| Traffic layer; satellite past z19 | Google raster tiles, both off by default | Yes | No |
| Traffic controls (lights, stops, crossings, humps) | Per-region road-features bake, Overpass only where no region exists | No | Yes |
| Surveillance and speed cameras | Bundled and hosted DeFlock dataset; OSM speed cameras | No | Yes |
| Fuel prices on gas stations | US: Google's search reply. UK: the government's Fuel Finder, trimmed and hosted on the fuel-gb release (5.8) |
US: in the search. UK: no | UK: the last file downloaded |
| Bridge openings (Netherlands) | NDW open data, planningsfeed_brugopeningen |
No | No |
| Transit boards and stop icons | Transitous (open GTFS + GTFS-Realtime); a Google-listed stop Transitous does not cover falls back to the stop's Google page | Only as the fallback | Last board seen, cached areas |
| Transit directions | Google's transit page; Transitous' planner (/api/v1/plan) when Google is off or answers nothing |
Yes, unless Google is off | No |
| Street View | Google keyless pano metadata and tiles, rendered in-app | Yes | Viewed panoramas |
| Reverse geocoding (pins, house-number and building taps) | Nominatim | No | No (the pin reads "Dropped pin"); a typed address geocodes offline from the region packs |
2. Architecture¶
2.1 Modules and boundaries¶
Two Gradle modules.
:coreis the UI-agnostic extractor: data sources, parsers, routers, the navigation engine, offline stores, remote config, diagnostics. No MapLibre type and no Android UI type appears in it; coordinates convert at the view boundary. Compile-time switches are inVelaConfig.:appis the Compose UI, MapLibre Native 13.6.1, the foreground navigation service, the Android Auto service and the five hidden WebView scrapes. Root packageapp.vela, application classVelaApp.
:app reads :core; :core cannot read :app. A setting that must act inside :core is
written by :app into a plain flag there: CategoryFilter.enabled, LowRamMode,
LowDataMode, NoGoogle, RoutingPrefs, RoadNumbers, SpokenRoadNames, SpokenDetail.
Use Vela without Google¶
GoogleFree (Settings > Privacy, pref google_free, default off) mirrors into
NoGoogle.enabled. With it on:
- Search answers from Photon, two requests run together: 20 results softly biased toward the
user, and 10 inside a hard box around the view for partial addresses. Vela's own places lead
the list (place packs plus the places archive, downloaded or streamed by HTTP range,
PlacesArchiveSearch). Photon is skipped when they answer a category query, or a name query with a hit within the view span of its center, at leastGOOGLE_FREE_NEAR_M(3 km) and at mostGOOGLE_FREE_NEAR_CAP_M(25 km). - The page-2 search, the ambient fan-out, reviews and photos answer empty. Street View answers null.
- The Google directions call answers empty, so every route is the open router's: no traffic, no Google alternates, no abbreviated fallback. Transit directions come from Transitous' planner.
- In
:app,HiddenWebView.requestreturns null, the traffic raster is not added, the satellite Google fallback draws no deep layer, the tap lookup is skipped, and the Street View pill and the full-screen reviews page are hidden. - A short Google Maps link (
maps.app.goo.gl) is resolved by a cookieless request to Google's shortener that reads the redirect and stops (ShortLinks.resolve), only while "Open shared Google Maps links" (GoogleFree.resolveLinks, prefgoogle_free_resolve_links, default on) is on. Off, it is refused with a toast. A short link opened from another app takes the same path (MainActivity.handleIntenthands it toopenSharedText). The shortener's usual target is a place link with no coordinate, only the place's feature id (MapLink.featureId): the name is searched near the id's S2 cell (MapLinkParser.featureCell), the map moves there, and the hit whose id matches opens (pickLinkHit). Amaps.google.com/?cid=<id>link carries only the id's second half and no name, and Google answers it with a page, not a redirect; it is not opened (ROADMAP). The target is parsed on the phone and searched through the open sources. - A shared list is refused (
importListreturns null): its places exist only on Google's servers.
2.2 Module tree¶
The main classes by package. Parentheses name a class inside the preceding file.
:core (app.vela.core)
VelaConfig, di/CoreModule
model/ LatLng, Place, Route, Maneuver, Transit types
data/
MapDataSource, MockMapDataSource
google/
GoogleSession, GoogleMapsDataSource
PbBuilder, SearchPb, DirectionsPb request protobuf grammar
GoogleResponse XSSI strip and positional-array navigator
PolylineCodec, StreetViewParser
parse/ Search, Directions, Transit, Photos, Reviews, EntityList,
PopularTimes parsers
naming/ HybridRoute, LineNamer, RoadNameTiles
RouteGeometry OSRM steps, lanes, via snapping
RouteEngine on-phone routing interface
ObfRouteEngine OsmAnd router over .obf files
ValhallaRouter bicycle routing, map matching
RouteCorridor search along a route; ahead() during a drive
PhotonGeocoder, ShortLinks, PlaceCache, StreetViewCache
OverpassPois, OverpassEndpoints, OverpassTrafficSignals, OverpassAlprCameras
NdwBridgeOpenings Dutch bridge openings (NDW open data); BridgeAlerts
OfflinePoiStore, OfflineAddressStore, OfflinePacks, OfflineRank
transit/Transitous MOTIS client: stops, boards, trips, plans
CategoryFilter content gating
tiles/ map style catalog
net/ GoogleTransport (the Cronet hook, AgedSession)
location/ LocationProvider (AOSP), HeadingProvider, MotionProvider, SpeedKalman,
AlongRouteFilter, DemoTrace
nav/ NavEngine (pure), NavSession, NavReplay, RouteProjection, RouteBar,
CameraAlerts, CameraFacing, CameraDetour, DetourEstimate, SpeedingAlerts,
ExitLabel
voice/ VoiceGuide, NeuralSynth, SpokenScript, SpeechText
feedback/ Haptics
config/ Calibration, CalibrationStore, BundleSignature, JsSandbox, JsTransforms
search/ QueryIntents, VoiceCommandExamples
replay/ TripLog, TripScrub, TripShareBatch
i18n/ NavStrings
util/ SunTimes, NameScript, PlaceNames, OpeningHours, Jitter, OsmHours (lines()
is the one entry point for OSM opening_hours)
diag/ DiagLog, DiagEvent
:app (app.vela)
MainActivity, VelaApp
ui/map/ MapScreen, VelaMapView, MapViewModel, NavController, SearchGates,
PoiIcons, AmbientStability, FollowEstimator, RoadShields, MapFonts,
StyleLayers, MapDpadController
ui/place/ PlaceSheet (DirectionsPanel), GoogleChooser, RouteTopCard, StopsEditor,
PlaceOrigin, StreetViewScreen
ui/nav/ NavOverlays (ManeuverBanner, NavControls), StepsSheet, RouteBarStrip,
RoundaboutGlyph, RouteShield
ui/search/ SearchBar
ui/settings/ SettingsScreen, SettingsHub, SettingsScaffold, sections/
ui/theme/ AppTheme, Theme
ui/ settings holders (section 2.3), SheetPalette, Format (Units), VelaMenu,
VelaDialog, DpadFocus, AdaptiveDensity, QuickCategories
web/ HiddenWebView and its five fetchers (WebDirectionsFetcher,
WebPhotoFetcher, WebPopularTimesFetcher, WebReviewsFetcher,
WebStopDeparturesFetcher), ReviewsPanel, WebViewIdentity,
WebViewCookieJar, WebProxy, SessionRotation, GoogleStanding,
GoogleTelemetry
net/ CronetTransport
offline/ ObfStore, RegionCatalog, RegionPolys, PoiPackStore, PlacesTileStore
(PmtilesRegionStore, BasemapTileStore), PlacesArchiveSearch,
PmtilesReader, PmtilesPatch, PmtilesCompact, OverlayTileStore,
MaxspeedOverlayStore, GlyphPackStore, OfflineMaps, LegacyGraphs
(removes old GraphHopper graphs)
car/ VelaCarAppService, VelaCarSession, CarMapRenderer, CarBridge,
ManeuverMapper, screen/
data/ RoadFeatures, FlockCameras, ContactAddresses, TransitStopCache,
TransitBoardCache
voice/ AsrRecognizer, AsrEngine, PiperSynth, VoiceInstaller, KokoroInstaller
service/ NavigationService, NavGlyphs
download/ DownloadService (DownloadWork)
update/ SelfUpdater, ApkChoice, InstallSource
diag/ DiagExporter, DiagScrub, NavTrace, CrashCatcher
replay/ TripStore
streetview/ PanoramaView, StreetViewTiles
2.3 Seams and process-wide state¶
MapDataSourceis the only interface the UI depends on.GoogleMapsDataSourceis the real scraper;MockMapDataSourcekeeps the app usable with no network.CoreModulebinds one byVelaConfig.USE_GOOGLE_SOURCE.GoogleSessionbootstraps a logged-out session. The in-memory cookie jar pre-seeds Google'sSOCSandCONSENTcookies so an EU session is not sent toconsent.google.com, and drops anySet-Cookiethat would downgradeCONSENT.- Settings are process-wide holders, a
mutableStateOfmirror overSharedPreferences, started inVelaApp.onCreate. A holder not started there reads its default on every launch. They areAppFont,AppLocale,AppTheme,BikeSafe,BuildingDebug,BuildingOverlay,Buildings3d,CategoryChipsPref,ContactsSearch,DetailsRetry,DynamicColor,FasterRouteAuto,Flock,FlockDetour,FlockNavAlert,FlockRouteAlert,FullPlaceLoad,GoogleFree,HideAdult,HideExternalLinks,HouseNumbers,LayersButton,LinkAction,LiveReviews,LoadPhotos,MapColors,MapPoiPrefs,MapTilt,NavEndConfirm,NavNorthUp,NorthLock,OfflinePlaces,Onboarding,OtherLocationsAuto,PageTransitions,ParkingButton,PauseInBar,PhotosOnTap,PipTurnCard,PreferButtons,PuckStyle,QuickChipsPref,RegionUpdates,ReviewsOnTap,RoadLabel,RoadNumbers,RoutePicker,RouteTrafficOnTap,RouteTrail,SatelliteLayer,ShowReviews,SimLocation,SpeechPreload,SpeedCamWarn,SpeedCams,SpeedDisplay,SpeedingAlert,SpokenDetail,SpokenRoadNames,StartView,Topography,Traffic,TransitLayer,TurnDeclutterPref,UiScale,Units,VoiceSearch,WhatsNew. MemoryPressure,PipModeandConstrainedNetworkhold runtime state, not a pref.- One view model.
MapViewModelownsMapUiStateand delegates navigation toNavControllerthroughNavController.Host. Nav code never reaches into the view model. Anything an init-time collector touches is declared aboveinit:viewModelScopeisMain.immediate, so a collector's first pass runs inline, before properties declared belowinitexist.
2.4 Data flow, search example¶
MapScreen calls MapViewModel.search(), which calls GoogleMapsDataSource.search(). That
builds the pb with SearchPb, issues the GET, and parses the body with a remote JS transform
when one is pushed (JsTransforms.searchOverride, section 11), otherwise with GoogleResponse
plus SearchParser over the calibrated index paths. The list passes through a second JS hook
(refineSearch) and returns to the view model, which publishes it into MapUiState.
3. The Google extractor¶
Google's field numbers and array indices move when it reshapes a response. The live values are
in calibration.json (section 11). Calibration.DEFAULT is the compiled fallback and is
brought in step at each release. The PbBuilder grammar and PolylineCodec need no
calibration. A response that no longer matches throws CalibrationNeededException, which the
UI shows as a notice.
3.1 Endpoints¶
No request carries a key or an account. A bundle is rejected unless searchEndpoint,
directionsEndpoint, reviewsEndpoint, photosEndpoint, sessionWarmUrl and
suggestEndpoint are on www.google.com or google.com (CalibrationStore.ALLOWED_HOSTS).
| Purpose | Request |
|---|---|
| Session cookies | GET /maps?hl=en&gl=us (sessionWarmUrl), once per process before the first data call (GoogleSession.ensure) |
| Search | GET /search?tbm=map&authuser=0&hl=en&gl=us&q=<q>&pb=<SearchPb> |
| Ambient places | the search endpoint, one request per category term (5.4) |
| Autocomplete | GET /s?tbm=map&gs_ri=maps&suggest=p&authuser=0&hl=en&gl=us&pb=<suggestPb>&q=<q>&tch=1&ech=<n> (suggest, SuggestParser) |
| Driving line, traffic, alternates | GET /maps/preview/directions?authuser=0&hl=en&gl=us&pb=<DirectionsPb> (4.1) |
| Steps | FOSSGIS OSRM, routing.openstreetmap.de/<backend>/route/v1/driving/<coords>?overview=full&geometries=polyline6&steps=true, backend routed-car, routed-bike or routed-foot |
| Map match; safety-weighted bicycle | FOSSGIS Valhalla, valhalla1.openstreetmap.de: /trace_route and /trace_attributes; /route with costing bicycle, use_roads 0.1 |
| Photos | POST .../batchexecute?rpcids=hspqX (3.7); the page walk as fallback and for photo categories |
| Reviews | hidden scrape of the place's ?cid= page; the qv9Egd feed behind nativeReviewFeed (3.7) |
| Place details | the search endpoint with name plus address (placeDetails); the details page as last resort |
| Shared list | /maps/preview/entitylist/getlist, the request built from the list id in the share link, or lifted from the share page for a link without one (3.5) |
| My Maps | GET /maps/d/kml?mid=<id>&forcekml=1 (5.6) |
| Transit directions | hidden WebView on /maps/dir/<o>/<d>/data=!4m2!4m1!3e3 (section 8) |
| Street View metadata | POST to Calibration.STREETVIEW_SEARCH_URL; by pano id photometa/v1 (10.7) |
| Street View tiles | streetviewpixels-pa.googleapis.com/v1/tile |
| Reverse geocoding | Nominatim /reverse. Google's map search does not reverse a coordinate |
A bare q= returns an empty envelope; results come from the viewport in the pb. hl=en is
rewritten to the app language when SearchParser.STATUS_LANGS has it (Chinese as zh-CN or
zh-TW), and gl=us to the phone's region.
3.2 Search response¶
Results are at root[64][i], and each entry's place node is [1]. The keys are
Calibration.DEFAULT_PATHS; a bundle's paths overrides them one at a time.
| Key | Path | Field |
|---|---|---|
results |
root[64] |
result list |
single |
root[0][1][0][14] |
the one place node of a focused or geocoded reply |
atThisPlace |
root[0][1][0][14][68] |
businesses at a searched address, node at [i][0] |
similar |
root[2][11][0] |
"People also search for": [featureId, name, [[_,_,lat,lng], ..., rating@6]] |
alsoSearched |
root[0][1][0][14][99][0][0][1] |
related places under a focused result, entries [_, placeNode] |
name |
[1][11] |
|
address |
[1][39] |
fallback: addressComponents [1][2] joined |
rating, reviewCount |
[1][4][7], [1][4][8] |
|
lat, lng |
[1][9][2], [1][9][3] |
|
category |
[1][13][0] |
|
website |
[1][7][0] |
|
phone |
[1][178][0][0] |
|
priceText |
[1][4][2] |
a range such as "$10-20"; SearchParser.priceLevelOf derives the 1 to 4 level |
fuelPrice |
[1][88][0] |
"$5.34/Regular" on US stations; on UK ones a label ("Diesel fuel") the digit gate rejects, and 5.8 fills the price |
placeType |
[1][88][1] |
SearchResult.TYPE_<KIND>, language-independent; null when the block is empty |
countryCode |
[1][88][2][1] |
two letters ("GB", "FR") |
actionLabel, actionUrl |
[1][75][0][0][5][0], [1][75][0][0][5][1][2][0] |
the Book, Reserve or Order link |
featureId |
[1][10] |
0xHIGH:0xLOW |
placeId |
[1][78] |
|
photos |
[1][72][0] |
FIFE URL at [i][6][0], resized with =w500-h350. Landmark extras at [1][204][0][i][1][2][0][0] (compiled) |
featuredReview |
[1][142][1][0][1][0][0] |
|
about |
[1][100][1] |
title [s][1], items [s][2][j][1]. The wheelchair filter reads attribute id has_wheelchair_accessible_entrance at [s][2][j][0] |
updates |
[1][122][1] |
business posts: text [1][0][0][0], posted epoch [2][0], link [4][1], link label [4][2], photo [5][0][0] |
editorialSummary |
[1][32][1][1] |
|
ownerDescription |
[1][154][0][0] |
|
statusRich, openStatus |
[1][203][1][4][0], [1][203][1][8][0] |
status text |
status118 |
[1][118][0][3][1][4][0] |
the first department's status text |
hours203, hours118 |
[1][203][0], [1][118][0][3][0] |
weekly hours (3.3) |
departments |
[1][118] |
per entry: name [0], hours [3][0], status [3][1][4][0] |
closedFlag |
[1][23] |
1 = permanently closed |
editMenu |
[1][96][5] |
"Suggest an edit" entries, kind at [6]; kind 3 ("Reopen this place") on a closed place. A place's own reply only, not a list |
popularTimes |
[1][84] |
[0] holds 7 days, each [dow, [[hour, percent, ...], ...]] |
| none | regex over the entry | Street View thumbnail pano id and yaw (SearchParser.svThumb) |
Shape rules:
- A specific or far address answers with no
[64]list, only thesinglenode, which has the same schema.singleResultEntry,atThisPlaceEntriesandfindResultsArrayvalidate throughpaths.name, so recalibratingnamereaches them. similarandalsoSearchedexist only on a focused reply (empty[64]).- A list reply carries no popular times. The details request (3.7) returns them.
PopularTimesParsertakes rating, count, hours, address and the other backfill fields only from the entry whose feature id matches, andmergeDetailsfills blank fields only. - The status text is
statusRich, elsestatus118, elseopenStatus, and the hours come from the same block.[203]is the main entity's schedule and[118]a department's. Mixing them reports a department's closing time against the store's hours. - Open or closed is parsed from the status text by
SearchParser.parseOpenNow(status, lang), a prefix match against per-language word tables (replaceable throughstatusClosedWordsandstatusOpenWords). Closed words are tested first, because several languages' opening phrases start like their open words. The integers beside the text (statusCodeRich,statusCodeSimple) are style markers and are not read: reading them colors closed places green. - A temporary closure usually sends no status text and no hours.
SearchParser.hasReopenActionreads it fromeditMenu: open places carried kinds 1 and 2, a closed one 3 in place of 1 (San Francisco and Davis listings). The status words ("Temporarily closed" and its translations) still count.closedFlagwins: a permanently closed place also carries kind 3.PlaceDetailscarries the closure and the category, so a place opened from a map label, whose first reply is a summary without them, gets both throughmergeDetails. A closed place's sheet says so in red and not "Hours not listed".
Other locations of a business¶
A business name focuses one branch. Entries of alsoSearched whose normalized name contains
the normalized query (3 or more characters) and that sit more than 30 m from the focused place
join the results (SearchParser.otherBranches). They carry no address and the list is partial.
MapDataSource.searchBranches fetches the rest:
- One page-one request for
<query> near meover a 30 km window (BRANCH_SPAN_M) around the focused place. Google answers with a list of branches with full cards. The view is not used, because the list is capped and its contents change with the window. - The plain query again when the first reply had no
[99]block (SearchResult.strippedFocus, a new session's first seconds). - Rows that pass
SearchParser.isBranch(the name contains the query, the query contains the name, or it is the focus's own name) are merged bymergeBranches: the same name within 50 m is one row, and the copy with an address is kept. - Up to 3 rows (
BRANCH_FILL_MAX) still without an address are looked up by name at their own point (searchOnce, nearest within 60 m).
This runs with the search when Settings > Search "Find other locations automatically" is on
(OtherLocationsAuto, pref other_locations_auto, default on, mirrored into
core/data/OtherLocations.auto). It costs 1 to 5 Google requests per focused name search. Off,
the reply returns SearchResult.focus, the list ends in a "Show other locations" row
(MapUiState.resultsBranches), and the tap calls searchBranches and frames every branch
(resultsBranchesLoaded lifts the hold-view rule).
3.3 Hours node¶
Each entry of [1][203][0] is [name, dow (1 = Mon .. 7 = Sun), [Y,M,D], ranges, flag, flag,
special?]. The list is the next seven days by date, so holiday hours are already in it.
ranges is [[text, [[openH],[closeH]]], ...], with several entries on a split-shift day, and
special[1] is a holiday label. readHours joins the ranges and appends the label,
collapsing a label that repeats itself across a separator to one;
OpeningHours strips the label before it parses the times. Google's live status string stays
primary, because only it reflects an owner's one-off closure.
3.4 Directions response¶
The keys are Calibration.DEFAULT_DIRECTIONS_PATHS; a bundle's directionsPaths overrides
them one at a time.
| Key | Path | Field |
|---|---|---|
routes |
root[0][1] |
one node per route |
geometries |
root[0][7][i] |
index-aligned with the routes: [0] latitude deltas, [1] longitude deltas, E7, first element absolute |
summary |
route[0] |
|
distance |
summary[2][0] |
meters |
typical |
summary[3][0] |
seconds without traffic |
traffic |
summary[10][0][0] |
seconds in traffic, per route; absent without live traffic |
typicalLow, typicalHigh |
summary[10][4][0], summary[10][4][1] |
the typical spread, seconds |
start, end |
summary[7][3][2], summary[7][3][3] |
[_, _, lat, lng] |
summaryText |
summary[1] |
|
spans |
route[3][5][0] |
[level, startMeters, lengthMeters], congested stretches only |
Steps are <step maneuver='..' meters='..'> markup strings anywhere under the route node. The
turn side and severity are in the child <turn side='..' type='..'>. A leading "Use the ...
lanes to" clause becomes Maneuver.laneHint.
placeManeuvers puts each maneuver on the polyline at the fraction given by the summed
distance of the steps before it over the sum of all step distances, and pins the last one
(ARRIVE) to the route end. Step distances fall short of the geometry, and an unpinned arrive
lands early and fires the arrival trigger there.
Request side: the mode is !1e{MODE} (0 drive, 1 bicycle, 2 walk, 3 transit). Avoid options
apply to driving and sit in the !6m feature block: inside its !2m submessage !1b1 avoids
highways and !2b1 avoids tolls, and !7b1 avoids ferries as a direct child of the outer
block. DirectionsPb.withAvoid places them by pattern and fixes the m group counts, so a
recalibrated template still works. A stop is one more !1m4!3m2!3d<lat>!4d<lng>!6e2 group
before the destination's (withWaypoints).
A destination that is a Google place is asked for the way Google's web client asks:
!1m6!1s<text>!2s<feature id>!3m2!3d<lat>!4d<lng>!6e0 in place of the destination's bare-point
group (DirectionsPb.withPlace, calibration directionsPlaceGroup), with ! and * in the
text escaped as *21 and *2A. The text is the place's name and address. Google's route then
ends at the place's own entrance point instead of the road nearest the pin. On twelve Davis and
Sacramento stores the end moved by 0 to 123 m. MapViewModel.route records the place by its
point (DestinationPlaces, 16 kept, a point within 2 m is the same), so a reroute or a recheck
to that point asks for the place too. An open-router snap through Google's course (the via-snap,
the stops snap and nameRoute) ends where Google's line ends, not at the pin, when that end is
within DestinationPlaces.END_MAX_M (400 m) of it (DestinationPlaces.routeEnd).
VelaDirections logs how far Google's line and each returned route end from the pin.
Not reachable without a key or a login. Each was probed and settled:
- A per-departure or time-of-day ETA curve. The response has none, and injected time fields are ignored or rejected. The typical spread stands in.
- The
listentitiesreviewsRPC. It answers 404. Its template stays in calibration (reviewsEndpoint,reviewsPb) and nothing sends it. - Review "helpful" counts, which are zero for logged-out sessions.
- EV charger detail beyond the type marker, the recently-opened badge, and live incidents (Google serves binary vector tiles; Waze's feed is reCAPTCHA-gated).
- A full session's review feed from a native request (3.7).
3.5 Shared-list import¶
A maps.app.goo.gl link fetched logged out redirects to
/maps/@/data=!4m3!11m2!2s<listId>!3e3. ShortLinks.listId reads the id off that target
(or off the older /maps/placelists/list/<id> page), and GoogleMapsDataSource.importList
builds the getlist request from it: pb=!1m4!1s<id>!2e1!3m1!1e1!2e2!3e2!4i<LIST_PAGE_SIZE>!28e2!16b1,
with no token from the page; the endpoint answers from the id alone (971 of 971 at 5000,
2026-10-12). The share page used to embed that request as a link with a session token and the
page's own count (!4i500); since 2026-10 it carries only the id, which is why a link's page
is read only when its form carries no id, and then the embedded link is lifted by regex, its
& unescaped and its count raised to LIST_PAGE_SIZE (5000, issue #755). The reply rides
the large-reply client. The view model hands importList the resolved target, not the short
link. Response after the guard
(EntityListParser): root[0][4] title, [5] description, [3][0] author, [8] items.
Each item: [2] display name, [3] the owner's note, [1][4] address, [1][5][2..3]
coordinates, [1][6] feature id as a pair of decimal signed int64, whose two's-complement hex,
zero-padded to 16 digits, is the 0x..:0x.. form.
3.6 Browser identity¶
Two user agents, never mixed:
- Requests to Google send
calibration.current().userAgentwith Chrome's header set, built byBrowserHeaders.browserHeaders(a navigation) orbrowserXhrHeaders(a data call).VelaConfig.USER_AGENT,SEC_CH_UAandCHROME_FULL_VERSIONare only the compiled fallbacks. - Community services (FOSSGIS OSRM and Valhalla, Nominatim, Photon, Overpass, Transitous) and
the calibration fetch send
VelaConfig.VELA_UA, the contactable identifier their usage policies ask for.
Headers¶
| Request | Accept |
Sec-Fetch-Dest, -Mode, -Site |
Referer |
Downlink, RTT |
|---|---|---|---|---|
| Session warm-up | BrowserHeaders.ACCEPT_DOCUMENT |
document, navigate, none |
none | no |
| Data call | */* |
empty, cors, same-origin |
https://www.google.com/maps/ |
yes |
Image (GoogleTransport.imageHeaders, Street View tiles) |
image types | image, no-cors, cross-site |
https://www.google.com/ |
no |
All three also send User-Agent, Accept-Language, Sec-CH-UA, Sec-CH-UA-Mobile: ?0 and
Sec-CH-UA-Platform: "Windows".
- The UA is a desktop Windows Chrome string. Mobile web Maps serves different markup and
endpoints and deep-links to
intent://, so a mobile UA means recalibrating every parser. It tracks Chrome's current stable on Windows, never the next major (scripts/check-chrome-ua.pycompares it with chromiumdashfetch_releases, channel Stable, platform Windows). secChUais derived from the UA's major byBrowserHeaders.secChUaFor, Chromium's rule fromuser_agent_utils.cc: the GREASE brand's two characters, its version and the brand order are picked by the major modulo the table sizes.CalibrationStore.parseBundleuses a pushedsecChUaonly when the UA names no Chrome major. Older builds read the pushed value, so the bundle carries the derived string too.BrowserHeadersTestpins the rule against real Chrome 120, 124 and 130 headers, and the compiled pair against the rule.BrowserHeaders.sanitizetrimsuserAgent,secChUa,chromeFullVersionandrpcContexton parse and rejects a blank value, one over 400 characters, or any character outside 0x20 to 0x7E. A rejected value falls back to the compiled default; a rejectedrpcContextsends no header. OkHttp throws on a control character at request build, inside arunCatching, so one stray newline in a bundle would otherwise stop every request with no log.Accept-LanguageisBrowserHeaders.acceptLanguage, which the app sets fromLocaleList.getDefault()(the list the WebViews read) throughacceptLanguageFor: each tag, then its bare language unless the next tag shares it, q from 0.9 down by 0.1.DownlinkandRTTgo on data calls only. google.com asks for them in the document'sAccept-CH, so a real session sends them after the document. Over Cronet the values come from its network-quality estimator, scaled by a per-host noise factor of 0.9 to 1.1 and rounded as Chrome rounds them (rttHint: 50 ms steps, capped at 3000;downlinkHint: 50 kbps steps printed in Mbps, capped at 10). Until the estimator has a value, and on OkHttp, they are10and50.- Data calls send the three low-entropy hints only. Chrome ignores a subresource's
Accept-CHfor the high-entropy set. - Neither client sends
X-Client-Dataor the fourx-browser-*headers that Chrome adds on Google requests. A shared fakeX-Client-Datawould be identical on every install, andx-browser-validationis a hash that needs Chrome's own key.
Transport¶
GoogleTransport.hook on the shared OkHttp client hands every request to a Google host
(GoogleUsage.isGoogle: google.com, googleapis.com, gstatic.com, googleusercontent.com,
ggpht.com) to app/net/CronetTransport, Chromium's network stack (dial useCronet, default
on). Everything else stays on OkHttp. So does a Google request when Cronet is off, cannot be
built, or throws before answering.
OkHttp's handshake identifies OkHttp whatever the user agent says. Measured 2026-09-23 on tls.peet.ws (JA4, then the HTTP/2 fingerprint):
Chromium 152 desktop, Android WebView 153
t13d1516h2_8daaf6152771_806a8c22fdea 1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
OkHttp (no GREASE, ECH or ALPS)
t13d1513h2_8daaf6152771_eca864cca44a 4:16777216|16711681|0|m,p,a,s
CronetHolderbuilds oneExperimentalCronetEngineon first use: HTTP/2, QUIC, Brotli, the network-quality estimator, a 64 MB disk cache incacheDir/cronet. A navigation goes atREQUEST_PRIORITY_HIGHEST(Priority: u=0, i). The OkHttp call timeout still bounds the wait. A client with no call timeout (callTimeout(0)) is bounded at 30 s there, so a Google reply that needs longer is asked through a client with a set deadline (GoogleMapsDataSource.largeReplyHttp).- The library is Chromium's own prebuilt Release build for the Chrome for Android stable
version pinned in
gradle.propertiesvela.cronetVersion, the same major the UA claims. Bump the two together. Maven'scronet-embeddedstopped at 143. scripts/build-cronet-aar.shpacks the jars, the four ABIs' libraries, Chromium's ProGuard rules and its LICENSE fromstorage.googleapis.com/chromium-cronet/android/<v>/Release/cronet/intoapp/libs/cronet-<v>.aar(gitignored).cronet-build.ymlpublishes it weekly to thecronet-runtimerelease; CI fetches the pinned one from there, else packs it. The jars are Java 25 class files, which AGP 9.4's R8 reads and AGP 8.10's does not. Protobuf is shaded inside them (org.chromium.net.internal), so it does not clash with OsmAnd's.- The all-in-one APK carries Cronet for arm64-v8a and armeabi-v7a only. On x86 and x86_64 the engine fails to load once and Google requests stay on OkHttp. The per-chip x86 APKs carry their own.
- Cronet advertises
gzip, deflate, brand stripszstdfrom a caller'sAccept-Encoding, sozstdis not sent. - Coil loads images through the shared client with
GoogleTransport.imageHeadersin front, so photos carry the browser headers and ride Cronet.
WebViews¶
- Every WebView (the five fetchers and the all-reviews page) calls
app/web/WebViewIdentity.apply. It sets the calibrateduserAgentand, through androidx.webkit where the feature exists, user-agent metadata built fromsecChUa: the brands, mobile false, platform Windows 15.0.0, x86, 64-bit, form factor Desktop, and the full version fromBrowserHeaders.fullVersionFor(Calibration.chromeFullVersionwhen it is a build of the UA's major, else<major>.0.0.0; the GREASE brand keeps<n>.0.0.0). Without the metadata a WebView with an overridden UA still sends"Android WebView",?1and"Android"hints. It also turns off file access, content access and geolocation. AVelaWebidentity:log line records the WebView package and which switches took. - A WebView adds
X-Requested-With: <package name>to every request it sends itself, and no app setting removes it: Chromium abandoned the header's removal, and the androidx allow-list API is disabled on Google's WebView and unsupported on Vanadium.loadUrl(url, headers)could replace it on the document request only. app/web/WebProxyremoves the header by sending the page's requests over Cronet. DialwebProxy: compiled default off, on for every install throughcalibration.jsontuning.webProxy= 1.- GETs are intercepted in
shouldInterceptRequestand streamed (WebStreamProxy) with the WebView's own cookies (WebViewCookieJar), so the page keeps its session. - POSTs: a document-start script (
WebProxy.SHIM, dialwebProxyPosts, default 1) wraps XHR, fetch and sendBeacon on google.com, tags the URL with a one-time id and hands the body over a JS interface. Text goes as is; a Blob, ArrayBuffer, typed array orRequestgoes as base64 (putB64). The interface name and the tag parameter are random per process. - CORS preflights to a Google host go out over Cronet too. A 204 is answered to the page as 200, because an intercepted 204 loses its CORS headers.
- A body the shim cannot read (FormData) leaves from the WebView with the header and is
logged
untagged POST body:. OtherVelaWebProxylines:carries:,answers locally:,passes through:. - Any proxy failure returns null and the WebView loads the request itself.
- Cost on a Pixel 9 place tap: about 0.2 s on the review page's load (2.15 s against 1.92 s).
- Page telemetry (
play.google.com/log,gen_204,ogads-pa.*) is answered locally with an empty 200 only when Settings > Privacy "Block Google's page telemetry" is on (web/GoogleTelemetry, prefblock_google_telemetry, default off). It works with the proxy on or off, and the dialwebProxyBlockLogsoverrides it when set. It is off by default because a browser that never sends telemetry looks less like one. - A bridge object is visible to the page's scripts, so bridge names are random per process.
Scripts are written with
VelaBridgeandVelaPaneland pass throughJsNames.of.
Values that differ per install or per request¶
A value every install sends identically would pick out Vela and nothing else. RequestShape
and BrowserViewport produce these:
| Value | Rule |
|---|---|
batchexecute _reqid |
random start per process, plus 100000 per call (nextReqId) |
| batchexecute URL and body | localized, a gl added, source-path encoded as %2Fmaps, body ending in & (batchUrl) |
autocomplete ech |
counts up per request (nextEch) |
| Street View JSONP callback (the old GET) | _xdc_._ plus 6 random characters (callbackName) |
map span !1d |
a long decimal within 0.2% of the asked value (span) |
| directions viewport | centered on the trip, spanning it at 1.35x, at least 1.5 km (fitDirections) |
| window size | one of BrowserViewport.CHOICES (maximized desktop Chrome sizes, weighted toward 1920x945), picked once per install (pref browser_viewport) |
SearchPb.build, DirectionsPb.build, suggest and the photo request write the window size.
In search and directions that is !3m2!1i<w>!2i<h> and the four page-chrome rectangles
(!30m28 in search, !20m28 in directions). A recalibrated template without the captured
1024x768 shapes is left untouched. The health probe runs at 1920x945.
Every fixed wait before a Google request is drawn through core/util/Jitter: plus or minus 25%
by default (DEFAULT_SPREAD), 50% on retry backoffs. That covers the nav recheck, directions
retries, the slim-pool heal, neighbor prefetch gaps, the photo-load stagger, place retries and
the review retry. OSRM's retry backoff uses it too.
Sessions¶
- There are two cookie jars: the app's in-memory jar, new at every launch, and the WebView's, kept on disk. One phone is two sessions from one IP.
- Per-place requests (details, photo pages, the review feed) carry the
AgedSessiontag, andCronetTransportsends them with the WebView's cookies (WebViewCookieJar; dialagedSession, default 1). Google gives a new session a limited view: five reviews, and popular times missing on busy places. Without Cronet the request keeps the app's session. web/SessionRotation(Settings > Privacy, prefgoogle_session_rotate) discards the saved session every week (default), every day, or at every process start, and on "Start a new session now". A rotation clears the WebView's cookies and site storage, Cronet's disk cache when the engine has not opened it yet, and the WebView HTTP cache when the next Google WebView is built (consumeCacheClear). The button also empties the app's jar (ResettableCookieJar). Log tagVelaSession.web/GoogleStandingmarks the session limited when the firsthspqXpage returns at most 20 photos (LIMITED_PHOTO_PAGE_MAX) with a next page waiting, or when "More reviews" on the all-reviews page loads nothing. A first page of 40 or more (FULL_PHOTO_PAGE_MIN) clears it. 50 are asked for; a full session answers 50 and a limited one 10. The mark is stored against the session's start stamp and reset by a rotation. A missing popular-times chart is not evidence. While marked, a Google place without a chart showsplace_limited_viewwhere the chart would be, and Settings > Privacy showssettings_google_session_limited.
Request counter¶
core/net/GoogleUsage counts every request to a Google host by purpose, on the phone only.
GoogleTransport.hook records each one from the caller's GoogleUsage.Kind tag or
kindOf(url). A hidden page load counts at HiddenWebView.request or ReviewsPanel, and each
request a Google page makes afterward at WebProxy.intercept, with the proxy on or off.
app/diag/GoogleUsageStore keeps 14 days (KEEP_DAYS), Settings > Privacy shows today and the
week, and the diagnostics export carries googleRequests. MapLibre's own tile fetches (traffic
raster, the satellite fallback) are not counted. The hidden reviews page costs about 137
requests per load, measured on a Pixel 9.
Dials¶
- Any
tuningdial can be overridden on one device withadb shell setprop debug.vela.tune.<key> <n>(ui/AppTune). netLog(Cronet's network log for 90 s and the WebView remote inspector) andfeedDump(raw review-feed replies saved to the app's files) read the property alone (AppTune.localOn). A bundle cannot turn them on.demoClock <minutes since midnight>is the screenshot clock (ui/DemoClock), property only. It pins "now" to that time's next occurrence: status lines are recomputed from the place's hours, the arrival clock counts from it, and transit boards and itineraries are fetched for it.
3.7 Hidden WebView scrapes¶
What a place tap loads¶
| Part | First source | Then |
|---|---|---|
| Photos | one hspqX request for 50 (MapDataSource.placePhotoPage, PHOTO_COUNT), each photo dated |
retried while empty. After the last empty answer the sheet keeps the search's hero photo and "More photos" walks the page |
| More photos | the next hspqX page, one request each |
one retry, then the full page walk, which also brings the photo categories |
| Reviews | the page scrape, capped at FIRST_REVIEWS (10). requestReviews arms it and ensureReviews starts it when the Reviews tab's area is on screen, never during a drive |
up to 2 more scrapes when fewer than min(4, review count) came back |
| Details | nothing when the search reply has popular times, a review count, an address and weekly hours. Else one plain request of the details search (MapDataSource.placeDetails, parsed by PopularTimesParser) |
retried while popular times are missing. The details page only when no try returned popular times or a count, and not during a drive or with the route chooser up |
- A one-request load gets
placeTries()tries (dialplaceTries, default 3, range 1 to 5). The wait before retry n isplaceRetryMs(2500) plusplaceRetryStepMs(1000) per later try, jittered. A new Google session answers its first seconds stripped and the repeat in full. - Each details reply is merged as it lands (
mergeDetails). Only popular times wait on the retries. - Photos and details start a jittered 700 ms after the tap resolves.
- Per-place cache, process lifetime, 80 places each: photos and the feed 6 hours
(
PHOTOS_CACHE_MS,REVIEWS_CACHE_MS), details 15 minutes (DETAILS_CACHE_MS). - Kill switches in
tuning(1 = the one-request path, 0 = the page path):nativePlacePhotos(default 1),nativeDetails(default 1),nativeReviewFeed(default 0). - With
nativePlacePhotos0 the first batch is a page walk stopped atFIRST_PHOTOS(6). - The full walk also sends one
hspqXrequest (placePhotos) and joins its dates by image id.photoDatesRpc0 stops that request. - No Google page is warmed.
warmWebViewsWhenQuietboots the WebView engine alone, with a throwaway view, at a quiet moment after the map settles, so Chromium's start does not land on the first place tap. Creating WebViews ahead of a cold search held results at 13 s against 4 s. - The ambient neighbor prefetch runs only when Google is the sole places source.
- A place with no category, rating, review count or featured review (
isListing()false: an address or a pin) gets no Reviews tab, no review scrape, no popular-times placeholder and no limited-view note.
The two RPCs¶
Both are form-encoded POSTs to
https://www.google.com/maps/_/MapsWizUi/data/batchexecute?rpcids=<id>&source-path=%2Fmaps&hl=<hl>&gl=<gl>&_reqid=<n>&rt=c
with body f.req=[[["<id>","<proto>",null,"generic"]]]& and the headers X-Same-Domain: 1
and x-maps-diversion-context-bin: CAE= (Calibration.rpcContext). Without the context header
the feed answers empty and the gallery answers zero photos. The reply is )]}' plus chunked
rows; the data row is ["wrb.fr","<id>","<payload JSON string>",...].
hspqX (photos) |
qv9Egd (review feed) |
|
|---|---|---|
| Template | photosEndpoint, photosProto |
URL compiled, reviewFeedProto |
| Request | {FID} at [2][0], {COUNT} at [4][2][1], cursor at [4][2][2], the window at [4][1] |
{FID}, {TOKEN}, 10 per page |
| Payload | [0] photos, [5] next cursor. [1] is not the photo total and is not read |
[1] next-page token, [2] reviews, [5] true at the end of the list |
| Entry | URL [6][0] (googleusercontent only, resized to =w1024-h768), date [21][6][8] = [year, month, day, hour] |
under [i][0]: author [1][4][5][0], avatar [1][4][5][1], relative time [1][6], stars [2][0][0], text [2][15][0][0], photos [2][2][k][1][6][0] |
The photo RPC tags no category, so the Menu tab comes only from the page walk.
The feed stays off. Google limits a new anonymous session to five reviews with no paging. A
full session answers a native request with an empty list and [6] = [true]: it requires the
single-use X-maps-bgkey BotGuard token that Google's page script mints for each request. The
page scrape on that session sends the token and gets the full list.
HiddenWebView¶
Five fetchers run Google's own pages anonymously, because a rendered page is served data a bare
request is not. Each subclasses app/web/HiddenWebView and is its URL, its extractor script
and its parser.
| Fetcher (log tag) | Page | Timeout |
|---|---|---|
WebReviewsFetcher (reviews) |
/maps?cid=<cid>&hl=<reviewsHl()>&gl=us, 1200x1000 CSS px |
45 s |
WebPhotoFetcher (photos) |
/maps?cid=<cid>&hl=en&gl=us, 1200x3200 px |
55 s |
WebPopularTimesFetcher (popular) |
google.com/, then sessionWarmUrl, then a same-origin fetch of the details search URL |
22 s |
WebDirectionsFetcher (directions) |
/maps/dir/<o>/<d>/data=!4m2!4m1!3e3?hl=<lang>&gl=us |
20 s |
WebStopDeparturesFetcher (stops) |
/maps?cid=<cid>&hl=en&gl=us |
20 s |
cid is the low half of the feature id as unsigned decimal.
The base class owns:
- The view: JavaScript, DOM storage,
WebViewIdentity, the proxy shim and the result bridge. - A request id per page load, so a late poller can complete only its own request. A request that is given up on stops its page.
session { }: fetches are serialized, withonResumebefore andonPauseafter. A loaded Google page otherwise keeps its compositor and timers running, measured at about 27% of app CPU during a map pan.pauseTimers()is process-wide and is not used.- The reap after 120 s idle (
reapIdleMs), and at once under severe memory pressure. - Blocking non-http(s) schemes. A fetcher can refuse hosts through
allowNavigation; the photo walk stays on google.com. - Console errors logged under
VelaWeb.
Rules for a fetcher:
- Use the
mainHandler, notView.postDelayed: a headless WebView never attaches. - Size the view in CSS pixels times density. A raw 1200 physical pixels is about 450 CSS pixels on a 2.75x phone, which gets Google's narrow layout.
- In a Kotlin raw string
${'$'}{x}emits the literal text and the script dies with a syntax error.
Reviews scrape¶
- Cards are
.jJc9Adwith a uniquedata-review-id. They are accumulated across scroll windows and de-duped by id, keeping the longest text seen per id, because a card read on the tick its More toggle was clicked is still truncated. The selectors (card,id,moreToggle,author,text,date) can be replaced through calibrationreviewSelectors. - The Reviews tab is found by
[role="tab"]and clicked untilaria-selected. A selected tab whose list is still loading is never clicked again, because that restarts its render. - Every text test on a tab or button runs through
STRIP_PLACE_NAME_JSfirst. Google puts the place name in those labels, and a name can contain a review word in some language. - The script ticks every 250 ms. It ends at the cap, or when cards are on screen and the list is idle: 13 ticks at the bottom and 18 without growth once the full list is open, 9 and 9 before that. "Cards on screen" is tested per tick and never latched, because the overview's preview cards render just before the tab click blanks the panel. It stops at 130 ticks regardless.
- The star histogram comes from the same page (
onHistogram, rows parsed byReviewWords.HISTOGRAM_ROW).
All-reviews page¶
ReviewsPanel (GoogleReviewsPanel, used full screen only) shows Google's own reviews pane in
a visible WebView, carved by injected CSS. It opens from the Reviews tab's button; the inline
list is the scrape above.
vhunits are 0 in an embedded WebView, so everything is sized in pixels.- The ancestor chain must be un-clipped and un-transformed, or nothing paints.
- Google's summary block is hidden with opacity first and collapsed with
display:noneonly after the feed has shown cards for about 5 s. Removing it from layout while the virtualized list mounts unmounts every card. - The feed watchdog keys on relative-date texts, not class names, because Google serves builds with rotated classes.
- A review's media buttons are found by
jsaction*="review.openPhoto", never the aria-label, which Google sometimes writes as a description. - The sort menu is clicked by index, because several languages label the button with the current choice.
- All navigation is blocked once the page has loaded.
- A downward drag from the top edge is forwarded as raw deltas for pull-to-close. Otherwise the WebView scrolls itself.
- Ad, analytics and beacon requests are always answered with an empty body (
BlockedHosts, shared with the hidden pages since issue #751: a tracker blocker on /e/OS counted googlesyndication every minute of use, from the pages the scrapes load).
Language¶
Both review paths load the page in the app language (reviewsHl(); English when the word
tables lack the language), because the page language decides which reviews Google serves.
Reviews are never translated. Every text test uses the per-language tables in :core
ReviewWords (keys review, more, sort, star, ago, write, like, share,
actions, all, processed), replaceable through calibration reviewWords. Ratings read the
leading number. The more-reviews button must match a review word and a more word, or a bare
match clicks the review composer.
Photo walk¶
The place page's gallery tabs are visited in turn (Menu, Food and drink, Vibe, By owner), each
tab's photos tagged, then "All" is swept for the rest. Tabs come from role="tab" only, because
the overview's Menu action link leads off the site. A photo is any element whose src, inline
background or computed background is a googleusercontent URL, de-duped by image id. Partial
results stream whenever the set grows. Per-photo dates are read from the page's
APP_INITIALIZATION_STATE.
Details page¶
WebPopularTimesFetcher needs a specific query, name plus address. A bare-name search returns
a 20-result list without [84]; name plus address resolves to one focused result that has it.
Transit directions¶
They go through the page because a keyless transit request is answered with a driving reply.
The payload is the longest )]}'-guarded string in window.APP_INITIALIZATION_STATE. The
script polls for it (up to 12 times, 600 ms apart, wanting more than 5000 characters) because
the page fills it after load, and a small stub sits beside it.
Place sheet¶
- The header holds the name and the X. Save and Share are pills in the action row with Directions, Start and Call, Google's layout (issue #830): Save opens the save menu (the quick save, Save to list, the note, the icon, the name, Set as home, Set as work; a drawn shape adds edit and delete), Share the share menu (open on the web, open in another app, copy the name or the link, send a pin, the coordinates or the address).
- Tabs sit under the action pills and open on Overview (info rows, popular times, a review summary card, About, related places). Selection is keyed by tab name. A pinned copy of the tab row shows once the in-flow row scrolls under the sheet top. Over three tabs the row scrolls.
- The tab set is decided from the first reply; a rated or reviewed place gets Photos up front. Placeholders hold the chart's and the histogram's height while those load.
- Reviews tab: a full-width button to the all-reviews page, then the loaded list, sorted (relevance, highest, lowest) and filtered locally.
- Photos tab: a grid filtered by Google's photo categories. With none yet, a food place offers
a Menu chip (
loadPhotoCategories, the full walk, once per place). - Business posts from
paths.updatesland inPlace.updateswith no extra request. Overview shows the newest with "Show all N updates"; the Updates tab exists when there are two or more.
Settings¶
| Setting | Holder, pref, default | Effect |
|---|---|---|
| Performance > Load all photos and reviews | FullPlaceLoad, place_full_load, off |
every tap runs the full photo walk and scrapes up to 50 reviews at once |
| Places > Load reviews only when I tap | ReviewsOnTap, reviews_on_tap, off |
a Show reviews button replaces the scroll trigger (reviewsAwaitingTapFor, loadReviewsNow); the rating card's Show reviews on the overview counts as that tap and opens the tab loading (issue #845); overrides FullPlaceLoad for reviews |
| Places > Load photos only when I tap | PhotosOnTap, photos_on_tap, off |
the photo request waits for a Show photos button (photosAwaitingTapFor, loadPhotosNow) |
| Places > Wait for popular times | DetailsRetry, details_retry, on |
off makes placeTries() 1 |
| Privacy > Live traffic only when I tap | RouteTrafficOnTap, route_traffic_on_tap, off |
clears RoutingPrefs.googleTraffic for each new trip, so directions, reroutes and rechecks skip Google and the transit chip is not prefetched. The chooser's Show traffic (requestRouteTraffic) sets it for that trip and refetches |
| Navigation > Start drives north-up | NavNorthUp, nav_north_up, off |
sets navNorthUp at every drive start. The compass still toggles it per drive, and a tap while the camera is detached also re-centers |
| Map > Keep north up | NorthLock, keep_north_up, off |
the rotation gesture is off (set after setAllGesturesEnabled, which turns it back on), a resting camera more than NORTH_LOCK_SLACK_DEG (0.05) off north is turned back at camera idle (a following drive camera is left to its ticker), drives start with navNorthUp and the compass toggle keeps it, VelaMapView treats navNorthUp as on whatever the state says, the free-drive follow stays north-up, the drive compass fades at north, and the car map is north-up, flat and centered while following |
| Navigation > Navigation icon | PuckStyle.shape, puck_shape, arrow |
see below |
| Appearance > Map buttons | MapButtonShape.mode, map_button_shape, round |
the locate and parking buttons round, or with 16 dp corners (square); the FABs read it through mapButtonShape, a getter in place of CircleShape's, so MapScreen grows no bytecode |
| Navigation > Road numbers first | RoadNumbers, road_numbers, off |
mirrored into core/nav/RoadNumbers.preferred: roadLabel and instructionRoad put the number on every road that has one (issue #836) |
| Navigation > Zoom out as far as | ZoomToTurn.floor, zoom_to_turn_floor, 0 |
the floor of Zoom to the next turn, 12, 10 or 8 (Town, Region, Far); 0 is no pick, and the turnZoomMin dial decides (4.7, Framing) |
| Navigation > Turn arrows on the route | TurnArrows.on, turn_arrows_on, true |
arrows on the route through the turns ahead during a drive (issue #804) |
| Navigation > Your speed on the car screen | CarSpeed.on, car_speed_on, false |
the car's speed badge; off, the limit sign alone |
| Map > Where the map opens | StartView.mode, start_view, here |
the view the map starts on: here, last, home, place or drive, which is here in driving mode (4.7, Where the map opens and Driving mode) |
| Map > Names on the map | MapNames.mode, map_names, english_latin |
which name a road or place label shows for a Latin-script UI: English then the basemap's romanized name, English then the local name, the local name alone, or local and English (4.10, the label rules); rides styleKey |
The navigation icon is the arrow, a top-down car (drawCarPuck, color pref puck_car_color:
red, blue, white, green, yellow), a UFO, a pirate ship or a rubber duck (drawUfoPuck,
drawShipPuck, drawDuckPuck). Those are top-down bitmaps for the map symbol, the
notification and the car screen. In the nav follow overlay the four are 3D models
(ui/map/Puck3D.kt, PuckModels): flat-shaded low-poly meshes drawn every frame,
orthographic, from the heading relative to the camera and the camera's tilt
(puckOverlayTilt), back faces culled, faces painted far to near, over a ground shadow. The
arrow stays flat. Measured on a Pixel 4a demo drive: 60 fps, 0.17% janky frames.
The nav Overview button is a toggle. With inNavOverview set (by Overview; cleared by
Re-center, a pan and the end of the drive) a press re-centers instead of fitting again. The fit
keeps the chrome clear: in portrait the turn card, the bar, the route bar strip and the button
column; in landscape the whole left column plus 28 dp, with 12% top and bottom.
3.8 Recalibration procedure¶
- Capture the live request in browser devtools or a proxy. Mask the query and any coordinates before saving the capture anywhere.
- For a moved field, edit the path in
calibration.jsonpaths,directionsPathsorsuggestPaths. Each merges key by key over its compiled default (DEFAULT_PATHS,DEFAULT_DIRECTIONS_PATHS,DEFAULT_SUGGEST_PATHS). - For a moved endpoint or pb, edit the template. The host must stay on the allowlist.
- For a reshaped response, ship a
transformsJsbundle (section 11). - Raise
version, run./scripts/sign-calibration.sh, and commitcalibration.jsonwithcalibration.json.sigin the same commit. - Bring
Calibration.DEFAULTin step at the next release.DEFAULT.versionstays 1 so that any remote bundle is newer.
4. Routing and navigation¶
4.1 Which source answers¶
GoogleMapsDataSource.directions serves every route request from five sources.
| Source | What it is |
|---|---|
| Open router | FOSSGIS OSRM, routing.openstreetmap.de/{routed-car,routed-bike,routed-foot}/route/v1, steps=true, geometries=polyline6, alternatives=3 on a trip without stops |
| Keyless directions (3.4): the line, typical and in-traffic time, congestion spans, alternates. Its own steps are abbreviated on longer trips (a 6-mile route returned 2 of about 10 turns) | |
| Matcher | FOSSGIS Valhalla trace_route and trace_attributes at valhalla1.openstreetmap.de (ValhallaRouter) |
| Tiles | Street names from the map's z14 vector tiles (RoadNameTiles, LineNamer) |
| On-device router | ObfRouteEngine over downloaded region files (4.5) |
Driving to one destination: the open router and Google are asked at once, three attempts each with backoff on a planning request. The line driven is Google's, because Google knows closures and traffic. The steps come from open data. A turn whose street cannot be confirmed goes out without a name.
| Situation | Line | Steps | RouteSource |
|---|---|---|---|
| Both answer, Google's line leaves the open route | Google's | Open router's on shared road. On each differing stretch: matcher, else tiles, else bare turns (4.2) | GOOGLE_HYBRID |
| Both answer, same road throughout | Open router's, with Google's times and spans | Open router's | OSRM |
| Google silent | Open router's, no traffic | Open router's | OSRM |
| Open router silent | On-device route when a region answers, else Google's | That source's own. Google's are abbreviated | OBF, GOOGLE_ABBREVIATED |
| No network | On-device route, no traffic | On-device | OBF |
| Google off | As "Google silent". No Google request is made | ||
| Reroute during a drive | The same rules under a deadline, one attempt per source, with the on-device route taken early where a region covers the trip (4.6) |
Google is off when NoGoogle.enabled is set ("Use Vela without Google") or
RoutingPrefs.googleTraffic is false ("Live traffic only when I tap", until Show traffic is
tapped).
Other modes:
- Walking: the open foot router. Google's walk is offered only when at least 15% shorter (4.3).
- Cycling: a safety-weighted route by default, from the on-device bicycle profile, else Valhalla (4.3).
- A trip with stops: 4.4. Transit: section 8.
The open router is asked for polyline6 geometry. The default polyline is a 1.11 m latitude
grid, which scatters the vertices of a straight road. TripLog still writes 1e5 so existing trip
files read back.
4.2 The hybrid route, traffic and alternates¶
HybridRoute builds the GOOGLE_HYBRID route for DRIVE. Nothing is routed through sampled
points, so the result cannot loop, and it is Google's line exactly.
Stretches¶
HybridRoute.stretchesFor returns the parts of Google's line that leave the open route, in
meters along Google's line.
| Constant | Value | Rule |
|---|---|---|
STEP_M |
20 m | Sampling interval on Google's line |
OFF_M |
15 m | A sample farther than this from the open route is off it |
JOIN_GAP_M |
60 m | Off runs closer together than this are one |
MIN_RUN_M |
40 m | A shorter run is drawing noise |
TIGHT_M, WALK_MAX_M |
10 m, 600 m | Each end is walked out to where the lines are this close, at most this far |
PAD_M |
90 m | Added at both ends, so the turn off the shared road and the turn back belong to the stretch |
EDGE_CLEAR_M, EDGE_BEND_DEG |
60 m, 35 degrees | An edge keeps this clear of a corner this sharp |
Touching stretches merge. An open-router step outside every stretch is carried over only when
vouched: the open route's own path stays within AGREE_OFF_M (15 m) of Google's line for the
AGREE_BACK_M (80 m) before the step and for up to AGREE_M (400 m) of its leg after it,
sampled every 40 m and at the leg's end. A step that fails gets a stretch around it, so no
open-router step is dropped without a stretch covering its place. With no stretches the open
route goes out.
Steps for a stretch¶
The first source that answers:
- The matcher (
ValhallaRouter.matchWithEdges):trace_routeover the slice,shape_match: map_snap, costingauto, 2.5 s (1.2 s on an urgent fetch). A stretch overMATCH_MAX_M(180 km) skips it; the server refuses 200 km. LineNamer.name(strict = true)over the tiles.LineNamerwith no tile lines: bare turns from the line's bends.
Tiles come second because, measured on 90 routes in six areas, they named 1.4% of named turns
wrong. StretchNamer runs the three. (debug.vela.tune.noMatch, adb only and read at launch,
turns the matcher off so the other two can be seen on a phone.) The tiles under a stretch are read beside its match:
TILE_HEDGE_MS (1 s; TILE_HEDGE_URGENT_MS 0.3 s) into a match that has not answered, and at
once when it fails. The matcher answers a town stretch in 0.35 to 1.2 s, so a healthy one costs
no tile request. In low data mode the tiles are read only after the match fails.
When the stretches are not done within HYBRID_WAIT_MS (5.5 s; HYBRID_WAIT_URGENT_MS 1.5 s),
the hybrid is rebuilt from what each stretch has in hand (StretchNamer.inHand): its match if
that finished, without lanes if those were late; else the tiles already read
(RoadNameTiles.linesAlong(fetchMissing = false), no request); else bare turns. A matched
stretch keeps its road shape for the drawn line. The open router's own route is never
substituted for a stretch. A hybrid built past the deadline, or with any stretch bare, is marked
namesShort, and the drive's recheck asks again on the degraded interval.
A match is accepted by offLine, which samples both paths every 30 m. A sample over
MATCH_OFF_M (22 m) from the other path is a stray. Strays within 90 m of each other join and
are padded 40 m. The match is refused when one stray run exceeds OFF_RUN_MAX_M (380 m), the
strays total more than OFF_TOTAL_SHARE (8% of the line, 400 m at least), or the lengths differ
by more than MATCH_LENGTH_SLACK (6%) plus 30 m, the end slack and the strays. On a stretch that
touches the trip's start or end, the first or last MATCH_TRIP_END_SLACK_M (150 m) is not
compared. A stretch touches the end when it runs to within 1 m of the measured length of
Google's line (HybridRoute.tripEndSlack), the scale stretches are cut on. Google's stated
distance is not that length and is not used. Accepted strays (Match.off) reach the stitch as
untrusted intervals.
Lanes come from the open router, because the matcher has none (laneDetail, planning fetches
only, and only when the edges came back). The open router is led along the matched path with a
via in the middle of every step of LANE_VIA_MIN_STEP_M (80 m) or more, at most LANE_VIAS_MAX
(20), headings pinned, within LANE_TRY_MS (1.8 s). When its path equals the matched path
within LANE_SAME_PATH_M (8 m), its steps replace the matcher's and its turn names pass
recheck. Otherwise, and always on a stretch at a trip end (where only the part past the end
slack is asked for), the matcher's steps stay and borrow lanes one step at a time: the same side
of turn within LANE_BORROW_AT_M (20 m), and the open path within LANE_BORROW_PATH_M (12 m)
of the matched path 30 and 60 m either side.
The name check¶
trace_attributes returns the edges under the matched path: names, length, and a soft flag for
pieces inside a junction (internal edges, turn channels). ValhallaRouter.checkedRoad tests
each turn's stated street against them. Ramps, merges and roundabouts are not tested; they name
where they lead. The turn's edge is the one beginning nearest it within EDGE_AT_M (12 m), and
edges are read for LOOK_M (300 m) past it.
The stated name is kept when all of these hold:
- It begins within
LEAD_MAX_M(60 m;SOFT_LEAD_MAX_M150 m when everything before it is soft) and within the step's first half. - Only unnamed pieces, soft pieces and stubs up to
STUB_M(19 m) come before it, with at mostNAMED_LEAD_MAX_M(40 m) of them named. - It holds for
HOLD_M(20 m) or half the step.
Otherwise the turn takes the first street held for RENAME_HOLD_M (40 m) with only stubs
before it, or no name. A route number stands in for the street name only when the road has no
other. Without edges a turn carries no street name; exits and sign text are kept.
Related corrections:
- Unsaid turns (
withUnsaidTurns): the matcher treats staying on a numbered route through a corner as going straight. Where the matched line turnsUNSAID_BEND_DEG(60) or more with no step withinUNSAID_NEAR_M(50 m), and the street nameUNSAID_SIDE_M(45 m) before differs from the one after, a turn is inserted and named by the same rule. - Roundabouts: the enter step takes the exit step's street. The ring's own name is never said.
- A turn that keeps the street the car is already on is said without the name, "Turn right":
"onto X" says the street changes. The step keeps its
road. The street the car is on, for this rule, is the one the driver was last told (toldRoad): a rename with no turn is silent and tells nobody, the first step of a stretch cut from mid-trip is never said (departSaid = false), and a ramp or merge that says only its sign ("toward X") has not said the road. A long road that takes the cross street's name for its last block therefore gets "Turn right onto X" at that corner.HybridRoute.stitchapplies the same rule across the seam, where an open step named the road and a stretch step turns onto it. A slight bend that keeps the road's name stays a silent rename, told or not. ValhallaRouter.recheckruns the check on another router's turns. The open route's steps are checked againstValhallaRouter.edgesfor its own line, requested when the open router answers and waited forOPEN_NAMES_WAIT_MS(1.5 s;OPEN_NAMES_WAIT_URGENT_MS0.3 s). This covers the steps carried into a hybrid and the plain open route when it goes out. No answer: the names stand. A turn not found on the edges keeps its name there and loses it inlaneDetail.- The same edges say what kind of road each piece is (
Edge.track, the service'suse). OSRM's car profile drives an unsigned farm or forest track as a slow road; in much of Europe it is closed to cars. When the open route drives throughTHROUGH_TRACK_MIN_M(30 m) or more of track (ValhallaRouter.throughTrackM: track with ordinary road both before and after, so a trip that starts or ends on one is left alone) and that route is among those offered, the other service's car route replaces it (ValhallaRouter.driveRoute,use_tracks0, the same avoid options). It must answer withinOFF_TRACK_WAIT_MS(4 s; 1.5 s on a reroute) and be at most 1.3 times as long plus 2 km, or the open route stands. A trip with stops gets the same check when the line offered is the open router's own (offTrackRoute, the other service asked through the same points). A line longer than the matcher's 200 km is not checked. With Google on the route follows Google's line and only an alternate can be replaced.
Stitch¶
HybridRoute.stitch merges the two step lists onto Google's line.
- An open step is kept when it projects within
SNAP_M(40 m) of Google's line, lies outside every stretch and is vouched. The open router's first and last step are always kept, at 0 and at the end of the line. - A stretch step is placed by projecting it onto Google's line inside a window around where the
step lengths plus the drift so far put it:
PLACE_REACH_M(40 m) or 8% of the step just driven,PLACE_REACH_END_M(150 m) withinTRIP_END_M(400 m) of the trip's ends. It never lands before the previous step. - A stretch's left, right or sharp turn is dropped where Google's line bends under
FLAT_DEG(20) withinFLAT_REACH_M(40 m), and a U-turn where the line turns underUTURN_DEG(100). - Inside an untrusted interval no stretch step is used. Each corner of Google's line of
UNTRUSTED_BEND_DEG(50) or more there becomes a bare turn. - An open step and a stretch step within
MERGE_M(30 m) are one junction, and the open one is kept. Two steps from one source are never merged, except a ramp's two bends named for the same road withinSAME_ROAD_M(150 m). - Step lengths are re-measured along Google's line. Durations are Google's typical time by share of distance.
A result that does not begin with a departure and end with an arrival is discarded, and the
via-snap below applies. The line drawn for a hybrid is Route.drawPolyline (4.8).
HybridRoute.splice: a stretch whose matched road shape does not meet its ends is drawn on the shape where Google's line runs within 9 m of it, else on Google's line.
LineNamer¶
LineNamer (core/data/naming) keeps a route's line and derives its steps. It gives no lanes.
Google's keyless step list is not used, but its exits are (Route.exitSigns, below), and so
are its steps' street names for turns the tiles leave bare (Route.stepNames, below).
- Sampling: every 8 m, heading over 16 m either side.
- Turns: peaks of the heading change across 32 m either side, 35 degrees or more, at least 30 m apart. Classes: 55 degrees a turn, 135 sharp, 165 a U-turn, less is slight.
- Names: the nearest tile street within 30 m driving or 25 m walking that runs within 35 degrees of the line. Runs under 40 m are absorbed.
- A turn is announced when the name changes across it or it bends 70 degrees or more. A name change without a turn is a rename folded into the step before.
- Driving phrases come from link roads (
ramp=1intransportation, car classes only), said once each the way a router that reads junctions says them. A sample is on a link when a link running its way is withinLINK_OFF_M(12 m) and no named street is more thanLINK_TIE_M(1 m) nearer, so a numbered link, which is also in the names layer, counts. A run of such samples, gaps ofLINK_GAP(2 samples) bridged, is a ramp when it isRAMP_MIN_M(80 m) long and a motorway or trunk is at one end; a shorter link is a slip lane. The roads at its ends are the nearest named runs off it within 128 m. - From a highway it is an exit ("Take the exit onto" the road it leads to), said where the line moves onto the link: at the bend there, else at the link's start, on the side the heading moves across 64 m either side. Back onto a highway of the same name it is a keep (express and local lanes).
- Onto a highway from anything else it is "Take the ramp onto" the highway, at the bend onto the link. When the road just past that bend is a named street, the bend is a turn onto it and the ramp is its own step where the line moves onto the link.
- A bend with the line on the link both sides is a curve of the ramp and says nothing. A bend
off its far end is a plain turn onto the street, and onto a highway only at
CURVE_DEG(50 degrees) or more, under which it is a merge and quiet. A link onto a highway that ends in such a turn is a turn lane, and the turn is its only step. - With no link, a bend onto or off a motorway or trunk is an at-grade turn ("Turn left onto"
it). A bend under
CURVE_DEGon a highway with no other named road after it is a curve and quiet (Organic Maps says nothing for one way out under 50 degrees). A split under 55 degrees between two highways is a keep. - A bend keeps the road when the name is the same; a change of ref or class alone is not a turn.
- In a car, lines of classes a car does not drive (
path,rail,transit,aerialway,pier,raceway,busway,bus_guideway,bridleway) never name the line, and a named footpath beside a road does not make strict naming unsure. - Two plain turns the same way within
SPLIT_TURN_M(50 m, OsmAnd's figure), the second onto the street the first went onto and at least one of them changing road, are one turn of their summed angle. Two bends that both keep the name are a hairpin and stay two. - Measured with
NamingStudyTest.tileStepCensuson 39 lines ingoogle_lines, both modes, against the rule this replaced (any bend onto a motorway or trunk a ramp, off one an exit): exits 41 to 69 (the old count includes at-grade turns and second exits at a ramp's end), keeps 8 to 25, an exit said twice within 500 m 4 to 2, same-way turns onto one street within 60 m 13 to 0, steps 780 to 841. The Davis line from Richards Boulevard onto I 80 and off at Chiles Road says the ramp, the exit, the left onto Chiles Road and the right onto Mace Boulevard, the four steps Google gives. Where the line runs under an elevated highway (FDR Drive in New York) the tiles cannot tell the two roads apart. - Exit numbers and signs come from Google's own exits on the same reply (
Route.exitSigns).DirectionsParser.exitSignsreads every step of the route, also the ones without<step>markup:[7][2]is the maneuver's own point,[14]the whole instruction as parts with the names flagged, and the array the step heads carries its icon. A step is an exit when its text says "exit" or "junction" or its icon isdir-tt-ramp-left/-right(the side), and it is no roundabout's. The words before each name say what it is: after "exit" or "junction" the number, after "toward", "signs for" or "ramp to" a sign, after "for" or "onto" the road. Signs are written as the open router's are: route numbers, a colon, places ("I-5 N: Redding"). A sign that repeats the number is dropped. The reply is alwayshl=en. - Each of Google's exits within
SIGN_OFF_M(20 m) of the line goes to the tiles' exit nearest it along the line withinSIGN_ALONG_M(150 m), which takes its number, its signs and its side ("Take exit 4A toward I-5 N: Redding"). - With no step within 150 m, a tiles' exit up to
SIGN_LATE_M(400 m) past it is the same exit seen late and moves back to Google's point. With none, Google's exit is added, unless it is within a turn window of an end of the line (a hybrid stretch's neighbor may say it). - On 7 lines kept with their replies (
google_lines/<name>.exits), all 16 of Google's exits are said once: 13 matched, 2 added where the tiles had no link (Denver exit 284, San Francisco exit 423A), 1 moved back 296 m. Two sides were wrong from the bend and are Google's now. The 39 lines without replies are unchanged. - Bare turns take Google's street (
Route.stepNames,DirectionsParser.stepNames, the same[7][2]and[14]parts): every step's point, the name after "onto ", "stay on " or "becomes ", and the side from a name that is "left" or "right". A plain turn with no name (strict mode leaves the short middle of a grid jog bare, since the street does not runSTRICT_RUN_Mpast it) takes the street of the nearest unused step withinSTEP_NAME_M(25 m) that turns the same way or says no side. The route number then comes from the tiles only when they have the same street there. - A bare bend under 55 degrees with no step within
CURVE_STEP_M(40 m), where the nearest street within 30 m a turn window either side has the same name (or none), is the road curving and is dropped. Google's silence alone is not enough: from Trafalgar Square its keyless reply has one "Head toward" step for 1.1 km past a real bear-left onto Pall Mall. - This runs before the same-way merge, which also joins two turns within
SPLIT_TURN_Mwhen one took a step's street and Google has no other step at the other one (a wide corner the tiles read as two bends). - Measured on the 7 lines kept with their replies (
google_lines/<name>.names, written byNamingStudyTest.tileStepCensusfrom a<name>.rawreply beside a line;-DvelaNoStepsfor the before side): in strict mode 8 bare turns named and 3 bare slight bends on curves dropped, in lenient mode 1 curve dropped. The other 32 lines are unchanged. A Davis to El Macero reply outside the set also had a corner said twice ("Turn right", then "Turn right onto Mace Boulevard" 32 m on), now said once. - Walking ignores the name of a road bridge of tertiary class or higher, marked from
transportationbridge segments within 6 m, sincetransportation_namehas no bridge flag. - Under
MIN_NAMED_SHARE(60%) of the line named, orMIN_NAMED_SHARE_WALK(50%), the result is null. - Strict mode, used for stretches, is never refused for a low named share. It matches within
STRICT_MAX_OFF_M(12 m). A sample is unnamed when the nearest aligned street with another name is less thanAMBIGUOUS_M(12 m) farther from it than the nearest street. That other street counts at any distance, pastSTRICT_MAX_OFF_Mtoo. Both are found over every segment near the sample before either limit is applied, so the order the tiles list them in does not decide whether the other street is seen. A turn names its street only when the line stays on itSTRICT_RUN_M(60 m), a ramp or renameSTRICT_FAR_RUN_M(100 m). Refs containing "historic" are dropped.
The source is GOOGLE_LINE_NAMED when it names a whole route. Names come from RoadNameTiles:
the z14 tiles the line crosses (48 at most, 96 kept in an LRU), fetched by the app's
RoadNameTileSource, a downloaded basemap archive first, else live OpenFreeMap tiles (template
from its TileJSON, cached 6 h).
Traffic times and calibration¶
applyTraffic puts Google's times on an open-router route.
- Traffic factor: Google's in-traffic over typical duration, clamped 0.5 to 4.0. The route's
durationInTrafficSecondsis its duration times the factor. - Calibration: OSRM's free-flow model has no signal timing and runs under Google's typical on arterials. Route, leg and step durations scale by Google's typical, times the ratio of the two distances, over the open router's duration, clamped 0.5 to 3.0.
- One calibration is computed per response and applied to every open-router route in it. The
basis is the open top route when it is not
RouteGeometry.divergentfrom Google's top, else a via-snap. The hybrid is never the basis and takes no calibration: its times are Google's. - A route that does not follow Google's course (a trip with stops where Google skipped a stop
or took another way) uses
speedCal: the ratio of the two average speeds, same clamp. - On a same-course route Google's typical spread carries over, scaled by distance.
Congestion spans¶
Google's spans are [level, startMeters, lengthMeters] on its own line. A same-course route
maps them by fraction. Every other route goes through RouteGeometry.transferSpans: each span
is sampled every 25 m and projected onto the other route through a 0.005-degree cell grid
(SegmentGrid). Samples within 35 m mark that distance, and runs become spans with an 80 m gap
tolerance and a 40 m minimum. Road Google did not drive stays uncolored.
The via-snap¶
The older way to follow Google's course: sampleVias takes 12 interior points of Google's line
and routeVia routes OSRM through them (OSRM_VIA_SNAP). The code still uses it in four
places: a DRIVE route whose stitch failed, cycling on the general chain, a trip with stops
(4.4), and nameRoute. The first three require RouteGeometry.divergent (one of five points
sampled on Google's line over 700 m from the open route), and a planning fetch or an avoid.
- Twelve vias, because a via landing on a turn replaces the turn: at 60 vias about 1 in 10 named turns is lost.
- The public OSRM
/matchcaps at 10 coordinates, so it cannot do this job. - Refused when an interior via snapped over
VIA_SNAP_MAX_M(40 m), when the route ends overSNAP_REACH_M(500 m) from the destination, or when it is longer than Google's course timesSNAP_LENGTH_SLACK(1.05) plusSNAP_LENGTH_SLACK_M(400 m). - Refused on a spur (
RouteGeometry.spurAt): at leastSPUR_MIN_M(80 m) of route that advances underSPUR_PROGRESS_FRACTION(45%) of the distance traveled along Google's line. The stretch resets on progress ofSPUR_NORMAL_FRACTION(80%). The first and lastSPUR_END_SLACK_M(300 m) are exempt, and pastSPUR_LOCAL_M(200 m) from the windowed match the whole course is searched.spurWithTurnrefuses only when a turn or U-turn sits withinSPUR_TURN_NEAR_M(150 m) of the spur, since a loop ramp has the same shape without one. - It leads only when Google's live ETA is within
SNAP_ETA_MARGIN(1.2) of the calibrated open free-flow best. With an avoid on the margin is skipped.
nameRoute names a provisional alternate when it is picked: the via-snap with the same
refusals, else LineNamer over the tiles, else Google's abbreviated steps
(GOOGLE_ABBREVIATED). The route keeps its own Google time figures through naming.
Ordering and alternates¶
- Google's other routes are offered as provisional alternates (
GOOGLE_PROVISIONAL), each with its ownduration_in_traffic. - Open-router routes offered beside a hybrid: none when
RouteGeometry.divergentholds, otherwise all but its top route. With an avoid on: none. - The list sorts by
durationInTrafficSeconds ?: durationSeconds, the figure the picker displays, with named routes ahead of provisional ones on a tie. Sort key and displayed value must stay the same expression, or the "fastest" tag lands on a row that is not first. - A route whose four sampled points all lie within 150 m of an earlier route is dropped. At
most
MAX_ROUTES(4) are returned.
Step fixes on every router's output¶
RouteGeometry.consolidateExits(OSRM and Valhalla) folds the merges right after a ramp, or after a fork on it, into that step when each gap is underEXIT_COMPLEX_GAP_M(500 m). The step keeps its line and takes their length, time, road and ref. A fork on the ramp stays its own step: folded into the ramp, the exit was said and the split never was. A ramp sign listing both directions drops the one the fork after it does not take. A fork withinCHAIN_M(130 m) of the exit is said on the exit's line ("Take the exit toward ..., then keep left"). A bare exit (the language's off-ramp phrase with no number or sign,isBareExit) followed in the complex by a fork or merge with a ref or road becomes "Take the ramp toward" that ref or road, both forms. A turn with no road or ref right after a ramp shorter thanRAMP_SPLIT_MAX_M(200 m) is the ramp splitting inside its curve, and becomes a fork of the same side ("Keep right").ExitForkTest,OsrmRouterTest.aBareExitTakesTheRoadItLeadsTo,OsrmRouterTest.aBareTurnJustPastARampStartIsAKeep.RouteGeometry.foldSameRoadMergesfolds a merge onto the road the driver is already on into the step before, which takes its length, road and ref. "Already on" means the road or ref the earlier steps entered is the merge's, or the step before pointed toward it and has run more thanEXIT_COMPLEX_GAP_M(500 m). The merge at the end of a ramp is kept.SameRoadMergeTest.RouteGeometry.roundaboutModwords an OSRM roundabout fromRoundaboutGeometry.exitAngleDeg("straight" within 30 degrees), because OSRM's modifier is not the entry-to-exit turn. With no geometry a "straight" is dropped.osrmPhrasephrases "turn straight" as continue, and anotificationstep (a change of travel mode on the same way) as a continue, a silent CONTINUE when straight.RouteGeometry.bentRenames: a CONTINUE onto a road with another name, where the line turnsRENAME_TURN_DEG(60) degrees or more within 10 m of the step (StepAudit.bendAt), is a turn, "Turn left onto 2nd Street" (sharp from 135). OSRM reads a rename's modifier at the node, so a street that turns a corner into another came out "straight" or "slight" and went unsaid. A road that keeps its name round a bend, or changes it and curves 30 m on, stays silent. On the 54 stored Google lines it adds the Davis corner Google words "Turn left onto 2nd St" and, on OSRM's own route, a left from one street onto another in Boston, and nothing else.RenameCornerTest.- A ferry leg says the language's
ferry()phrase ("Take the ferry") with a straight arrow: an OSRM step with modeferry(foot) or the intersection classferry(bicycle, where the mode ispushing bike), and Valhalla's ferry entry (type 28). Leaving the ferry is a continue.FerryStepTest.
RouteGeometry.rampTurns, all three routers. A turn whose road has no name or ref, followed
within RAMP_TURN_MAX_M (600 m) by a merge onto a named road, is the turn onto that road's
on-ramp. It takes the language's ramp phrase toward the merge's ref or name ("Take the ramp on
the left toward I 80"). Type, arrow and lanes are unchanged.
RouteGeometry.stayOnForks, all three routers, after the passes below. A fork or keep whose
sign's first route (NavStrings.signParts, routeKey: I, US or a state or provincial route and
its number, however written) is the road the car is on, the end of the step before it, says so:
"Keep left to stay on I 80 West" (NavStrings.stayOn). Read as "toward" the same road it
sounded like a road to join. Only the instruction changes; the no-street form keeps "Keep left".
English only; a language without stayOn keeps its text.
RouteGeometry.foldTurnLanes, all three routers. A turn lane mapped as its own way
splits one turn in two: an unnamed slight turn where the lane leaves the road, then the turn
onto the street the same way ("Turn slight right, then turn slight right onto" a street, for one
right turn at a divided corner). A slip lane that joins the street going straight (a STRAIGHT
or CONTINUE second step) is the same turn: on the stored lines, Davis's "Turn right onto Mace
Blvd" and one in Tel Aviv. The pair becomes one TURN_LEFT or TURN_RIGHT at the first
step's place, onto the second step's road, with both lengths and times, the first step's lanes
and lights, and the second's renames moved by the first's length. Only when the first step runs
at most TURN_LANE_MAX_M (120 m), bends the line at most TURN_LANE_PEEL_DEG (45) degrees
(the 30 m before it against the lane; any angle for a slip lane, which holds the whole turn),
and the line turns TURN_LANE_MIN_DEG (60) to TURN_LANE_MAX_DEG (135) degrees across both. On the 39 stored Google lines it folds three
pairs, each a turn lane on the map: a 29 m connector off a dual carriageway, a left-turn lane
mapped beside a one-way street, and a dual carriageway's approach to a junction
(NamingStudyTest.turnLanesOnCapturedLines, and replayCapturedLines lists them). Every folded
turn agrees with the line in StepAudit, and the simulated drives flag nothing new.
TurnLaneFoldTest.
Checking a trip¶
Every hybrid logs its stretch sources and steps vs line: N turns, N agree, ... under
VelaDirections. StepAudit looks up each left or right where the step lengths put it and
expects the line to bend that way within 40 m, and expects a step within 60 m of every bend of
60 degrees or more. adb shell setprop log.tag.VelaSteps DEBUG adds the step list with each
step's source. log.tag.VelaCapture DEBUG logs Google's line for a trip. Captured lines live in
core/src/test/resources/google_lines/, and NamingStudyTest.replayCapturedLines rebuilds and
checks the route from each.
4.3 Avoids, walking and cycling¶
Avoids¶
RoutingPrefs.avoidTolls, avoidHighways and avoidFerries mirror the chooser's sticky
toggles and are seeded in VelaApp. Every fetch carries them, including the ones NavSession
makes for itself (reroute, recheck, changed stops, nameRoute), so a reroute cannot route back
through what the plan avoided. They apply to DRIVE.
- Google honors them through the pb (3.4), and its route is the avoiding one. The avoid counts
as honored only when the pb template carries the feature block (
DirectionsPb.avoidSupported). - The public OSRM rejects
exclude=for every value.OSRM_SUPPORTS_EXCLUDEis false and the parameter is never sent. With an avoid on, the open router's routes are not offered as alternates. - Google answers but neither a hybrid nor a via-snap could be built on a divergent course:
Google's own routes go out as
GOOGLE_ABBREVIATED. - Google silent and a region installed: the on-device router is tried for
AVOID_ONDEVICE_TIMEOUT_MS(4 s). The attempt runs on an unstructured scope so the timeout can abandon the search. - Google silent and no route on the phone in time: the FOSSGIS Valhalla car route with
use_tolls,use_highwaysanduse_ferryat 0 (ValhallaRouter.driveRouteAvoiding), within the same 4 s. Those are preferences, so the route is kept only when the trip summary'shas_toll,has_highwayandhas_ferryare false for what was asked. Start and end only: a trip with stops does not take this path. - The on-device car profile takes
avoid_toll,avoid_motorwayandavoid_ferriesas dynamic routing.xml parameters.avoid_highwaythere belongs to the horse-riding profile and does nothing for a car. - Nothing honored the avoid: the normal route is tagged
avoidNotHonored. The chooser shows the note only when every route carries it.
Walking¶
walkRoutes handles a walk without stops. Google is asked once, on planning fetches only, and
waited for WALK_GOOGLE_WAIT_MS (6 s). Its walk is offered, first, when it is at least
WALK_GOOGLE_SHORTER (15%) shorter than the open walk or the open router gave nothing, and
LineNamer can name it within WALK_NAME_WAIT_MS (8 s). It is never snapped: a foot route
forced through points on Google's line doubles back at each one (20 to 120% longer on Davis and
Sacramento walks). There is no traffic row for walking. Logcat VelaWalk gives both lengths.
Cycling¶
RoutingPrefs.bikeSafe is on by default. bikeSafeRoutes tries the on-device bicycle profile
when a region is installed (BIKE_ONDEVICE_TIMEOUT_MS 6 s, BIKE_ONDEVICE_URGENT_MS 3 s),
then Valhalla route with costing: bicycle, use_roads 0.1, use_hills 0.5 and
bicycle_type Hybrid. Valhalla maneuver types map into the OSRM grammar (osrmGrammar) and are
phrased by osrmPhrase, so voice, banner and step list match every other route. These routes
carry no Google traffic. With the setting off, or when neither answers, routed-bike runs
through the driving chain without the hybrid.
4.4 Multi-stop¶
directions(origin, dest, mode, waypoints) returns one route for a trip with stops. Neither
router offers alternates for one.
- Google is asked for the trip through the stops.
DirectionsPb.withWaypointsadds one top-level!1m4!3m2!3d<lat>!4d<lng>!6e2group per stop between the origin and destination groups, with no count to change. - The open router is routed through the stops with
routeVia. The arrive and depart at each via fold into the step before, so the trip reads as one leg. RouteGeometry.stopsOnLinedecides whether Google honored the stops: each withinSTOP_ON_LINE_M(250 m) of a vertex of its line, in trip order. A reply that missed one is the direct trip and only calibrates speed (speedCal).
| Case | Result |
|---|---|
| Google honored the stops, same course | The open route with Google's time and spans |
| Google's course diverges (planning, or an avoid on) | The open router snapped along Google's line leg by leg (sampleViasThrough: 12 samples per leg with the real stop between them). Stops are exempt from the via-snap distance refusal (looseVias). Kept under the reach, length, spur and ETA-margin rules of 4.2 |
| Avoid on, no usable snap | Google's route through the stops, GOOGLE_ABBREVIATED |
| Detour not worth it, or Google missed a stop | The open route with speedCal and transferred spans |
| Open router silent | The legs chained on the device (chainOnDevice), else Google's route, abbreviated |
During a drive:
NavEngine.stopMarks(route, stops)projects each stop onto the line in order. A stop overSTOP_ON_ROUTE_M(150 m) from it has a null mark.NavSessionholds the stops, the marks and a passed counter, and speaks one cue per stop when progress comes withinSTOP_ARRIVE_TOL_M(25 m) of its mark.- Rechecks fetch with
stops.drop(passedStops), so a traffic re-check never pulls a drive off a saved route or a camera detour. A reroute after leaving the route drops the silent stops and fetches through the real ones only: the driver is taken on from here, not back to the stretch just left. For a saved route (plannedWayName) that is said once,NavStrings.leftYourRoute, with a status card naming it (onLeftPlannedWay). - A stop with a null mark counts as passed only when a later stop with a mark is passed
(
NavEngine.stopsPassed). A stops edit, or a reroute that could not fit the stops, therefore keeps them all. With no later mark, it is reached when the car comes withinSTOP_NEAR_PIN_M(250 m) of its pin: the middle of a mall or a park gets no mark, and without this such a stop stays ahead for good. The rule is off between a stops edit and the route for the new list. - The cues and the skip test act only while the engine's route is the very object the marks
were measured on (
planRoute).applyEnrichedRoute(base, lit)therefore replaces_state.route,planRouteand every other reference tobasetogether, and does nothing unless both still arebaseand no reroute is in flight. - Progress that jumps more than
STOP_SKIP_JUMP_M(250 m) past the next stop in one fix, faster thanSTOP_SKIP_SPEED_MPS(70 m/s), is a skip (NavEngine.stopSkipped). Ground covered over a pause or a GPS gap is slower than that and counts as driven. The session holds the stops and reroutes through them each fix until a new route lands. That reroute is not put through the back-on-course test, which discarded every answer because the car had never left the line. A jump that only passed silent stops is not a skip (onlySilentSkipped): the driver went another way round the stretch a saved route or a camera detour was built through, and those points count as passed. NavSession.setStopsis the one replan entry;addStopdelegates to it. It ignores the reroute cooldown, and the new list is the plan at once, so a failed fetch keeps it.MapViewModel.applyStopscalls it only when the list differs fromNavSession.remainingStops().NavSession.State.nextStop(NextStop: label, distance, seconds) is published with every fix, atstart, and with every route swap (seededNextStop: a reroute, a faster route, a healed one, a stops edit), measured from the new route's start, so the figures never show the old route's stop. A stop added or the stops edited mid-drive clear it at once; the new one shows when its route lands. The stop is the first one not passed and not silent (nextStopIndex); null when there is none, when that stop has no mark, or when the engine's route is notplanRoute. The distance is along the line to its mark. The time is the engine's remaining time lessNavEngine.secondsBeyond(route, mark)(the same per-maneuver pro-rating and traffic ratio as the whole trip, so it reaches zero at the mark), times the leg's own scale, timesetaScale; neither figure can exceed the trip's. The scale (NavEngine.legScale) is the leg's own time over the pro-rated time of the same leg, when the route carries its legs' times (Route.legTimes: Google answers a trip asked through stops with each leg's distance, typical and in-traffic time atroute[1][j][0], read byDirectionsParserand kept through the hybrid and the traffic overlay; the on-device chain keeps each leg's time) and a leg boundary lies withinNavEngine.LEG_MATCH_M(250 m, or 1.5% of the line) of the mark (legEndingAt); the leg starts at the marked stop before, silent vias included, or at the route's start. So the countdown starts on Google's figure for that leg, traffic where it sits, and still counts down with the trip's own reckoning; a constant leg figure subtracted from the shrinking remaining time did neither (review 2026-10-10). The scale is held to 0.25 to 4. The closing-time check'sstopArrivalsreads the legs up to the stop (legSecondsTo), else the pro-rating. The trip file'sRDline sayslegs=Nwhen the route had them.- With a
nextStopthe bottom bar (NavBarTop, also the step sheet's header) shows the stop's time, distance and arrival clock as its main figures and "To" under them, and the step a line under that with the whole trip, "Trip - The ongoing notification and Android Auto show the same stop: the notification's line is the
stop's time, distance and arrival with "To
" after them, and the car's travel estimate is the stop's (named with TravelEstimate.setTripTextfrom car API 5), itsTriplisting the stop and then the trip's end as destinations in order of arrival.
Step sheet: NavStopsRow always leads it. With no stops ahead it reads "Edit route" and opens
the stops editor. With stops it also offers "Remove next", which after a VelaDialog confirm
calls applyStops(stops.drop(1)). Title and buttons share a line only when they fit, measured.
The mid-drive editor's Add stop applies pending edits, closes, and opens the along-route search
(NavSearchChips); a pick joins the drive through addStopDuringNav, which puts it LAST among
the stops still ahead (NavSession.addStop(atEnd = true)): the editor can drag it into place,
and a stop that jumped the queue could not be undone without it. The tapped-place card's
"adds N min" prices the drive with the place last too. The planning pick (beginPickStop) is
not used during a drive, because the search page is never drawn then.
Closing-soon warning (NavController.maybeWarnClosingSoon, at nav start): each stop ahead is
checked at its own arrival, then the destination. Only the first place that closes within 60
minutes after arrival, or before it, is spoken. A trip with stops arrives as one leg, so a
stop's arrival is the trip's time scaled by the stop's along-route fraction (stopArrivals). A
stop added during the drive is checked on the replanned route, waited for up to 20 s.
4.5 Offline routing¶
ObfRouteEngine runs OsmAnd's Java router and binary reader over .obf region files. The same
files answer the posted speed limit (currentRoadLimit) and supply romanized road names
(Route.roadNamesLatin). Profiles are car, bicycle and pedestrian.
Data and selection:
- Region files are baked off-device (
scripts/build-obf-region.sh,VelaObfShim) and hosted as release assets with a manifest. The catalog istools/routing-regions.json. - The router gets every installed region whose box intersects the trip's padded box (a quarter
of the span each way, 0.27 degrees at least). Both ends must fall inside a candidate's box, or
the engine returns empty and the caller goes online.
coversis that test without opening a file. - A box can hold a trip its data does not. A trip is refused when either end has no road within
ENDPOINT_SNAP_M(2 km), tested before the search and on the route found. Without the test the router joins the nearest roads it has, tens of kilometers from each end. index.jsonis parsed once and kept until the file changes.coversandcurrentRoadLimitare asked several times a second during a drive.
Memory and highway hierarchy (HH):
MEMORY_MBis 256, because the app already runs near itslargeHeapceiling. Past its budget the plain search throws. Car profile on a desktop at 256 MB: 57 km in 5.65 s, 151 km fails. The threshold depends on the region.- The bake adds OsmAnd's precomputed shortcuts to each region file (
bake_obf_hhinscripts/bake-lib.sh:hh-routing-prepare,hh-routing-shortcuts, thenBinaryInspector -ccombines the section into the file). The manifest row carrieshh: true. A region the step fails on ships without it (hh: false). ObfRouteEnginecallssetDefaultHHRoutingConfig()for DRIVE and BICYCLE. The router falls back to the plain search when a file has no HH, when the trip spans two files, or when the HH answer is not correct.- Measured on a dense 136 MB state file at 256 MB: a 256 km car trip runs out of memory after 27 s on the plain search and takes 0.5 s in 32 MB with HH. On a Pixel 4a the Delaware file routes 148 km in 0.7 s using 71 MB.
- Car sets: default and
avoid_motorway(--routing_params=---avoid_motorway). The router picks the set matching the avoids and filters it for tolls and ferries. A file with only the default set fails an avoid-highways trip on HH and falls back about a second later. The default set is about 3.5% of the file, the second about 2%. - Bicycle set:
--routing_profile=bicycle, best effort, about 9% of the file. A region it fails on keeps the car sets. Without it a bike route loses 0.1 to 0.6 s before the fallback. - Walking has no set and stays on the plain search, which failed past about 28 km on that state
file. Grid cells (
build-cells-region.sh) get no HH. - HH asks
OsmandRegions.getRegionsToDownloadwhich regions hold the trip's ends. Vela ships no world-regions index, so its stub returns an empty list, which HH reads as no restriction.
Engine rules:
ObfRouteEngine.spokenTypemaps a turn OsmAnd marksskipToSpeakto CONTINUE, which folds into the previous maneuver as a rename. The router emits such a turn where a road only bends. A left or right with underSTRAIGHT_TURN_DEG(20) of measured turn is a CONTINUE too. Roundabouts keep their type.- The departure heading reaches the engine as
RoutingConfiguration.initialDirection, in compass radians. - A caller that waits a bounded time passes it as
route(maxMs =). Past it the engine setsRouteCalculationProgress.isCancelled, which both OsmAnd planners poll, and returns empty. Time spent waiting for the engine's lock counts. This keeps an abandoned search from holding the lock against the speed-limit lookup and the next reroute. Planning with no network passes no limit.ObfStopProbeTest(-DvelaObf=<dir with delaware.obf>).
Android runtime requirements, all set before any OsmAnd class loads:
- commons-logging is pinned to
SimpleLog. R8 strips the implementation and its reflective discovery fails on ART. kxml2-vela.jaris upstream kxml2 without its bundledorg/xmlpull/**, which duplicates platform interfaces and fails R8.PlatformUtil.setOsmandRegions(OsmandRegions(false))andRoutePlannerFrontEnd.CALCULATE_MISSING_MAPS = false. OtherwisesearchRouteloads a world-regions index from the working directory, which is read-only on Android.
4.6 The navigation loop¶
Each fix that reaches NavSession.onLocation runs in this order: project it onto the route
(NavEngine.update), advance the step, recompute remaining distance and time, act on the events
(speak, vibrate, arrived, reroute), announce a stop just passed, consider a recheck.
Fixes¶
- Guidance takes GPS fixes only, with accuracy of 50 m or better.
- A network fix moves the dot only when GPS has been quiet for
NETWORK_FIX_QUIET_MS(12 s) and it beats the last fix aged (FixRules.betterThanLast: the last fix's accuracy radius grows by max(5 m/s, speed) per second of age). - A fix at least twice as accurate as the one showing, itself 50 m or worse
(
FixRules.isUpgrade), skips the outlier hold and the low-pass, so the first GPS lock lands at once. A GPS fix that follows a GPS fix does so only when it lands within twice the shown fix's radius: under poor sky a receiver's accuracy figure halves and doubles from fix to fix, and a multipath leap taken as is becomes the position the outlier hold then keeps against the next good fixes. A first lock sharpening on a phone with no network location still lands at once. - Guidance steers by the fix itself. The speed-adaptive low-pass in
sanePositionis the dot's: under 10 m/s it trailed the car by up to 12 m while the course handed beside it was fresh, and it marked every slow fix as not the fix's own, so slow driving started no recheck. Only an outlier hold steers with the held position (fromFixfalse). - Time between fixes comes from
elapsedRealtimeNanos.loc.timemixes GNSS UTC with the system clock. - A fix wider than
Stillness.ACC_TRUST_M(30 m) underStillness.SLOW_MPS(3 m/s) says nothing about direction: its course and the course derived from the last fix are not taken, and the heading holds. On such a fix the course drifted 20 degrees on a straight approach to a light (issue #818). - A speed under 3 m/s on a wide fix, or on any fix while the phone is at rest, reads as 0: a
parked car's 0.7 m/s showed as 1.5 mph on the tile (issue #819). At rest is
core/location/Stillness: the accelerometer, sampled every 100 ms over 15 samples while a drive is on (held by the view model for the phone's drive and by the car renderer for its own), with the magnitude's standard deviation under 0.25 m/s². It is only consulted below 3 m/s: at speed a steady cruise and rest look alike to it. - The provider registration keeps
minDistanceM = 0. A distance filter delivers nothing at a standstill. - A measured speed more than 8 m/s² × dt + 5 m/s from the last accepted one is rejected once.
The second such fix in a row is accepted (
gateMeasuredSpeed).
Progress and off route¶
Progress is the projection of the fix inside the window from 60 m behind to 600 m ahead of the
progress so far, scored by distance plus ANCHOR_PENALTY (2 cm per meter of along-route
distance from that progress), so on a road driven out and back the pass being driven wins. It is
accepted within ON_ROUTE_M (60 m). Outside that the whole route is searched with the same
penalty, and a jump over REACQUIRE_JUMP_M (1,500 m) must repeat for three fixes. Otherwise
progress holds. Off-route distance is the distance of that projection, never the whole route's
nearest point.
NavEngine.offRouteCorridor(mode, accuracyM) scales the corridor with the fix's accuracy,
clamped to 3 to 40 m and taken as DEFAULT_ACC_M (12 m) when absent. farOffDistance is twice
the corridor, capped.
| Mode | Corridor | Clamp | Far cap | Moving floor |
|---|---|---|---|---|
| Drive | 18 + 2.0 × accuracy | 24 to 70 m | 110 m | 2.0 m/s |
| Bicycle | 12 + 1.9 × accuracy | 18 to 55 m | 75 m | 1.0 m/s |
| Walk | 8 + 1.8 × accuracy | 15 to 50 m | 60 m | 0.6 m/s |
At 12 m a car gets 42 m and 84 m. OFF_ROUTE_M (40 m) and FAR_OFF_M (90 m) are only the
NavEngine.update defaults that tests and replays use.
OFF_ROUTE_HITS(3) hits request a reroute. A fix inside the corridor on the route's heading clears the count.- A fix outside the corridor is one hit while moving. Below the moving floor it counts only beyond the far distance, so drift at a red light does not reroute and a crawl out of a parking lot does.
- A moving fix beyond the far distance is two hits.
- A moving fix whose course is more than
HEADING_OFF_DEG(60) off the route's local bearing is a hit even inside the corridor, and two when it is also a quarter-corridor off the line. It never counts toward the on-route streak. Driving, the course counts only fromHEADING_MIN_MPS(5 m/s) and from a fix ratedHEADING_MAX_ACC_M(30 m) or better (headingMinMps; walking and cycling keep their moving floor). A car pulling away from a light between tall buildings was read crawling backward along its own route at 2.7 to 3.9 m/s for three fixes, on the line, and was rerouted three times in 50 s. A course within 60 degrees of the route's bearingHEADING_NEAR_M(25 m) ahead or behind is not against it. Mid-turn the course has swung while the fix still projects before the corner, or not swung enough once it projects past it, and a right turn from a stop, taken as told, rerouted 3 s later (real drive 2026-11-17). A wrong turn points away from the road on both sides of the corner and still counts. - No reroute fires while both the route left and the straight-line distance to the destination
are under
DEST_ZONE_M(150 m). The request is held until the car leaves that zone. - Turn prompts are muted while off route.
Guidance¶
- Prompt distances scale with speed v: far
max(400 m, v × 35 s), nearmax(150 m, v × 10 s), each rounded to 50 m, and turn-nowv × 2.5 sclamped to 25 to 90 m.spokenstores band slots, so each prompt speaks the true distance. - In
FULL, any maneuver atSpokenDetail.FAST_MPS(22.2 m/s, 80 km/h) or more, and a ramp, fork, keep, U-turn (SpokenDetail.exitLike) or turn onto an on-ramp (NavEngine.onRampTurn: a nameless turn whose next spoken step, within 600 m, is a merge) atEXIT_ONE_LINE_MPS(15 m/s) or more, has one approach line instead of two (oneApproach):bandsForgives both slotsmax(near, v × FAST_APPROACH_S),FAST_APPROACH_S15 s ("In a quarter mile" from 50 to 80 mph), so they are said together. Then comes the turn-now line. Far, near and turn-now made eight lines of one exit, the fork on its ramp and the merge after it, and a car near 50 mph got far, near and turn-now or one line by turns. - "How much the voice says" (
SpokenDetail, Settings, Voice) has three values.FULLis the lines above.BRIEFsays each maneuver once, in its short form with no street name: a ramp, fork, keep or U-turn at the far distance and keeping its exit number, any other maneuver at the near distance, and nothing at the turn.EXITSisBRIEFfor ramps, forks, keeps, U-turns and the arrival only; any other maneuver is spoken only atSpokenDetail.FAST_MPS(22.2 m/s, 80 km/h) or more, and roundabouts and merges never. The buzz at a turn is kept in every value, andupcomingPromptsprepares the same lines. - The step advances at
v × 2.5 sclamped toADVANCE_MIN_M(5 m) to 90 m, so at a crawl or a standstill the card and the road name stay on the turn in hand until the car is at it. The turn-now line is still said 25 m out, once (TURN_NOW_SLOTinspoken). Both used to happen 25 m out: a car waiting at a stop line 20 m short of a left turn was shown the turn after it. - A step's first prompt carries lane guidance. Its approach repeats speak
NavStrings.repeatShort. Its line at the turn, and a "then" that names it, speakrepeatWithRoutefor a ramp, fork or keep: the head and the first route number on its sign ("Keep slight right toward US 50 East"), so the voice names the road the banner shows where the choice is made. A sign with places only says the head alone. English marks the sign with " toward "; the other languages have no override and sayrepeatShort. A "then" leaves out a route its own line just named ("Keep slight left toward I 80 West, then keep slight left"). A merge is said once: its near-band line, or the "then" of the step before it. At the merge itself it only buzzes. Arrival gets one near-band cue. - In English a lane clause on a ramp of the same side drops the ramp's side: "Use the right lane to take the ramp toward ...", not "... the ramp on the right toward ...".
- A band the car would reach within
BAND_MERGE_S(8 s) of a prompt, at the fix's speed with aMIN_PACE_MPS(1.5 m/s) floor, is taken as said by that prompt: entering a step 170 m before its turn at 13 m/s said the line, and the 150 m band said it again three seconds later. - The turn-now line interrupts whatever is playing. A first prompt that could not end before the
car reaches the turn-now point (
SPEECH_CPS13 letters a second plusSPEECH_LEAD_S0.6 s) keeps its lane clause and drops the sign tail, as a repeat does: a 78-letter ramp line said 107 m before the ramp at 15 m/s lost its "toward" half to the line at the turn. - The next stop is said coming the way the destination is.
NavSession.stopAheadForhands the engine aStopAhead(mark, name, side, lot flag) for the stopnextStopIndexpicks, only while the engine's route isplanRoute. The last spoken maneuver before the stop (NavEngine.stopLegManeuver, a silent continue passed over), when the stop is at mostSTOP_THEN_M(300 m) past it, says it after itself on its first line and on its turn-now line:NavStrings.thenStop, "Turn left onto Covell Boulevard, then Davis Food Co-op will be on your right". That line takes no traffic-light lead. Otherwise the stop gets its own line at the near distance,NavStrings.stopAheadininThen("In 150 meters, Davis Food Co-op will be on your right"): once per stop (NavState.stopCuedAtM), never off route, never in a fix that already speaks, never within 50 m.BRIEFputs the clause on the maneuver's one line;EXITSsays the stop's own line, as it says the arrival's. - The side is
NavEngine.stopSide: where the stop's pin sits against the line's direction through its mark, read 25 m either way. It is null ("will be ahead") when the pin is withinSIDE_MIN_OFF_M(8 m) of the line or the line bends more than 45 degrees through the mark. - The turn into the stop's parking lot. A way into a lot ends with the turn off the street and
often a turn or two between the aisles, all bare.
NavEngine.lotTurnsBefore(route, mark)lists the lefts and rights onto a road with no name and no number that run unbroken up to the stop's mark, at mostLOT_DEST_TURNS(3), none more thanLOT_DEST_BACK_M(400 m) before it, earliest first.NavSession.lotTurnchecks them in that order withParkingLotTurn.entersLot, which reads the map's z14 tiles along the route (RoadNameTiles.roadsAlong, thetransportationlayer'sclassandservice), every 8 m from 10 m past the turn for up to 60 m or to the stop. Every sample's nearest car road within 12 m has to be a service road that is not an alley, and one aparking_aisle. The first turn that passes is the turn into the lot (StopAhead.lotTurn): its lines readNavStrings.intoLot, "Turn left into the parking lot", and when it is also the last turn before the stop,NavStrings.intoLotThen, "Turn left into the parking lot, then Davis Food Co-op is on your right". No router marks a parking aisle, so this is the only source. One lookup per route and stop, in the background, withinLOT_LOOKUP_TIMEOUT_MS(8 s) a turn; until it answers, or when the tiles cannot be read, the plain wording stands. - The end of a trip gets the same test against the destination, when the route is planned
(
ParkingLotTurn.wordDestination, DRIVE only, fromGoogleMapsDataSource.directionsandnameRoute). The candidates areNavEngine.destinationLotTurns,lotTurnsBeforeto the end of the line. The first one whose way on the tiles show entering a lot is the turn off the street: itsinstructionandinstructionNoRoadbecomeNavStrings.intoLot, "Turn left into the parking lot"; its type and place stay, and the turns after it keep their plain words. The step carries the words, so the banner, the step list, the voice and the car say them, andmadegainslotTurn. The tiles round the destination are asked for when the fetch starts (not in low data mode), and the built route waitsLOT_WORD_WAIT_MS(1.2 s;LOT_WORD_WAIT_URGENT_MS0.3 s) for the answer, on the IO dispatcher (the tiles' protobuf is decoded there) and for every route of the answer at once. A route with abbreviated steps or a provisional alternate is left alone. stopAhead,thenStopandintoLotThenare in everyNavStringstable, with a blank name read as "your stop".- Two turns within
CHAIN_M(130 m) of each other along the road are said on one line (NavEngine.chainedNext,NavStrings.thenNext): "Turn right onto Elm Street, then turn left onto Oak Avenue", on the first turn's first line and on its line at the turn. The second turn's approach lines are then not said (NavState.chainedStep); its line at the turn is, unless the line at the first turn named it in the same words and its own would come withinCHAIN_REPEAT_S(5 s) at the current pace (chainRepeatsSoon, slotTURN_NOW_SAID_SLOTinchainedBands). Then it only buzzes: at 25 m/s two forks 45 m apart said "keep slight right" twice in two seconds. Not on a line with lane guidance, a stop or a traffic-light lead, and never onto the arrival.thenNextexists in 13 languages; Dutch, Swedish and Japanese have none yet and say the two turns apart, as before. The chained line is not amongupcomingPrompts, so the voice renders it when it is spoken. - A next step past
CHAIN_Mbut withinTHEN_SOON_M(500 m), whose first approach line would fire as the first turn is made (the far band plusBAND_MERGE_Sof travel,dueNext), rides on the first turn's line at the turn only: "Take the ramp, then keep slight left". Its bands the car reaches withinBAND_MERGE_Sof the turn count as said (NavState.chainedBands); a later one is still said; a merge named this way counts as said. A "then" says the step's lanes (withLanes): "Take the exit toward US 50 East, then use the left lane to keep slight left". Not onto a roundabout, and never from a roundabout. - The chained line at the first turn has to end before the second turn's own line, which
interrupts (
turnNowLine): the time to the second turn's turn-now point at the current pace againstSPEECH_CPS(13 letters a second) plusSPEECH_LEAD_S(0.6 s). When the whole line will not fit, the first turn drops its street ("Turn right, then turn left onto Oak Avenue"), then the second does ("Turn right, then turn left"); that last form is said even when it will not quite fit. A first turn with no form without its street, or a lot line, is said alone. At 14 m/s a pair 60 m apart loses the first street, at 16 m/s both (NavEngineChainTest). - CONTINUE and STRAIGHT are silent unless their lanes show a real fork
(
continueHasGenuineFork). The DEPART maneuver is spoken once byNavSession.startand skipped by the engine. - A roundabout's exit step right after its entry is silent too (
NavEngine.ringExit): both carry the same words, so it spoke the roundabout twice, its line at the exit cut the entry's off inside the ring, and as the entry's "then" it named the same roundabout again. The chain, the stop leg and the prepared prompts pass over it (NavEngine.quiet). An exit step after anything but its entry (a route that starts in the ring) still speaks. The drive camera still frames the exit (NavTurnTarget). - A roundabout said at its near band by its own approach has no line at its entry, only the
buzz: the words would be the same, about 10 s later, while the driver is yielding. The entry
line still comes when it carries the step after the roundabout (a "then" or a due step), or
when the roundabout was only said as another turn's "then".
upcomingPromptsleaves it out too. - Maneuvers more than
PASSED_SLACK_M(75 m) behind are caught up silently. - Traffic-light guidance (Settings > Navigation, pref
nav_traffic_lights, off by default, English only). With it on,NavController.lightCueslooks up the signals along each route the drive takes up andRouteGeometry.enrichWithLightsmarks them on the plain left and right turns they come before (Maneuver.lightsBeforeM, meters before the turn): signals withinLIGHT_APPROACH_M(400 m) of the turn andLIGHT_SNAP_M(25 m) of the line, one per junction (LIGHT_CLUSTER_M, 30 m), never the turn's own. The marked copy goes to the session throughapplyEnrichedRoute; it has the same line, so the route observer writes no trip block and fetches nothing again. Instruction text is not changed. When an approach prompt is spoken,NavEngine.lightLeadcounts the lights still at leastLIGHT_AHEAD_MIN_M(20 m) ahead of the car and puts "Pass the traffic light, then" (or "Pass 2 traffic lights, then") in front for one or two. A lane prompt, the turn-now line and the arrival cue never take it. The signals come from the downloaded road features. Where no region is downloaded the public Overpass server is asked for the first route of a drive only. With the switch off nothing is looked up. LogcatVelaDirectionsprints how many steps got a light, how many stops have been passed each time one is counted, and every route the drive adopts (at the start and each swap) with its typical and live time, the sum of its steps' times, and its leg times when it has them: the figures the bar shows come from these. - Arrival fires within
ARRIVE_RADIUS_M(25 m) along the route of the arrive maneuver, withinARRIVE_PROX_M(40 m) straight-line of it, or with under 50 m of route left while stopped and within 60 m straight-line. Those three run on the last step. On any step, a car stopped withEND_PARK_ALONG_M(60 m) or less of route left and withinARRIVE_PROX_Mof the end, forPARK_STILL_FIXES(10) fixes in a row (NavState.stillFixes), has arrived: the step does not move on at a standstill, so a car parked short of a last turn into a lot never reaches the last step. The count keeps a car waiting to turn in from arriving at the entrance. - The arrival line is "Your destination is on the left/right" when the arrive step has a side,
else "You have arrived". OSRM and Valhalla put a side on their arrive step; the on-phone router
and a route named from Google's line do not, so
NavEngine.withArrivalSidegives one where a route enters the session (NavSession.start, anddriveablefor every reroute, recheck and stops replan): the destination pin against the line's lastSIDE_SPAN_M(25 m), asstopSidereads a stop, and the step's words say it. A pin withinSIDE_MIN_OFF_M(8 m) of the line, or an arrive step that has a side, is left as it was. - The destination's approach prompt reads the same side (
NavStrings.destinationWillBe): "Your destination will be on the right", or "will be ahead" with no side. Said "ahead", it contradicted the arrival line that named a side. - ETA sums the remaining step durations, the current leg pro-rated, times the route's traffic
ratio, then times
etaScale. It is never remaining distance over average speed, unless the steps carry under 70% of the route's duration. So every fold of one step into another (a via's boundary steps and an exit complex inRouteGeometry, the on-device chain's leg joints, renames) keeps the folded step's time as well as its length; a via's DEPART carries the minutes from the stop to the next turn, and dropping it ran a trip through one stop a fifth short (2026-10-10). - Turn card shields (
roadSigns,ui/nav/NavOverlays.kt): the exit tab, the maneuver's own ref and every route number in the instruction text, deduplicated byrouteKey(letters and number; spaces, dashes and a trailing direction dropped), three at most. The card's "then" row skips a roundabout's own exit step and shows the maneuver after it at the summed distance. - Turn glyphs come from one table,
maneuverGlyph(ui/nav/ManeuverGlyph.kt), for the turn card, the step list, picture-in-picture, the notification and Android Auto (NavGlyphs). Ramps, forks and keeps draw the slight-left or slight-right arrow: a glyph that also drew the branch not taken read as a sign allowing either way. Merges keep the merge glyph and roundabouts their ring.
Rerouting¶
REROUTE_COOLDOWN_MS 10_000 minimum gap between adopted reroutes (a recheck's heal does not count)
REROUTE_FETCH_TIMEOUT_MS 20_000 an urgent attempt's deadline
REROUTE_LADDER_TIMEOUT_MS 40_000 an escalated attempt's deadline
REROUTE_ESCALATE_AFTER 2 failed urgent attempts before the full ladder
REROUTE_STUCK_GRACE_MS 5_000 past deadline plus this, a running job is abandoned
REROUTE_FINISH_RESERVE_MS 4_000 kept from the deadline for naming and adoption
REROUTE_NAME_SLACK_MS 500 naming gives up this long before the deadline
REROUTE_SPEAK_MIN_MS 30_000 "Rerouting" is spoken at most this often
REACH_TOLERANCE_M 500 an adopted route must end this near the destination
BACK_ON_COURSE_HITS 2 consecutive on-route fixes that discard a reroute
URGENT_OSRM_TIMEOUT_MS 6_000 the one urgent OSRM call
URGENT_GOOGLE_GRACE_MS 2_500 urgent wait for Google once OSRM answered
URGENT_DEFAULT_BUDGET_MS 16_000 an urgent fetch given no budget
PHONE_FIRST_ONLINE_WAIT_MS 2_500 urgent wait for OSRM before the on-device route is taken
PHONE_FIRST_ONDEVICE_WAIT_MS 4_000 how long past that the on-device search may still take
LADDER_OSRM_TRY_MS 8_000 one escalated OSRM try
LADDER_OSRM_SHARE 0.55 share of an escalated budget OSRM may spend
LADDER_SNAP_RESERVE_MS 6_000 an escalated fetch stops waiting for Google this early
REACH_S 5.0 a driving reroute's first turn must be this many seconds away
REACH_MIN_M 25 and never closer than this
LATE_TURN_PAST_M 10 an ask again waits until the car is this far past that turn
LATE_TURN_ASKS 2 asks again for one reroute when its first turn is out of reach
LATE_TURN_MIN_LEFT_MS 1_500 deadline an ask again must leave after its wait
REROUTE_COOLDOWN_UNJOINED_MS 3_000 the gap after a reroute whose route the car never joined
JOINED_M 50 meters along an adopted route that count as joining it
BACK_ASKS 2 asks again for one reroute whose route turns the car round where it is
BACK_ASK_WAIT_MS 3_000 the wait before each of them
BACK_ASK_MIN_MPS 4.0 only while the car moves at least this fast
HELD_COURSE_MAX_M 25 a stopped car keeps its moving course this far from where it showed it
TRACK_KEEP_M 300 the car's own track kept for the turn-round test
NavSession.rerouteGateallows one fetch at a time and enforces the cooldown. A job older than its deadline plus the grace is abandoned and a new one starts. The fetch runs on an unstructured scope:withTimeoutOrNullcannot interrupt a blocked socket read or the on-device search, and a fetch stuck there would otherwise block every later reroute.- A failed fetch clears the off-route latch on the location thread, and so does a request the cooldown turned away, so the next deviated fixes ask again.
- The first
REROUTE_ESCALATE_AFTERattempts are urgent: one try per source, a budget of the deadline minus the finish reserve, shorter hybrid waits, no lane detail, and no via-snap unless an avoid is on. After that the three-try ladder runs under the longer deadline. The failure streak resets on any adopted route and on session start and stop. - Phone first: when
RouteEngine.covers(origin, destination, mode)is true, an urgent fetch starts the on-device route beside the open router and adopts it when the open router has not answered withinPHONE_FIRST_ONLINE_WAIT_MS. The on-device search getsPHONE_FIRST_ONDEVICE_WAIT_MSmore, then the fetch goes back to waiting on the open router. A trip with stops chains its legs the same way. The adopted route is offline and trafficless, so the recheck heals it. On such a fetch the open router's call runs outside the fetch's scope (abandonableAsync): a scope returns only when its children have finished, and as a child the blocked call would hold the phone's route for the rest ofURGENT_OSRM_TIMEOUT_MS. The call is canceled when the fetch returns or is canceled, and ends at its own timeout. - When the open router gives nothing,
RerouteFallback.picktakes Google's route if it is already back, otherwise races Google against the on-device router inside the remaining budget. Google's routes are taggedGOOGLE_ABBREVIATED. A fallback's routes, and the phone-first routes above, are one router's answers alone: on a reroute the one that turns the car round least leads while it costs little more (RouteGeometry.leastTurning, theturnRankand allowance of the turn-round rules below), and theirRClines carry the same flags. The adb switchdebug.vela.tune.openRouterDownat 1 (read at launch,RouterTestHooks) makes the open router answer nothing, to try these paths on a test phone. - A reroute pins its departure heading. OSRM gets
bearings=<heading>,65for the first waypoint and an empty entry for every later one; the count must match the coordinates or the request is rejected. Planning fetches and stationary fixes send none, and neither does a fix under the heading term's speed or accuracy (NavSession.departCourse), so a reroute from a crawl is not told the car points the way GPS drift says. - A reroute that names a provisional Google route (
NavSession.driveable,nameRoute) pins the snap's departure the same way, and leaves out the samples withinVIA_ORIGIN_CLEAR_M(150 m) of the origin (RouteGeometry.snapVias): they sit on Google's own start, which Google chose with no heading. An unpinned snap began a reroute on a cross street, round a block, across the road the car was on. - Google's request carries no heading. On a fetch that has one, a Google route whose first 80 m
run more than 120 degrees off it (
RouteGeometry.startsAgainst, measured at the point 80 m along the line, not the first vertex past it) is set aside when the open router answered, so the hybrid cannot tell a moving car to turn around. So is one that backs up: a point of its first 60 m more than 12 m behind its start along the heading (RouteGeometry.startsBehind), a U-turn to the street just passed that then turns off it, which reads as sideways at 80 m. A reroute also passes the car's own track (behind, the lastTRACK_KEEP_Mof trusted fixes), and a route that runs 30 m or more back along it, within 25 m and more than 135 degrees off the way the car drove it, in its first 400 m turns the car round too (RouteGeometry.goesBack): a U-turn onto either side of the road, or the way round a small block back to a missed turn, which starts the car's way and passed the heading test. A loop ramp never comes back onto the road driven and is not caught. The track starts where the car last turned round (RouteGeometry.sinceTurnRound): its newest stretch more than 135 degrees off the car's course, and everything before it, is left out. Kept whole, the track of a car that had made its own U-turn read every route on back down the road as turning it round again, and the reroute waited out both back re-asks. Both routers' routes are tested (forwardPick) and ranked (turnRank): one that goes on beats one that turns the car round further on (round a block, back from the next exit), which beats one that turns it round where it is (startsAgainstorstartsBehind), while it costs no more than the allowance below over the best. When the open router's best turns round, the lowest-ranked of its alternates within that allowance leads, and Google's best is set aside only for an open route ranked below it.forwardChoicelimits what that may cost: a Google route of a lower rank withinFORWARD_MAX_EXTRA_S(180 s) orFORWARD_MAX_EXTRA_SHARE(8 percent) of the best one, else the open router's route when it is that close without traffic, rank by rank, else the best route, turn-around and all. The open router's time is first put on Google's clock (its length at the best route's average speed, factor held to 0.5 to 3), because its own free-flow time runs fast. The open router's route taken that way keeps the set-aside best route's clock and traffic (applyTrafficwithspeedCal, spans carried where the roads are shared), as a trip through stops does when Google's detour is not taken. Without them its ETA stayed short until the recheck's heal. - A driving reroute's first turn must be one the car can still make. A turn, sharp turn, U-turn,
roundabout entry, ramp, exit, fork or keep (
NavSession.firstTurnAheadM,PLACED_STEPS; a ramp or a fork needs the car in its lane) underREACH_Sseconds away at the newest trusted fix's speed, and never underREACH_MIN_M, is out of reach (turnOutOfReach, only atHEADING_MIN_MPSand up). The first line is said after "Rerouting", a second or more after the route lands. The fetch then waits until the car isLATE_TURN_PAST_Mpast that turn at its speed (lateTurnWaitMs, under 7 s) and asks again from the newest trusted fix and its course, up toLATE_TURN_ASKStimes whileLATE_TURN_MIN_LEFT_MSof the deadline minus the finish reserve is left after the wait. Asked at once from the same fix, the answer is the same turn. A failed ask keeps the answer in hand. Pinned to the heading, the open router sends a car that has to turn round into the nearest side street, which can be a meter ahead when the route lands. - A route that still turns a moving car round where it is (at
BACK_ASK_MIN_MPSor more, bystartsAgainstorstartsBehindagainst its newest course) is not shown or said when no route that turns round less was offered: the fetch waitsBACK_ASK_WAIT_MSand asks again from the newest trusted fix, up toBACK_ASKStimes, then takes the last answer. A route that turns round further on is taken at once, and so is a turn-round when a route that turns round less was offered and cost more than the allowance (TurnRoundVerdict.lessCostsMore, filled in bydirections): from a few seconds on, the answer is the same. - A car stopped at a light points the way it was going: a reroute from a fix with no course
keeps the last moving course while the car is within
HELD_COURSE_MAX_Mof where it showed it (NavSession.heldCourse). Unpinned, both routers sent a car back the way it came from a stop, and it pulled away the other way. Once the car isHELD_TURN_CHECK_M(10 m) from that point, the bearing of the newest 10 m of its track must be withinHELD_TURN_MAX_DEG(45 degrees) of the course (RouteGeometry.courseStillHeld), or the reroute goes unpinned: under the heading speed a car crawls round a corner or turns in the road and shows no course. - A reroute whose route the car never joined (under
JOINED_Malong it when it went off again) is followed byREROUTE_COOLDOWN_UNJOINED_MS, not the full cooldown, once: the next waits the full time, so a fix biased off the road still settles. - A reroute that lands after the driver is back on the original route is discarded
(
route === fromRoute && onRouteStreak >= BACK_ON_COURSE_HITS). One grazing fix is not enough. - A provisional route is never driven raw.
NavSession.driveablenames a provisional top candidate. If naming fails, a full-stepped route from the same reply is preferred even when slower. - A reroute that could not include the remaining stops is still adopted. The stops stay in the plan and the voice says so.
Rechecks and faster routes¶
RECHECK_INTERVAL_MS 120_000 each wait drawn +/-25% (Jitter), redrawn per recheck
DEGRADED_RECHECK_INTERVAL_MS 20_000 while the route is degraded, same spread
DEGRADED_FAST_TRIES 6 then back to the normal interval
MIN_RECHECK_DISTANCE_M 1_500 no recheck this near the destination
SAME_COURSE_M 250 a candidate within this of the current line is the same course
FASTER_THRESHOLD_S 90 minimum saving before a route is offered
MIN_PLAUSIBLE_ETA_FRACTION 0.4 a candidate under this share of the time left is not offered
A recheck fetches from the current position through the remaining stops. It does not run off
route, in a replay, with an offer on screen, or with "Live traffic re-checks" off (pref
nav_live_rechecks, NavSession.liveRechecks). It starts only from a fix that is the phone's
own position (onLocation's fromFix: not a dead-reckoned point, not an outlier hold), rated
RECHECK_MAX_ACC_M (30 m) or better, with no off-route hits counted (recheckFrom). What it
brings back is dropped unless the last such fix, at most TRUSTED_FIX_MAX_AGE_MS (5 s) old, lies
within CAR_ON_CANDIDATE_M (50 m) of the candidate's first km (startsAtCar). A real drive
downtown had dead reckoning carry the puck down a reroute's line the car had not taken, and a
recheck from there swapped in a route 185 m behind the car. A degraded route (RouteHeal.degraded) is one
with abbreviated steps, no live traffic, or street names that fell short (Route.namesShort).
- Same course, with traffic: the shown arrival time is recalibrated.
etaScaleis multiplied by candidate ETA over time left, clamped 0.5 to 2.5, applied where the state is published, and reset to 1.0 on every route swap. - Same course, better quality (
RouteHeal.gains): the candidate replaces the current route silently. Full steps replace abbreviated ones, a named route replaces one short of names, and a traffic-carrying route replaces a trafficless one. None of the three is given up for another, except that full steps short of a name still replace abbreviated ones. The names gain takes only a candidate that is Google's line (GOOGLE_HYBRIDorGOOGLE_LINE_NAMED): a re-check that could not build the hybrid answers with the open router's own route, and the same-course test (five samples) cannot see a short detour. The note in the trip says which was gained. - Same road (
RouteGeometry.sameRoad: every point along the candidate, every 50 m or more with at most 400 read, past its first 100 m, within 40 m of the current line): never offered. Its lower time is fresher traffic, and the recalibration above has taken it. - Different course: offered when it has traffic and real steps, covers every remaining stop,
saves more than
FASTER_THRESHOLD_S, and its ETA is between 0.4 and 0.9 of the time left. A trafficless candidate is never offered and never calibrates, because free-flow always appears to beat traffic. A dismissed candidate returns only when it saves 60 s more than before.
The offer resolves itself. A bar across the card drains over 10 s, and focus anywhere on the
card freezes it until focus leaves. Then the route is taken, or dismissed when FasterRouteAuto
(pref faster_route_auto) is off. The countdown is keyed on the offer, so a recomposition
cannot restart it.
Tunnels¶
When no fix has fed guidance for DR_START_MS (3.5 s) while navigating, on route and not
replaying, NavController synthesizes 1 Hz fixes along the route through
NavSession.onLocation. Speed starts at the last shown speed and decays with DR_DECAY_S
(60 s). Synthesis never starts or continues below DR_MIN_SPEED (1.5 m/s) and stops after
DR_MAX_M (3 km). It never passes the next maneuver: it holds DR_TURN_HOLD_M (15 m) short of
it until a fix says where the car went, so a feed that stalls at a junction no longer carries
the puck down a turn the driver did not take (issue #745; a reporter's puck ran a turn and some
forty seconds of road on a stalled feed). The "searching for GPS" chip stays up, the first real fix re-anchors, and
synthesized fixes are never recorded into a trip.
Pause¶
While NavSession.paused is set, onLocation records the fix and returns before the engine.
Nothing downstream runs: no off-route detection, reroute, arrival, stop cue, voice, recheck or
offer. The puck keeps moving because it is drawn from the raw fix, and the arrival clock slides
on a 30-second tick. Resume reroutes once when the fix is outside the corridor, otherwise speaks
the current instruction. Auto-resume is armed by the stop: a stationary or off-route fix sets
autoResumeArmed, and then AUTO_RESUME_HITS (3) consecutive moving, on-route fixes resume.
Without the arming step a pause taken at speed would resume itself three fixes later.
4.7 The puck and the camera¶
During navigation the drawn position is a filtered estimate of meters along the route, not the
raw fix. The per-frame loop (the nav ticker) is in ui/map/VelaMapView.kt.
Position and speed¶
- Position is
core/location/AlongRouteFilter, a 1-D Kalman filter over meters along the route. It dead-reckons at the modeled speed and folds in each accepted fix weighted by its reported accuracy (along-route sigma 0.66 of the 68 percent radius, since snapping discards the lateral part). A discontinuity callsreseedand is not averaged. - Speed is
core/location/SpeedKalman. Each fix is the measurement. Between fixes the accelerometer steers the prediction:MotionProvider(TYPE_LINEAR_ACCELERATIONplusTYPE_ROTATION_VECTOR, no Google services), projected onto the travel bearing. Its noise is cut by the gaina² / (a² + n²)withACCEL_NOISE0.5, which keeps a 4 m/s² brake within 1.5 percent and cuts 0.3 m/s² of vibration to a quarter. - Progress advances in the rate domain: the modeled speed plus
error / PUCK_CORRECT_TIME_S(0.6 s), capped at1.5 x speed + 2 m/sof catch-up and0.25 x speed + 0.5 m/sof hold-back. An ease toward a target under a monotonic clamp stalls and lurches at the fix rate. - Dead reckoning stops
DEAD_RECKON_S(3 s) after the last accepted fix. A fix's advance is accepted up tospeed x dt x 2.5 + 60 m. - The smoothing window's width eases toward its speed target with
PUCK_WIN_TAU_S(2.5 s). On a curve the width is a lateral position, so speed noise in it is sideways movement. - Snap tolerance (
puckSnapTolerance): driving, 22 m plus a speed term of up to 13 m. Walking and cycling, 8 m plus 1.2 times the fix accuracy, capped at 16 m. The heading gate is skipped below 1 m/s driving and 2.5 m/s on foot or by bike. - A fix within reach of the line but heading 55 degrees or more against it is a heading miss:
it freezes the reckoning, and the second in a row drops the arrow to the raw fix. One such
miss already
PUCK_LEAVE_NOW_M(12 m) off the line drops it at once (issue #745, a video: the arrow turned with the route for five seconds while the car went straight past the junction at 48 km/h): a car rounding a corner on the route stays within a lane of it, a car past the turn is a lane and more off within a second. The reroute itself is the engine's (OFF_ROUTE_M,OFF_ROUTE_HITS), untouched.
Nav camera¶
- Bearing eases with a time constant from
CAM_BRG_TAU_STILL(1.6 s) at small error toCAM_BRG_TAU_TURN(0.35 s) pastCAM_BRG_TURN_DEG(25 degrees). Geometry noise is a few degrees and a turn is tens. - Zoom runs from 18.5 at a standstill to 15.8 at 30 m/s, on a speed eased over 0.6 s, less the framing's pull-back (below). A pinch sets an override that a pan or Re-center clears. With "Zoom to the next turn" on (Settings > Navigation, off by default) the zoom is the lesser of that and the zoom that frames the next maneuver (Framing, below).
- Tilt wants 55 degrees heading-up (0 north-up, or the angle a two-finger tilt set), capped by
navTiltCapat a zoom the user pinched to: the whole tilt fromNAV_TILT_FULL_ZOOM(15) in, flat fromNAV_TILT_FLAT_ZOOM(12.5) out, linear between. MapLibre holds the pitch under a ceiling that follows the top padding (TransformState::getMaxPitchForEdgeInsets): with the arrow's pad of 0.45 the drive camera sits at 52.6 degrees on a 1080 x 2340 px, 2.75x screen (two simulated drives, 400 seconds each), and about 48.5 at 546 dpi. The ticker records that ceiling the first time the eased tilt sits 0.3 degrees above the camera (navTiltCeiling, cleared when the drive ends), and the turn framing below uses it. The cap is applied during the pinch itself (onScale), where the follow ticker stands aside, and by the ticker after it. A view tilted 55 degrees at city-wide zoom reaches the horizon and loads the tiles for all of it. Pixel 4a, San Francisco, eight zoom sweeps between z16.7 and z10.6 in a drive: 4,195 frames and 16 stalls over 250 ms (longest 943 ms) uncapped, 5,178 frames and none (longest frame 148 ms) capped, 5,554 flat. Without Zoom to the next turn the camera's own zoom stays at 15.5 or above, so only a pinch meets the cap; with it the zoom to a far turn meets it too (NavFraming.tiltAt). - Cosmetic eases take
dtEase, the frame time capped at0.065 x replaySpeedups. Integration keeps the real time. Uncapped, one long frame moves an ease 45 to 70 percent of its error. - A two-finger move is a pan only after
TWO_FINGER_PAN_DP(44 dp) of travel with no tilt or pinch begun. The tilt detector claims its gesture after 20 dp, after the move detector starts, so a move judged at its first event read every tilt as a pan. - The follow loops (drive and free-drive) stop writing the camera from the second finger down
(
twoDown, set by the map's touch listener), not from the pinch being recognized. Until then the fingers slid the map and the loop put it back every frame, which felt like the map holding on. - MapLibre starts a pinch zoom only above a span speed.
res/values/map_gestures.xmllowersmaplibre_minimum_scale_speedfrom 0.6 dp to 0.15 dp per millisecond. On a Pixel 4a a pinch closing at 990 px a second zoomed nothing at 0.6 dp, and one at 400 zooms at 0.15. A level tilt drag, a diagonal one with uneven fingers and a two-finger pan still read as tilt and pan.scripts/touch/two-finger.shplays these gestures on a phone. - A pinch whose fingers also turn needs
maplibre_minimum_angled_scale_speed, lowered from 0.9 dp to 0.15 dp. A hand's pinch always turns a little: on a Pixel 4a a pinch at 1,000 px a second with a 20 degree twist zoomed nothing at 0.9 dp and 0.6 levels at 0.15. - A pinch and a turn work in one gesture (
isDisableRotateWhenScalingandisIncreaseScaleThresholdWhenRotatingoff). MapLibre's defaults let whichever is recognized first shut the other out, and with the lower pinch speeds the pinch nearly always won, so the map would not turn. A turn starts after 3 degrees of twist (TURN_START_DEG), and after 15 once a pinch is under way (TURN_START_PINCHING_DEG, set in the scale listener). A turn of the browse map that rests withinBROWSE_TURN_KEEP_MIN_DEG(12) of north goes back to north, checked at camera idle because the turn's fling runs on after the fingers lift. While a drive follows the car a pinch does not turn the map. With "Keep north up" (NorthLock) no gesture turns it, and every drive runs north-up and flat. - A parked drive slows the loop to
NAV_IDLE_TICK_MS(120 ms). A moving detached camera keeps it at frame rate.
Framing¶
ui/map/NavFraming places the arrow and sets the zoom's pull-back from the map the drive's chrome
leaves visible. At the default display and font size the frame is unchanged.
- The arrow sits at a top padding of
DEFAULT_PAD(0.45 of the map height, 72.5 percent down). It rises until what hangs under its point clears the bottom chrome byMARGIN_DP(8 dp), and never aboveMIN_PUCK_FRAC(55 percent). Under the point:ARROW_BELOW_PX(62 px, the arrow's glyph), plus the road-name pill when it is pinned under the arrow. - North-up, the road ahead can run any way on screen, so the arrow takes the middle of the map between the turn card's bottom and the bar's top, never lower than its heading-up place, and the zoom is the speed's.
- The bottom chrome is the bar's top edge, the road-name pill when it sits above the bar
(
BAR_PILL_GAP_DP, 10 dp, over it), and the speed box once its right edge reaches the arrow's column (ARROW_HALF_PX, 101 px, times the arrow size). At default size the box stays in the corner and does not count. - The phone's arrow is 202 px times the arrow size, times
PuckStyle.screenFit: the screen's short side over 1080 px, at most 1 and at least 0.4. A screen 1080 px wide or more keeps the 202 px; on an 800 by 480 screen the arrow is 90 px instead of 42% of the width. The car screen sizes its own arrow. - The look-ahead ratio is the dp between the turn card's bottom and the arrow, over the same on the
same phone at its default density (
DisplayMetrics.DENSITY_DEVICE_STABLE) with the card endingREF_TOP_DP(230 dp) down, orREF_MIN_AHEAD_FRAC(a quarter) of the map on a short screen. At or aboveDEAD_RATIO(0.8) the zoom is the speed's. At or belowFULL_RATIO(0.6) it pulls backlog2(ratio)levels, ramping in between, at mostMAX_ZOOM_OUT(1.5), and never takes the camera's own zoom belowZOOM_FLOOR(15.5): lights and stop signs draw from z15.4. A lane strip and a "Then" tab at default size stay above the dead ratio. - The edges are measured where they are drawn into
NavChromeEdges: the turn card's bottom and the speed box withonGloballyPositioned, the pill withonSizeChanged(the tallest at the current density and font scale, since a long name shrinks its text). The bar's top isnavBarTopPx. Values stay while an element hides. NavFramer(held by the ticker'sNavPuck) takes a new frame only after the inputs move by 1 dp or more and then hold forSETTLE_MS(400 ms), so a bar being dragged or a card animating in does not move the camera. The first frame is taken at once. The pad eases like the camera's position and the zoom like its zoom.- In landscape (the chrome is a left column) and in picture-in-picture nothing covers the arrow's column, and the frame is the default.
- On a 1080 x 2340 px, 420 dpi fixture: card bottom at 250 dp, no change. At 546 dpi with the card capped at a third of the screen (about 257 dp), the zoom pulls back about 0.8 levels.
Zoom to the next turn (ZoomToTurn, Settings > Navigation, off by default; issue #781):
- Heading-up, the zoom is the lesser of the speed's (its pull-back and
ZOOM_FLOORincluded) and the zoom at which the next maneuver's point landsTURN_MARGIN_DP(72 dp: room for the turn callout, a bubble about 40 dp tall anchored on the corner, up to 60 m past it when a light stands there) under the top chrome's edge: the turn card's bottom as the framer adopted it, the top of the map in landscape, in picture-in-picture and with no card. The tilt it frames for is the one the camera holds (navTiltCeilingabove, else the wanted 55). Never below the floor: the user's pick under Navigation (ZoomToTurn.floor, 12, 10 or 8), else theturnZoomMindial, elseZOOM_TURN_MIN(12). The zoom eases like the speed zoom (0.5 s), so a passed turn eases out to the next one and a near one eases in to the speed's. North-up, and under a pinch, the zoom is what it was. - Measured on the 4a over a 13 mile simulated drive with the
VelaFpsframing fields: the projection model and MapLibre's own projection agree within 1 dp at every tilt and zoom; framed for 55 degrees while the camera held 52.6, the turn sat 27 dp above the aimed row, at the card's edge, for the whole tilted stretch; flat, it sat on the row. Framed with the held tilt, it sits on the row within 2 dp, tilted or flat. On the freeway the floor bound for nine minutes with the next maneuver off the top of the screen. - The point is
NavTurnTarget, written byNavControlleras the step changes: the step's maneuver, past any CONTINUE or STRAIGHT step the voice is silent for (no genuine lane fork,continueHasGenuineFork, the engine's own test); a straight step with a fork the voice announces is a target, and the arrival counts. No drive, or no maneuver left, leaves the speed's zoom. NavFraming.turnZoom: the straight-line meters from the drawn arrow to the point, taken as straight ahead, against the ground the rows between the arrow and the edge cover. Flat, a row is a ground dp. Tiltedp, a rowudp above the arrow reaches `d cos p tan(p + atan(u / d))- d sin p
ground dp at the center's scale,dbeing the camera distance0.5 height / tan(FOV / 2)(the mirror ofCarFraming.targetOffset). Meters per dp at the center are40,075,016.686 cos(lat) / (512 x 2^zoom)`. A turn off to the side lands lower than the edge, never higher. A turn farther than fits at z12 sits off the top until it is near enough. - Below
NAV_TILT_FULL_ZOOMthe camera lies flatter (navTiltCap, applied to the camera's own zoom as to a pinch), a flatter camera reaches less ground per row, andturnZoomFlatteningbisects the zoom against the tilt it will have there (twelve halvings). - At z12 the basemap draws motorways through minor roads and the route line. Street names (the road-name pass runs from z14.6), lights and stop signs (z15.4) do not draw that far out, which the option accepts. Lower would load a region's tiles at each step and show nothing a drive needs.
- The camera turns toward the maneuver it frames (
NavFraming.turnYaw): the bearing's target is the heading plus the angle from the heading to the point, at mostTURN_YAW_MAX_DEG(90, so any turn ahead of the car can be brought to the top of the frame; 45 left a turn farther round off the side of the screen on a curving road) either way, scaled from nothing while the speed zoom governs to all of it once the turn's unfloored zoom isTURN_YAW_BLEND_LEVELS(1) under the speed's, so the yaw fades out over the last stretch before the turn and the view is heading-up through it. The bearing eases as for a turn, and the arrow is drawn turned off vertical by the yaw. North-up and under a pinch there is no yaw. - The car screen runs the same zoom and yaw on the phone's switch and floor (10.6), from the
arrow's row to
TURN_MARGIN_PX(40) under the top of the visible area, and its tilt flattens with the zoom as the phone's does (tiltAt). - The pre-engage camera (the car not yet on the line, a reroute) takes the same zoom, so a reroute does not zoom in and back out.
- On the fixture with the card at 230 dp and latitude 38.5: 344 dp above the arrow reach 949
ground dp at 55 degrees. The speed zoom at 30 m/s (z15.8) frames a turn 1,019 m ahead and
takes over inside that; z17 frames 443 m. A turn 1 km ahead frames at z15.8, 2 km at z13.7
with the camera at 27 degrees, 3 km at z12.8 at 7.5 degrees, 5 km at z12.0 flat, and the
floor frames 5,146 m (
ZoomToTurnTest).
The puck overlay¶
While navigating, the puck is a Compose overlay at projection.toScreenLocation of its point,
computed right after the camera move. A GeoJSON source update is tiled asynchronously while
moveCamera is synchronous, so a symbol lands on time or a frame late at random. Per-frame
values go into mutableFloatStateOf holders read in the draw phase.
- The overlay also draws before the puck engages, at the raw fix, and while the camera is detached, projected through the live camera.
- The overlay stays up while a gesture moves a detached camera, re-projected every frame. A
swap to the map's own flat symbol for the gesture and
PUCK_GESTURE_SETTLE_MS(180 ms) after exists behind the test dialpuckGestureSwap; it is off because the car vanishes for several frames at each end of a pinch on a Pixel 4a (San Francisco fixture). - The browse map uses the GeoJSON symbol.
Where the map opens¶
MapViewModelseedscenterandmyLocationat construction with the simulated point, elseLocationProvider.lastKnown(): the newest last-known fix the system holds, else the fix Vela last cached invela_location.VelaMapViewcreates the map there at z15.5, and the first camera pass and the launch-center effect fly to the fix. With no seed the map is MapLibre's world view until the first fix.MainActivity.onCreatehandles the launch intent, then callsopenStartView(), before the map is composed.startFor(ui/StartView.kt, pure,StartViewTest) picks the view from the setting (StartView.mode, Settings > Map > "Where the map opens"), whether fixes can arrive (LocationProvider.canLocate(): a permission granted and a provider on, or a simulated position), the seed fix, the view the map was left on, Home and the picked view.here("Where I am", the default) with location on and a seed fix changes nothing: the map opens on the fix and follows it. With location off, or with no fix yet, it opens on the view the map was left on and waits there for the first fix. With no such view it opens on the seed fix, else the world view.last("Where I left the map"),home("Home", atHOME_ZOOM15.5) andplace("A place I choose") open on their view and hold it. A choice whose target is missing (Home removed, nothing saved yet) opens likehere, and Settings shows "Where I am" (shownStartMode). The stored choice is kept, so a new Home brings it back.drive("Driving mode") decides the camera asheredoes and setsStart.drive, which turns driving mode on (4.7, Driving mode).- A held view sets
center,startZoomandstartHoldinMapUiState.VelaMapViewcreates the map oncenteratopenZoomand starts with its three launch moves marked done (startFramed: the first run of the recenter branch, the first target fly and the launch-center effect), so the first frame is the start view and nothing animates.startZoomis cleared at the first settled viewport. MapSurfacepassesdriveFollowing && !startHold, so the free-drive follow does not pull a held map to the fix.recenter()(the locate button), the start of a drive and "Simulate my location" clear the hold.- A view that waits for the first fix gives way to it like a locate tap (
recenterTick), unless the map was panned or a place, results, directions or a drive are up. A permission granted during the session (the locate button's ask) makes any held view wait this way. - An intent that opens a place, a search or a route (
openDeepLink,openSharedText,openTripShortcut) setslaunchLinkbefore the decision, andstartForreturns nothing. A launch from a link is the same in every mode. So is an activity reopened while a drive runs. - A view is
StartCamera: the point at the middle of the screen and the zoom, noted by the map's idle work asStartView.live. The viewport box is off-center on a tilted map and the camera target is off-center under a sheet's padding. Bearing and tilt are not kept. MainActivity.onStopwritesliveaslast_viewinvela_location, which backups leave out, like the last known fix. The choice (start_view) and the picked view (start_view_loc, "lat,lng,zoom") are invela_settings. "Use the current map view" storesliveas the picked view and selectsplace.- The decision reads the permission state and stored values. It requests no permission and sends nothing.
Free-drive follow¶
- The target is
FollowEstimator, fed the raw accepted fix, with half of each residual spread over 0.9 s. - It turns heading-up once the speed, averaged over
FREE_HEADING_UP_TAU_S(4 s), passesFREE_HEADING_UP_MPS(3 m/s), and stays so until the follow ends. A single noisy fix on foot does not reach it. - The bearing eases toward the GPS course with a speed-scaled look-ahead
(
FREE_LOOKAHEAD_TAU_S2.5 s). The fly-in to street zoom runs once per follow. With "Keep north up" the follow stays north-up at any speed, flat unless tilted by hand, and the beam still prefers the course. - Below 0.5 m/s, target moves under
FOLLOW_STILL_DEADBAND_M(2 m) are ignored, so a parked car lets the loop go idle. - The dot is drawn at the eased follow position, so it stays centered as the map glides. While
the follow glides back in from where a pan left the camera (
browseSeeking), it is drawn at the fix until the camera is withinSEEK_DONE_M(3 m) of it; drawn at the eased position then, it jumped to the screen's center and rode back with the map. - A two-finger tilt pauses the follow's camera writes and becomes its tilt target
(
browseUserTilt) in place of the automatic 0 or 55 degrees. It survives a pan, a sheet and the locate button. The compass, visible while a tilt is held, returns the map to north and flat and clears it, as does starting a drive. A tilt ending underBROWSE_TILT_KEEP_MIN_DEG(8) is a pinch's wobble and is dropped. The idle test compares against the active tilt target. - A hand rotation releases the follow.
Driving mode¶
The map in the drive's layout with no route (issue #727), for a mounted phone, a tablet or a head
unit without Android Auto. DrivingMode.on (ui/DrivingMode.kt) is memory only.
- On: the free-drive follow as above (heading-up and tilted once moving, the fly-in to street
zoom), the search bar alone at the top (
CategoryChipsdraws nothing), the layers button hidden, andDrivingChrome(ui/nav/DrivingChrome.kt, composed fromMapFloaters): the drive's bar innavBarLook()colors with an X (leaveDrivingMode) where End sits, the mode's name and the time of day, a 56 dp locate button andNavVoiceButtonin the drive's right-edge column, and the map credit above the bar. Landscape puts the bar in the left column (landscapeColumn,DRIVING_LAND_EDGE_DP8 dp) and the buttons at the bottom edge. - The speed box (
NavCorner) shows from the first fix, standing still too, above the bar in portrait (the bar's measured height,DrivingBar.heightPx, plus 16 dp) and right of it in landscape (DrivingBar.rightPxplus 10 dp), under "Show speed and speed limit". SearchGates.drivingChromesays when the chrome draws: the mode on, nothing owning the screen (no drive, search page, place, results, directions, steps, pick, replay, arrival, Street View, area pick, drawing or resume prompt).fabChromeOkis false while it draws, so the locate and parking buttons, the scale bar and the browse credit yield, and the zoom buttons hide as they do in a drive. The gate is published asSearchGates.drivingChromeLiveforDrivingChromeandNavCorner, which get no parameter fromMapScreen.- The browse follow flag is
FollowMe.on(a holder, formerly aMapScreenlocal), so the mode's locate button re-arms it as the browse locate button does; with no permission the tap asks. - A place or a route picked from search runs as usual: the chrome hides behind the sheet, the route picker and the drive, and the mode is still on when they close, so a drive that ends returns to it. The X is the only way out; Back behaves as on the bare map.
- The screen stays on under "Keep screen on while navigating" for the whole mode, a sheet or a search up or not, and while a drive in it is paused; the setting is read on every pass of the chrome, which the clock recomposes once a minute.
- "Day and night while navigating" counts the mode as navigating (
isAppInDarkTheme,isMapDark). - Alerts: the speeding alert runs from each guidance-quality fix (
NavController.drivingModeFix, afterupdateSpeedLimit), withSpeedingAlertsreset when the mode is left. The speed camera and plate camera alerts, which a drive projects onto its route, run here against a look ahead: a straight lineDRIVE_AHEAD_M(1,200 m) along the fix's course, rescanned everyDRIVE_SCAN_MS(4 s) orDRIVE_SCAN_M(150 m) driven (scanAhead), with the cameras withinDRIVE_CORRIDOR_M(60 m) of it as (key, meters ahead). Speed cameras come from the baked road features only (no corridor fetch per scan); plate cameras from the bundled set, grouped within 40 m as on a route.CameraAlerts.dueKeyedapplies the drive's timing with the meters driven since the scan and a set of announced keys, so a camera is announced once however the list is rebuilt. A camera past a bend ahead sits outside the corridor and is not seen; the same settings gate the alerts as in a drive. Leaving the mode clears the scan and the announced sets. - Settings > Map > "Where the map opens" > "Driving mode" (
StartView.DRIVE):startFordecides the camera as "Where I am" does and setsStart.drive, whichopenStartViewturns into the mode before the map is composed. A launch from a link keeps its place in every mode. The layers panel's "Driving mode" row (enterDrivingMode) is the way in from the map, and closes an open place, whose sheet would hide the chrome; with the layers button hidden, the setting is the way in. - Android Auto is untouched: the car's own drive screen (10.1) is the same idea on the car.
Compatibility rendering¶
Two launches in a row that die before the map's first render set texture_render (a TextureView
map). On API 30 and above only REASON_CRASH_NATIVE counts: counting any death flipped healthy
phones that had been force-stopped, and the TextureView renderer used 89 percent of a core on a
Pixel 4a. Settings > Performance shows the date it engaged.
Diagnosing jitter¶
Measure first, in this order: the arrow in a screen recording (scripts/jitter/puck_track.py),
uneven map motion or rotation (map_motion.py, rotation_fit.py), over-budget renders in a
Perfetto trace (gl_frames.py; evenly spaced means a periodic cause, random is the device's
floor), then Compatibility rendering, which should be off. A demo drive has no GPS noise, so
jitter there is not GPS.
Measured and not worth doing:
- A per-frame LineString source for the route cut: a line re-tiles on every worker. Route geometry is never uploaded per frame (4.8).
- A whole-route
line-gradientcut: 256 texels smear it overrouteLength / 256meters. - Smoothing route geometry to calm the arrow: the camera's turn rate through bends was already smooth to 0.02 degrees per frame.
- A least-squares bearing fit over the window: no better than the chord.
- Subtract-the-floor accelerometer shrinkage: it taxes a real brake by the floor.
4.7a The first seconds of a drive¶
Frame rates are a Pixel 4a on a demo drive, per second from Start.
- The drive starts with a cut. Its first camera move is a
moveCamerato the car at the nav zoom, tilt 0, and the tilt eases to 55 withNAV_START_TILT_TAU_S(3 s). A flight from the route overview places a tile set at every zoom it crosses: seconds 2 to 4 ran 6 to 20 fps flying and 29 to 59 cutting. A 0.55 s tilt ease has one second at 5 to 9 fps. - The overview and the way back are cuts too. A fresh Overview press
moveCameras to the fit; the 4 s refits (OVERVIEW_REFIT_MS) animate. Re-attaching from more thanCUT_BACK_ZOOM_GAP(1.5) zoom levels out seeds the camera at the car, flat. - A step previewed from the overview ends it: the camera goes to the step and stays, and
resuming the preview returns to the car (
MapViewModel.previewStep). A pan, a pinch, Re-center and a preview all stop the refit within a quarter second. - A step tapped in the step list drops the list (
StepsSheetdismisses itself), and that close keeps the preview (closeStepsafter a pick). Any other close of the list ends a preview. - Each cut lays a veil in the land color of the palette in use (black on AMOLED and over
satellite imagery) under the puck at
CUT_VEIL_ALPHA(0.85), faded off overCUT_FADE_MS(320 ms). It is adrawRect(alpha); a layer alpha renders offscreen. - The overview hides the
OVERVIEW_HIDE_PREFIXESlayers (places, POIs, minor road names, house numbers, one-way arrows, controls, cameras, transit stops, nav callouts, 3D buildings, the building overlay) and restores them in its effect'sfinally. Major road names, shields, the route and the destination stay. - Before the puck engages, the loop still eases the opening tilt, waiting out a pre-engage
re-point flight (
preEngageAnimUntil, 600 ms). placesNavHoldhides the places icon layers forNAV_PLACES_HOLD_MS(7 s) from the start of a driving trip, so their sources request no tiles: seconds 4 to 6 ran 16/7/23 fps shown and 29/45/50 hidden. A style reload mid-hold rebuilds throughapplyOpenPlacesHidden.- Drive navigation hides
road_one_way_arrowandroad_one_way_arrow_opposite. - The voice speaks at
PiperSynth.SPEAK_PRIORITY(nice 8, foreground group). At the default priority it held the map at 2 to 30 fps;BACKGROUNDputs a prompt ten seconds out. An imminent-turn prompt and the opener (interrupt = true) keep the default. No prompt is dropped by priority. The engine's own threads (PiperSynth.poolTids, found by the worker's name after a load) take every priority the worker takes: they start inside the load and kept its priority of that moment, background after a warm-up, and a render waits for its slowest thread. On a Pixel 4a with eight busy loops on the cores, a 52 letter test line rendered in 25 s with them left at nice 10 and 11 to 15 s with them moved along (4.6 s idle either way). - The opener and the first two turns' prompts are synthesized while the route preview is up
(
NavSession.prepareStart->VoiceGuide.prepare->PiperSynth.prepare, background priority).NavEngine.startPromptsgives the far and near approach lines at the 400 m and 150 m band floors and the turn-now line, inupdate's wording (StartPromptsTest). Up toMAX_PREPARED(8) lines are kept, by voice, speaker, speed and exact text. A spoken line drops any prepare queued behind it (speaksAsked) and raises the one in hand (9.1). - No hidden Google page loads during a drive: the details page not while navigating or with
the route chooser up (
pageWanted), the review page not while navigating. A loaded page works on for about 20 s after its answer, whether stopped, paused or blanked. route()warmsroadFeaturesCoverRouteon the first route, so the road-features file is parsed while the chooser is open.- The one-tap Start from the place sheet (
startNavToSelected) first waits forMapViewModel.awaitRouteWork(road features plus the camera job, at most 3 s). - The building-overlay gate is asked on a timer during a drive:
NAV_OVL_FIRST_MS(2.5 s) after the start, then everyNAV_OVL_TICK_MS(4 s). It probes once per 550 m cell the car enters, only while the camera follows (6.4).
Measured and not worth doing:
- A slower zoom ease for the first 3 s, or deferring the declutter and the first road-label pass: the work only moved later.
- Hiding all of Vela's runtime symbol layers for the first 2.5 s: the reveal has its own dip.
- Tile workers at background priority: no gain, street detail later.
- Waiting for the voice lines or for map idle before starting: no gain.
4.7b Turns and trip playback¶
Turns¶
TurnDeclutter cuts the map back to street names while the follow camera swings, because symbol
placement re-runs on every frame the camera rotates. On a Pixel 4a Davis demo drive at 3x, turn
seconds ran 40 to 49 fps with all layers and 48 to 60 with it. No one layer group carries the cost.
- While the bearing error is at least
START_DEG(15) forARM_FRAMES(3) frames in a row, every visible symbol layer is hidden except the street names (highway-name-major,-minor, the shields, exit numbers, thevela-nav-callouts) and the arrow. They return once the error stays underCALM_DEG(4) forSETTLE_MS(1 s). - Only layers visible when the hide began are touched. The open places layers are re-filtered
by
applyOpenPlacesHiddenafter a restore. The overview takes the layers back first. - Each flip re-lays out the layers' sources, a 60 to 200 ms map frame. With the start threshold at 10 degrees, a gentle curve, which holds an 8 to 11 degree error, flipped the map through every bend.
- Settings > Performance "Simplify the map in turns" (
TurnDeclutterPref, prefturn_declutter, default on). Dialdebug.vela.tune.turnDeclutter 0turns it off, read at each drive's start. - A hand gesture hides nothing: strokes with rests between would flip the set twice per stroke.
- While the camera is off the car the cross-street bubble layers are hidden. The turn and exit callouts stay.
Camera-idle work¶
MapLibre reports camera idle after every moveCamera, so under a follow ticker the idle listener
fires every frame. Its work (the viewport pass, the building-overlay gate, the warm-up schedule)
runs at most once per IDLE_WORK_GAP_MS (1 s) while the camera moves, plus once
IDLE_WORK_TRAIL_MS (250 ms) after the last idle event.
- The nav road-name pass does not run below zoom 14.6: its query returns every road name in every loaded tile on the main thread.
Tile level of detail¶
MapLibre 13.6.1 (OpenGL artifact). setTileLodPitchThreshold(30 degrees),
setTileLodMinRadius(1), setTileLodScale(6), zoom shift 0, set once at map creation: above
the threshold, tiles away from the view point load at lower zoom. The engine's default of 60
degrees never engages at the drive's 55. Zoom strokes over a tilted drive view in San Francisco
ran 51 fps and about 190 map requests with it off, 55 and about 95 on.
Work beside the map¶
The render thread shares the fast cores with the rest of the app, so background work that never ends shows as dropped map frames (33 against 57 fps on a 117 km demo drive from Davis at 3x; a 4 km route shows none of it).
- Plate cameras on the shown routes are worked out once per set of routes (
flockOnRoute). Only a set overCONTROLS_ONSCREEN_CAPis cut to the view, from the list in hand. - An on-device route search ends when its caller stops waiting (4.5).
- Starting a drive cancels the chooser's background fetches (
cancelChooserPrefetch).HiddenWebView.requeststops a page whose request was cancelled or timed out, and logs each page asked, answered, given up and destroyed underVelaWeb. - The streamed speed limit is read, not mounted (
data/StreamedSpeedLimit): the tile under the car at the archive's deepest zoom, decoded bycore/util/MvtLines, nearest tagged line within 20 m, twelve tiles kept, an empty tile asked again after 60 s. Mounted as an invisible layer, every tile the tilted view covered was requested. - The streamed archive carries
maxspeed:conditional.OsmMaxspeed.conditionalKmhapplies its time rules at the phone's local time on every lookup: hour ranges, past midnight included, optionally after weekdays. The last rule in force wins. Weather, weight, date ranges and a rule with a quoted comment are never in force, so the plainmaxspeedshows. The obf path reads OsmAnd's plain limit and does not apply them. - Whether a downloaded region answers the limit is decided by its boundary (
limitsOnPhone), not the engine's box. Dialdebug.vela.tune.streamLimits 1reads the streamed limits over a downloaded region too. offline/ReleaseRedirects, in the map's HTTP client and the speed-limit reader's, keeps the signed address a release file redirects to until a minute before itssetime, at most 30 minutes. Anything but a success drops it. Without it each range read is two round trips.
Idle and background cost¶
MapScreen reads the sheet's edge and the puck's screen position through SheetEdge and
PuckScreen: composition sees threshold booleans and layout reads the position. Also gated: the
speed readout recomposes on a new digit only; a newly closed place updates the places filter,
not the sources; the nav notification re-posts only when what it shows changes (notifKey); the
screen-on flag drops while a drive is paused; the compass sensor is registered only on the bare
map in the foreground; the last-known position is written at most once a minute or after 100 m
(LocationProvider); the voice's AudioTrack is paused after each prompt; the day and night
theme ticker waits in the background.
Measuring¶
- Frame rate:
debug.vela.fpsandscripts/map-fps.sh(section 13). AVelaFpsline carries the second's zoom range and bearing change, so a dip at a turn reads off the log. With "Zoom to the next turn" on it also carries the next maneuver's screen column and row (turnX,turnY), the row the framing model predicts for the same camera (pred), the live card edge (card) and the one the framer adopted (top), the tilt, the ground distance, the arrow's pad and the arrow's heading (hdg, against the camera'sbrgthe yaw), window px, so a miss on a drive can be laid at the model or at its inputs. - Layer bisect:
debug.vela.hide, re-applied every 250 ms while set, so layers nav adds at Start are hidden too. - Thread CPU first:
adb shell top -H -b -n 2 -d 5 -p <pid> -o TID,%CPU,CMD -s 2. Coroutine workers on both Default and IO are namedDefaultDispatcher-worker. debug.vela.tune.offline 1makesMapViewModel.isOnlineanswer no, so search takes the offline path (OfflinePoiStore, the places archives,OfflineAddressStore.geocode) on a phone that is online. Read on every call;setpropit back to 0 after.debug.vela.tune.demoSpeedup <n>runs a demo drive at n times real time, as a trip replay runs.debug.vela.tune.camTurnTau <s>replacesCAM_BRG_TAU_TURN.- Traps: the travel mode is sticky, and a demo started in walking mode skips the driving declutter. A first zoom past z17 dips whatever is hidden; that is the next level's tiles. Measure a long route and alternate A and B runs.
Measured and not worth doing:
- One synthesis thread (
debug.vela.tune.synthThreads 1): prompts about 30 percent slower, the dips at turns unchanged. - A slower turn swing (
camTurnTau0.8): 35 to 45 fps on the worst dip over three turns, too few to call.
4.8 Route line rendering¶
The geometry drawn¶
- A hybrid route (
GOOGLE_HYBRID) carriesRoute.drawPolylinefromHybridRoute.drawLine, which is OpenStreetMap geometry where it can be: the roads are drawn from OpenStreetMap, and Google's line sits a few meters off their center on curves. Where Google's line runs along the open route, that route's own line. Inside a stretch where they differ, the matched road shape (Valhalla, only when the match has no off-line part). A piece whose ends are over 25 m from Google's or whose length is off by a third keeps Google's line, and so does an open route piece that goes more thanOFF_M(15 m) from Google's anywhere, read every 20 m (HybridRoute.staysNear). Stretches are found from Google's side only, and an open route that takes an exit and the entrance straight back stays near Google's line the whole way. - A piece left on Google's line is nudged onto the middle of the map's roads (
RoadCenter), from the tiles the naming already read (RoadNameTiles.roadsAlong(fetchMissing = false), up toDRAW_ROADS_MAX_TILES48; nothing is requested for it, and a tile not in hand is left out). The tiles' bytes are kept for the last 96 tiles, two stretches' worth. The line is read everySTEP_M(6 m). A point moves sideways onto the nearest car road withinMAX_OFF_M(9 m) that runs withinALIGN_DEG(25) of the line's own heading. It stays where Google put it when no such road is there, or when roads on both sides are withinAMBIGUOUS_M(3 m) of equally near. An unmoved run underBRIDGE_M(40 m), a junction, takes the moves either side, and every move is averaged overSMOOTH_M(18 m) each way so the line eases on and off a road. On a captured 12 km town route, Google's line sat a median 0.8 m and at most 3.4 m off the road's middle, 67% of it by more than half a meter, and the nudge added no more than 10 degrees of bend in any 48 m. It runs once when the route is built, off the main thread (13 ms for that route on a desktop JVM), never per frame.madegainsnudged=<meters>. - MapScreen draws
roundBends(removeZigzags(straightenCircles(line)))(core/nav/RouteSmoothing). Guidance keeps the router's line. - The arrow sits on the drawn line. Its heading, and so the camera's, comes from
puckLine,straightenJogsof the drawn line, so neither turns into a median jog and back out.RouteSmoothing.alongOriginalandmapAlongmap a distance on the drawn line to the same place onpuckLine. On 39 captured routes the arrow is never more than 1.4 m from the line. RidingpuckLineit was over 3 m off on 29 of them, up to 11.7 m.
The rules only drop or cut router vertices, and never touch a bend that keeps turning one way.
straightenCircles: the median-jog rule at traffic-circle size (CIRCLE_MAX_SPAN_M45,CIRCLE_MAX_JOG_M8). A route straight through a small circle follows half the ring.removeZigzags: drops a vertex whose segments are both under 35 m, that turns 15 degrees or more with an opposite turn of 15 or more next to it, within 4 m of its neighbors' line. Up to four passes, at most 5.3 m of movement.roundBends: bends underROUND_MAX_TURN_DEG(45) are cut twice, by at mostROUND_MAX_CUT_M(8 m) or a quarter of the shorter side. Junction corners stay exact.- The median-jog rule (the arrow's heading only): a stretch up to 140 m that leaves a straight road by 1 to 12 m and rejoins it within 2 m, on the same heading in and out within 3 degrees and along the chord within 7, becomes its chord. On the drawn line it put the stripe on the median of a divided road (up to 11.3 m off).
RouteSmoothingTest bounds them over 39 captured Google lines: no line longer, no length change
over 0.5 percent, no router point more than 12 m from the smoothed line.
The moving cut¶
The line is inserted above all road and bridge geometry and below labels: under the first symbol
layer after the last bridge_* layer. The style's first symbol layer, the one-way arrow, sits
under the bridges.
- During a drive the route is a traversed full line, a far tail, a 3 km ahead window and a
400 m cut piece (
ROUTE_CUT_LAYER) on top. The split is geometry, with traffic spans remapped onto each piece: MapLibre bakes aline-gradientinto 256 texels and has no line trim. - Per frame only paint changes: the cut piece's gradient carries the cut at 1.6 m per texel. Route geometry is never moved per frame or on a short timer.
- The cut piece slides about every 300 m. A piece or window that already reaches the route's
end does not slide or re-anchor, or the last
NAV_CUT_SLACK_MandNAV_WINDOW_SLACK_Mof every drive re-upload per frame. - With the driven trail off (
RouteTrail, default off) the ahead line's gradient is transparent up to one texel before the cut piece's end, so the piece paints over nothing. - Every moving piece is double-buffered (
ROUTE_*_B). A re-anchor uploads into the hidden copy, tagged with a generation number (ROUTE_GEN_PROP) and drawn atROUTE_PENDING_OPACITY(0.004; at 0 MapLibre never tiles the source). One frame afterquerySourceFeaturesfinds the tagged geometry, the copy goes to full opacity and the other is hidden. Re-anchored in place, the new gradient painted the old geometry for a frame. - The far tail is not waited on; it is usually off screen, where tiles never load.
- A copy outside
projection.visibleRegion(read at most once per frame) swaps at once. The query is a blocking round trip to the render thread, 3 to 45 ms on a Pixel 4a.ROUTE_PENDING_MAX_PASSES(40) is the backstop for a copy on screen whose tiles never report. - A cut piece under
ROUTE_PENDING_MIN_DP(4 dp) long on screen swaps at once too. MapLibre's tiler drops a line shorter than 0.375 px of its tile, so below about z6 the 400 m piece is in no tile, and waiting on it costs all 40 queries at every slide. A few dp under the arrow cannot be seen to flash. The window still waits at every zoom: its swap shows the far tail with it, which zoomed out is most of the route on screen. - While the camera is detached, a cut piece off screen is not repainted per frame.
- The six piece layers have no opacity transition (
lineOpacityTransition0); the default 300 ms fade dipped the route on every swap. - A change of color, trail setting or traffic spans repaints every piece in place
(
paintReset) and never re-anchors: paint lands at once and geometry a few frames later.
Colors¶
- A piece takes its base color from whether the route has traffic spans, not whether the piece
does (
routeGradient(routeHasSpans =)): free-flow blue when the route has any, the route's overall traffic color when it has none. Judged per piece, the 400 m under the car drew amber beside a blue line ahead. - A paused drive draws the ahead line in
ROUTE_PAUSED_COLOR(#9C8AD6), no spans, one color end to end. A slate gray vanishes into the dark map's road fill. - The route preview draws each traffic stretch as its own line (
ROUTE_TRAFFIC_LAYER, one feature per span, colored by level, from the driven fraction on). A gradient texel on a 30 km trip is about 120 m, too coarse for a short jam. - Alternates draw below the selected route, nearly as wide (6.3), as a faded blue fill on
ALT_ROUTE_LAYERinside a darker outline onALT_ROUTE_EDGE_LAYER(line-gap-width):#7FA9F0in#3566C4on the light map,#7C9FE0in#0E2247on AMOLED,#DCE7FFin#2F7BF0on the dark map, where a mid blue is the roads' own family. A plain gray reads as one more road on a dense grid.
4.9 Road furniture, cameras and alerts¶
Traffic controls¶
- Signals, stop signs, level crossings and speed humps come from the per-region road-features bake, with Overpass as the fallback only where no region exists.
- Same-kind nodes within
CONTROLS_CLUSTER_M(45 m) merge to their centroid. OSM maps one node per approach, and at 30 m a wide four-way drew two lights. - Icon size runs from 0.98 at z15.5 to 1.95 at z19.
- The browse map fetches them from z16 and draws them from
CONTROLS_BROWSE_SHOW_ZOOM(z19). Navigation draws from z15.4, just under the camera's 15.5 floor (NavFraming.ZOOM_FLOOR). With Zoom to the next turn the camera goes as far out as z12, where they do not draw. - A level crossing or hump within 25 m of a light or stop sign is drawn offset down and left
(
CONTROL_NUDGE_PROP). Camera badges nudge up and right. - OSM maps signals more consistently than stop signs (Delaware's bake: 2,331 signals, 2,144 stops), so a residential area can show lights and no signs.
During a drive only controls on the route are drawn, tested on raw nodes before clustering, since a cluster's centroid sits in the junction's middle. The corridor fetch is 120 m wide.
- A light, hump or crossing counts within
SIGNAL_ON_ROUTE_M(12 m) of the route (RouteProjection.signalIsOnRoute). The cross street's approach, the other carriageway and the parallel street are farther. Direction is not tested: a middle node is on two roads. - A stop sign counts within
STOP_ON_ROUTE_M(20 m) when its road orientation (0 to 179, from the bake) is within 40 degrees of the route's bearing there (RouteProjection.stopIsOnRoute,alignedWithRoad). Direction alone keeps the sign on the parallel street; distance alone keeps the one facing the cross street. - A stop sign with no orientation counts within
STOP_NO_BEARING_M(10 m). On a Davis route the route's own signs sat 0 to 8 m from the line and the cross streets' 12 to 25 m. The live Overpass path never has an orientation. - The bake (
scripts/road_features_tsv.py) takes a node's orientation from drivable ways only (motorway to track, a*_linkranked with its parent). A stop line's node is often shared with a crosswalk, which runs along the main road. A stop sign on a node shared by several roads takes the most minor road's orientation. It is empty when the sign is taggedstop=all, or when the most minor roads through it differ by more than 40 degrees. - The set is keyed per driven route, so a same-course heal never refetches, and capped at
CONTROLS_ROUTE_CAP(800) nearest the start. - While a corridor set is loaded the viewport path neither refetches nor runs its zoom-clear branch, and the viewport job re-checks ownership after its settle delay, or a box set replaces the corridor set 350 ms later.
- Corridor queries run off the main thread through
SegmentIndex(line simplified to 3 m, segments in 0.01-degree cells). A whole-region parse reads the inflated bytes once and parses decimals by hand into primitive arrays.
Plate cameras¶
FlockCamerasships a bundled floor plus a hosted update: a gzippedlat, lon, operator, directionTSV, about 129,000 points in the bundled July 2026 snapshot, loaded off the main thread into flat arrays with a 0.1-degree grid. The loader prefers the higher version and deletes a download the bundled floor has passed.- The weekly bake asks Overpass for every
surveillance:type=ALPRnode as CSV (157,576 nodes, 7 MB, in November 2026; the same reply as JSON is 59 MB and ran past the servers' gateway timeouts). It tries the three servers in order, twice, ten minutes apart. No answer, or one under 90 percent of the published count, keeps the published file and ends the run with a warning. - With a route up (chooser or drive) only cameras on a shown route draw (
FlockCameras.along, 45 m and facing the road). With no route the layer shows the viewport's. - Badges cluster at 40 m: below z16 one badge per cluster, from z16 one badge and a facing cone per head. The badge carries no count.
- Direction (
CameraFacing): the camera's facing against the nearest non-degenerate route segment's bearing as undirected lines,min(d, 180 - d) <= 50degrees. A camera with no facing counts. Applied to route counts, the avoid re-rank, the alerts and the route bar. - "Avoid surveillance cameras" (
FlockRouteAlert, also the pickers' "Avoid cameras" chip, which refetches the routes) re-ranks the alternates on offer. The fewest-camera route leads within a detour of at most the lesser of 25 percent of the ETA and 10 minutes. It does not route around cameras. - "Try side streets around cameras" (off by default, under the re-rank, drive mode only):
CameraDetourclusters each route's cameras (join 40 m, nearest first, at most 3) and tries the points 150 m left and right of the road at each. A candidate whose count drops within the same cap is kept and the next cluster builds on it. Per trip: at most 6 route requests, 4 on one route; a cluster within 60 m of one already tried is skipped.CameraDetour.chooseis the one rule for both: fewest cameras, ties to the faster, beating the leader within the cap. - A kept route leads the list and carries its waypoint plan (
Route.detourPlan). A drive on it holds the detour points as silent stops, which every reroute and recheck routes through and nothing speaks or lists.NavSession.withSilentViasputs those still ahead back in after a mid-drive stops edit.
Alerts¶
- Camera alerts (
CameraAlerts.due):LEAD_SECONDS12, floored atMIN_LEAD_M150 and capped atMAX_LEAD_M600, silent belowMOVING_FLOOR_MPS2.0, once per camera per route, never for a camera behind. Cameras within 40 m along the route are one alert. A speed camera alert is spoken and shown as a heads-up card for 6 s. A plate camera alert is the card, the voice, or both, by its two settings. - Speeding alert (off by default): after 4 s continuously over the limit, re-armed after 8 s back under, at most once per 45 s, with the badge's 5 km/h tolerance.
- The voice has three modes (issue 735), one state shared by Settings > Voice > Spoken
directions and the drive's speaker button, which opens the three with the current one filled
and steps On, Alerts only, Off, On on a long press
(
MapViewModel.setVoiceMode, prefsspoken_directionsandspoken_alerts_only,VoiceGuide.mutedandalertsOnly, the holderVoiceAlertsOnlyfor the hold control). In Alerts only the speeding, speed camera, plate camera and bridge alerts playVoiceGuide.alertChime, two short notes at 1046.5 Hz, instead of their spoken line (NavController.alert); every other chime and every prompt stays silent. Off is silent throughout. The car's speaker button steps the same three in the same order (CarVoice.step, issue #842) and shows the mode as its glyph (ic_car_unmute,ic_car_alerts,ic_car_mute); the car settings switch sets On or Off and leaves Alerts only (CarVoice.set). Both write the same two prefs; the phone's state follows the prefs through a listener, so the two never disagree. - Bridge openings (
BridgeAlert, on by default): a drive whose line enters the Netherlands (NdwBridgeOpenings.inNetherlands) fetches NDW'splanningsfeed_brugopeningen.xml.gz(about 115 KB, DATEX II v3), keeps the bridges within 30 m of the line and asks again everyBRIDGE_REFRESH_MS(5 min) for the whole drive, since the feed lists only bridges with an opening and one can be planned after the first ask. An alert is keyed by the bridge's meters along the line, not its place in the list.BridgeAlerts.duegives one alert per bridge withinAHEAD_M(5 km): "open" for a record with statusimplementedorbeingImplemented, else "opening planned at" for a planned opening withinMARGIN_MS(3 min) of the time you reach it, from the route's remaining time per meter. A planned bridge that opens is announced again.beingTerminatedrecords are dropped, and an "open" record older thanMAX_OPEN_MS(60 min) is ignored: the feed keeps some that were never closed. The alert is the card for 6 s, the voice (a chime in Alerts only, like the camera alerts) and a car toast. A recorded-trip replay asks nothing.
Street callouts¶
Cross-street labels are points Vela places, not line-center labels on the basemap layer.
- The pass runs once per 400 m of progress or when the upcoming turn targets change, never on a short timer. A quantum is marked done only once something was placed.
- Per crossing street: where it meets the route window (first proper crossing, else a
T-junction end within 25 m, 60 m for a next-turn target), then
NAV_XLABEL_OFFSET_M(35 m) up the street, on a ladder of offsets on both sides, the first with clearance. Points carry atierfor the class split and zoom gates. - Clearance runs from the route to the bubble's anchor, the tip of its tail. The chip is wider
than the anchor, so the gap on screen is under
NAV_XLABEL_CLEAR_M(44 m). BelowNAV_XLABEL_MIN_CLEAR_M(26 m) no callout is drawn. - A callout covers nothing. A candidate within
NAV_XLABEL_AVOID_M(30 m) of a drawn light, stop sign or camera is skipped (crossLabelPoint(avoid=)), and the cross-street layers sit below the camera badges, the controls' collision claim and the POI layer, so they yield. - The street the next turn enters (turn, slight, sharp and roundabout-exit maneuvers that name
a road or ref) gets a blue callout on
NAV_TURN_LAYER(#1A66D9) with its tail on the corner (TURN_CALLOUT_AHEAD_M, 0). It never yields, and steps into the street (TURN_CALLOUT_STEPS_M, up to 60 m) until no light, stop sign or camera is within 30 m. That street leaves the white cross-street callouts. - A passed callout is let go when its anchor projects within 28 dp of the nav bar's top edge
(
navBarTopPx) or off either side, checked everyNAV_XLABEL_TICK_MS(80 ms), withNAV_XLABEL_DROP_BEHIND_M(600 m) as the backstop. - A let-go callout fades on
NAV_ROADLABEL_FADE_LAYER, a collision-free layer whose constant opacity falls to 0 overNAV_XLABEL_FADE_MS(1.2 s). It is filledNAV_XLABEL_HANDOFF_MS(250 ms) before the main layers let go. A data-driven opacity on the main layers would re-run their placement every tick. - The main layers' filter is one
atMthreshold, lifted on re-upload over any callout whose street was already let go within 60 m. atMis measured along the current route line, so a new line starts the threshold over (resetNavLabelsForLine, at the top of the label effect). It used to be reset only when navigation started, and a reroute, a healed route, an added stop or an accepted faster route left every white callout of the new line hidden for as far as the old line had been driven.
4.10 Trips, replay and demo mode¶
- The trip format is
core/replay/TripLog: aMETAheader, then route blocks andlat,lng,t,bearing,speedfixes. Every fix also carries its provider and the engine's off-route hit count. - Trips are segmented. The start route and every mid-drive swap is its own
RP/RD/Mblock, active from the fix where it appears. Auditing or replaying a multi-block trip against one merged route corrupts it. - A drive resumed after its process died records into the trip it interrupted:
launchNavsaves the trip id undertripinvela_nav_resume, and resume reopens that file (TripStore.resumeTrip), writes aresumed:note and its route as a block with reasonresume. With no trip to continue it starts one. The fixes either side of the restart have a gap between them. RDcarries the route's provenance flags and source name, thennamed=KofN(how many of its lefts, rights and U-turns name a road or a number; ramps, exits, merges, forks and roundabouts are not counted, since a sign names them) andRoute.made, how the steps were put together: the open route's source and step count, the stretches where Google's line left it and their meters, how many were matched, named from tiles or left bare, the naming time,namingLatewhen the deadline passed first, andopenNames=for an open route whose names were checked. Counts and milliseconds only.- An
Mline's text may be followed by tab-separated fields: the road the turn enters, its ref, and the step's duration. A replay needs the first two for the callout and the shield. Remaining time is the sum of the step durations ahead; a file without them has the route's time shared out by step length at parse. - A
Tline afterRDcarries the congestion spans (level:startMeters:lengthMeters;...), so a replay paints the traffic the drive was shown. - Every nav decision is a
Kline written throughNavSession.onNote, never with a coordinate or a name: a stop reached is noted by count. A recheck's note gives the named turns of the candidate against the current route's. Aneta:note every 30 s records minutes and kilometers left, the step, the traffic ratio, the number of congestion stretches and the route's source. - An
Nline is one call of the nav engine as the drive made it:N,<t>,<kind>,<msSinceFix>,<lat>,<lng>,<speed>,<accuracy>,<bearing>. Kindfis a fix as it came,hthe last good position an outlier hold kept (files from 2026-11-11 to 11-17 also wrotehfor the dot's low-passed point, which guidance then steered by),da dead-reckoned point between fixes;msSinceFixcounts from the last fix line, and an empty field was not passed. The location path writes the route block first if the route changed (NavController.syncTripRoute), so an input never lands ahead of the route it ran against. A file runs about 600 KB per hour of driving, 39 percent of itNlines and 3 percentRC(a 4-minute Davis mock drive with two reroutes, 40 KB). - A
routing:note at the start says the units, the avoid switches, Google traffic, rechecks and the travel mode. - Each route fetch during a drive writes what the routers answered (
TripLines): aroute answers (reroute|ladder|plan):note with each router's count and time, how many of each turn the car round, the heading and how many of Google's were set aside, and anRCline per route:RC,<t>,<stage>,<source>,<flags>,<etaS>,<distanceM>,<encoded-polyline>, sourceopen,google,phoneor a fallback's, flagsback(it turns the car round),later(it does so further on, not where the car is) andaside(a Google route set aside). TripScrubdrops unknown line kinds, so a new line kind needs a decision there on whether it is safe to share. It keeps or drops anMline's extra fields with the line, and dropsT: a shared copy's route is trimmed and the offsets no longer fit.NandRChold positions and are dropped too; theroute answersnote has none and is kept.- Replay is hermetic:
NavSession.replayModesuppresses live reroute and recheck fetches, and recorded swaps play back throughreplaySetRoute. - A file with
Nlines replays them: the engine gets the drive's own inputs (fix, hold or dead-reckoned point, speed, accuracy, heading) at the moment it got them, the fixes move the dot, and a route swap lands at the first input that ran on the new block or at the fix where the block was written, whichever is first. The engine speaks in the units of therouting:note. An older file derives the inputs from the fixes as a drive would: GPS fixes of 50 m or better only, with their accuracy, and the fix's heading while moving (a recorded 0 is none). - Re-drive, the debug dial
debug.vela.tune.replayLiveat 1: the replay runs at 1x withreplayModeoff and plays none of the recorded swaps, so today's code reroutes live from the drive's own inputs. It is how a rerouting change is tried on a recorded wrong turn. Nothing is written to a trip; the nav notes and route answers go to logcat (VelaTrip, andVelaRCfor the routes when that tag is set to DEBUG). - The map scales the puck's clocks by
replaySpeedup: the chosen speed for a trip replay and 1 for a demo drive, unlessdebug.vela.tune.demoSpeedupis set. NavReplayruns fixes through the realNavEngineand checks cards and voice against the maneuver positions, flagging silent turns, early announcements and wrong distances.TripLog.audit(csv)is the one-call entry. WithNlines it runs the engine's own inputs, headings included; without them it passes each fix's recorded speed, as a live drive does: prompt distances, the line at the turn and chained-turn timing scale with speed, and a replay without it is timed for a crawl. Not the fix's bearing: one the phone gave none is recorded with 0, which reads as north. The on-demand harnesses take-DvelaTrip=<abs.csv>and-DvelaSeg=<n>, forwarded to the test JVM incore/build.gradle.kts.- Demo drive (pref
demo_drive, off by default):DemoTrace.fromRouteturns a planned route into oneReplayFixper second and runs it down the same hermetic path. The drive keeps a realistic pace: each step at its length over its time (4.5 to 38 m/s; the route's average or 13.4 m/s with no times), 13, 8, 5 or 3 m/s through a bend of 18, 40, 70 or 120 degrees measured 12 m either side, pulling away at 1.8 m/s2 and braking at 2.2, from rest to rest. A constant 72 km/h cut off half the spoken lines on 110 m town blocks; this pace cuts none (DemoTraceTest). The car waitsSTART_HOLD_S(3 s) before pulling away, while the opening line is said. The demo drives the route the drive is on: when it changes to a new line that starts withinDEMO_REPLAN_NEAR_M(150 m) of the car (a stop added, the stops edited), the trace is drawn again along it from the car's speed (demoReplanned). Start with a chosen start away from the car drives the planned line from that start; only a real drive re-plans from the car first (MapViewModel.startNav,START_FROM_ME_M; issue #835). It is presented as real navigation: the replay controls are hidden and End cancels the demo job, whosefinallyresumes live GPS. A demo that reaches the end of its route stays on the arrival card, as a real drive does, and Done ends it throughstopNav. -
LocationProvider.pinnedholds the simulated position (SimLocation.onChangesets it inVelaApp). While it is set, or a replay runs,updates()asks the phone for no fixes: it emits the pinned point once a second (providerSIM_PROVIDER) and mirrors the replay's fixes (REPLAY_PROVIDER), andlastKnown()answers with the pinned point. Every collector follows, the car screens included, so a head unit never shows where the phone really is. -
During a recorded drive
MapPerfis sampled once a second and writes aKnote for a UI stall ofSTALL_MS(250) or more, underLOW_FPS(20) map frames during a gesture, or a main-thread pass of 100 ms or more, at most one perMIN_GAP_MS(2 s). Acamera:note marks the camera leaving or rejoining the car. A summary is written every 10 s. - An
Sline is a line the voice said. With the voice muted or on alerts only, the line it would have said is still written, asSwith(muted)in front (VoiceGuide.onMuted). - Other
Knotes: build and settings, each spoken line's wait and render time, a change of the voice mode (voice: on,voice: alerts only,voice: off, from the speaker button, Settings or the car), and network, thermal, memory, screen and GPS changes. No note holds a coordinate, a name or spoken text. - A trip replay runs at 1x, 3x (default) or 10x, pauses, and seeks. A seek restarts it and runs silently to the chosen moment.
4.11 Tap-to-stop during a drive¶
MapPoiPrefs.navTapPlaces, off by default. Its setter also turns places on and remembers
whether it had to, so turning it off restores what was there. While it is on, the drive-nav
places filter widens from fuel only to NAV_DRIVE_GROUPS, and a tap on a place does not select
it. The place becomes navTapCandidate, which MapScreen renders as NavStopOffer above the nav
bar.
- The first tap only offers. The card's button is the only thing that changes the drive, so one stray touch at speed re-routes nobody.
- The card prices the stop. One route through the candidate is fetched, bounded at
NAV_DETOUR_TIMEOUT_MS(8 s), andDetourEstimate.minutesAddedcompares it with the drive's live remaining time. The candidate goes first in the waypoint list, whereNavSession.addStopputs it. A difference underMIN_SHOW_S(20 s) or overMAX_PLAUSIBLE_S(3 h) shows no figure. The fetch changes nothing in the session. - The card dismisses itself after 10 s, or 25 s under
dpadMode, shown as a countdown ring around the close button. The countdown is keyed onnavTapOfferTick, which every offer bumps, since a second tap on the same place leaves the state equal. - Within
NAV_STOP_MATCH_M(60 m) of a stop ahead the card adds "Remove stop" beside "Add stop", which drops the next occurrence throughapplyStops. Adding the place again stays possible. - The offer is drawn on the map as a red "+" teardrop (
PoiIcons.CANDIDATE_PIN), by the effect that draws numbered stops and the destination flag.
5. Places¶
5.1 Sources¶
Settings > Places > "Place icons on the map" (MapPoiPrefs.placesSource, pref
map_places_source), also a tile row in the map's layers panel (10.2, Browse map).
| Value | Label | Draws | Google while browsing |
|---|---|---|---|
open |
Vela data (default) | Vela's baked archive (5.2) | None |
both |
Both | The archive, plus what Google adds | One fan-out (5.4) once panning stops |
google |
Google's ambient places | A fan-out per pan or zoom |
- The fleet default is
calibration.jsondefaultPlacesSource, pushed intoMapPoiPrefs.setRemoteDefaultat init and after each refresh. An explicit pick always wins. - Where no archive covers the view, every value behaves as
google. - "Show places" is the master switch for the ambient layer, the open layer and the basemap POI
tiers (
refreshPlacesOverlays;onPoiPrefsChangedapplies it at once). - "Parks, schools and civic places" off drops the
park,eduandcivicgroups from the ambient pool and the open layer. MapPoiPrefs.lookupTappedPlaces(default on): whether a tapped open place is looked up on Google.
Both mode¶
Google wins a twin: its point is the storefront and its rank comes from review counts.
hideOpenTwins is debounced (400 ms and 2 s after an upload, camera still for
TWIN_PASS_STILL_MS, 700); a pass costs 80 to 190 ms in Manhattan on a Pixel 4a.
- It queries rendered icons only. A twin has the same normalized name within
DEDUPE_SAME_NAME_M(150 m), or passesPlaceNames.sameBusinesswithinDEDUPE_NAME_M(80 m) orPlaceNames.sameFuelLot. - Twins leave the open icon and dot layers. A hidden id whose Google partner is gone is released.
- An open icon matching a permanently closed Google listing within 80 m, with no open listing
of that name within 150 m, joins the persisted closed set (
CLOSED_OPEN_PLACES_CAP, 2,000). - Offline nothing is hidden.
Basemap POI tiers¶
poi_r1, poi_r7 and poi_r20 hide when "Show places" is off, in a route preview, over an
archive whose rev is at least tuning.placesOneSetRev (20260923; it carries OSM's landmarks
itself), and, outside navigation, when the ambient pool covers the view or several search
results are up. Over an older archive they stay, or its parks would vanish, and their
vegetation exclusion (wood, forest, tree, grass, wetland) must not cover park or garden. In
drive navigation they show fuel only.
Where they hide for the one-set archive or the ambient pool (browsing, at most one marker),
vela-osm-parking shows the basemap's car parks with no name (class parking): the bake drops
places without a name and Google's dots have no parking lots, so those lots had no icon at all
(issue #935). A named lot is in those sources and would draw twice. It is one layer over the
poi source-layer below poi_r20, rank under 20 from z15 and every rank from z18, as the tiers.
Keeping the three tiers up with a parking filter instead cost frames over Shinjuku's dense tiles;
the one layer did not measure (Shinjuku, z17 pan on a 4a, three runs each: 38 fps median with
it, 41 hidden, 50 for a placebo layer hidden).
Over an older archive osmFillIn drops OSM points whose name matches a drawn open icon within
80 m (OSM_AREA_TWIN_M, 1,500 m, for area classes). It is viewport-only, rendered-only and
grow-only (OSM_EXCLUDE_MAX 1,500 names; each setFilter re-lays the source), and throttled to
once per 2.5 s after a fifth of a screen or 0.4 zoom of movement. A rendered query costs 37 to
55 ms in a dense view. Never build a Regex inside a per-feature loop.
5.2 The places bake¶
tools/build-places-region.sh <id> S W N E out.pmtiles [release] [local.parquet] runs DuckDB
over Overture Places (public S3 parquet or a local extract) and writes PMTiles (tippecanoe
-Z11 -z17).
Sources¶
- Overture: businesses only; its park, school, campus, housing and transit rows are dropped.
Categories are the
categories.primaryset, and a release withtaxonomyis mapped back throughtools/overture-taxonomy-map.csv. - AllThePlaces: the newest weekly run (
data.alltheplaces.xyz/runs/latest.jsonunlessATP_RUNpins one; the last pinned id is the fallback). Rows come from the world PMTiles (pmtiles extract --bbox, tippecanoe-decode, jq), filtered and mapped byisbizandosmcat. Confidence 0.85. Chains carry OSM-syntaxhours. - OSM business nodes: the Geofabrik extract through
osmium tags-filterand geojsonseq (strip the 0x1e separator before jq), same macros. Confidence 0.8; the id is the node id. Ways and relations stay out: a building centroid is the same guess as a parcel point. - A row is added only where no row of the same brand or the same two leading name words sits within about 150 m. A dropped duplicate still gives its hours, phone and website.
Name keys and folds¶
snapkeymirrorsPlaceNames.normalizedand keeps letters of every script ([^\p{L}\p{N}]is the separator, likePlaceNames.PUNCT); a Latin-only key made every name rule a no-op in non-Latin regions.- The core key is the snap key minus the words in
tools/place-generic-words.txt(PlaceNames.GENERIC, pinned equal byPlaceNamesTest). A street number or one word under five letters is not a core. - Rows with the same snap key within about 60 m collapse onto one leader. Fuel rows also key
by house number (
fuel@<number>). - Rows with the same core key within 60 m fold too, when every word of one snap key is in the other. A shared core alone folded the Empire State Building into "Empire Beauty School".
- Leader: the row standing for a landmark, then not a kiosk, confidence, more fields.
- The OVERLAP family (5.5) stays app-side: it needs the kinds and the pool's shared words.
Positions¶
Preference: OSM, the AllThePlaces locator, Overture's parcel point. Tenants never move.
osm_snapmoves a row onto an OSM node agreeing on the whole or the core name within about 150 m (120 m for a chain). Mutual best match only.- An Overture row moves onto a same-name locator point 30 to 120 m away. Under 30 m the two agree (median 7.4 m on Davis chains).
- Overture stacks a building's tenants on one parcel point (17% of Davis rows). A tenant whose address names a unit snaps to the Overture address point with that house number and unit within about 200 m.
- The rest of a stack spreads on a golden-angle ring of 10 to 20 m (8 m plus 2 m per row, capped at six), best row in place.
Landmarks¶
OSM landmarks, points and polygons, are baked in: tourism museum/attraction/gallery/zoo/theme
park/aquarium/viewpoint; amenity place_of_worship/school/college/university/library/hospital/
townhall/community_centre/theatre/arts_centre/courthouse/police/fire_station; leisure park/
stadium/sports_centre/water_park/garden/nature_reserve; historic monument/memorial/castle/
ruins/archaeological_site. A second osmium pass (wr/wikidata, then
wr/building wr/man_made=tower; osmium cannot AND two tags) adds named buildings with a
Wikidata link as landmark_and_historical_building.
- A landmark that matches existing rows by snap key is not added; one row stands for it
(
markbest: its own category, else a landmark category, confidence, distance). - Notability orders
lrankandxrank: outline size (log10 of the area in m² minus 2, 0 to 3), Wikidata (1.5), fame (0.6 x log2(1 + name languages), capped at 3). - Wikidata credit needs a name in three or more languages when the object is only a building
(
markcat0null). landmarkis 1 for anchor categories (hospital, university, stadium, mall, zoo, museum, airport) and for a park, attraction, historic, civic or religious place with Wikidata credit, an outline of a hectare or more, or fame of 1.5. A landmark is never a tenant.
Tenants and kiosks¶
- Flagged
tenant: a department of an anchor within about 200 m (address, brand or name-head match), a kiosk category or name, or an anchor brand's fuel station or convenience shop within about 275 m. - A department or forecourt loses 2 prominence points. A tenant bakes at minzoom 17, except fuel, which stays visible for driving.
- The demotion is a semi-join (
EXISTS), not a LEFT JOIN: a tenant matching two anchors is otherwise emitted twice. - A forecourt row named exactly like its anchor gets " Fuel", " Charging" or " Market" appended, or store and pumps draw under one label. No other name is rewritten.
Closed places¶
Overture's confidence is not a sign of life, so three signals delete rows before scoring:
- Foursquare, by exact id (
FSQ_SQL): for a row whose first Overture source is Foursquare,sources[1].record_idis Foursquare's id. Rows with adate_closedare dropped, unless a live second source lists them (an OSM business of the same name key within about 150 m, or a chain locator match). The newestfoursquare/fsq-os-placesrelease is read whenFSQ_HF_TOKENis set (a repository secret inplaces-overlays.yml), else a public mirror of the 2025-02-06 release (FSQ_BASE).FSQ_CLOSED=offskips it. - OSM lifecycle tags (
GONE_SQL): named nodes and ways taggeddisused:orwas:+shop/amenity/tourism/leisure, orabandoned:orclosed:+ the first three, with no live tag. A non-OSM row with the same name key within about 80 m is dropped, unless a live OSM business of that name is there. - Wikidata: an OSM object whose item has a dissolved or demolished date (P576) in the past is
removed and joins the closed list. P3999 is set on venues that reopened and is not used.
WD_CLOSED=offskips it.
Overture's update_time (its import date) and a chain's own locator (incomplete per brand) are
not used. Foursquare OS Places is Apache 2.0, notice in
tools/licenses/FSQ-OS-PLACES-NOTICE.txt. No Foursquare record is published in an archive.
Prominence¶
A category prior, plus 1.6 for a brand, 0.5 for a website, 0.4 for a phone, 0.2 for an address,
plus (confidence - 0.5) * 1.6, plus srcbonus, plus the landmark's outline size.
| Prior | Categories |
|---|---|
| 4.5 | Anchors: hospitals, universities, supermarkets, museums, malls, airports |
| 3.2 | Hotels, pharmacies, banks, attraction-type landmarks |
| 2.6 | Food |
| 2.2 | Everyday services, parks, schools, places of worship |
| 1.6 | No category |
| 1.0 | Otherwise |
| 0.5 | Offices |
srcbonus: 0.6 for an OSM pair, 0.6 for a chain-locator match, 0.8 for a Wikidata link on the paired OSM node, 2.0 for a landmark with Wikidata credit.- An Overture row with confidence under 0.75 that no second source lists (no
srcbonus, no outline) is capped at 3.0 and is never a landmark: closed and miscategorized places sit there.
Ranks and minzoom¶
Cell ranks: frank (about 100 m), rank (400 m), crank (1.6 km), xrank (6.5 km). lrank
is the landmarks' own budget per 1.6 km cell and is not written to tiles.
| First match | Minzoom |
|---|---|
| Tenant other than fuel | 17 |
Landmark, xrank 1 |
11 |
Landmark, xrank <= 3 |
12 |
Landmark, lrank <= 4 |
14 |
Landmark, lrank <= 10 |
15 |
crank 1 and prominence >= 6 |
13 |
crank <= 2, or prominence >= 5 and crank <= 6 |
14 |
rank <= 3, or prominence >= 4.5 and rank <= 8 |
15 |
rank <= 12, or prominence >= 3.5 and rank <= 24 |
16 |
| Else | 17 |
The cell budgets are caps. When prominence bypassed them, a z16 tile in central Tokyo carried 963 places (Davis: 86).
Tile properties¶
id, name, name_en, class, group, icon, prominence, confidence, brand, addr,
loc, website, phone, hours, src, origin, landmark, tenant, mark, and the
ranks frank, rank, crank, xrank.
srcstaysoverturefor every row because the tap gate keys on it.origin(overture,atp,osm) tells the datasets apart.mark(0 or 1, always written): an OSM landmark or building, or the row standing for one.name_en: a non-Latin place's English name, from the OSM row's tags, its name pair, or the chain dictionaryendict(side tablenames_en). Shown under a Latin-script UI and used by the twin test.
Script and workflow rules¶
- Every row-to-row rule is a hash join; a correlated subquery or an OR of tests goes quadratic over a state.
- Every S3 read prunes on
bbox, never on the geometry: on Kentucky the geometry filter was 504 s of a 570 s bake,bboxunder 4 s. - DuckDB runs with
-bailand.timer on, and the bake step sets pipefail (its output goes throughtee), so a crashed bake fails its job. - The main heredoc is unquoted: a backtick in a SQL comment executes as a command.
- DuckDB is pinned (1.5.4), and the toolchain cache key names the pinned versions. DuckDB 1.5.6
crashes (
INTERNAL Error: Failed to cast expression to type) onrow_number() OVER (...)filtered to the first row over a join with a distance filter; those statements usearg_min,first(x ORDER BY ...)orDISTINCT ON. - A seventh of the catalog rebakes nightly, so an OSM edit reaches the map within a week;
only=<region>ships one region. A full nightly rebake would offer every download a fresh copy daily. scripts/archive-churn.pyhashes two archives' tiles and builds azstd --patch-fromdelta;places-churn.ymlbakes a region against OSM extracts N days apart. Kentucky over seven days: 1.3% of tiles, 3.2% of bytes, a 4.4 MB delta against 183 MB.
5.3 What draws, by zoom¶
Density is decided by rank, not by collision. The named numbers are calibration dials.
| From zoom | Icon and label when |
|---|---|
| 11 | In the tile |
| 13 | crank <= 2, or prominence >= 6.0 |
| 15 | rank <= 1, or prominence >= 5.0 |
| 16 | rank <= openRankZ16 (3), or prominence >= openPromZ16 (5.5) |
| 17 | rank <= openRankZ17 (8), or prominence >= openPromZ17 (5.0) |
| 17.5 | frank <= openIconCapNear (8), or prominence >= 6.0 |
| 18.5 | frank <= openIconCapClose (16), or prominence >= 5.0 |
| 19.5 | frank <= openIconCapMax (40), or prominence >= 4.5 |
- From z13 to z17.5 a landmark always passes.
- A tile with no
frankfalls back torank<= 4 times the cap. - A tenant other than fuel gets no icon from z17.5 to z18.5, so the store owns the block.
- Default-group and health-group places need the top
openGenericBlockTop(3) of their block oropenGenericMinProminence(4.0), else they stay dots untilGENERIC_ICON_ZOOM(20.3). - In a packed area such a place past
rankopenGenericHideRank(GENERIC_HIDE_RANK, 120) draws no dot either, from z17 toGENERIC_REVEAL_ZOOM(19.5). The rule applies only wheremarkexists and is 0 andlandmarkis 0, so it never hides a named building. - Labels use the icon steps. From z17.5 only
rank<=openLabelCap(20), prominence >= 3.0 or a landmark gets a name: a label is glyph layout plus a collision pass over four anchors. - Everything below the cut draws as a category-colored dot. Dots thin by opacity steps, because
a filter cannot read zoom: none below z15,
rank<= 6 at z15, <= 15 at z16, all from z17. - Settings > Places > "Place names" (
MapPoiPrefs.namesSooner, prefmap_poi_names_sooner: Default 0, More 1, Most 2) moves every icon and label step in this table, and the ambient label steps (5.4), out by that many zooms. The dot steps and the overlap zooms stay. The tiles cap what can draw: a z15 tile holds only places baked for z15 (5.2, Ranks and minzoom). - Icon overlap is allowed from z18 on the open layer and z17 on the ambient layer. Below those, Google's extras lose collision to the open icons.
- Route preview: the basemap tiers, the open layer, transit icons, stop badges and saved pins all hide. The destination draws as its own pin with its name; the flag pin marks only a trip ending at "your location".
- Drive navigation: the open layer is fuel only, with no dots, hidden for the first
NAV_PLACES_HOLD_MS(7 s). With "Tap places while driving" on it showsfuelandfoodwithfrank<=NAV_DRIVE_BLOCK_TOP(2). - The ambient GeoJSON source is maxzoom 18. Past a source's maxzoom every overscaled tile lays out all its parent's features: maxzoom 12 gave 22 fps where 18 gives 43 (Manhattan, Pixel 4a).
5.4 Google ambient ranking¶
ambientProminence = ln(reviews + 1) * (0.6 + rating / 10) + (categoryPrior - NEUTRAL_PRIOR) *
PRIOR_WEIGHT, with NEUTRAL_PRIOR 2.2 and PRIOR_WEIGHT 0.9. Review count dominates, the
prior makes a supermarket outrank the sushi counter inside it, and a place with no category
sinks.
- The on-screen set is capped by zoom,
ambientCapMin(45) at z14 toambientCapMax(140) at z17.5. - Labels (
ambientLabelField): prominence >= 6.0 below z15.5, >= 5.0 from z15.5, >= 3.0 from z16.5, every place from z17.5. "Place names" moves these steps out (5.3). - The collision sort key is
(10 - prominence) * 1000 + i, never the list index: the streamed pool re-ranks as terms land, and an index key reshuffles placement on every partial upload. - Sticky ranking (
AmbientStability): a settled view is painted several times with different review counts.rememberfreezes each place's prominence at its first rich paint; an all-zero pool is the slim flavor and is not remembered.prominenceOffeeds the view filter, the cap, the collision order and the icon sizes.reset()runs on the re-query gate. - Slim flavor: a fresh session's first seconds return rating without review count.
nearbyPlacesdetects it (at least 3 rated, a majority without counts) and refetches once about 1.2 s later, healed places first sodistinctBykeeps the rich copy. Before diagnosing a flat ambient layer, check whether the pool's counts are null. - Fan-out:
nearbyPlacesfires 15 category requests (8 on the lean path), each parsed whole into a JSON tree of roughly 30 MB in a dense area. ASemaphore(4)(ambientFanoutPermits, read at construction) bounds them; unbounded, a fresh launch held about 400 MB of parse trees (Pixel 9). Do not unbound it. - Partial paints escalate their batch (25 places, then 50 more, then 80 more once 100 are painted), because each re-runs whole-layer placement. A partial never shrinks the painted set.
- Offline or with Google off (
googleOff()),maybeLoadAmbientPoisreturns after the cache repaint, so a visited area keeps its dots. On a flaky link each request would hang to the call timeout. - An empty
nearbyPlacesresult is never cached: each term swallows its network error into an empty list. On null or empty the painted set stays, the freshest covering entry is served whatever its age, andlastAmbientCenterstays unset so the next settle retries. ambient_cache.jsonholds 32 areas of 200 slim places (14-day TTL, write-through from non-empty results, blank areas dropped at load). Entries carry their fetch span and a hit is withinspan * 0.45. The cache repaint is unconditional.- A fetch under
AMBIENT_FRESH_MS(3 min) old that still covers the view is served as is: Google's ranking jitters between identical requests, and the tap-frame camera shift trips the moved gate.
5.5 Tap resolution¶
A tap queries a box 24 dp around the finger. Each class picks the feature nearest the tap in screen pixels, never render-stack order. First match wins:
- the parking pin;
- a search-result pin;
- a saved pin;
- a grayed alternate route line;
- a business or a canonical GTFS stop icon, competing by distance. A class priority let a few-pixel dot steal a tap on an icon;
- a house-number label;
- an unnamed POI icon, reverse-geocoded at the tap;
- a custom map's or drawing's line or area (the line wins);
- a building footprint, reverse-geocoded at the tap;
- nothing. Only a long press drops a raw coordinate pin.
What is drawn under the finger wins: before step 5 the tap asks what is rendered at the finger's own pixel on the business icon layers, and when something is, only those compete. A pin is anchored at its tip, about 40 px below its blob, so distance to the point favors a tenant's dot. With no icon under the finger the box rules run. During navigation a tap opens nothing.
A house-number tap keeps the tapped number. The reverse geocode (Nominatim) supplies street and city, and a regex replaces its house number, which is often the neighbor's. The tile's road name vetoes a mismatched geocode street unless the geocode's house number is exact.
Resolving a named place¶
MapViewModel.onPoiTap searches the tapped name at the tapped point. A non-transit tap never
adopts a listing whose category is transit or map furniture (JUNCTION_CATEGORIES). The pool
is the first non-empty of:
- listings within the 1.5 km cap that are the same business (
PlaceNames.sameBusiness, the listing's town andlocalGenericas generic words); - the cross-script second search (below);
- listings of the tapped kind within
NO_NAME_MATCH_M(60 m); kindBesideAnchor: one extra search for the tapped kind around the nearest name-agreeing listing on the lot, nearest same-kind hit within 60 m of that anchor;- anything within 60 m.
Then:
- The house number gates it. When the tapped row and a candidate both have one and they
differ, the candidate is out of every fallback and out of name matches beyond
SAME_LOT_M(120 m). On the lot an agreeing number wins. A missing number decides nothing. - A live listing beats a permanently closed one.
- On the lot, listings whose name is the tapped name (
PlaceNames.same) beat the loose pool, and among them those of the tapped kind: a brand's store, fuel station and pharmacy all agree loosely. - The nearest wins, unless one within 35 m has
reviews >= 2 * nearest.reviews + 5. - The pick must be within 1.5 km of the tap, 30 km for a settlement label, unbounded for a transit stop. Otherwise the label keeps its own name and point.
- A permanently closed pick hides the open pin for good, unless a live listing of that name is within 150 m.
NameScript.prefer(uiLang, google, label)keeps the map's label as the sheet title when Google's name is not in the app language's script and the label is.openPlaceCacheremembers each open place's listing (an LRU of 500, persisted toopen_place_links.json). It is dropped when the app updates or the region's archive changes: a link made by an older rule outlives the fix. The recorded closures are kept.- Offline or with Google off (
googleOff()), the tap runs no search, reviews or photos. An open place shows its tile data or the remembered listing. - The
VelaTaplog line carries each gate's counts (cross=N) and no coordinates. - A tap Google did not match keeps the open data's address, which is often a city alone. With
no street line (no digit) it takes the address at its point (
fillUnlinkedAddress): the on-device address index (OfflineAddressStore.reverseGeocode,completeAddress), else the reverse geocode a dropped pin gets. Google was just asked about this place by name and point, so the second request adds nothing it did not have. - Any selected place with no street line that is not a Google listing (an open-data place, a
saved place kept without an address) is filled from the on-device address index, online or
offline (
backfillOfflineAddress). That fill never asks Google, so opening a saved place sends its location nowhere.
The same-business rule¶
core/util/PlaceNames is one rule for the tap resolve, the Both-mode twin hiding and, mirrored
in SQL, the bake's dedupe. PlaceNamesMatchTest pins it.
normalizedfolds accents (and ß, æ, ø, œ, ł, đ, ё), drops parentheticals, legal forms (LLC, Inc, GmbH, SARL, S.r.l., B.V., ООО, Kft), chain tails ("by Wyndham"), a leading "The" and a trailing store number, reads "&" as "and", keeps a possessive on its word, expands abbreviations (St, Ave, NY, Dr, Str., ул.) and joins dotted initials ("U.S." is "us").match(a, b, extraGeneric)answers EXACT (normalized equal), VARIANT (one name is the other plus only generic words: "CVS", "CVS Pharmacy"), OVERLAP or NONE.- OVERLAP: nested with non-generic extra words ("SpeeDee-Midas" over "SpeeDee"); two identifying words in common; a brand prefix of two or more words; the shorter name as a phrase inside the longer; or the shorter's identifying words all inside the longer when the longer leads with them.
- A nested or subset match needs a strong core: two identifying words, or one of five letters that is not an ordinal. A four-letter brand (Lidl, Aldi, Rewe) carries it when it leads both names and the longer adds exactly one identifying word.
- A single shared identifying word is not a match ("Arroyo Park", "Arroyo Pool"), and a name of only generic words matches nothing by overlap.
GENERICis the union of one table per language (en fr de es it pt nl sv pl ru uk hu he, about 1,850 words): names on a map belong to the region, not the phone. A caller adds the town out of an address andlocalGeneric(names), the words three or more names in the pool share.- Plurals fold pairwise. A name glued into one word of eight letters or more is read as the words that spell it.
- Scripts written without spaces (Han, kana, Hangul, Thai) are compared as strings by
cjkMatch: descriptor affixes (店, 支店, 薬局, 銀行, 有限公司, 지점, สาขา) are stripped, equal cores are a VARIANT, a core inside the other an OVERLAP, and a core under two characters matches nothing. sameis EXACT only;agreeis anything but NONE.sameBusiness(a, kindA, b, kindB)refuses an OVERLAP between two known, different icon groups (a fuel station and the pizza place on its lot). EXACT and VARIANT cross kinds ("Safeway Pharmacy", "Safeway"). Two names that reduce to one four-letter word match when their kinds agree.sameFuelLot(kindA, kindB, distance, numberA, numberB)calls two fuel stations withinFUEL_LOT_M(30 m, short of a road plus two setbacks) one station whatever their names. Two known house numbers that differ refuse it. Ambient features carryhnfor it.- Not in the rule: a non-fuel department at the same point with a different name, and Google's two profiles for one business.
Cross-script: Google answers in the app's language where the archive has the local script, and
no name rule bridges that. When nothing agrees and the label's script
(NameScript.scriptLanguage: kana or Han inside Japan ja; Han elsewhere zh-CN, zh-TW over
Taiwan, Hong Kong and Macau; Hangul ko; Cyrillic ru; Hebrew iw; Thai th; Arabic ar;
Greek el) is not the app's language, MapViewModel.crossScriptCandidates runs the search
again with hl=<that language> (MapDataSource.search(lang)), keeps the listings that agree,
and fetches the nearest one's copy in the app's language by its own name. The copy replaces it
when the feature ids match. Two requests at most.
5.6 Search and results¶
- A query runs three pages of 20 over the viewport window. When the user is inside the window
and it is over 1.5 times
NEARBY_SPAN_M(2.5 km), or no window size is known, one extra page runs over a 2.5 km window around the user and leads the list. SearchPb.buildstretches the template's window to the viewport span, floored atMIN_SPAN_M(1 km) and capped at 500 km.- Ranking and shown distances use
rankFrom: the user's location within about 50 km of the viewport, else the viewport center. The request bias stays the viewport.plausibleBias()discards a point near0,0. - A name match "near you" that replaces a far view's results must not be permanently closed and
must be within
HOME_NAME_MAX_M(40 km) of the user. - The "more results" row pulls the next three pages. It goes when a pull adds fewer than five or the query changes.
- "Search this area" keeps the results inside the view, padded by 10% per side
(
AreaNarrow.PAD), or the whole answer when none fall inside. A list the pan minimized stays minimized until the search answers (runSearch(expand = false)): opened at once, it still held the old results and the map framed them before the new ones. The camera's remembered center becomes its own target after the pan, at the view's zoom (centerZoom), so the map does not move: a center alone flies at the browse zoom (15.5). - Filters are local to the fetched results and also drop the map pins. "Open now" also asks
again: the fetch is about 60 results, and late at night nearly all of them are closed, so
the chip calls
MapViewModel.searchOpenNow(throughSearchActions), which searches the same words withsearch_open_now_phrase("open now") added, and Google answers with open places. The search box keeps the user's words and the reworded search is not added to the recents. Off asks the plain search again. A saved or imported list, an offline search and Google off keep the local filter only. - One quick-category list (
ui/QuickCategories) serves the map chips, search along route, in-nav search and the car's lists. Every query must be one the offline store expands.catalog()is every chip in the default order,arranged()the catalog in the user's order andall()what the rows show, the arranged list less the chips switched off (QuickChipsPref, keysquick_chips_orderandquick_chips_hiddeninvela_settings). A chip is keyed by its English query, never its position; the fuel chip's key isGas stationwhatever region word its query uses. The order rule isQuickChipOrder.arrange: the saved keys first, in their order, then every other chip in its default place; a saved key with no chip is skipped. With a saved order, a chip that returns (Bars after "Hide adult categories" goes off) or arrives with an update takes the end; with no saved order (only switches changed) it sits in its default place.homeNameHitstests a typed query against the catalog, so a chip switched off is still a category when typed. - The camera frames the first
SEARCH_FIT_LEAD(12) results; an open list or custom map is framed whole. Pins are median-centered, and outliers past 4 times the median spread (minimum 40 km) are dropped. The fit consumeslastCameraTarget, or the recenter branch re-fires on the stale center. - A search from a close zoom holds its view: no fit under
HOLD_VIEW_SPAN_M(2.5 km) with at leastHOLD_VIEW_HITS_NAME(1, a name:SearchKind.isName) orHOLD_VIEW_HITS_KIND(3) results in the visible strip. - Opening a place flies to it at
browseZoom(15.5, a dial) or the current zoom, whichever is closer; it never zooms out. A link's own zoom (geo:...?z=,/@...,15z) wins. An area result frames by its kind, opened or leading a results list (Place.areaZoom, carried onMapMarker.areaZoomfor the results fit; issue #752): the keyless search answers a country, a state, a county, a city or a postal code with no bounds, so an entry with no category and no rating and no address at all is a country or a state (6.5), one whose address is only its region is a city or a county (11.5), and "Postal code" is 13. Anything else is a place. - Result markers are red circles; rated food results get a rating bubble. Pins collide by result order, and losers draw as small dots.
- Result cards show the name, a facts line, the open-or-closed line, amenity ticks, up to three
photos from the search reply, and buttons that act without opening the place (Directions,
Call, Website, Share, Menu). The address shows only when the name repeats, the place is
unrated, or there is no photo strip. No extra request is made per result. A closed place
reads in plain red on dark surfaces (
themedStatusColor). - A result's distance is from the point its search ranked from. A tapped map place and a saved
or recent place are looked up around their own point, so
MapViewModel.fromHeresets their distance from the user's position, or none without a fix.
Suggestions and addresses¶
- Network suggestions come from Google's search-as-you-type request (
MapDataSource.suggest, the keyless/s?tbm=map&suggest=pcall biased to the viewport). A row without a location runs as a search. When it fails or is empty, or Google is off, the search endpoint and OpenStreetMap race answers. - A query that is only digits (a house number being typed) keeps Google's rows within
SUGGEST_NEAR_M(80 km) of the view when there are any (issue #746): the keyless autocomplete mixes the same number on streets abroad into its rows (two of four from a view over Paris, 2026-10-10), and aglcountry code makes no difference to that. - Local suggestions (recent queries and places, saved and list places, opted-in contacts) are computed synchronously per keystroke and are all that shows offline. Contacts load into memory once. They dedupe against network rows by name plus coarse location, and by feature id.
- Every row except a contact has a fill-in arrow.
AddressQuery.parsereads a leading house number and the street's first word that is not a direction or a street type;matchesneeds both as whole words of a result.- A typed address is searched over at least
ADDRESS_SEARCH_SPAN_M(40 km). When no matching result lies that near the view, the suggest request geocodes it. Matching rows lead, byAddressQuery.score(a point per typed street word, minus one for a different direction or street type: "1451 W Covell Blvd" before "1451 East Covell Boulevard"), then nearest. - The on-device geocoder's estimates (ids
addr~,OfflineAddressStore.isApproximate) are dropped when another result has the address. Bracketing house numbers overINTERP_MAX_GAP_M(300 m) apart are not blended; the nearer one's point is used. - A place named by a street line whose address holds only the town shows and copies the two
joined (
Place.fullAddress). A listing keeps its own address when the first part of that has a number (hasStreetLine); one without, an address Google files under a category, is joined too. - Typed coordinates drop a pin:
MapLinkParser.parseBareCoordinatematches the whole string, requires a decimal point in both halves and range-checks.
Without Google, from a wide view¶
- "Near", for answering a name from Vela's own data alone, is capped at
GOOGLE_FREE_NEAR_CAP_M(25 km): from a whole-world view every hit was inside the view and the open geocoder was never asked. - Over a view wider than
GOOGLE_FREE_WIDE_M(50 km) a name search leads with the geocoder's ranking and keeps at most five own hits, only those carrying every typed word. A top hit named exactly as typed opens on its own. - Photon is asked in English when it does not speak the UI language. A Photon hit with a name and a kind (not a bare house or street) takes that name, its kind the category.
Saved rows and links¶
- A saved pin or address is a point (
SavedPlace.isPoint:bare, apin:id, or a name that is the first line of its own address) and reopens as saved, with no search. Saving a place that is not a listing (Place.isListing()false) setsbare; so does a contact's address. - A reopened point also asks what Google lists on it (
MapViewModel.listingsAtPoint): its address, or its name when it has none, is searched once, and the listings withinSAVED_ENRICH_SAME_SPOT_M(30 m) go under the sheet's "Also at this location", a tap from their pages. The point stays the place that is open. Online, with Google on, and not for a label that is still looking for its own listing (awaitsListing). - A star or a list entry made from a map label before its listing was known (the tap still
resolving, no connection, Google off) is kept under the label's id (
LabelPlace:poi:plus the name's hash for a basemap label,overture:plus the feature's id for an open place). The star isbarewith an id that still matches its name (SavedPlace.awaitsListing; a renamed one no longer matches and stays a point). The list entry has no feature id (ListPlace.awaitsListing). - Such a place takes its listing when it is next opened online with Google on
(
MapViewModel.relinkKept, onesearchOnceby its name), or when a tap on its label (the one it was made during, or a later one) resolves to a live listing that agrees by name. On open,keptLabelListingaccepts a listing whose name agrees, withinKEPT_LABEL_MAX_M(250 m), open, with a feature id and no other house number than the kept address; a transit stop or a junction is never taken; the same name leads, then the nearest. The listing is written back (linkSaved,linkListing): the star losesbareand takes the listing's point and address, and every list entry kept from that label takes the feature id and address. The kept name, note and icon are not changed, and a sheet opened from the kept place keeps its id and name, so the star and the list marks hold. A basemap label's id is shared by every place of that name, so only a copy withinLabelPlace.SAME_LABEL_M(30 m) of the opened one is written. - A star put on a sheet that has a feature id before its details loaded (a picked suggestion)
loses
barewhen that sheet becomes a listing (mergeDetails: same id, same name). - None of this asks anything at launch, offline or under "Use Vela without Google". With "Look
up tapped places on Google" off, an
overture:entry opened from a list is not looked up. - Any other saved or recent place takes a listing's details only from one within 30 m, or
within 250 m whose name agrees (
PlaceNames.agree). - Rename (
SavedActions.rename,MapViewModel.renamePlace) is on the pinned rows, in the sheet's save menu, on a search-page row's own menu (SuggestionOverflow) and on an open list's selection bar for exactly one picked place (BulkBar,renameListEntry; issue #736, where the reporter looked for it), for a saved place and for a place in any list: it renames the saved record (marked bare only when the Place is no listing, carries no feature id and the record already reads as a point, so a starred listing renamed from a list row keeps its lookups) when there is one and the place's entry in every list (PlaceListStore.rename). An address saved from a search carries its street as the name and the locality as the address, so a rename, and setting Home or Work, moves the street into the address first (SavedPlace.addressKeepingStreet: a point whose address does not already start with its name, or a record named by a street line whose address has none, an address Google filed under a category and so saved as a listing), once: the record is then markedstreetKept, so a second rename leaves the address alone. Whether the place is a point is read off the stored record, never off the Place a row hands in, which carries no listing fields. An address picked from a search as Home or Work is kept as a point (MapViewModel.isAddressPick: a result with no category, rating or reviews), so its street moves in too. A Home or Work kept before that, with a street line for a name (a house number first or last,SavedPlace.isStreetLine; "7-Eleven" is not one) that its address lacks, is mended once at start (SavedPlace.labelMended). The row, Copy and Share keep the street. The listing's name is taken only when it agrees with the saved one. - A location link's action is a setting (
LinkAction,link_action): show the place (default), open the route chooser, or start navigation. Start also applies to directions links and passes the precise-location and notification gates. - Directions links open the route chooser on the destination:
maps?saddr=&daddr=[&dirflg=](the lastto:place is the destination),maps/dir/?api=1&destination=&origin=&waypoints=&travelmode=,maps/dir/A/B/C/@...(an empty A is "from here") and thegoogle.navigation:q=|ll=&mode=intent.MapLink.directionsroutesopenDeepLinktoopenDirectionsLink: a coordinate becomes a reverse-geocoded pin, a name runs the "navigate to" search (openDirectionsOnResult). - Street View links (issue #847,
MapLinkParser.parseStreetView, asked before directions):maps/@<lat>,<lng>,3a,...,<n>h,...with the panorama as!1s<pano>!2e0in itsdata=,maps/@?api=1&map_action=pano&viewpoint=&heading=&pano=, and the oldmaps?layer=c&cbll=&cbp=<n>,<heading>&panoid=.MapLink.streetViewsendsopenDeepLinktoopenStreetViewLink: the camera moves to the point at z18 and the viewer opens on the named panorama, or the nearest one when there is none or it fails, facing the link's heading. With Google off (GoogleFree) the link opens as a plain point. - The places between the start and the end are
MapLink.stops, at mostSavedRoutes.MAX_STOPS. A path-form link from a desktop browser carries each place's own coordinate in itsdata=blob (MapLinkParser.dirPins: a1m<n>field per place, with1d<lng>and2d<lat>among itsnfields, and3e<0-3>for the mode). The pins are used only when the blob lists exactly the path's places; such a place is taken as named and pinned, with no lookup (linkPin). - A link with stops, or with a start more than
LINK_ORIGIN_HERE_M(150 m) from the fix, opens as a trip (openTripLink). The chooser opens at once, and the endpoints card lists the start, every stop and the destination byMapLink.label(the link's name or address, else its coordinate), each with its own spinner, check or warning (LinkTrip, a holder the card reads because MapScreen takes no new parameter).linkPlacelooks the destination up near the user, then the start and every stop together near the destination: a name with its own coordinate as it is, a bare coordinate reverse-geocoded, a name or address by search, an address the search does not carry by the autocomplete geocoder, and with no connection the downloaded places and addresses. Each lookup hasLINK_PLACE_TIMEOUT_MS(8 s) and then counts as not found (linkPlaceWithin, on an unstructured scope so a blocked request is abandoned): a name nothing answered for held the trip 20 s on a Pixel 4a. The trip is routed once, when every place has answered. A stop that found nothing is left out of the route, and a start that found nothing leaves the trip starting where you are. When the trip lands a dialog says so, one place at a time (LinkTrip.asking,nextMissing: the stops in order, then the start). For a stop it offers "Search for it", which opens the stop search on the link's words (findLinkStop) and puts the pick back where the link had the stop (LinkTrip.insertAtoverlinkStopSlots), or "Skip it". For the start it offers "Choose a start" or "Start where I am". The card keeps one line, "1 place not found" with "Fix" to open the dialog again, until every place is answered or the trip is edited (linkTripFor, checked inroute). A destination that found nothing closes the chooser with "Could not find". Back cancels the lookups, and the mode tabs work during them. During a drive a trip link only says "End navigation to open this trip". - A point dragged onto the route on a desktop sits in the blob inside the block of the place
before it (
3m4,1m2,1d<lng>,2d<lat>,3s<id>), and comes out as a stop markedMapLink.via, in travel order, at mostLINK_VIAS_MAX(12). The view model keeps them as the trip'sLinkPlan:routegoes through the stops and the dragged points together and stamps the result'sdetourPlan, so a drive passes them as silent stops (NavController.navStopsFor). They hold while the trip is the link's (same end, same given start, same stops in order) and are dropped at the first edit. - The link's mode applies to its trip only (the next
routeToSelectedfor a single destination) and is not made sticky. - A link that names something at a point (
geo:lat,lng?q=Name) searches the name near the point. When no result lies withinLINK_ANCHOR_MAX_M(50 km) of it, the point itself opens under the link's name (anchorLinkSearch): the sender gave a position, and the one hit was a namesake on another continent. A category near a point finds places close by and is kept. - A
geo:link'sz=sets the camera's zoom. It is applied after the pin is dropped, which clears it. - A whole Google Maps address in the search box (
MapLinkParser.isMapsUrl: one token on a Google host with a maps path) opens as that link. It used to be searched as text.
Google My Maps¶
A link google.com/maps/d/<viewer|edit|embed>?mid=<id> (MapLinkParser.myMapId) opens like a
shared list. MapDataSource.importMyMap fetches the KML
(https://www.google.com/maps/d/kml?mid=<id>&forcekml=1) and the public viewer page, with no
key and no session; it is refused under "Use Vela without Google". core/data/MyMapKml reads
it with regexes, each compiled once in the object and none per placemark. Both fetches use
GoogleMapsDataSource.largeReplyHttp, the shared client with a 90 s call timeout
(LARGE_REPLY_TIMEOUT_S) and a 60 s read timeout: a large map's KML runs to megabytes, and
the shared 12 s timeout cuts it off.
<Folder>is a layer (mapLayer,ListPlace.layer).<Point>placemarks become places, the description as the note.<LineString>and<Polygon>(outer ring) becomeMapShapes in the map's<LineStyle>/<PolyStyle>colors (aabbggrr), through<StyleMap>.- A marker keeps its color (
<IconStyle>,Place.pinColor,ListPlace.color) and up to 12 photos (gx_media_linksand<img>,ListPlace.photos). - Caps: 2,000 places, 500 shapes, 150,000 shape points.
- Saving an import (a custom map or a shared list) goes through
importTarget. The same import saved again refreshes its list and keeps the name, icon, color and sound set on it: the list is found by the id its source gives (ImportedList.sourceId, the map's id or the list's link), or, for a list saved before imports carried a source, by the title's id while it still has that title. A list that only shares the name is never replaced, so two maps both called "Untitled map" are two lists. - Icons: the KML names an icon only by number (
icon-1577-FFD600).MyMapKml.iconNamesreads the full names from the viewer page andMyMapKml.iconUrlbuilds the address onmt.googleapis.com/vt/icon, kept asPlace.pinIconUrl/ListPlace.iconUrl. The plain pin (1899), an unnamed icon or a failed viewer fetch keeps Vela's pin.MyMapIconsloads the images (counted as Google requests), and the saved-pin layer draws them (MapMarker.drawn = falsekeeps them out of the red result pins). - A layer with exactly one line and 2 to
MAX_ROUTE_STOPS(12) points, the line's ends withinROUTE_END_M(250 m) of the first and last, is a directions layer. Its points becomeMapShape.stopsand the list gets a row (id prefixshape-route:).openShapeTriproutes from the user through every stop when the first is within 50 km, skipping it within 150 m, and otherwise from the first stop. - The result is an
ImportedListwithshapes; a map with no pins getsShapesOnlySaveBar. Saving storesPlaceList.shapes, andVelaMapView.ensureShapesdraws them (one GeoJSON source, a fill layer, a line layer, two label layers), except while navigating. - Two or more layers get a Layers chip (
MapLayers,MapViewModel.toggleListLayer,PlaceList.hiddenLayers; before saving,pendingHiddenLayers). A hidden layer is neither listed nor drawn. - A tapped shape opens a sheet (
MapViewModel.openShape) with its name, its measure on the address line (core/util/ShapeMeasure,formatArea) and its description. The measure is not the category, which would make the sheet a business listing. - Not carried: the base map style and videos.
The lists sheet¶
ListsSheetis a dialog onsurfaceContainerHigh, so it stands off the dark background. Its title row holds Draw and New as icons; while lists are selected (a long press on a row, or OK held on it) it holds the count, a trash that askslists_delete_countbefore deleting, and a close.- Each list row is a
SwipeActionRow(ui/map/SwipeRow.kt, material3SwipeToDismissBox): end to start deletes (a list with places asks first, an empty one goes at once), start to end opens the editor. The row ticks (tickHaptic:CONFIRMon API 30 and up,CLOCK_TICKbelow) as the swipe crosses its threshold and when it acts, then settles back; the row leaves when the store drops it. - A
ReorderHandleat the end of the row replaces the up and down arrows and the pencil: a drag moves the list one place per row height, with a tick per move (onMoveList); on a keypad Up and Down on the focused handle move it and OK opens the editor. With one list the handle is a pencil. - The handle is a focus sibling of the row's clickable part, not a child of it: focus search
only looks among siblings, so Right from the row reaches the handle and Left returns. The two
sit in a
focusGroupwhoseenterlands every focus move from outside the row on the row (FocusRequester), never on the handle, where Down would move the list. A held OK on the row starts selecting throughdpadLongClick(ui/DpadFocus.kt):combinedClickableonly clicks on a key, so the modifier takes OK and Enter itself and runs the long click on the first key repeat the platform flags as the long press (KeyEvent.isLongPress), or the click on a release before it. - On the search page a recent query or place row is a
SwipeActionRowthat removes it from history, painted in the theme'sbackgroundlike the page itself (thesurfacedefault is gray on the AMOLED theme and white on the light one, and the rows read as cards); Clear recents is aFilledTonalButtonbeside the Recent heading. A place row's start to end swipe opens its menu. A query row has no edit, cannot be dragged that way, and draws no edit background: the box reports the direction for a moment as it settles.
Drawing¶
- The lists dialog's Draw button sets
MapUiState.drawing(DrawState). Every map tap and long press then adds a point (drawDots,onDrawTap), ahead of all tap resolution. Back removes the last point, then leaves. DrawBar(reached throughShapeBottomBar, because MapScreen is at the method size limit) offers Line or Area, six colors (DRAW_COLORS), the live measure, a name, Undo and Save.- The typed name is kept in
DrawState.name(MapViewModel.drawSetName). The bar leaves composition whenever another sheet takes the bottom slot, such as a place opened from search while drawing, and starts from the kept name when it returns. - A line needs 2 points and an area 3; at most 2,000 points. A finger within 26 dp of a point drags it, and a tap removes it. Points cannot be inserted between two existing ones.
- Save appends a
MapShape(width 4, an area filled at 25% opacity) to the listlist:drawings("My drawings"). - The unfinished shape and a dot per point (
vela-shapes-dots) draw from a source of their own (ensureShapeDraft,vela-shapes-draft-src, a fill and a line layer directly above the saved shapes' fill and line), so a dragged point uploads that one shape. On the saved shapes' source every move event would re-upload and re-tile all of them.MapSurfacepasses the unfinished shape as the last ofshapes;VelaMapViewtakes it off the saved set. The fill and line layers sit under the basemap's labels, or above the satellite imagery when it is on (the raster buried them and a drawing showed as bare points, issue #816); the satellite toggle drops the four layers andensureShapeLayersseats them again on the fresh raster. - The shape sheet's menu has "Edit this drawing" (
DrawState.editOf, saved back in place) and "Delete this drawing" (ShapeActions.delete,MapViewModel.deleteOpenedShape).
5.7 Saved places, lists, parking and imports¶
- List membership matches on
ListPlace.matches(id or stable feature id), never a bare id: a Google place's id derives from its name hash and a coarse coordinate. SavedPlace.of(Place)carries an optional address, defaulted null so older payloads decode. Every store's JSON setsignoreUnknownKeys, so a downgrade survives.SavedPlace.pinnedandSavedRoute.pinned(default false) decide what the search page shows; the bookmark button's sheet has the pin toggles. Before pins the page listed every saved place, so with saved places and none pinned its Saved section shows one line saying where they are (SavedPinTip), until "Got it" (saved_pin_tip_doneinvela_notices).SavedPlace.iconandListPlace.iconhold a glyph name oremoji:X. The pin drawsListPlace.icon ?: PlaceList.iconandSavedPlace.icon ?: "bookmark"in the list's color. "Choose icon" callsMapViewModel.setPlaceIcon, which writes every list copy and the quick-save.- Saved pins draw at every zoom. From z8 (
SAVED_PIN_FULL_ZOOM) every pin draws atSAVED_PIN_SCALE(1.35), over a neighbor if it must; below it the pin shrinks to 0.45 of that by z3 and a pile collapses to the pins that fit, so a far-out map still says where you have places. From z14 (SAVED_LABEL_ZOOM) the place's name draws under the pin (12 px, Noto Sans Regular, anchored at the top 1.6 em down, 8 em wide,textOptional, so a pin whose name finds no room keeps the pin); the dark palette recolors it with every symbol layer. - A list's editor has a share button in its title row:
PlaceListStore.exportJson(id)writes that one list in the same JSON the export of every list writes, so it imports back as that list, andMapViewModel.exportListIntentshares it asvela-list-<name>.json(issue #822). - The sheet's star and its Save pill are filled when the place is quick-saved or in any list
(
ListPlace.matches). On a place in a list the pill opens the list chooser, where the ticks are; otherwise it toggles the quick-save. The star opens its menu either way. - Recents are timestamped under new preference keys. The legacy keys are read once and left in place for a downgraded build.
- Several places at once: a long press on a card of an open list, or on a Saved places row in
"Your lists", starts a selection (the select button is the key path). The sheet's title
becomes
BulkBar(ui/map/ListBulk.kt): the count, All, Move to list (any other list, or a new one named on the spot) and Remove behind a confirm. The stores write once per action (PlaceListStore.removePlaces,movePlaces,addPlaces,SavedPlaceStore.removeAll); a move to a list that is gone moves nothing. Moving a saved place puts it in the list, with its own icon, and takes the star off. Only rows on show are counted and acted on, so a row picked and then hidden by a filter or a layer switch is left alone. A new search closes the open list (openListId). - A list's sound:
PlaceList.alertis a key ofPassAlerts.SOUNDS(ping,bell,double,low,name) or null, set in the list editor, where picking one plays it. Each fix, live or simulated, goes toPassAlerts.Tracker.onFix(core/nav/PassAlerts.kt) with the places of every list that has a sound. A place sounds when the fix comes withinRADIUS_M150 of it atMIN_SPEED_MPS2 or faster, once until the car isEXIT_M250 away, and at most once inAGAIN_MS15 minutes. Several at once sound the nearest only. The first fix of a session marks the places it is beside without sounding. During a drive, a place within 150 m of the destination or a remaining stop is skipped. The tone plays on the guidance stream throughVoiceGuide.placeToneandnameis spoken, so muting the voice mutes both. The status card shows the place and its list. Fixes only arrive while the map is open or a drive is running; nothing asks for background location. Log tagVelaPassAlert(sound and count, never the name). - Parking is one tap on the P button, with a history. Settings > Map "Parking button"
(
ParkingButton, default on) hides the button while no spot is saved. With it on, the arrival card of a drive has "Save parking spot" (ParkingActions.saveHere), which saves the current position as the button does. A walk, a ride or a transit trip does not offer it. "Find my car" opens the spot as a sheet whose facts line gives the distance from you and how long ago it was saved (ParkingActions.parkedAt). On a key-first device the arrival card opens with focus on Done, and each of its buttons draws the focus ring. - The picker both Import buttons open starts in the phone's own storage at Download
(
DocumentsContract.EXTRA_INITIAL_URIon the external storage provider'sprimary:Download), not in the picker's Downloads view: that view lists the media index, where a file an unzipper or a file manager has just written is pending or absent, and a Takeout folder read "No items". A picker that cannot start there opens where it last was. - Imports accept GPX, KML and GeoJSON including Google Takeout (
core/data/PlaceImport). GPX is latitude first; KML and GeoJSON are longitude first. A KML placemark with several coordinate tuples is skipped. Only name, coordinate and a given address are taken. Ids derive from the rounded coordinate, so a re-import adds nothing;0,0and out-of-range points are dropped. A Takeout feature at0,0takes its point from itsgoogle_maps_urlfirst (TakeoutCsv.readLink, which reads?q=<lat>,<lng>as a point), and only a link without one drops it. The picker keeps*/*last, because Android reports.gpxas an octet stream.ImportResultdistinguishes added, nothing-new, wrong-format and unreadable. A lists import handed a file the saved places import reads says so (WrongFormat.placesFile). Never wrap the launcher in a barerunCatching: with no documents provider the button then does nothing. - Google Takeout's Saved folder holds one CSV per list (
Title,Note,URL,Comment, older exportsTags, and the header in the account's language,Titre,Note,URL,Tags,Commentaire) with no coordinates (core/data/TakeoutCsv). Either Import button takes one (isTakeoutCsv: a header with a URL column, the one name every language keeps;columnsfinds the rest by name where it is English and by position otherwise: the title first, the note after it, the comment last) andMapViewModel.importTakeoutCsvmakes a list named after the file, throughimportTargetwith sourcetakeout:<name>, so the same file again refreshes the list. A row's link is read on the phone: a/maps/search/<lat>,<lng>pin is kept as it is; a/maps/place/<Name>/data=...!1s0x<cell>:0x<id>listing carries only its feature id, so the title is searched and the hit whose feature id's second half (TakeoutCsv.featureKey, which an old?cid=<decimal>link carries too) matches is taken. The id's first half is an S2 cell (Link.cellCenter,core/util/S2Cell), roughly where the place is, within a hundred meters for a leaf cell, so a keyed row's search is biased there, which is what finds one branch of a chain in a list made on a trip; a keyed row missed there gets one unbiased search (near = null), matched on the key alone. A row with no feature id is searched where the user is and takes the one hit named like the title, none when several are (a chain's branches); with a feature id present the name is never trusted, a same-name hit with another id is another place. The choice isTakeoutCsv.pick. A row that finds nothing is counted and left out, never guessed at. Note and Comment become the place's note. With "Use Vela without Google" on, only pin rows import and the listing rows are counted asneedGoogle, not as misses. The lookups run inviewModelScope(importTakeoutCsvstarts them withasyncand awaits), one import at a time (ImportResult.Busyfor a second), so leaving Settings neither loses nor cancels them; the outcome (MapViewModel.takeoutOutcome) goes to the status card as well as to the caller's toast. Listing rows are looked upTAKEOUT_LOOKUP_GAP_MS(400 ms) apart; a pin row waits for nothing. The status card showssettings_takeout_progressevery five rows. The list is saved everyTAKEOUT_SAVE_EVERY(25) lookups as well as at the end, so an import Android stops part way keeps what it found; a running save isTakeoutCsv.partial(the places found so far, then the list's earlier places not found again yet), so it never shrinks the list of an earlier import. A listing row whose feature key is already in the list (TakeoutCsv.keyed) takes that place with no lookup, so the same file imported again goes straight through the rows it already matched (issue #761).ImportResult.ListAddedcarries the name, the count, the misses and theneedGooglecount. Rows are capped atMAX_ROWS(2,000). The Takeout zip itself is not read; pick the CSV inside it. - Trip shortcuts: the route card's menu pins the trip as a launcher shortcut. Its intent
(action
app.vela.action.OPEN_TRIP) carries names, latitudes and longitudes as parallel arrays (NaN means "your location") and the mode. Nothing is stored in the app.
Saved routes¶
"Save this route" in the route chooser's menu stores a SavedRoute (encoded 1e-5 polyline,
ends, mode, name, and the start's name when the trip was planned from a place, originLabel;
SavedRouteStore, prefs vela_saved_routes). The default name is "Route to defaultSavedRouteName, issue #815), and the list under
Settings > Saved places shows "
- A later trip with no stops, the same mode, a start within
SavedRoutes.ORIGIN_M(1 km) and an end withinDEST_M(250 m) gets it offered. A route already on offer that is the same way (every 25 m sample withinOFF_M, 60 m, both directions) takes its name. - Otherwise the router is asked for the trip through vias on the saved line, mid-stretch where
it leaves the fastest route: stretches under
MIN_RUN_M(150 m) are ignored, one more via perVIA_EVERY_M(2.5 km), at mostMAX_VIAS(8). The result carriessavedNameand the vias as itsdetourPlan, which the drive keeps as silent stops through every reroute. - A matching saved route leads the list, selected, with
SavedRouteChip. The reorder recomputes the camera counts, and provisional naming replaces its route by identity, not index. - A run: saving a trip with stops and "Stop at these places" on stores
SavedRoute.stops, at mostSavedRoutes.MAX_STOPS(10). A run is never offered as an alternate.openSavedRoutestarts it in its own mode from "Your routes" or the Settings list. - A trip takes at most 10 stops:
addStoprefuses the eleventh andapplyTriptruncates. - "Add stop" in the trip editor (
beginPickStopFromEditor) comes back to the editor when the place is picked or the pick is cancelled, with the new stop as the last row before the destination. "Add stop" on the route card still lands on the route. - Opening a saved route sets
openSavedRouteId, and the card's menu offers "Save changes to" ( updateOpenSavedRoute). - During a drive
NavControllerkeeps one fix perDRIVE_TRACE_STEP_M(15 m). On arrivalSavedRoutes.droveOwnWay(trace, planned)(at leastMIN_DRIVE_M, 500 m, and a real stretch off the planned route) fillsdrivenRouteOffer, and the arrival card offers to save the trace.debug.vela.tune.drivenOfferAlwaysforces the offer.
5.8 UK fuel prices¶
Google's keyless search carries a price for US gas stations (fuelPrice, 3.2) and none for UK
ones. For those Vela reads the UK government's Fuel Finder, which publishes every forecourt's
prices under the Open Government Licence v3.0.
The feed¶
.github/workflows/fuel-gb.yml runs hourly at :23 on its own cron, outside the bake conductor
(7.3).
- It asks the gov.uk CSV first
(
https://www.fuel-finder.service.gov.uk/internal/v1.0.2/csv/get-latest-fuel-prices-csv) with the bakes' user agent and logs the answer. The service returns CloudFront 403 to connections from outside the UK, GitHub's runners included. The fallback isdata.csvonmainofmatthewgall/fuelfinder-archive, from raw.githubusercontent.com, which republishes the same file about twice a day (09:05 and 15:05 UTC). Its own runner is self-hosted. - The alert: when the newest price in the published file is over
STALE_ALERT_H(36) hours old, the run opens one issue titled "UK fuel prices: the source has stopped updating", and the run that next publishes fresh prices closes it. 36 hours is two missed archive updates, and the app stops showing prices at 48. The run stays green, because a red hourly run would mail every hour. A healthy hour with nothing new makes no API request for this. - The app reads Vela's trimmed file and not the archive's own: that one is 7.8 MB (1.3 MB gzipped) against 147 KB, and a change to its columns would break every installed app, where the bake script absorbs it. Both sit on GitHub, so reading it directly would be no more reliable.
- Nothing is uploaded when the source's sha256 equals the published manifest's
sourceSha256. That check reads the manifest as a release download, not through the API, so an unchanged hour costs no API request. A publish is about seven. tools/build-fuel-gb.pydrops permanently closed forecourts, coordinates outside 49 to 61.5 N and 9.5 W to 2.5 E, prices outside 100 to 250 p (the source has placeholders such as 299.9), and forecourts left with no price or no report time. It writesfuel-gb.csv.gz(gzip with no timestamp, so one source gives one file) andfuel-gb-manifest.json.- The file is CSV with the header
brand,lat,lng,e10,e5,b7s,b7p,updated: coordinates to 5 decimals, prices in pence (blank when absent), andupdatedthe newest price report among the kept fuels in unix seconds. On the 2026-10-08 source it held 8,124 of 8,133 forecourts, 473 KB, 148 KB gzipped. E10 is on 97% of forecourts and standard diesel (B7S) on 99%. - The manifest holds
version,generated,source(gov.ukorarchive),sourceUrl,sourceSha256,stations,newestPrice,newestPriceEpoch,file,fileSha256andfileBytes. - A source that cannot be fetched or read, or whose newest price is more than 3 days old (exit
3), ends the run green with a
::warning::, and the published file stays. A publish that fails ends in a warning while the published manifest is under a day old and fails the run after that. - The
fuel-gbrelease is created on the root commit when missing, like thecells-<region>set (CELLS_RELEASE_TARGETinscripts/bake-lib.sh). The data file is replaced before the manifest, throughscripts/gh-retry.sh.
On the phone¶
core/data/FuelGbStore keeps the file in fuelgb/ under StorageLocation.root.
- Nothing is fetched until a gas station in the Fuel Finder area has no price (the rules are under Matching).
- At most every
CHECK_EVERY_MS(3 h, the stamp filechecked) it reads the manifest and downloads the data file only whenfileSha256differs from the stored manifest's. GitHub's release downloads give no conditional request to lean on, so the manifest is the change test. The download is checked for the gzip magic and the sha256, parsed, staged beside the target, and swapped in with the old copy moved aside first. A failure is retried afterRETRY_AFTER_MS(15 min) and never replaces a good file. - The client is the shared one with no call timeout, a 60 s read timeout and
VelaConfig.VELA_UA. - The forecourts are held in flat arrays with a 0.01 degree grid. A severe trim
(
MemoryPressure.isSevere) drops them, and the next use reads the file again. ui/map/UkFuelPriceswatchesMapUiState.resultsandselectedby identity. Google results, place-pack results, places-archive results and a tapped open-data place all pass through that state, so the prices work with Google off. Results show at once and the prices land when the file is ready.- The car's search, nearby and search-along-route rows add the price as a second text line, US
and UK alike (rows allow two). Their results are no shared state, so each screen calls
UkFuelPrices.fill(FuelGb.fill) after drawing them: it loads the store, and downloads the file, only when a row is a UK gas station without a price, and the screen redraws only if its results are still the ones it filled. The store is one per process, shared by the phone and the car;CarDeps.httpcarries the shared client for a car-only session.
Matching¶
- A place is a gas station when Google's reply types it
SearchResult.TYPE_GAS_STATION(Place.placeType, pathplaceType=[1][88][1]), which is the same in every app language. A place with no type (open data, the place packs, whose categories come out of the bakes in English) falls back to thefuelgroup ofPoiIcons.groupFor, less categories that say "charg" (UkFuelPrices.isFuelByCategory). - A place is in the Fuel Finder area when Google's country for it is
GB(Place.countryCode, pathcountryCode=[1][88][2][1]). A place with no country is tested byFuelGb.inUk: the box 49.8 to 60.9 N, 8.7 W to 1.8 E, less a coarse polygon of the island of Ireland, except a coarse polygon of Northern Ireland (35 points, kept a little inside the border where the two sides are close). Fuel Finder covers Northern Ireland (592 forecourts in the 2026-10-08 file, every one inside the area) and not the Republic, whose border towns (Lifford, Muff, Omeath, Pettigo, Clones, Dundalk) are outside it, so a Republic user never triggers the download. The polygons only gate the download; a match still needs a forecourt withinMATCH_M. FuelGb.picktakes the forecourts withinMATCH_M(75 m), nearest first. One whose brand agrees with the place's name wins when it is at mostBRAND_SLACK_M(25 m) farther than the nearest. A brand agrees when one of its words, filler words dropped ("ltd", "petrol", "fuels", "the"), is a word of the name, apostrophes removed ("Sainsbury's" against "SAINSBURYS").- Google's 20 results for a London petrol-station search all had a forecourt within 63 m, 18 of the same brand. The other two were a supermarket shop on another brand's forecourt, where the nearest forecourt is the right one.
FuelGb.labelshows nothing for a forecourt whose newest report is older thanMAX_AGE_S(21 days). Stations report only when a price changes, so an old report is often still the price: in the 2026-10-08 file a forecourt's newest report was within 1 day of the file's newest for 15% of forecourts, 3 days for 31%, 7 days for 57%, 14 days for 87%, 21 days for 96% and 30 days for 99%. Otherwise the text is "172.9p/E10 · 199.9p/B7": petrol first (E10, else E5), then standard diesel as B7. These are the labels on UK pumps, so the text is not translated.- A file whose newest report is more than
FEED_MAX_AGE_S(2 days) old fills nothing at all (FuelGb.fresh): the archive has stopped, and every price in it is aging. Prices come back with the next fresh file. - The report time goes in
Place.fuelPriceAt(unix seconds). The place sheet's pump line adds "Updated today", "Updated yesterday" or "Updated N days ago" after the prices, in local calendar days (FuelGb.daysAgo). Google's US prices carry no time and show none. - The text goes in
Place.fuelPrice, so it shows where Google's price shows: the result bubble (PoiIcons.fuelShort, the text before the first '/', is the petrol price), the results row's pump line, and the place sheet's pump line, first in the Overview body. That line sits below the action pills, so a price that lands after the sheet opened moves nothing above them. - A result with a fuel price draws as a gas station's price bubble whatever language its
category is in (
PoiIcons.resultGroup); the category words the map icons read are English. - The results camera fit keys on the markers without their prices (
markerFitKey), so a late price does not frame the results again. - A place is filled once. A newer file reaches the next search or tap.
6. Map rendering¶
The engine is MapLibre Native Android 13.6.1, artifact android-sdk-opengl. The plain
android-sdk artifact is Vulkan since 13.0.0.
6.1 Basemap and fonts¶
The basemap is an OpenFreeMap style loaded from its live URL so tile paths follow OpenFreeMap's current snapshot. Vela's zoom reads about one level lower than Google's for the same visible area (512-pixel tiles). Compare against Google by visible area, never by zoom number.
Settings > Appearance > Map look (MapLook.style, pref map_look, default liberty) picks the
style (MapStyle): Liberty is the Vela look, and Bright, Positron, Fiord and Black load as
OpenFreeMap serves them (Black is OpenFreeMap's Dark style, named so in the app so it is not
taken for the dark theme). All five share the openmaptiles source, the glyph server and the
sprite, so the offline basemap, the font patch and basemapSrc work on each. MapStyle.painted
is true for Liberty only: the palettes, widenStreets, the road edges, PoiIcons.applyToLiberty,
the twin fills of ensureLayers and the Map colors setting belong to it. Another look gets
applyLookTheme: the label language on PLACE_LABEL_LAYERS and ROAD_LABEL_LAYERS (Liberty's
ids, which Bright and Positron share, plus Fiord's and Black's place_*, water_name and
highway_name_other), and the per-theme colors of Vela's own layers (applyVelaLayerColors).
Vela's own layers (places, route, markers, house numbers, shields, transit, traffic, satellite)
are added on every look; a twin's missing anchor leaves that twin out. isMapDark() is
MapStyle.darkLook on an unpainted look (Fiord and Black are dark whatever the theme, Bright and
Positron light) and isMapAmoled() is false. The car map follows the look. The place icon tiers
(poi_r1, poi_r7, poi_r20) exist on Bright, so its vegetation and fuel-only filters apply;
Positron, Fiord and Black draw no basemap places.
Map labels draw in Google Sans Flex layered over Roboto and Noto, composited per glyph by
scripts/build-map-fonts.sh: Flex where it has the glyph (Latin, extended Latin, Vietnamese),
Roboto for Cyrillic and Greek, Noto for every other script. The folders keep the Noto stack names
(Noto Sans Regular, Noto Sans Bold, Noto Sans Italic), so the only style change is the
glyphs URL. The set is the map-fonts release, served from Pages at BuildConfig.MAP_FONTS_URL.
ui/map/MapFonts builds the style the map loads:
- At launch it uses the cached patched style of each look that has one (
files/style/liberty-roboto.json,<key>-roboto.jsonfor the others), then refreshes the chosen look's: probe the font host, fetch the live style JSON, pointglyphsat the font host, write the cache. Picking a look refreshes that look's (MapFonts.ensure). - With no validated network (
ConnectivityManager, INTERNET and VALIDATED) the refresh does nothing and the cache stays: it is what an installed offline basemap loads. - A font host that fails the probe evicts the cache, and the map loads the plain style in Noto. A style whose glyph URLs fail draws no labels at all.
- A failed style fetch keeps the last cache for at most 7 days (
STALE_EVICT_MS). A cached style pins a tile snapshot, and OpenFreeMap retires old snapshots. - Only OpenFreeMap looks are patched.
Under an installed offline basemap the style is built from JSON (MapFonts.offlineStyle): the
chosen look's patched cache, else the bundled assets/styles/liberty-roboto.json. The asset is
painted as the Vela look whatever the look, in the look's light or dark (isMapDark()), so a look
with no cached style is the Vela look offline and never stock Liberty under another look's colors.
The Liberty-only passes (applyMapTheme, the twins of ensureLayers) follow the style that
loaded, not MapLook.style alone. withLocalBasemap points its layers at the local
archive, maps the asset's Roboto stacks to the Noto names (GlyphPackStore.stackName), and serves
glyphs and the sprite from file://. GlyphPackStore unzips the map-fonts release into
glyphs/ under StorageLocation.root (about 200 MB) and copies the bundled sprite to
files/sprites/. asset:// hangs the same way an unreachable host does.
The bundled asset pins a dated tile snapshot, so it is used only where the tile source is
replaced. It is one minified line: edit it with a script that re-dumps with
separators=(',',':').
6.2 Palettes¶
applyMapTheme(style, dark, amoled) runs one palette function, then the passes every palette
shares (widenStreets, the road edges, label colors, the hide list, borders).
| Map state | Function |
|---|---|
| AMOLED | applyAmoled, which runs applyDark and then overrides colors |
| Dark, Classic | applyClassicDark |
| Dark, Modern | applyDark with MODERN_DARK |
| Dark, Contrast | applyDark with CONTRAST_DARK |
| Light, Classic | applyClassicLight |
| Light, Modern or Contrast | applyLight |
MapColorspicks Modern, Classic or Contrast: prefmap_palette, and with no pick calibration'sdefaultMapPalette(modern). AMOLED ignores the pick. The two Modern-shaped night palettes areDarkPalettevalues (MODERN_DARK,CONTRAST_DARK) thatapplyDarkpaints; Contrast by day draws as Modern.- The map's light or dark is its own setting:
AppTheme.mapMode(MapThemeModeFOLLOW / LIGHT / DARK, preftheme_map_mode, Settings > Appearance > Map).isMapDark()resolves the nav day/night override first, then the map mode, then the app theme.isMapAmoled()is true only while the map follows an app inThemeMode.AMOLED. The map surface, its route colors and the scale bar take these. Sheets, cards, bars and settings keepisAppInDarkTheme(). VelaThemeputs the AMOLED surfaces on whichever dark scheme is in use (ColorScheme.onTrueBlack): Vela's own, or the wallpaper's with "Material You colors" on, whose accents are kept.styleKeycarries the style URI, the dark and AMOLED flags, the palette, satellite, the puck style, the house-number level and the offline basemap archive. A change in any of them reloads the style.- Every layer is colored in every palette. An unstyled runtime
LineLayerrenders black, and a Liberty layer no dark function names keeps its light colors at night. applyAmoledsets colors only. Zoom gates and extrusion geometry come fromapplyDark.- The functions take a
StyleLayers, so the Android Auto snapshotter (SnapshotterHost) gets the phone's theme (StyleHost).
Modern is sampled from the Google app. Classic is the earlier look: white roads and yellow motorways by day, neutral slate by night. Contrast is a night palette for a glance from a mount: slate land, slate-blue buildings a few steps lighter, warm tan streets, a light motorway and white labels, set against a street-map night style on the Davis fixture at z12.5 and z15.5. In the table "land" is that palette's land color and "at 0.9" is a fill opacity.
| Element | Modern light | Modern dark | AMOLED | Classic light | Classic dark | Contrast dark |
|---|---|---|---|---|---|---|
Land (background) |
#f8f7f7 |
#162640 |
#000000 |
#f2f1ee |
#2b2f36 |
#293a4c |
Water (water, waterway_river) |
#90daee |
#000d2a |
#04080C |
#90daee |
#2f4a63 |
#1d2a3a |
Park (park) |
#d3f8e1 |
#0d3847 |
#050E0A |
#cfeccd |
#2c4a34 |
#22413f |
Grass (landcover_grass) |
#d3f8e1 |
#0d3847 at 0.9 |
#050E0A |
#d3f8e2 |
#2c4a34 at 0.9 |
#22413f at 0.9 |
Wood (landcover_wood) |
#d3f8e1 |
#0d3847 at 0.95 |
#050E0A |
#c9f2da |
#274330 at 0.95 |
#22413f at 0.95 |
Wetland (vela-wetland) |
#d3f8e1 |
#0d3847 at 0.9 |
#000000 |
#cdeff0 |
#26403c at 0.9 |
#22413f at 0.9 |
Pitches (vela-pitch, landuse_pitch, landuse_track) |
#a9eac2 |
#0d4956 |
#050E0A |
#d3f8e2 |
#2c4a34 |
#255250 |
Plaza and parking (vela-plaza) |
#dbe0e8 |
#2a3546 |
#0A0C0F |
#ededed |
#31363f |
#3a4d62 |
Commercial and retail (vela-commercial) |
#fdf9ef |
#1c2638 |
#000000 |
land | #31363f at 0.5 |
#2f4256 |
Campuses (landuse_school) |
#f0eded |
other landuse | other landuse | land | other landuse | other landuse |
Other landuse (remaining landuse*, landcover* fills) |
land | #2a3546 at 0.5 |
#000000 |
land | #31363f at 0.5 |
#34465a at 0.5 |
Buildings (building, building-3d) |
#e8e9ed |
#1c3b69 |
#0A0C0F |
#dde1e7 |
#383d45 |
#445976 |
| Building outline | #d6d9e6 |
#2e3d6d |
#14171A |
#c4c9d1 |
#464c56 |
#5a7094 |
Overlay footprints (vela-ovl-*), fill / outline |
#e2e3e9 / #c4c9d1 |
#1c3b69 / #2e3d6d |
dark value of the picked palette | #dde1e7 / #c4c9d1 |
#383d45 / #464c56 |
#445976 / #5a7094 |
| Minor, secondary, tertiary and link roads | #aab9c9 |
#3d5a77 |
#1A1D22 |
#ffffff |
#565b64 |
#7e7a60 |
| Trunk and primary | #aab9c9 |
#476789 |
#22262C |
#ffffff |
#6a707b |
#a39d7c |
| Motorway and its links | #8aa4c0 |
#476789 |
#22262C |
#f9d27a |
#9c7f4f |
#9db1cb |
| Service and track | #9bacbc |
#2a4056 |
#111418 |
#ffffff |
#565b64 |
#5e5f55 |
| Casings | land, then road edges | land, then road edges | #000000 |
motorway #f0b85a, trunk and primary #dadde2, secondary and tertiary #e4e6ea, others land |
land | land |
Trails (vela-trails) |
#7fcdb0 |
#167055 |
#1A3A28 |
#7fcdb0 |
#167055 |
#4a9a70 |
Bike paths (vela-bikeroutes) |
#007b8b |
#1f8f9c |
#0D2D36 |
#007b8b |
#1f8f9c |
#35a7b8 |
Airport area (aeroway_fill) |
Liberty's | #1c2638 |
#0A0C0F |
Liberty's | #31363f |
#2f4256 |
Runways and taxiways (aeroway_runway, aeroway_taxiway) |
Liberty's | #2a4056 |
#1A1D22 |
Liberty's | #565b64 |
#5e5f55 |
| Label text / halo, every symbol layer | Liberty's | #c3cad6 / #1a2230 |
#D0D4DC / #000000 |
Liberty's | #cdd0d6 / #1e2228 |
#eef1f5 / #293a4c |
| Hillshade exaggeration, then shadow / highlight / accent | 0.32, #6b7280 / #ffffff / #9aa0a6 |
0.45, #0a1018 / #3a4a68 / #0a1018 |
0.3, #000000 / #1A2030 / #000000 |
as Modern light | 0.4, #0b0d10 / #4a4d55 / #0b0d10 |
0.4, #141c27 / #5a7094 / #141c27 |
- Road names (
highway-name-path,highway-name-minor,highway-name-major) use theNoto Sans Boldstack and a 1.9 halo in every palette, white in the light ones, so a name stays legible over the route line. Other labels in the dark palettes get a 1.1 halo. - Vela's own label layers (
vela-ambient,vela-places-*,vela-transit-stops,vela-markers) take halo#FFFFFFby day,#11161Cat night and#000000in AMOLED. Result labels are#3C4043by day and#E8EAEDat night. Dot rings take the Modern land color. - Bike paths are OSM
highway=cycleway, split out of the trails layer, which keeps foot paths. On-street painted lanes are not in the tile schema and are not drawn. - Borders:
boundary_2(countries) is solid,#9AA0A6by day and#8C95A3at night.boundary_3is narrowed to admin levels 3 and 4 (states and provinces), dashed 3:2 from zoom 4,#B4B8BCby day and#6F7887at night. County and city limits are not drawn. Never put the boundary layer ids back in the hide list.
Road edges (applyRoadEdges, Modern light and dark only). Google's navigation map draws them.
By day each casing is a darker shade of its own fill, at night every casing is near-black. This
also splits the two halves of a divided road.
| Casings | Fill | Day | Night |
|---|---|---|---|
| Minor, secondary, tertiary, trunk, primary, link | #aab9c9 |
#94a1af |
#07090e |
| Motorway and its links | #8aa4c0 |
#5e75a0 |
#07090e |
| Service and track | #9bacbc |
#8593a2 |
#07090e |
Each edge is at least ROAD_EDGE_DP (1 dp) wide from z16, growing in from z13.5 (edgeFloor in
widenStreets).
3D buildings. Extrusions take the building fill color with the vertical gradient on, under a
style light of intensity B3D_LIGHT (0.25). At 0 every face draws one color and no wall reads as
a wall. At MapLibre's default 0.5 roofs draw about 40 percent brighter than the palette. At 0.25 a
roof stays within 1 to 3 percent of the palette color and a wall facing away from the light draws
up to 25 percent darker.
Extrusions show only with the 3D buildings setting on, satellite off, navigation off and the
camera tilted: on at B3D_TILT_ON (20 degrees), off below B3D_TILT_OFF (12). Seen straight
down, perspective leans tall buildings over the streets beside them. The change is an opacity
transition of B3D_FADE_MS (350 ms).
The layer starts hidden and costs nothing until the first tilt. From then on, on that style, the tilt gate is paint only: flat, the layer stays visible at opacity 0, which MapLibre skips at render, so tilting again re-lays out nothing. A visibility change re-lays out every basemap tile (the flip cost in 4.7b), which a gate on visibility pays twice per tilt. The price of staying visible: tiles at z17 and closer build the extrusion geometry while flat. The layer is hidden outright with the setting off and when a drive starts: after the fade when it is on screen, at once when it is at opacity 0, which for a drive is the frame the car-mode strip re-lays out the basemap anyway. A walk or a ride keeps it at opacity 0.
6.3 Layer rules¶
MapLibre behavior¶
- A layer's
maxzoomis exclusive. Liberty'sbuildingfill is minzoom 13, maxzoom 14, so the palette functions set min 16 and max 24. Min alone leaves an empty range. - Draw order and placement order are the same thing. The topmost symbol layer places first.
- A layer at opacity 0 is skipped: it is not rendered,
queryRenderedFeaturesdoes not see it and its source is not tiled. A layer that must stay live while invisible draws at 0.004 (ROUTE_PENDING_OPACITY). - On a source that is tiled anyway, a visible layer at opacity 0 still has its geometry built in every tile in its zoom range (MapLibre 13.6.1 hands a tile every layer of its source whose visibility is not none, whatever the opacity), so showing it again is a paint change. The 3D buildings' tilt gate rests on this (6.2).
- A visibility or filter change re-lays out every tile of the layer's source, also when the layer is hidden. An opacity change does not.
- An 8-digit hex color string is rejected and falls back to opaque black.
- A
fill-patternfrom the style cannot be cleared. The layer is hidden and a flat twin drawn. - A streamed archive (
pmtiles://https://, the address, building and places overlays of a region that is not downloaded) never reaches MapLibre's own PMTiles path: since MapLibre 13 that path answers one byte range of a streamed archive with another's bytes and fails the source's metadata with "incorrect header check" (maplibre-native issue 4462), so the overlay drew nothing, and a state with an address overlay lost its house numbers.offline/StreamedPmtilesreads the archive withPmtilesReader.Archive.httpinstead and serves its tiles to MapLibre as a plain tile template onpmtiles.vela.invalidthrough the map's HTTP client (overlaySource, headers read on IO first byprefetchStreamed). A downloaded archive file (pmtiles://file://) still goes to MapLibre as it is; that path loads. - The pmtiles path never cold-fetches a tile clamped two or more levels below the camera.
- Past a GeoJSON source's maxzoom every overscaled tile lays out all of its parent tile's features, so point sources set one. The route line sources set none.
| maxzoom | GeoJSON sources |
|---|---|
| 18 | ambient, markers, traffic controls, transit stops |
| 16 | plate cameras, their clusters, speed cameras, transit line labels, custom-map shapes, the shape being drawn |
| 14 | accuracy disc, transit lines |
| 12 | me, parking, saved, Street View |
- Every
setGeoJsonandsetPropertiesis identity-gated by alastAppliedholder. Every such holder is reset in the style-reload block, or a theme, palette or satellite flip leaves sources empty.
Vela's basemap layers¶
ensureLayers adds these on the basemap source (basemapSrc(style)):
| Layer | Source layer and filter | From zoom |
|---|---|---|
vela-wetland |
landcover, class wetland |
12 |
vela-plaza |
transportation polygons |
any |
vela-pitch |
landuse, class pitch, playground, track or stadium |
13 |
vela-commercial |
landuse, class commercial or retail |
12 |
vela-trails |
transportation lines, class path, subclass path or bridleway |
14 |
vela-bikeroutes |
transportation lines, class path, subclass cycleway |
14 |
Trails and bike paths are 0.7 dp wide at z14, 1.6 at z16 and 4 at z19, below road_minor.
Hidden Liberty layers: landcover_wetland and road_area_pattern (patterned, replaced by the
twins), road_path_pedestrian, bridge_path_pedestrian, bridge_path_pedestrian_casing,
tunnel_path_pedestrian, park_outline, and the six *_rail_hatching layers.
Route shields are Vela's own images (RoadShields, vela-shield-*, one per ref length 1 to 6),
installed after the theme pass. They carry the sign's colors in every palette.
vela-exit-shield adds motorway exit numbers from z12.5.
A drive hides the basemap's three shield layers: every numbered road in view carried them, the
other carriageway's too. The driven road gets its own instead (core/nav/RouteShields, layer
vela-nav-shields): from the steps' refs and mid-leg renames, one shield FIRST_AFTER_M
(350 m) into each numbered stretch of MIN_STRETCH_M (900 m) or more, then every EVERY_M
(1,600 m), none within END_CLEAR_M (300 m) of its end. Computed once per route in
MapSurface, drawn with the same images, placed under the signs and callouts so those win a
collision. Hidden in the overview with the other vela-nav- layers.
Buildings¶
- The flat
buildingfill draws from z16.building-3ddraws from z17 at 30 percent of its height, growing to full height by z19 (applyBuilding3dGeometry). With extrusions at z16, dense-city towers lean over the roads. - Overlay footprints (
vela-ovl-<i>, minzoom 16) draw beneathbuilding, so OSM wins wherever it has data. Their colors are in 6.2, their visibility in 6.4.
House numbers¶
- Two layers draw them:
vela-housenumber(the basemap'shousenumbersource layer) andvela-addr-<i>(the address overlay).vela-housenumberis hidden while an address overlay is mounted, so an address never draws twice. - Both gate on
houseNumberMinZoom()(HouseNumbers, prefhousenumber_zoom: near 18.3, normal 17.8, far 17.3) and fade in over the next 0.6 levels (houseNumberFade). - The address archives carry tiles only at z16-17, so
vela-addr-*has minzoom 17 and its gate is the text field, empty belowhouseNumberMinZoom(). With the gate as the layer minzoom a cold source fetched nothing. With an opacity gate every hidden number still ran placement. - Both carry
textIgnorePlacement(true): they yield to icons but never enter the collision index, so a number cannot evict an icon. vela-addr-*is inserted belowvela-controls-claim: above the basemap labels, below the ambient icons.vela-housenumbercarries awithinfilter, a box one screen wider than the view on every side (restrictHouseNumbers). The basemap tiles stop at z14, so past that every number in a tile draws each frame, on screen or not. The throttled idle work moves the box when the view comes within a quarter screen of its edge or has shrunk to under a fifth of the view it was built for. In a drive the box only moves belowHOUSE_NUMBER_NAV_MAX_MPS(4.5 m/s): a filter change re-lays out every basemap tile, and the follow camera reaches the box's edge every few hundred meters. The box does not move while the layer is hidden (an address overlay mounted, the overview, a turn): the relayout would be for nothing on screen. The address-overlay effect moves it in the frame it shows the layer again; otherwise the next idle work does. Pixel 4a, Montreal: 33 to 50-59 fps at z19 on a dense residential block, 40 to 52 at z20.5 downtown.
Symbol order¶
- Traffic controls draw in two layers.
vela-controlsalways draws (iconAllowOverlapandiconIgnorePlacementtrue) and sits above the route pieces and bridge geometry, below the basemap text.vela-controls-claim(iconOpacity0,iconAllowOverlaptrue,iconIgnorePlacementfalse) sits belowvela-ambient, above the basemap labels, so street names shift away from sign positions and no Vela icon is evicted. - Both dot tiers (
vela-ambient-dots,vela-places-dots-<i>) sit below the basemap's first symbol layer, so a label's halo covers its dot. - In a packed area a low-ranked generic open place is not drawn, dot included. The rule applies to
a row whose tile carries
mark0 and nolandmark, in group default or health, with prominence underopenGenericMinProminence(4.0) and rank in its ~400 m cell pastopenGenericHideRank(GENERIC_HIDE_RANK, 120). Dots return atGENERIC_REVEAL_ZOOM(19.5), pins and names atGENERIC_ICON_ZOOM(20.3). It is for clutter and has no frame-rate effect. Midtown Sacramento draws the same with the rule on and off.
Road widths¶
Liberty grows a road's line 1.2x per zoom level while the map doubles, so its streets thin out
next to the buildings as the map zooms in. widenStreets, run for every palette, draws each
class at the wider of its base curve and a real width in meters:
dp = min(cap, meters x roadWidthScale x 2^z / (78271.517 x cos 40))
An expression cannot read the latitude, so 40 degrees is fixed. Stops are every half level from z5 to z20. Roads, bridges and tunnels of a class share one curve.
| Class | ROAD_WIDTH_M |
ROAD_ONEWAY_WIDTH_M |
ROAD_WIDTH_CAP_DP |
|---|---|---|---|
minor (road_minor, bridge_street, tunnel_minor, tunnel_street) |
10 | same | 34 |
| service_track | 3.5 | same | 14 |
| link, motorway_link | 8 | 6 | 28 |
| secondary_tertiary | 13 | 9 | 42 |
| trunk_primary | 17 | 11 | 52 |
| motorway | 22 | 13 | 62 |
- The base curve is Liberty's own, except minor roads: 0 at z12.5, 1.6 at z13, 4 at z14, 9 at z16, 18 at z20.
- A casing keeps the style's border width around the wider fill, and at least the road-edge floor (6.2).
- A piece whose tile
onewayis set takes the one-way width: OSM draws a divided road as two ways, and at the whole road's width each the pair merged into one band about three times the route stripe. Minor and service roads keep their width, since a one-way street there is a whole street. - Browse pans at z16.6 on a Pixel 4a measure the same with Liberty's widths and these (51-59 fps). Repeated runs of one build on that phone vary by 5 to 7 fps of median, so a smaller gap is noise.
Painted roads (developer test, not shipped)¶
core/data/PaintedRoads, ui/map/PaintedRoadsLayer, dial debug.vela.tune.paintedRoads (1 =
the California bake, 2 = built on the phone). Road markings from OpenStreetMap tags, drawn at
real scale from z16.5 above the roads and below the route line: medians, road surface (3.3 m a
lane; bike lanes 1.2 m, set 0.9 m outside), center and lane lines, crosswalks, stop lines
(STOP_BACK_M 8.5 m back at a junction) and one turn arrow per lane (ARROW_BACK_M 18 m
before the junction, ARROW_M 8, set by eye). Lines stop JUNCTION_TRIM_M (8 m) short of
intersections. The crosswalk dash is 0.4 of its width, since at 0.22 MapLibre's dash texture
draws nothing, and arrows are bitmaps, since as SDF icons the strokes thinned to nothing.
The dial is polled from an effect that restarts at every style load, for every user. Mode 2
fetches through one HTTP client per process (paintedRoadsHttp), built on the first fetch: a
client built in that effect would set up TLS on the main thread at each style load.
Bake: scripts/bake-painted-roads.sh <pbf> <name> --upload (osmium, PaintedRoadsBakeTest with
-DvelaPaintIn/-DvelaPaintOut, tippecanoe z15 layer paint) onto the painted-roads release.
A version query on BAKED_URL moves the map cache off old tiles after a rebake.
Street names¶
highway-name-minorhas min zoom 13.5. A symbol layer draws nothing below its own floor however wide the line under it.highway-name-pathkeeps Liberty's floor.symbol-spacingonhighway-name-minorandhighway-name-major(roadNameSpacingExpr), linear between stops:
| Zoom | Spacing, px | Constant |
|---|---|---|
| up to 16 | 140 | ROAD_NAME_SPACING_PX |
| 18 | 300 | ROAD_NAME_SPACING_CLOSE_PX |
| 19 | 540 | |
| 20 | 960 | |
| 21 | 1500 | ROAD_NAME_SPACING_MAX_PX |
At MapLibre's default 250 most blocks of a grid carry no name at street zoom. Past z16 a block
fills the screen and 140 repeats each name along it. The tiles stop at z14, so further in a road
repeats its name along its whole tile every frame. Pixel 4a, downtown Montreal: 47-49 fps at 140
against 51-53 at 300 at the 50 m scale, and at z20.5 23 fps at 300 against 46 with street names
hidden.
- highway-name-path is filtered to class path with subclass path, bridleway, cycleway or
pedestrian, and never indoor. Liberty names every footway and indoor corridor while their
lines are hidden: 26 fps at z20.5 in downtown Montreal, 43 with the layer hidden.
Route line¶
routeWidth()is the wider of a pixel curve (7 / 11.2 / 11.5 / 11 / 17 / 20.4 dp at z10 / 14 / 15 / 16 / 17.5 / 18.5) andROUTE_REAL_M(8.5 m), capped atROUTE_CAP_DP(32). At 8.5 m it covers a two-lane street or one carriageway with a little road showing each side.- Alternates use
ALT_REAL_M(7.65 m), capped atALT_CAP_DP(30), with their edge (vela-alt-route-edge) inside that width. Both widths followroadWidthScale. - Each route piece has an outline layer
<piece>-olon the piece's own source:#0e326aby day,#061a45at night,ROUTE_OUTLINE_DP(1.25 dp) a side from z14, down to 0.5 dp at z11. All outlines sit below the lowest piece, so an outline's round cap never crosses a fill. Alternates sit below the outlines. Style.routeSetcopies each piece's visibility and opacity to its outline. The outline's gradient is transparent before the piece's driven fraction, so the trail behind the arrow has none.- A Pixel 4a demo drive measures a median 59 fps with road edges and outlines on and off.
Turn arrows¶
- During a drive a short arrow draws on the route through each turn ahead (issue #804, as
Google and OsmAnd draw them):
TurnArrowGeometry.arrowstakes the route's stretch fromBEFORE_M(30 m) before the maneuver point through the corner toAFTER_M(30 m) past it, for the maneuvers inTYPES(turns, forks, ramps, keeps, a U-turn, a roundabout's exit; not a continue, a merge or the roundabout's entry) from the step in hand onward. The corner is found on the line, fromCORNER_BACK_M(10 m) before the point toSEEK_M(150 m) past it: the first vertex where the chordsHOLD_M(25 m) long on either side differ byBEND_DEG(12) or more, moved on to a sharper vertex withinCORNER_NEAR_M(15 m). A fork's or a ramp's split lies past the maneuver point, and a lane change is a jog the chord after it does not hold. With no such vertex the stretch endsAFTER_Mpast the point. Each arm is simplified (Douglas-Peucker,SIMPLIFY_M1.5 m, well inside the stripe's half width; at 5 m a curve's chord ran up to 4.5 m inside it), the corner kept, and the arrowhead aims along the arrow's own lastHEAD_CHORD_M(6 m) as drawn. - The arrows are cut from the line the map draws (
VelaMapView'sroutePolyline, thedrawPolylinemoved to road centers and smoothed), passed asarrows'sline, not from the guidance line: a Google route is guided on Google's own line, which runs in a lane up to about 9 m from the drawn one, and arrows cut from it sat beside the blue line in places. Each maneuver is placed on the drawn line withinDRAWN_WINDOW_M(120 m) of where the guidance line puts it, scaled by the two lengths, so a U-turn's other carriageway is never taken for it. TurnArrows(holder,turn_arrows_on, on by default under Settings > Navigation) is written byNavControllerper tick, change-gated on the route and the step likeNavTurnTarget; it publishes the route and step (input), andVelaMapViewbuilds the arrows on its drawn line off the main thread, soMapScreencarries nothing for it. The layers sit above the topmostvela-route*line layer, the pieces' pending "-b" copies included, and are seated again when a piece has come in above them (the drive'svela-route-cut-bhid the bodies on a 4a), from z14, in this order:vela-turn-arrows-casing,vela-turn-arrows-head-casing,vela-turn-arrows,vela-turn-arrows-head. The arrow sits inside the stripe, as Google's does: its dark edge (TURN_ARROW_EDGE, an opaque dark indigo) spansTURN_ARROW_CASING_OF_ROUTE(0.72) of the stripe's width at every zoom and its whiteTURN_ARROW_BODY_OF_ROUTE(0.54), both from the stripe's own curve (realWidthCurve), with round caps and joins. The head is a plain triangle 1.45 shaft widths across with a 74 degree tip and corners rounded 1.5 dp, built in dp with the screen's density (turnArrowHeadBitmap) and sized by zoom to the shaft (turnArrowHeadSize); its dark edge is drawn under the white shaft and its white over it, and its base sitsTURN_ARROW_HEAD_TUCK_DP(1 dp) behind the shaft's end, so no dark line crosses the joint. Empty outside a drive.
Rasters¶
- The traffic raster (
vela-traffic, opacity 0.6) sits abovebuilding-3d, elsebuilding, else below the first symbol layer, so footprints do not paint over the congestion colors. With satellite on it sits above the imagery. Its source stops at z16 (issue #800): closer in, MapLibre scales the z16 tile, whose lines Google draws thin, so the layer reads the same everywhere; z17 and z18 requests were up to 16 per z16 tile, Google throttled them, and the tiles that never came left far-out tiles stretched into fat bands beside bare patches. - It carries a 900 ms
raster-fade-duration. Google's tiles expire while the map is open, and at the default 300 ms a replaced tile reads as the whole layer flickering. - It is not drawn during a drive (
navMode), whatever the setting: the route line carries the traffic, and in the tilted drive view the raster's tiles load at a different zoom for every distance from the camera and expire as the car moves, so the colored bands along a highway grew, shrank and blinked (issue 733). It comes back when the drive ends. - Satellite base imagery (Esri) caps at z19 and MapLibre stretches past it. From z17
(
SAT_DEEP_PROBE_ZOOM)refreshSatDeepprobes Esri's availability index at the view center, 20 then 21 then 22, stopping at the first missing level.ensureSatelliteDeepadds one raster layer above the base at the probed level, or Google's imagery to z21 where Esri stops at 19. "Use Vela without Google" leaves that fallback out. - The deep layer cross-fades in, opacity 0 at z18.6 to 1 at z19.6, because the deeper tiles are a
different capture program. Its minzoom is
SAT_DEEP_MIN_ZOOM(18.6), so it loads no tiles while invisible.
Attribution¶
A tappable "© OpenStreetMap" label sits bottom-left under the scale bar in every map state. It is
lifted over the nav bar, the minimized results bar and the free-drive speed box, and moves into
the map strip in landscape. The scale bar (ScaleBarReader) is never hidden for the speed box:
both rise by SPEED_BOX_LIFT_DP (78 dp) only while the box is drawn, moving without a route
with Show speed on (speedBoxLift). The scale used to hide for two minutes after any motion
while the map followed the dot, box or no box, and left the corner empty (issue #848). It opens openstreetmap.org/copyright. Never gate it on a chrome
state: the ODbL asks for the credit wherever the map shows. MapLibre's own info button and logo
are off. The satellite credit is a separate centered line, which adds Google where the Google
deep layer shows. The label is OsmCredit in MapScreen.kt; driving mode draws its own above the
bar's middle (DrivingChrome). Both fade out while the speaker's three voice choices are slid
out (VoiceSlideOutOpen, up to OPEN_MS), since that row runs across the same strip and was
drawn under them (issue #840).
Dials¶
"adb" is setprop debug.vela.tune.<key> (AppTune.local).
| Dial | Default | Read from | Scales or switches |
|---|---|---|---|
roadWidthScale |
1.0, clamped 0 to 3 | adb, then calibration | road, route and alternate meters. 0 leaves the base curves |
roadEdge |
on | adb, then calibration | road edges |
turnZoomMin |
12 | adb, then calibration | the floor of Zoom to the next turn (NavFraming.turnFloor) |
routeOutline |
on | adb, then calibration, at style load | route outlines |
roadNameSpacing |
140 | adb | name spacing up to z16 |
roadNameSpacingClose |
300 | adb | name spacing at z18 |
roadNameSpacingMax |
1500 | adb | name spacing at z21 |
openGenericMinProminence |
4.0 | adb, then calibration | packed-area rule |
openGenericHideRank |
120 | adb, then calibration | packed-area rule |
overlayCoverFrac |
0.18 | calibration | overlay gate threshold (6.4) |
6.4 The building-overlay gate¶
The overlay is occluded overdraw where OSM is dense, so a gate probes rendered OSM coverage per viewport and shows the overlay only where OSM is sparse. Four rules:
- Probing is bounded by time.
queryRenderedFeaturesis a synchronous round trip from the main thread to the render thread, and idle events can fire per frame. Camera-idle and render-idle events mark the verdict dirty and call the gate. The gate probes at most once perOVL_GATE_MIN_GAP_MS(1.2 s), at z16 and above, and only when the view's cell or integer zoom changed or a render finished since the last verdict. Probing straight from an idle event froze a Pixel 4a to about 1 fps. - Coverage is measured by area, never by feature count: tile generalization merges a dense
downtown block into two or three giant polygons. Twelve screen points (a 3 by 4 grid) are
tested against
buildingandbuilding-3d. A hit fraction ofOSM_COVER_FRAC(0.18) or more hides the overlay. - Layers are born hidden and revealed only after a finished render
(
addOnDidBecomeIdleListener). A "sparse" verdict before tiles land looks the same as a real gap, so it is discarded and asked again. Hiding is always safe at once. A call blocked by the time floor schedules one deferred retry, or an uncommitted verdict sticks forever on an idle map. - One probe per animation frame (
ovlProbeRun). Run back to back, the 12 probes stalled the main thread for 45 to 193 ms on a Pixel 4a. Spread over 12 frames the verdict lands about 200 ms later, which nothing waits for. A gate call while a sequence is in flight returns. The time floor applies while navigating too, and during a drive the gate probes only while the camera follows the car. A detached camera is the user's pan, and the drive's timer (4.x) probes again once the camera is back on the car.
Gate state is composable-scoped, because getMapAsync can register listeners twice.
7. Offline data¶
7.1 What a region download contains¶
MapViewModel.downloadRoutingGraph pulls a region as one flow under one progress card:
- The routing file,
obf/<id>.obf. - The region's place pack,
poipacks/<id>.db(rules below). - The places archive,
places/<id>.pmtiles, whenMapPoiPrefs.placesWithDownloadsis on (default on). - The basemap archive,
basemap/<id>.pmtiles. - After the basemap archive: the glyph pack and the world low-zoom basemap, if missing.
The status says "ready" once, after the last piece, or "incomplete" when one failed. A places or basemap piece that never arrived shows as an update on the region's row (7.3).
Saving an area with the whole-region box checked runs the same download for the region
RegionPick names for the area's center (7.2) and also pulls the smallest covering building
overlay (downloadRoutingForArea). Address and maxspeed overlays are only streamed. Road features
download per region the first time the map or a route needs them (4.9).
GraphHopper graphs are retired. LegacyGraphs.purge deletes filesDir/graphs at launch when it
exists and shows one status line asking the user to download those regions again.
| Dataset | Workflow and script | Release | Manifest | Rebaked | On the phone |
|---|---|---|---|---|---|
Routing .obf |
obf-regions.yml, scripts/build-obf-region.sh, VelaObfShim |
obf-regions |
obf-manifest.json |
90 days | obf/ |
| Place pack (SQLite) | poi-packs.yml, scripts/build-poi-region.sh, poipack_build.py |
poi-packs |
poi-pack-manifest.json |
30 days | poipacks/ |
| Places archive (PMTiles) | places-overlays.yml, tools/build-places-region.sh |
places-overlays |
places-overlay-manifest.json |
a seventh of the catalog daily | places/, or streamed |
| Basemap archive (PMTiles) | basemap-tiles.yml, tools/build-basemap-region.sh (planetiler) |
basemap-tiles |
basemap-manifest.json |
30 days | basemap/ |
| World low-zoom basemap | world-lowzoom.yml |
basemap-tiles, asset basemap-world.pmtiles |
none (WORLD_BASEMAP_URL) |
on dispatch | basemap/world.pmtiles |
| Grid cells (7.6) | grid-cells.yml, scripts/build-cells-region.sh |
cells-<region> |
cells-manifest.json on grid-cells |
30 days | parts in obf/, poipacks/, places/ |
| Road features | road-features.yml, scripts/build-road-features.sh, road_features_tsv.py |
road-features |
road-features-manifest.json |
30 days | filesDir/roadfeatures/ |
| Building overlay | building-overlays.yml, scripts/build-overlay-region.sh |
building-overlays |
building-overlay-manifest.json |
90 days | overlays/, or streamed |
| Address overlay | address-overlays.yml, scripts/build-address-region.sh |
address-overlays |
address-overlay-manifest.json |
90 days | streamed |
| Maxspeed overlay | maxspeed-overlays.yml, scripts/build-maxspeed-region.sh |
maxspeed-overlays |
maxspeed-overlay-manifest.json |
90 days | streamed |
| ALPR cameras | flock-cameras.yml, scripts/build-flock-cameras.py |
flock-cameras |
flock-manifest.json |
Mondays 08:17 UTC | bundled asset, refreshed at launch |
| UK fuel prices (5.8) | fuel-gb.yml, tools/build-fuel-gb.py |
fuel-gb |
fuel-gb-manifest.json |
checked hourly, published when the source changed | fuelgb/, checked at most every 3 h when a UK gas station needs a price |
| Glyphs | scripts/build-map-fonts.sh |
map-fonts, asset map-fonts.zip |
none | by hand | glyphs/<stack>/<range>.pbf |
The glyph set is also unpacked to GitHub Pages (/fonts) for the online map. The releases
obf-tools (the pinned mapcreator.zip the obf bakes use), obf-runtime, cronet-runtime,
tts-runtime and asr-models hold build and voice files, with URLs in the scripts and code.
A manifest is {regions: [...]} with rows {id, name, url, sizeMb, bbox: [S,W,N,E]}. Obf,
pack, places and basemap rows add rev. Obf rows add installedMb and hh. Pack rows add
installedMb, updatedAt, counts and an optional delta. Places and basemap rows take an
optional delta. Road-feature rows are {id, name, url, sizeKb, bbox, count, updatedAt}.
The place pack of a region¶
RegionPacks.packFor returns the pack with the region's own id, else its parent's. A piece of
a split country or state names the parent in parentheses ("Northern California (California)",
"Bayern (Germany)"). The parent pack's name must match and its box must hold the piece's
center, which keeps Andorra from getting Spain's pack.
- Pieces share the parent pack. It is deleted with the last installed piece that uses it, updated through any of them, and counted once in a group's size.
- A shared parent up to
RegionPacks.AUTO_PARENT_MAX_MB(600, zipped) comes with a piece's download. A bigger one (Germany's is 1.9 GB) waits for "Get places", whose row shows the parent and its size. - When a piece has a pack of its own but the parent's is the one installed, the parent keeps serving it.
- Saving an area finds the routing region holding the area, then its pack the same way
(
downloadOfflinePois). Only an area no pack covers is filled from Overpass.
Manifest merges¶
Each bake job uploads one file per region and emits a manifest entry. A merge job publishes the manifest.
- Basemap, places and grid cells derive the manifest from the files on the release:
scripts/repair-basemap-manifest.sh(run bymerge-basemap-manifest.sh),scripts/repair-places-manifest.sh(run bymerge-places-manifest.sh) andscripts/merge-cells-manifest.sh. An existing row is reused only when the size is unchanged and the asset was not uploaded after the row's rev. The run's own entries win for the regions it baked. A new basemap row's box is read from the archive's first 127 bytes; a places row's box comes fromtools/places-regions.json. The upload retries, and the script lists the release again afterward and rebuilds when a file landed meanwhile. These merges have no concurrency group: GitHub cancels a job pending in a group when a newer one joins, after its archives are already uploaded. - Routing, place packs, road features, buildings, addresses and maxspeed replace rows by id in
the existing manifest, serialized by a concurrency group (
obf-regions-manifest,poi-packs-manifest,road-features-manifest,building-overlays-manifest-merge,address-overlays-manifest-merge,maxspeed-overlays-manifest-merge). - An address source whose rows carry no house number is skipped with a warning
(
build-address-region.sh), and the published overlay stays. Delaware is baked from every source underus/de/for that reason: OpenAddresses' statewide file has an emptynumberin all 532,164 rows (its source definition names the columnHOUSENUMBNER, the state's layer calls itHOUSENUMBER), while the three county files and two city files carry 515,694 distinct house numbers between them. - A region with no road tagged
maxspeed(a small island) is skipped with a warning (build-maxspeed-region.sh) and has no manifest row. tippecanoe exits 110 on empty input.
Infrastructure releases¶
Every tag that does not start with v0. is file hosting whose assets exist nowhere else. A
cleanup that deletes or edits releases selects by the tag pattern v0.*, never by the
prerelease flag or age. Anything that lists releases pages through them or bounds by tag,
because the repository holds hundreds.
7.1a Where the files live¶
offline/StorageLocation roots the folders in StorageLocation.FOLDERS (obf, poipacks,
places, basemap, overlays, glyphs, cells, fuelgb) at filesDir or at the app's folder on a
removable SD card (getExternalFilesDirs, no permission). Pref offline_storage is internal
(default) or sd. The choice is in Settings > Offline maps and shows only when a card is
mounted or the card is the chosen location.
- Every store reads the root on each access.
:core'sObfRouteEnginereads it throughOfflineRoot.dir. - With the card chosen and missing, the root is internal storage.
- Voices, speech models, road features, the sprite and caches stay internal.
- The obf and PMTiles stores keep
index.json(id and box) andrevs.json(installed rev) beside the files. Packs keeprevs.json. PMTiles stores also keepdead.json(7.3).
MapViewModel.moveOfflineStorage refuses during a download, an update or a drive, and when
the target lacks the data's size plus 64 MB. It closes the routing readers, the place packs and
the map's archive sources, copies with a length check per file, and deletes the source only
after every file copied. A failed copy removes the partial destination. MapLibre's database
moves in two steps (point MapLibre at a temporary folder, copy mbgl-offline.db, reopen at the
destination), because MapLibre's path change opens a new database and carries nothing over.
adb shell setprop debug.vela.sdtest true makes the shared-storage app folder stand in for a
card.
Deleting¶
- A region (
deleteRoutingGraph): the routing file, the pack unless another installed piece uses it, the region's cells, the places and basemap archives of the same id, and any archive whose box center lies inside the boxroutingRegionBox(id)returns. - A saved area: MapLibre removes the area's rows, then
OfflineMaps.packDatabase(OfflineManager.packDatabase, a VACUUM) runs. MapLibre keeps saved areas and the browsing cache in one SQLite file, and a delete alone frees no bytes. Clear map cache packs too. - "Delete all offline data" (
deleteAllOfflineData, behind a confirm naming the total): every saved area, routing file, pack, places and basemap archive, building overlay, cell, the road features, the UK fuel price file, the glyph pack and any legacy graph folder. It then sweeps the store folders for files no index reaches (keepingindex.json,revs.json,dead.json), clears the browsing, place and Street View caches and packs the database. Voices and speech models stay.
Settings > Offline maps reports storage through offlineStorageBreakdown. The map figure
counts MapLibre's database, overlays/, basemap/, glyphs/ and roadfeatures/. "Offline
places" counts poipacks/ and places/.
7.2 Catalog and selection¶
Catalogs¶
| File | Rows | Bakes |
|---|---|---|
tools/routing-regions.json |
Every Geofabrik country-level extract, US states, Canadian provinces, first-level sub-areas of the countries Geofabrik divides, and regions Vela cuts itself: id, name, group, pbf_url, optional big, skip_obf |
obf, place packs, road features, basemap, maxspeed, grid cells |
tools/places-regions.json |
id, name, bbox (the OSM extract is matched by id in the routing catalog) |
places |
tools/overlay-regions.json |
Groups us, world, chunk; rows carry qkprefix where relevant |
building overlays |
tools/address-regions.json |
One row per OpenAddresses source | address overlays |
A dispatch takes region ids, a list of groups, or all-sub (every <country>-sub group). A
matrix holds at most 256 jobs, so catalog-wide bakes run as shards or group sets. skip_obf
marks a whole country or state that its sub-area rows replace: eleven are too large for the obf
bake, and Texas is offered in parts instead. The obf, basemap and cells bakes skip those rows.
After adding a catalog row, run scripts/region-polys.py.
A region cut from a bigger extract¶
A row's pbf_url is a Geofabrik URL or a cut:
"pbf_url": "cut:<parent id>:<polygon file>"
The parent is another row of tools/routing-regions.json with a downloadable pbf_url; a cut
of a cut is refused. The polygon is an osmium .poly file under tools/region-cuts/, named by
its path from the repository root. Every other field is as on any row.
scripts/fetch-pbf.sh makes the extract. It downloads the parent, runs
osmium extract -p <polygon> --strategy smart --set-bounds and deletes the parent.
--strategy smart keeps a way, a turn restriction's ways and a multipolygon that cross the
edge whole. --set-bounds writes the polygon's box into the header, which the obf, pack, road
feature, maxspeed and cell bakes publish as the region's bbox and
tools/build-basemap-region.sh passes to planetiler as --bounds. The places bake reads its
box from tools/places-regions.json, as for every region.
The basemap bake runs planetiler with --transliterate=false (issue #738): left on, it fills
name:latin with an ICU transliteration wherever OpenStreetMap has no Latin name, which for
Hebrew is a vowel-less skeleton a reader took for Turkish. The streamed tiles carry no such
name, so a street with no English name shows its local name online, and an archive baked after
2026-10-10 does the same; older archives keep the skeletons until their cycle rebakes them.
- Every bake reaches the extract through
fetch-pbf.sh, so a cut needs no change in a bake script or a workflow's region selector. A download that bypasses the script fails on thecut:scheme. - A job that bakes a cut needs osmium and jq.
basemap-tiles.ymlinstalls osmium for cut rows only; the other bake workflows install it for every row. PBF_CACHE_DIR=<dir>keeps the parent between cuts on one machine.PBF_DATE=<YYMMDD>takes Geofabrik's dated extract in place of-latest(places-churn.yml).scripts/region-polys.pyreads a cut's polygon from the repository and writes it unsimplified.- Neighboring cuts overlap, so a trip near a seam routes inside one part, and their outer edge is the parent's own polygon, so the parts together hold what the parent holds and a region's box claims no ground outside it.
- A cut's places archive covers its whole box, like any region's: the bake reads Overture by
the box, and
PmtilesRegionStore.sourcesForpicks an installed archive by its box. Only the OpenStreetMap rows in it stop at the polygon.
Texas in four parts¶
Geofabrik publishes no Texas sub-extracts. The catalog cuts four (group texas-sub), and the
whole-state row carries skip_obf and is left out of the places catalog, as California's is.
| Row | Name | Holds | Counties | Nodes | Extract |
|---|---|---|---|---|---|
texas-north |
North Texas | Dallas-Fort Worth, Wichita Falls | 31 | 31% | 213 MB |
texas-east |
East Texas and Gulf Coast | Houston, Beaumont, Tyler, College Station | 55 | 26% | 178 MB |
texas-south |
Central and South Texas | Austin, San Antonio, Waco, Corpus Christi, Laredo, the Rio Grande Valley | 75 | 31% | 204 MB |
texas-west |
West Texas and Panhandle | El Paso, Midland, Lubbock, Amarillo, Abilene | 93 | 14% | 85 MB |
Measured on the Texas extract of 2026-10-08: 95.2 M nodes, 690 MB. The parts are not equal quarters because no seam cuts a metro area: the four core counties of Dallas-Fort Worth hold 21% of the state's nodes and everything west of the 100th meridian 13%.
- Every county is whole in one part. West ends at the 100th meridian, and at 99 W north of 31.6 N, which puts Abilene's counties in it. North ends near 31.8 N and 96 W. East begins at the western lines of Freestone, Leon, Brazos, Grimes, Waller, Austin, Wharton and Matagorda counties.
- Each part reaches about 4.5 km past its seam, so the overlap bands are about 9 km wide.
- The outer edge is Geofabrik's Texas polygon, which holds the open Gulf down to 25.7 N. There the East and South seam runs due south from Matagorda Bay.
- The places bake reads a part's box, as it does for every region, so the seams keep each box off the other parts' cities: East's box ends east of Dallas and South's ends west of Houston. On Overture release 2026-09-23.1 the four boxes hold 2.06 M places, the four polygons 1.64 M, and the box of the whole state 2.42 M.
- Merged back, the four extracts hold every relation of the whole extract, all but 15 of its 11.84 M ways and all but 160 of its 95.15 M nodes. What is missing lies on or outside the edge of Geofabrik's polygon.
- Baked for
texas-weston a laptop: routing file 40 MB with the highway hierarchy (whole Texas is 216 MB, and its latest bake has none), place pack 24 MB zipped (252 MB), places 99 MB (801 MB), road features 93 KB (1,093 KB), maxspeed 13 MB (66 MB).
In Settings, regionTree lists a split state's parts under United States with the other
states (US_SPLIT_STATES). The whole-state row is listed only where that file is installed,
so it can be updated and deleted there. Everyone else is offered the parts alone, and
Download all does not fetch the state twice.
The routing file bake¶
scripts/build-obf-region.sh indexes a roads-only extract (bake_obf_filter: highway ways,
ferry and shuttle-train routes, turn restrictions, route relations) with VelaObfShim at
JAVA_HEAP 12g, the most a 16 GB runner allows. It then adds the highway hierarchy
(bake_obf_hh, 4.5). A region where that step fails ships without it. The file is served raw,
so sizeMb equals installedMb.
Indexing holds every node of its input at once. A roads-only extract over OBF_SPLIT_MB
(250 MB) is cut into strips of at most that size across its longer side with
osmium extract --strategy smart, which keeps a road or turn restriction that crosses a cut
whole in both strips. Each strip is indexed alone and BinaryInspector -c joins them into one
file. OBF_SPLIT=<n> forces n strips and OBF_OUT=<file> keeps the result unpublished.
Delaware forced into 3 strips matched the unsplit file on the ObfCellsProbeTest trips in
distance, time and step count.
Which region covers a point¶
RoutingRegion.covers and PmtilesRegionStore.Region.covers test the region's boundary
polygon (RegionPolys, assets/region_polys.json) and fall back to the box for an id with no
polygon. A box wider than WORLD_SPAN (350 degrees) and shorter than WORLD_BAND (120
degrees) never covers by itself: it is an extract crossing the antimeridian. Among covering
regions the smallest box wins.
The polygon file is baked by scripts/region-polys.py from the Geofabrik .poly beside each
extract, simplified to about 5 km, and loaded once at app start. A cut region's polygon is its
own file, unsimplified, because the overlap between two cuts is narrower than the
simplification. Every region-for-a-point
decision goes through these two functions: downloads for the view, the streaming unions, the
routing offer, updates, the saved-area pack lookup, the road-features region and the Offline
settings row.
A region download pulls the places or basemap archive with the region's id (archivesFor).
Without one it pulls every archive whose box center lies inside the region, and without any of
those the smallest archive covering the region's center.
RegionPick decides which region a download is offered or started for: the smallest covering
region, unless a larger covering region is installed, which then answers as already
downloaded. A phone that holds a whole state is therefore not offered one of its parts. It
serves the area picker's plan and its "too large" line (areaDownloadPlan), the region that
comes with a saved area, the one-time routing offer, and the places and basemap archives of a
saved area. The low-zoom world basemap covers every point and never counts as installed
coverage.
Places layer¶
PmtilesRegionStore.sourcesFor(center, manifestUrl, view) uses installed archives only while
one of them holds the center. It then mounts every installed archive whose box touches the view,
minus any archive nested inside another mounted one, nearest to the center first, at most
MAX_MOUNTED (8). Two nested archives would draw the overlap twice. Pick.rev is the oldest
mounted rev. With the center outside every installed archive, the smallest manifest region
covering the center streams.
Basemap, online¶
Online the map always streams OpenFreeMap and pickBasemapArchive mounts no file. Mounting one
online reloaded the whole style at every edge of the downloaded data.
offline/LocalBasemapTiles is an interceptor in MapLibre's HTTP client
(HttpRequestUtil.setOkHttpClient, installed after MapLibre.getInstance). It answers a
request for an OpenFreeMap tile from an installed region file when the file is baked to
FULL_MAP_ZOOM (14) and the tile's four corners, padded by EDGE_PAD_DEG (0.05 degrees), lie
inside that region's polygon. The shipped polygons are simplified to about 5 km, which the pad
absorbs. Border tiles, shallow bakes and the world file stream.
Basemap, offline¶
Offline here is offline || !isValidated(): a network that never reached the internet counts
as offline. BasemapTileStore.installedFor(center, mounted, corners, keepMounted = true)
returns the first of:
- The mounted archive, while its roads reach the center tile, one of the eight tiles around it or a viewport corner. When the center tile has none of its roads and another installed archive's box holds the center and its roads reach that tile, the smallest such archive instead: the region being looked at is drawn, not the one the view came from.
- The smallest installed archive whose box holds the center or a corner and whose roads reach one of those tiles.
- An archive in view that the probe could not read.
- The world archive.
The probe is PmtilesReader.hasRoads at COVERAGE_PROBE_Z (12): whether the tile carries the
transportation layer. Tile presence cannot answer, because a bake emits tiles across its
whole box from planetiler's global base data. Definite answers are memoized per archive and
tile. The pick runs off the main thread on camera idle and after every download or delete.
- The world archive (
BasemapTileStore.WORLD_ID, z0-7, about 11 MB) holds Natural Earth water, coastlines, boundaries and place labels and no roads. It is kept out of the candidate list and pulled once with the first basemap download (ensureWorld). - A shallow archive (max zoom under
FULL_MAP_ZOOM, read from byte 101 of the PMTiles v3 header) is used only offline. The bake drops one zoom level when a region would pass the 2 GiB release asset limit. - The mounted archive is part of the style key, so a swap reloads the style. Swaps keep a floor
of
BASEMAP_SWAP_COOLDOWN_MS(2 s), and a newer camera idle cancels a pending pick.
Overlays¶
Building and address overlays stream from up to the three smallest covering regions, because a neighbor's smaller box can cover a point its data does not reach. Installed building overlays are always mounted, and when one of the three is installed the others are not streamed. The maxspeed overlay is not mounted where an installed region or cell answers the limit on the phone.
7.3 Freshness¶
A manifest row's rev is an integer that only grows. The obf, basemap, places and cells bakes
stamp the UTC bake date as YYYYMMDD. Place packs count up, one past the live manifest's rev
for that region, which is the fromRev their deltas key on. A road-features file is
downloaded again when the manifest's updatedAt differs from the stored stamp, and the UK fuel
price file when the manifest's fileSha256 differs from the stored manifest's (5.8).
MapViewModel.refreshRegionUpdates lists each installed region's update kinds: routing (a
newer rev than the installed one), places and map (a newer archive whose box center lies
inside the region, or one the region should have and lacks). The row's Update button
(updateRegion) refreshes the pack when its rev is newer, then the places and basemap
archives, then the routing file. Routing files have no patches and download whole. "Update
all" under Update downloaded regions (updateAllRegions, shown with the count when any row
has one, issue #801) runs the same for every such region in turn, under one download card;
Cancel stops after the region in hand. An installed region's row ends with "updated regionInstalledRev;
the catalog's revisions are yyyymmdd dates, anything else shows nothing).
Place pack deltas¶
poipack_delta.py writes, per table, the rows to delete and to insert (del_<table>,
ins_<table>, one SQL EXCEPT each). The bake publishes <id>.delta.zip and
delta: {fromRev, url, sizeMb} only when the delta is under half the full zip.
PoiPackStore.applyDelta runs when the installed rev equals fromRev. In one transaction it
deletes by full-row match (NULL-safe IS, through each table's index), inserts, and checks
every table's row count against the manifest's counts before committing. A delta that fails
falls back to the whole pack.
Tables: poi(id, name, lat, lng, category, address, phone, website, hours),
streetname(sid, street, street_norm), addr(hn, sid, city, lat, lng),
streetpt(sid, lat, lng); PRAGMA user_version is 2. sid is the SHA-1 of the normalized
street name truncated to a positive 63-bit integer, and a collision fails the build. A counter
would renumber millions of rows on a rebuild and make the delta as large as the pack.
TABLE_COLUMNS in PoiPackStore, poipack_build.py and poipack_delta.py must stay in step.
Archive patches¶
A week of edits moved 1.3% of Kentucky's tiles (3.2% of its bytes, a 4.4 MB patch against a
183 MB archive), so places and basemap rebakes publish patches. The producer
(scripts/pmtiles-make-patch.py) and the reference applier (pmtiles-apply-patch.py) share one
reader (velapmtiles.py). The phone's applier is offline/PmtilesPatch (magic VELAPTCH,
version 2).
- Format. The patch carries the new directory's tile ids, run lengths and tile lengths, plus one flag per entry: the tile rides in the patch, or the archive already holds it under that id. It names no offsets. The applier resolves entries against its own file and reads the tile-data offset from the archive's own header, so a patch applies to an archive that earlier patches or a compaction rearranged.
- Apply, in place. Append the changed tiles, append the rebuilt directory, sync, verify, then
rewrite the 127-byte header last. An interrupted apply leaves the old archive intact, and the
free space needed is the patch's size. The result is unclustered, which MapLibre reads and
pmtiles verifyrejects. - Verify. The fingerprint is SHA-256 over sorted tile ids, run lengths and tile hashes (Android has no blake2b). It is computed against the new directory while the header still describes the old archive. A mismatch truncates the file back and the caller downloads the region whole.
- Publish (
places-overlays.yml,basemap-tiles.yml). The bake diffs against the published archive, applies the patch to a copy and checks the fingerprint. It uploads<places|basemap>-<id>.<fromRev>.vpatchand addsdelta: {fromRev, url, sizeMb}to the row only when that passes and the patch is under a third of the archive. A bake with the same rev as the published one makes no patch; therevinput overrides the date stamp. A rebake after a bake-script change usually fails the one-third test.scripts/archive-churn.py(places-churn.yml) measures the churn between two bakes of one script. - Dead space. A patch leaves the replaced tiles behind, and
dead.jsonholds those bytes per archive. Past a fifth of the file (DEAD_LIMIT_DIVISOR5)PmtilesCompactrewrites the archive in tile-id order to a temporary file, checks its fingerprint against the original and swaps it in. The result is the published layout (header, directory, metadata, clustered tile data, no leaves) and needs room for a second copy. Past half the file in dead spaceupdateWithDeltarefuses the patch and the region downloads whole.scripts/pmtiles-compact.pyis the same code: a patched 3.36 MB places archive compacted to 3,259,268 bytes against 3,259,285 for a fresh download of that rev, same fingerprint (the 17 bytes are the leaf directory a fresh bake writes).adb shell setprop debug.vela.compact truecompacts after every patch.PmtilesCompactTestruns a fixture fromscripts/pmtiles-test-fixture.pythrough the real producer and applier.
Automatic updates¶
app.vela.ui.RegionUpdates, pref region_update_mode: off, wifi (default) or mobile.
wifi means an unmetered network as the system reports it.
maybeAutoPatch runs AUTO_PATCH_DELAY_MS (1 min) after start, every AUTO_PATCH_POLL_MS
(3 h), and AUTO_PATCH_NET_DELAY_MS (15 s) after a validated network appears. It works at most
once per AUTO_PATCH_EVERY_MS (20 h; stamp region_autopatch_at, written only after a
manifest was read) and never during a drive. It applies every published patch whose fromRev
matches an installed places archive, basemap archive or pack, and pulls installed grid cells
with a newer rev again. An archive is never downloaded whole automatically. A pack whose delta
fails to apply is.
A tapped Update tries the patch first, then downloads the whole file over the installed copy.
Every attempt is recorded in the diagnostics ring (kind delta) and logcat VelaDelta with the
bytes and the reason for any fallback.
The progress card names the stage (MapUiState.updateStage): 0 a download with its percent;
1 an update being checked and written, indeterminate because neither the pack transaction nor
the fingerprint pass reports progress; 2 the whole file after an update that could not be
applied.
Manifest caches¶
PmtilesRegionStore.manifest runs on every camera idle. It caches a fetch for
MANIFEST_TTL_MS (1 h), so a long-lived process still sees a new rev, and a failed fetch for
MISS_MEMO_MS (10 min). CellStore caches both for 10 min. RegionCatalog.manifest keeps the
last obf catalog on disk, so the Offline maps page lists regions with no signal.
Bake schedule¶
The Actions token has 1,000 API requests an hour for the whole repository. Overlapping bakes
spend it and fail other workflows with HTTP 403, so the bakes have no crons of their own.
bake-conductor.yml (hourly at :05) runs scripts/bake-conductor.py over
tools/bake-schedule.json. Each hour it:
- Settles the run it started last. Success marks the job fresh. Failed regions are retried
alone (a dispatch with the job's
retryInput, at mostmaxRetries3 per cycle). A run whose only failure is a non-region job is rerun withgh run rerun --failed. - Publishes a staged manifest when its checks pass (below).
- Starts at most one bake: a pending retry first, else the most overdue job. It starts nothing
while a scheduled workflow is running or queued or with fewer than
reserve(400) requests left, and does nothing at all under 60.
Its state is state.json on the bake-conductor release, and its run never fails. Cadences
(everyHours): a seventh of the places catalog every 24 h (slice is the UTC weekday); place
packs, road features, basemap and grid cells every 30 days; routing files, buildings, addresses
and maxspeed every 90 days. ALPR cameras keep their own weekly cron, and UK fuel prices their own
hourly one (5.8): that job fetches one small file and spends no API request while its source is
unchanged.
The routing bake merges into obf-manifest-staging.json (staging=true), which the app never
reads. flip() copies it over obf-manifest.json once all three routing jobs finished a clean
cycle (every region baked, retries included) and staging passes its checks: no live region
missing, no rev going backward, every row's file on the release, something newer. The old live
manifest is kept as obf-manifest-previous.json. A cycle that gave up with regions missing
does not flip until each of those regions has been baked since (heal(): the region's file on
the release is newer than the cycle's last attempt, which one region dispatched by hand does).
The record keeps the lost regions as lost.
Every bake gets its extract through scripts/fetch-pbf.sh: a plain download, then the
redirects walked one hop at a time with a trailing slash dropped from a file name, then the
newest <region>-YYMMDD.osm.pbf in the folder listing. This survives a mirror that redirects
-latest.osm.pbf in a circle. A cut: row's parent is downloaded the same way and the region
cut out of it (7.2).
7.4 Download discipline¶
- Every multi-megabyte download runs through
MapViewModel.downloadLaunch(label). The work runs on the app-lifetimeDownloadWork.scopeand the refcounteddataSyncforeground service (DownloadService) keeps the process alive.viewModelScopeis canceled when the task is swiped away. The area tile save is MapLibre's own download and holds the service directly. - Every large download uses a client derived with
callTimeout(0)and a 60 s read timeout (120 s for the Overpass address body). The shared client's 12 s call timeout aborts a large body and the error is swallowed. Manifest fetches stay on the shared client. - A download lands in a temporary file, is checked (PMTiles magic and more than 127 bytes,
SQLite format 3, an obf over 1024 bytes) and is renamed over the installed copy, so a failed update keeps the old file. - Every download can be canceled. Store functions take
active: () -> Boolean, polled per chunk. The view model holds per-kind cancel flags, reset at each start, and a cancel is not reported as a failure. The area tile save cancels by detaching the observer, setting the region inactive and deleting the partial. Any UI that shows progress shows a cancel. - Whole-parent downloads queue their pieces (
regionQueue) and run one at a time. Cancel clears the queue. - Sizes shown are installed sizes: the manifest's
installedMb, else the download size for an obf and the zip times 2.35 for a pack, plus the region's places and basemap archives (regionExtrasMb). The row states that size, and Download starts at once.
Offline detection¶
MapViewModel.observeConnectivity, core/net/NetHealth.
- The offline flag latches only when the system has no usable network and none of Vela's own
requests got a response within
NetHealth.FRESH_MS(15 s), or one has failed to reach its host since. The check waits at least 3 s and until that window ends. - Any HTTP response clears the flag at once (an interceptor first on the shared client and after the local-tile hook on MapLibre's).
- The system check uses the callback's last default network when
getActiveNetwork()returns null, which Android does for an app whose access is blocked (backgrounding, doze, standby).onBlockedStatusChangedand every activity resume re-check. - Tapping the offline marker calls
recheckConnectivity:reportNetworkConnectivity, one HEAD to the calibration host (no Google contact), then a status line.
7.5 Offline basemap rules¶
Each rule prevents a blank map.
withLocalBasemapremoves theopenmaptilessource from the style JSON and points its layers atvela-basemap. The archive is added under that id after the style loads, and the layers are re-attached. A source declared in the JSON or handed to the style builder never gets past the z0 tile.- A labeled tile completes only once every glyph range and the sprite resolve, and with no
signal a remote host never answers. Both are served from
file://: glyphs from the pack inglyphs/(GlyphPackStore,PACK_VERSION2; an older pack is replaced once per run on an unmetered validated network), the sprite fromfilesDir/sprites/, copied from the APK. The new pack is unzipped toglyphs.newbeside the old one and swapped in by rename, with the old pack moved toglyphs.oldfirst and put back if the swap fails: a rename from the cache folder fails when the maps are on the card. - A process that starts offline on the remote style leaves the engine's shared glyph and
sprite managers with requests that never answer, for every later style. The archive is
therefore picked before the first style load (
refreshBasemapArchive(seed)at init). - Every helper that reads the basemap source goes through
basemapSrc(style), or the offline map comes up light and bare.
7.6 Grid-cell downloads¶
A catalog region is also published as grid cells, so the area picker can download the part of a region a frame touches. The bake is 7.6.1 to 7.6.4, the app side 7.6.5.
7.6.1 Grid¶
Cells are the tiles of one global grid at STEP degrees (cells_grid.py, 0.5 by default),
each clipped to the region's header box (clamped by clamp-bbox.py). Each ring of the region
polygon is clipped to the tile, and a tile where every clipped ring has zero area is not a
cell: it touches the region only at an edge or a corner, or sits in a bay of a concave polygon,
where clipping leaves a flat outline. Only rings with area go into the cell's cutline. Without
a polygon the tile's box is the cell. A cell with no road and no pack row is dropped.
The key is the tile's SW corner, fixed width: [ns]DD.D[ew]DDD.D, for example n38.5w075.5.
The cell id is <region>.<key> (delaware.n38.5w075.5); region ids hold no dot, so the first
dot splits them.
A release holds 1000 assets, the zips plus the fragment. A re-bake starts at the step of the
cells already on the region's release (the largest cell side in its fragment), because a new
step renames every cell: phones keep the old cells, which the manifest no longer lists and which
never update, and the release would hold both sets. A new region starts at 0.5 degrees, and
CELL_STEP overrides both. A region with more than MAX_CELLS (999) cells is regridded at
double the step until it fits; past 8 degrees the bake fails. A published region whose step
changes ends its bake with a warning. The app never assumes a cell size: every cell carries its
box.
7.6.2 Bake¶
scripts/build-cells-region.sh <region> [local.pbf]. Shared steps are in scripts/bake-lib.sh,
which the obf and pack bakes also source.
- The extract is cut to the union of the obf and pack tag filters (
BAKE_OBF_EXPR,BAKE_PACK_EXPR).osmium extract -s complete_waysthen writesCELLS_BATCH(4) cells per pass. A way crossing a cell edge is whole in both cells. osmium's id sets take about 2 GB per dense cell (Northern California: one dense cell peaks at 3.7 GB, five at 11.8 GB), so 4 per pass fits a 16 GB runner. - Per cell,
CELL_JOBSat a time (default 2, CI 3): the routing obf (bake_obf_filterandVelaObfShim, heapCELL_HEAP, default 3g, CI 4g; skipped with no highway way) and the place pack (bake_pack_filterandpoipack_build.py; skipped with no POI, address or street-point row). - The places slice is
pmtiles extract --regionof the region's places archive, with the region polygon fromapp/src/main/assets/region_polys.jsonclipped to the cell. The places archive is baked by box, so a box cut would put the neighbor's places into border cells. A region with no polygon is cut by the cell box. Low-zoom tiles overlap cells, so slices repeat some tiles. <cell-id>.zipholds<cell-id>.obf,<cell-id>.dbandplaces-<cell-id>.pmtiles, each only when present. The obf and PMTiles entries are stored, the pack deflated.
7.6.3 Hosting and manifest¶
One release per region, tag cells-<region>, holds the zips and the fragment
cells-<region>.json. It is created with --target the repository's root commit
(CELLS_RELEASE_TARGET in scripts/bake-lib.sh). GitHub sorts releases by the target commit's
date and Obtainium reads only the first 100, so hundreds of data releases created on HEAD
would push the app's releases off that page. ci.yml, promote-stable.yml and
fdroid-repo.yml read the whole list through scripts/app-releases.sh (GraphQL, three fields a
release; the REST listing carries every asset and a page of 100 takes 9 s). cells-manifest.json on the grid-cells release indexes every region:
{ "version": 1,
"regions": [ { "id": "delaware", "name": "Delaware (state)", "rev": 20260927,
"cells": [ { "id": "delaware.n38.5w075.5", "bbox": [38.5, -75.5, 39.0, -75.0],
"url": ".../releases/download/cells-delaware/delaware.n38.5w075.5.zip",
"sizeMb": 10.81, "installedMb": 15.94, "rev": 20260927,
"parts": ["obf", "pack", "places"] } ] } ] }
bbox is [S,W,N,E] of the clipped cell. sizeMb is the zip and installedMb the unpacked
parts, decimal MB rounded up to 0.01. rev is the bake date, and a region's rev is its
newest cell's. parts names what the zip holds (obf, pack, places); without it the app
assumes all three. The fragment has the shape of a region row.
scripts/merge-cells-manifest.sh [fragments-dir] derives the manifest from the releases (7.1)
through one paginated release listing. Per cells-* release it takes the fragment's rows,
narrowed to cells whose zip is on the release, with sizeMb from the listing. A zip with no
fragment row gets its box from its key, as a 0.5 degree cell, and its rev from its upload date.
The run's own fragments win for their regions. The upload retries five times, 5 to 19 s apart,
and the merge lists the releases again and rebuilds, up to three passes, when an asset landed
meanwhile. DRY_RUN=1 writes the manifest locally.
7.6.4 Upload and workflow¶
Zips go up 100 per gh release upload call and the fragment last, so the merge never lists a
cell whose zip is missing. One request per asset bounds a catalog-wide bake at about a thousand
cells an hour.
rate_waitstops atRATE_RESERVE(200) requests left and waits for the reset, up to an hour. The reserve is for the repository's other workflows.- An upload refused for the rate limit backs off 5, 10, 20, then 30 minutes a try
(
RATE_BACKOFF, eight tries). The release's view and create go through the same backoff (ensure_release), because a refused view reads as "no release" and the create then fails. - Other workflows' GitHub calls go through
scripts/gh-retry.sh(gh_retry: 60 s doubling to 15 min,GH_RETRY_TRIES6).
grid-cells.yml is dispatch only and bakes four regions at a time. Inputs: regions, group
(or all-sub), all, and shard a or b. An empty selection bakes nothing, and skip_obf rows
are skipped. The merge job has no concurrency group.
ObfRouteEngine hands the router every installed file whose box intersects the trip's padded
box, so a trip over several cell files routes like one over the region file.
ObfCellsProbeTest (-DvelaCells=<dir with cells/ and whole/>) checks four Delaware trips
across cell edges: the distance is within 2% of the whole-region file's.
7.6.5 App side¶
offline/CellStore reads the manifest (BuildConfig.CELLS_MANIFEST_URL, override
-PcellsManifestUrl) and installs cells. A cell's parts go into the stores a region download
fills, under the cell's id: ObfStore.installFile, PoiPackStore.installFile (SQLite magic
check) and PmtilesRegionStore.installFile (PMTiles magic check). Routing, offline search and
the places layer (sourcesFor, 7.2) therefore read a cell with no cell-specific code.
cells/index.json lists the installed cells (id, region, name, box, rev, installed MB) so the
Downloaded group can show and delete them per region.
areaDownloadPlan fills AreaPlan.cells with the region's cells whose box intersects the
frame and are not installed, and cellsMb with their installedMb sum. Both are empty where
the whole region is installed or the region has no cells. The card shows a cells checkbox above
the whole-region one. The two exclude each other and cells are the default. Unticking cells
leaves both off: the whole region is ticked by hand.
downloadPickedArea(withCells = true) runs downloadCells: one cell at a time under the region
download card (routingDownloadingId = CELLS_DOWNLOAD_ID, name "mapvm_cells_incomplete). The zip streams through ZipInputStream. Each
entry is staged in cells/<id>.tmp/ and handed to its store. A part that fails to install is
dropped, and the cell is listed when at least one part landed, so it can always be deleted.
Progress is the zip's bytes.
When a region download completes with its pack and places archive, the region's installed
cells are deleted. Otherwise offline search answers from the cell pack and the region pack and
lists every place twice. The files must be on the phone (regionPlacesInstalled): the download
steps also report success when nothing is published for the region, when its pack is a large
shared one that does not ride along, and when a manifest cannot be read.
deleteCellRegion(regionId) removes every cell of the region from all three stores.
deleteRoutingGraph(id) and "Delete all offline data" remove cells too (7.1a).
refreshRegionUpdates compares every installed cell's rev with the manifest's (newerCells)
into MapUiState.cellUpdates. The Downloaded row says how many pieces have a newer version and
its Update pulls them again whole (updateCells). maybeAutoPatch does the same under the
update setting (7.3).
8. Transit¶
Google plus Transitous (MOTIS over GTFS and GTFS-Realtime, core/data/transit/Transitous.kt).
| Piece | Source |
|---|---|
| Departure boards | Transitous: every route at a stop, realtime lateness, agency colors. Google's place page, which embeds as little as one route at a hub, is the fallback. |
| Stop icons | Transitous positions from z15; OSM basemap icons without coverage. A tapped icon opens its board by stop id. |
| Route stop list | The run's own stops (/trip by the tapped run); the Google itinerary as fallback. |
| Directions | Google's page, for traffic-aware times; Transitous.plan when Google is off or answers nothing. |
Lines on the map¶
"Highlight transit lines" draws a plain highlight from the basemap's transportation layer
(class rail one color, class transit another) and above it each line's own color from
/api/experimental/map/routes (Transitous.linesInBox). The plain highlight hides for a kind
(metro, train) while colored lines of that kind are in view. Both hide while a non-transit route
is on screen (nonTransitRouteUp in MapSurface): orange and red lines read as traffic.
- The endpoint has no mode parameter and answers one polyline per pair of consecutive stops. The
phone drops buses, coaches and boats, cuts a shape at every gap over
CHORD_SPLIT_M(4 km; a subway bridge is one hop of 2 to 2.5 km) and thins what it keeps to 4 m. An unreadable reply is "no lines". - A run whose points average over
CHORD_MAX_M(700 m) apart is dropped as a chord when it is a train's, or a metro's whose routes all reportpathSourceNONE(no path, a straight line from stop to stop). Any other metro run is kept at any spacing: straight track between two stations is two points, and a dropped stretch is a hole, because the plain highlight is hidden for the whole kind. Five New York cells: the spacing test would drop 46 of 380 metro runs, 39 of 434 km, each 700 to 1,450 m long and 44 of them two points. - The request's
zoomis 8 (long-distance and regional rail) underTRANSIT_LINES_METRO_ZOOM(10.5), 12 from there. Nothing is asked underTRANSIT_LINES_MIN_ZOOM(8) or during a drive. On a constrained link nothing is asked either, and the cells kept on the phone are drawn. - Lines come per grid cell:
TRANSIT_LINE_CELL_METRO_DEG(0.05) at subway level,TRANSIT_LINE_CELL_RAIL_DEG(0.5) for rail only. A view padded by a quarter takes at mostTRANSIT_LINE_CELLS_PER_VIEW(24), nearest first, three at a time, each drawn as it lands;TRANSIT_LINE_CELLS_KEPT(96) stay in an LRU. A line returned by two cells draws once. Pixel 4a over Midtown Manhattan: a four-step zoom-out takes 19 cells in 4.5 s. - Every fetched cell is kept on the phone (
TransitLineCache,files/transit_lines/, one JSON file a cell, lines as encoded polylines at 6 decimals). A cell kept there is drawn before any request, so a view seen before has its colors at once and with no connection. It is fetched again when it is overFRESH_MS(7 days) old and stays on the map meanwhile. The folder holds at mostMAX_CELLS(300) files andMAX_BYTES(32 MB), oldest fetch first out. A subway level cell of Manhattan is 130 to 160 KB and reads in under 10 ms; fetching it is 2 to 4 MB of JSON. Pixel 4a, upper Manhattan: 6.5 s for a first look at four cells, 41 ms for six cells after a restart in airplane mode. The memory copy is the one the file gives back, so a stretch shared by a fetched cell and a kept one still draws once. - Lines sharing a stretch draw as side-by-side strands, one per color, at most 4.
- Metro stretches carry their lines' letters (
MapLine.labels: routeshortNameand color) from z13 onTRANSIT_LABELS_LAYER, below the business icons: "6X" folded into "6", numbers before letters, at most six. - A stretch gets one pill per line color, filled with it and rimmed in the map's land color
(
ensureTransitPill), in both themes. Letters sit two spaces apart in black or white by contrast (transitInk: WCAG ratio, white favored 1.6x). Several colors split the stretch equally, a pill at the middle of each part (lineSlice). - Settings (
TransitLayer): lines metro / trains, stop icons bus / metro / train, all on by default. A stop's kinds come from its Transitousmodes.
Stops and boards¶
- Boards refresh every 30 s while the sheet is open. Google-fallback boards are one-shot: a refresh there is a whole page load.
- A multi-bay center merges through its parent station.
Transitous.mergeDirectionalPairsfolds same-name stops withinPAIR_MERGE_M(160 m) to their midpoint with the other ids as siblings, because US GTFS names both curbs alike and has no direction field. The board merges stop times across siblings, fetched in parallel; its(route, headsign)rows keep the directions apart. Direction-suffixed names never merge.- "Same name" is
Transitous.stopKey: case, ordinals, "&" / "/" / "at", street-type and compass abbreviations and cross-street order do not count. - Before that pass, stops within
COLOCATED_M(3 m) fold whatever their names: one corner in several feeds, or a station complex's several parents. An all-caps merged name shows in title case (Transitous.displayName). Midtown Manhattan: 78 icons become 55. - A merged icon carries the modes of every stop in it.
- A stop's badge follows its modes (
stopKind): a train calls there, a rounded square with the railway glyph; else a subway, tram or light rail, a rounded square with the subway glyph; else the round bus badge. Station badges are 1.25 times the bus badge and place first (symbol-sort-key), so a station's name wins a crowded corner. - Where Transitous stops are drawn, the basemap's OSM bus icons hide by filter (rail and airport stay).
- A looping run boards at the tapped lap. Some agencies publish a day of laps as one trip (a
Davis Unitrans line: 589 stops, 6:55 AM to 9 PM).
Transitous.buildTripSteptreats every stop withinLAP_SAME_STOP_M(30 m) of the nearest as a pass, boards at the pass nearest the tapped departure time (the first without one), and shows one lap. TransitStopCache: each successful viewport fetch overwrites its area in a 24-area on-disk LRU, so visited areas keep their stops offline.TransitBoardCache: the newest 48 boards on disk, keyed by stop coordinate to about 10 m, with a 40 m near-match. Offline, a stop shows its last board and when it was seen (stopDeparturesCachedAt). A live board replaces it.- The board fetch is gated on category: multilingual gate words must match and exclusion words (fuel, EV, emergency, broadcast) must not, because "station" is in all of them. Both regexes are remotely overridable.
- A tap the basemap class marks as transit, with no Google stop listing, gets a Transitous board by proximity.
- A transit-named place that resolves to an "Intersection" re-resolves to the co-located stop:
search
<name> bus stop, thenbus stop, nearest live transit listing within 250 m (a real pair measured 89 m).
Directions¶
WebDirectionsFetcherloads Google'smaps/dirpage in a hidden WebView, in the app's language (the reviews page's rule). DialtransitAppLanguage0 returns every install to English.- Its
datais!4m2!4m1!3e3, or with n option entries!4m{n+3}!4m{n+2}!2m{n}!<entries>!3e3: the!4mwrappers are descendant counts. Entries in order: route preference!4e{v}(2 fewer transfers, 3 less walking, nothing for best), preferred vehicles!5e{k}, the time block. !8jin the time block is a local clock: Google reads the seconds as wall-clock-as-UTC, so the phone's zone offset is added.- The payload is taken up to 6,000,000 characters (a long intercity trip in Japanese passes 1.5 MB). A cut payload does not parse, and the open planner's trips show instead.
- Times are formatted from each tuple's epoch and zone, not the page's clock text.
- A line is its badge, or an agency icon filename when the badge has no text (subway bullets). A line icon is operator-scoped and contains a slash; the generic vehicle icon is bare.
- A badge is
["name", int, "#fill", "#text"]. Inside the line facet[5, badge]it can come with no fill, a line the agency gives no color; the trip summary writes some lines that way while their own leg gives a fill. A summary line with no color takes its ride leg's. - A line badge (
LinePill) keeps the agency's fill. When that fill is underBadgeContrast.MIN_RATIO(1.7, WCAG's contrast formula) against the sheet or an inset row of the theme (a white or pale yellow line on the light sheet, a navy or black one on the dark sheet), it gets a 1 dp outline in the theme's secondary text color at 70% (issue #888). - Mode comes from icon filenames only: mode words in nearby text also occur in place names.
- A ridden leg in Japan has no generic vehicle icon. Its operator icon's path decides:
shinkansena train,metroorsubwaya subway,jp2ltrorjp-jra train, any other a generic ride, never a walk. - In a trip summary an operator icon entry followed directly by a text entry is one line. The icon's file name is the line's name only when no text follows.
trip[13]is[seconds, "10 min", seconds]where the service has a headway; the card shows "Every 10 min".Transitous.plan(/api/v1/plan) asks for up to 5 itineraries, witharriveByfor arrive-by and last-available andtransitModesfrom the vehicle chips. Its reply parses into the same itinerary shape (walk and ride legs, lines with agency colors, board and alight stops with codes and realtime-vs-timetable times, headsigns), so the chooser, the map drawing and guidance are unchanged. Walk legs carry no distance text; their steps come from the walk router on demand.TransitOrder.byPreferenceapplies the route preference the planner lacks.- Durations Vela formats itself, the planner's included, use the platform's short units in every language but English ("6 h 16 min").
- In the chooser an expanded row frames its legs; with none expanded the camera frames the trip's own points (start, stops, destination). With the Google-style picker on, the transit tab keeps the classic body under the picker's header.
- The preview draws a ride along its real path where one is known, else straight lines through
its stops. Paths are looked up when a trip is expanded (at most five rides, never offline or on
a constrained link) and held in
ui/map/TransitShapes.Transitous.legShapetakes the open planner's leg geometry for a ride whose two ends are within 300 m of the stops, and sends nomaxTransfers: the public instance answers nothing withmaxTransfers=0. A bus without a path takes the road route through its stops when that is at most 1.8 times their straight-line chain. - Guidance in a pocket (issue #880):
startTransitNavstartsservice/TransitGuideService, a location foreground service that keeps the fixes and the voice going with the screen off, andMapViewModel.publishTransitNoticewrites its card intoTransitGuide.noticeat every leg change and fix (a state flow, so unchanged content is not re-posted). The card uses the drive's silent channel (NavigationService.ensureNavChannels), id 44, with End: a ride readstransit_nav_takeandtransit_nav_towardsovertransit_nav_get_offandtransit_notice_stops_left; a walk readstransit_nav_walkover the next ride's boarding stop or "To your destination".TransitProgress.stopsLeftcounts the stops after the one nearest the phone among boarding, intermediate and alighting stops (the leg'snumStopswith no position or list).TransitProgress.nextIsYoursis one stop left, or withinALERT_M(600 m) of the alighting stop when the leg lists fewer than three stops; it posts a heads-up on the turn channel (id 45, 30 s) once per leg and the voice says it once (transitAlertedLeg). Arrival removes the ongoing card and posts a dismissable one (id 46);TransitGuide.end(Done, End, closing the card) stops the service and clears it. Posting the arrival over the detached ongoing card lost the race on a 4a, hence the separate id. A refused start leaves guidance in the app as before.
9. Voice, dictation and language¶
9.1 Spoken guidance¶
Guidance text comes from per-language NavStrings tables in :core/i18n, switched by
NavStringsRegistry. Both routers feed them: RouteGeometry.osrmPhrase and
OfflinePhrases.phrase map maneuvers onto the OSRM (type, mod) pair.
Speech defaults to an in-process neural voice: the bundled sherpa-onnx runtime with a downloaded
Piper model (PiperSynth behind the :core NeuralSynth seam). About 40 catalog voices install
to filesDir/piper/<id>/; the installed set is derived from the filesystem, so a partial
download self-heals. The selection is voice_model, the speaker per voice voice_speaker_<id>.
- R8 must keep
com.k2fsa.sherpa.onnx.**: JNI resolves classes by original name. app/voice/PlaceDictionaryswaps theen_dictin an English voice'sespeak-ng-datafor the app's (assets/pronunciation/en_dict, 228 KB, version = the first 16 hex of its SHA-256) before the engine loads, once per voice and again when the asset changes. The voice's own file stays asen_dict.stock; the dialplaceDictionary0 restores it.- That dictionary is eSpeak NG's source (rhasspy/espeak-ng at the voices' commit; the engine is
1.52-dev in sherpa-onnx 1.13.3) plus
tools/pronunciation/places.tsv: 3,484 place names from the US, UK, Australia, Canada, Ireland and New Zealand with local pronunciations from English Wikipedia (CC BY-SA 4.0, credited in Settings > About), American-only and British-only readings split by eSpeak's?3/?!3flags.scripts/build-espeak-dict.sh <espeak-ng-data>rebuilds it and stops unless the source reproduces the stock file byte for byte. The location guard skips the list (scripts/check-location.shandlocation-guard.yml, kept in step). - A line renders phrase by phrase (
SpeechText.speechFragments) andPiperSynth.speakhands each phrase to thepiper-playthread as it is made (Pixel 4a, 52 characters, a medium voice: first audio at 0.29 s, all rendered at 0.70 s). Prepared lines (prepare) render whole. - Playing starts once the audio made outlasts the next phrase's render and the amount the rest
renders slower than it plays (
StreamStart.ready, from per-letter render time and audio length kept per voice, speaker and speed). A fast voice starts on its first phrase. A voice that renders slower than it speaks (a high-quality voice on a slow phone, or a raised speed) waits, instead of stopping mid-line for its next phrase. Pixel 4a, high-quality voice, normal speed, the 52-letter test line: first audio at about 2.0 s either way, mid-line silence 0 to 240 ms. - When the next phrase is not ready the player writes
STARVE_MS(60) of silence: an underrun makes AudioFlinger drop the track, which aborts the process. A line withSTARVE_NOTE_MS(300) or more of it adds a "voice: paused" note to the trip. Audio is written in about 200 ms pieces with a generation check between them, which bounds an interrupt. - Every line starts with
SpeechLeadIn.msof silence, in the neural player and on the phone's engine alike:MS(300), orBLUETOOTH_MS(700) when navigation speech is routed to a Bluetooth output (Android 13 and up:getAudioDevicesForAttributes; before that, any Bluetooth output connected). The track is paused between prompts so the output can stand by, and a sink waking from standby (a Bluetooth head unit above all) dropped the first syllables when the words were written the instant the stream started (issue #802); 300 ms still cut "Starting navigation" to "tarting navigation" on one reporter's output. - Pauses are spliced silence, 0.16 s at a comma and 0.32 s at a period, tuned at the default
0.8x and multiplied by 0.8 / speed (
gapFrames). The runtime's own silence scale is a no-op. - Every fragment gets terminal punctuation before synthesis, or the last consonant is swallowed.
- A Piper voice speaks one language. When
NeuralSynth.voiceLanguagediffers from the text's,VoiceGuideasksNeuralSynth.voiceFor(lang), which loads an installed voice of that language (VelaPiper.languageOverride, never persisted, cleared when guidance returns to the selection's language). Failing that, a system TTS in that language speaks. Failing that, it stays silent and fireslangUnavailable, whose card offers a one-tap download of the language's recommended voice (PiperCatalog.defaultFor,MapUiState.statusVoiceDownloadId). A selected voice of another language than the app's is never heard, so its row in the voice library says which language directions are spoken in and which one the voice needs (VoiceRow, issue 701). showStatuscards dismiss afterSTATUS_AUTO_MS(10 s) with a draining bar (InfoCard(autoMs)), frozen while focused. A card with a fix (statusVoiceAction) stays.flashStatuscards drain over their own duration.- A system TTS keeps the voice chosen in its own settings (
TextToSpeech.defaultVoice) when that voice speaks the directions' language, offline and installed (VoiceGuide.ownVoice). Otherwise it sets the language and takes the best-rated installed offline voice for it (selectBestVoice). Always taking the best-rated voice spoke with one the user had not picked, in engines with several voices a language. - A system TTS speaks with
USAGE_ASSISTANCE_NAVIGATION_GUIDANCEandCONTENT_TYPE_SPEECH(setAudioAttributesinonInit), as Vela's own voice and the focus request do. Unlabeled, its prompts played as music, and a car or a projection app that routes audio by usage mixed them into the music instead of ducking it. - Audio focus is refcounted through the utterance callbacks. A system TTS
speak()returningERRORfires no callback, so that path rolls back its acquire. A failedonInitclears the pending queue. - A fresh focus grant leads the first sample by
FOCUS_LEAD_MS(350 ms), the time a player that pauses on a duck takes to stop. Focus held from the previous prompt (FOCUS_HOLD_MS1500) speaks at once. - Text is fixed before the phonemizer.
SpeechText.spokenNumbersexpands three-digit street ordinals ("128th" as "one twenty eighth", space not hyphen).expandForSpeechrewrites<XX>-<n>refs to "State Route n" and puts a comma before " toward ".SpeechText.spokenClock(English) spells out clock times, which otherwise read as a measurement. A new spoken string with numbers, units or punctuation needs the same look, and a test. voice_volume(0.6 softer, 1 normal, 1.6 louder, 2.2 loudest) scales the neural voice from a leveled base (VoiceLevel). The voices render well under full scale: the default Vela voice (Piperen_US-hfc_female-medium) has a long-run RMS of about 0.053 on a Pixel 4a, a gain of 2.43 at Normal. Each line gets one gain,TARGET_RMS(0.13) over the voice's long-run RMS, between 1 andMAX_LIFT(4), times the setting. The RMS is summed over every speech chunk the voice and speaker have rendered (VoiceLevel.Meter; a chunk peaking underMIN_PEAK, 0.02, is a pause and is left out) and kept in thevela_voice_levelpreferences, so the level is the same from the first line of a session. It is not set from the loudest sample: that rose from 0.23 to 0.42 over the first minute of a drive and took the gain from 3.8 to 2.0. Samples pastKNEE(0.8) are bent toward full scale by a tanh curve, so nothing clips flat. The system TTS path takesKEY_PARAM_VOLUMEcapped at 1.0: Android can only attenuate.-
A voice install or a delete-fallback never speaks. Only an explicit library pick auditions.
-
The voice prepares the lines
NavEngine.upcomingPromptspredicts for the current and next spoken turn (the approach bands above and turn-now), up toMAX_PREPARED(8), at background priority. - A line asked to be spoken drops every prepare still queued and ends the one being rendered at
its next phrase. A phrase is one engine call and cannot be cut, so the line waits for the
phrase in hand, and the worker renders that phrase at the waiting line's priority
(
PiperSynth.boostBackground): the default for an imminent turn, the speaking priority otherwise. A voice load started by a warm-up or a prepare is raised the same way. A prepared line that was on its last phrase is kept.
9.2 Foreign scripts¶
A road name can be in a different script than the guidance language.
SpokenScript.forVoice(text, voiceLang, dict)substitutes a real Latin name from the dictionary first, then falls back to ICU transliteration. Each voice keeps its own script. CJK is never romanized, because ICU reads Han as pinyin.SpokenScript.forDisplaydoes the same for the banner and step list with no ICU fallback: a vowel-less skeleton reads as broken, so an unmapped name keeps its local script.- The dictionary is the basemap's
name:enandname:latinper road, collected by the pass that places the crossing labels, plusRoute.roadNamesLatinfrom the obf route. - The dictionary query re-runs every 2 s until three passes in a row add nothing, because a drive starts with low-zoom tiles that carry major roads only. It is a synchronous render-thread round trip that materializes every loaded road name on the main thread (Pixel 4a at the nav zoom: 100 to 430 features, 14 to 58 ms). When a full pass adds nothing and the dictionary is still empty, the region's names are all Latin and the warm-up settles at once.
- The navigation opener is held up to
OPENER_MAX_WAIT_MS(2.5 s), retrying every 200 ms, until the dictionary covers its road. An opener with no non-Latin letter never waits. - Road labels use
roadLabelTextField(), by Settings > Map > Names on the map (MapNames, prefmap_names, issue #738): for a Latin-script UIcoalesce(name:en, name:latin, name)(english_latin, the default),coalesce(name:en, name)(english_local, what Google shows),name(local), or the local name followed by the English one where OpenStreetMap has a different one (local_english: on one line for a road and for Liberty's line-placed water labels (LINE_PLACED_LABEL_LAYERS), since a label along a line cannot break, and on two lines with the English a step smaller for a point label, by aformatexpression); the localnamefor any other UI, in every mode. The basemap'sname:latinis OpenMapTiles' machine romanization where OpenStreetMap has no English name: readable for Cyrillic or Greek, a vowel-less skeleton for Hebrew. The mode ridesstyleKey, so a change reloads the style. Nav bubbles filter on the canonicalnameand display the chosen form. - Place, POI and water labels (
PLACE_LABEL_LAYERS) take the UI language'sname:<lang>first (placeLabelTextField()), then the same fallback chain as the roads;localisnamealone. Place names are data and are never transliterated by Vela. SpokenScript.applyDictreturns in O(length) when the text has no character the reader cannot read, and digests each dictionary once per instance. A full scan twice per fix was a 60 ms main-thread stall at 1 Hz.
9.3 Dictation¶
Two tiers, both keyless.
- Tier 1, in process:
AsrRecognizerover the same sherpa-onnx runtime, with three downloadable engines (AsrEngine): Whisper tiny int8 multilingual (58 MB, the default for English), Whisper base and small (91 and 222 MB, the same 99 languages, base the default for any other app language,AsrEngine.defaultFor, since tiny is too weak outside English), SenseVoice (154 MB; en, zh, ja, ko, yue) and Moonshine (101 MB, English). Each archive carries its own Silero VAD. Recognizers cache on"<engineId>|<lang>". Whisper is pinned to the app language: auto-detect transcribes noisy far-field audio into the wrong script. Recording takesAUDIOFOCUS_GAIN_TRANSIENT, so media pauses instead of ducking. - Tier 2, handoff:
ACTION_RECOGNIZE_SPEECHto an installed voice-input app, which records, so Vela needs no microphone permission for it. Only apps that register the activity count; an IME or aRecognitionServicecannot be launched this way. The component is the user's pinned one, then Android's default, then the first installed app, so the system chooser never interrupts.
RECORD_AUDIO is requested at the point of use. listen() returns a typed result (Text,
NoSpeech, Failed(reason)) and the UI explains every failure.
The model load is crash-sentineled: a truncated or corrupt archive makes sherpa-onnx abort natively, which cannot be caught, and warm-up runs at startup, so a bad model would crash every launch. A strike counter is raised before every native load and cleared after. Two stranded loads quarantine that engine and delete only its directory. One is forgiven, because a process killed mid-load strands the counter too.
9.4 Interface language¶
The picker has 19 languages (AppLocale.SUPPORTED). Estonian (et) has a partial translation
from Weblate and English spoken guidance. Romanian (ro) has a partial translation, its own
spoken guidance (RoNavStrings) and the Mihai Piper voice.
AppLocale holds the language (empty means follow the system) and is applied in both
MainActivity.attachBaseContext and VelaApp.attachBaseContext. When following the system it
also restores Locale.setDefault to the captured device locale: the override is process-global
and otherwise leaves date formatting and the scrape's hl in the previous language. Changing
the language calls recreate().
The directions language (AppLocale.directions, key directions_language) is empty by default,
which means the same as the app. Set, it replaces the app language for NavStringsRegistry, so
turn text on the banner and in speech, the voice's target language, the Voice library's
suggested voice and the Vela voice id follow it. Menus, transit walk lines from strings.xml
and the scrape keep the app language. Changing it needs no recreate(). A route already
planned keeps the instructions it was built with.
- Strings live in
res/values/strings.xml(US English) plus one folder per translated language.values-en-rGBcarries only the strings whose British wording differs. - Counts use
<plurals>with each language's CLDR categories. - A string that doubles as a logic key is not in
strings.xml. Where a display label and a logic key must both exist they are split, and the key stays English. - The scrape's
hlfollows the app language only where a status keyword table exists (SearchParser.STATUS_LANGS). Any other locale stayshl=en, because an unreadable status string leaves open/closed null.glfollows the phone's region. - Hyphenated language codes resolve through
Locale.forLanguageTag.Locale(String)makes a bogus lowercase language that matches nothing. - Names, streets and reviews are data and are never translated.
-
The repository is US English. The exceptions are
values-en-rGBand data strings that match a foreign source's spelling (OSM'sneighbourhoodplace class, OSM tag values such asfitness_centre, the MOTIS wire fieldcancelled), marked where they appear. -
Clock: Settings > Appearance > Clock (
clock_mode) is the device's 12/24-hour setting, or either for Vela alone.Clock24.onandClockFormat.use24hcarry it; the transit Depart at time picker dials by it too (it was a fixed 12-hour dial, issues #357 and #762). Transit directions times come from the payload's epoch and time zone (ClockFormat.at);ClockFormat.showconverts the text of the one page still fetched in English, Google's stop-board fallback.
9.5 Query intents¶
Every submitted query, typed or dictated, goes through core/search/QueryIntents.parse(text,
lang) first: Home, Work, NavigateTo, Route(from, to), Search with filler stripped, or Eta. Null
means a plain search, so the parser cannot make a query worse. Word tables cover every app
language but Estonian, with English as a fallback in each.
- A bare verb counts only before home or work or an explicit "from A to B".
- The Home and Work chips (
openShortcut) open the same bare place the typed intent does:Place(id, name = the chip's label, location, address)throughselectPlace, so a stop, origin or destination picked from the chip is named "Home" or "Work".selectSavedis not used for them: it enriches by searching the address and dressed Home as the business there. - A bare "X to Y" is a route only when X is not a question word or a verb.
routeBetweenruns the whole phrase as a search first, so a place whose name contains "to" stays a place.
A fuzzy pass runs after the exact passes miss, in spaced languages only. Tolerance is per word and only over the vocabulary, never the free text. Accents fold. One edit is allowed from four letters in a leading or trailing phrase and from five in a whole-phrase match, two from eight. A single-word phrase never fuzzes, and a multi-word phrase must match word for word, so "home depot" cannot collapse to "home".
10. User interface¶
10.1 Sheet physics¶
The place sheet, the results sheet and both route pickers share one drag grammar. A new sheet reuses it.
- The sheet is a hand-driven
Animatable(the height for the sheets, the body height for the pickers), dragged 1:1 from the handle and, through a nested-scroll connection, from content scrolled to its top. - Every drag goes through
sheetDragGestures(ui/place/PlaceSheet.kt). It tracks velocity on integrated drag deltas, becausechange.positionis local to a node that moves as the sheet resizes and reads as zero. The release velocity is the larger of the tracked value and travel over time. - Release projects the fling with
exponentialDecay(frictionMultiplier = 1.6f)and takes the detent nearest the projected end. A release faster thanFLING_COMMIT_DPS(180 dp/s) moves at least one detent in its direction. - When the coast reaches the detent, the sheet rides
animateDecaywith theAnimatablebounds clamped there, so the detent stops the coast. Otherwise it settles on a spring. The Google-style picker always settles on the spring. - The animated value is read in a layout or
graphicsLayerblock, never in composition, so a frame re-measures the sheet without recomposing it. - A scrollable region with zero scroll range never starts a drag. A minimized card whose content fits has its own drag surface.
SheetFoldfolds a section with the sheet's own height fraction. Its fade usesCompositingStrategy.ModulateAlpha: a plain alpha below 1 renders offscreen, which cost 20 ms of GPU per frame on a Pixel 4a (frame p50 32.1 ms against 16.7 ms).- A map pan minimizes the sheets.
onUserPanfires for a gesture camera move only, never a programmatic one, and not in picture-in-picture. - A sheet that takes a tick (
minimizeTick) remembers the value it mounted with. ALaunchedEffectalso runs on first composition, and a remounted sheet would replay a stale tick.
10.2 Chrome¶
Layout rules¶
- Nothing above the place sheet's action pills moves after the first frame. The photo strip and
the rating row reserve their space while
detailsLoadingis true and the place has a non-blankcategory. The test is on the category because a place tapped on the open places layer has no Google id until details land. - The place sheet's tab row is always a
ScrollableTabRow, so each tab is as wide as its label. A fixed row clips long labels at large font sizes. - Chrome hides on the sheet's measured top edge (
SheetEdge), not on the expanded flag. A short place flips the flag while its wrap-capped card never grows. - Top-of-map cards (status, downloads, the update card, notices, the faster-route offer) stack in
one top-center column, each with its own dismiss. During a drive the column hangs off the turn
card's measured bottom edge (
navBannerBottomPx). - In landscape, route and drive chrome is a left column. Both sheets, the route pickers, the
endpoints card, the turn card and the nav bar take a start alignment plus
landscapeColumn(...), which caps the width atsidePanelWidth()and pads the display cutout on the start edge. The camera takescameraLeftInsetin place of a bottom inset. New route or drive chrome without this spans the screen. sidePanelWidth()is 0.56 of the screen width, betweenSIDE_PANEL_WIDTH_MIN(400 dp) andSIDE_PANEL_WIDTH_MAX(600 dp).- Picture-in-picture: everything after the map call is inside one
if (!pipUi)gate. The map's compass and all gestures are off in PiP, because the system's taps on the window reach the map as gestures and detach the follow camera. -
MapScreentakes no new call or parameter. It is at the JVM method-size limit ("Method too large" in the debug compile) and at ART's verifier limit, which fails on the phone. New floating pieces go inMapFloaters(the replay controls, the Street View preview, driving mode's chrome),NavCorner(the speed box and Re-center) orLayersCorner(the layers button and its panel), each of which decides for itself when to draw. -
UI font: Settings > Appearance > Font offers Google Sans Flex (the default; SIL OFL 1.1, in
res/font, license inassets/licenses), the system font (prefui_font_system), or a user file (filesDir/fonts/ui.ttf), throughvelaTypography(family). Scripts Flex lacks fall through to the system font.
Browse map¶
- Landscape browse chrome is one line. The condition (
landscapeOneLine) does not include!searchOpen: focusing the bar flipssearchOpen, and moving the bar to another subtree would remount and blur it, which flipssearchOpenback. - The search page's full-size background (
SheetPalette.bg) is drawn whilesearchOpen, except underSearchGates.pickingResults: a search submitted while picking a stop or an endpoint shows its results sheet over the map, and the background drawn there read as a black map under the results (issue 737). - In landscape the place card may fill the height, the search bar hides while the place panel or the results list is up, and "Search this area" centers in the map beside the panel.
- The locate, parking and layers buttons share
mapButtonColor,mapButtonInkandmapButtonRing: a gray circle (#3C4043) with a white glyph and a faint ring in the dark themes, white with a gray ring in light,primaryContainerand no ring under wallpaper colors. The locate glyph is blue. A saved parking spot tints the glyph, not the button. Their centers all sit 44 dp from the screen's end (a 56 dp button at 16 dp; the 42 dp layers button at 23 dp, the 48 dp parking button at 20 dp, the compass at 44 dp less half the stock image), so the four line up when they stack in landscape. The compass view is 48 dp whatever image it shows, so the drive compass, whose 56 dp image is scaled into it, sits at 20 dp under the drive's column, on the same line. - The layers button (
LayersCorner,ui/map/LayersPanel.kt) opens aVelaMenuof picture tiles, four to a row, with a label under each. Three groups: Map type has the five looks (MapStyle, the same pick as Settings > Appearance > Map look) and Satellite; Map details has traffic, transit lines, terrain and 3D buildings; Place icons has Vela data, Google and Both (MapPoiPrefs.placesSource). The "Use Vela without Google" switch stays a row under them. Every tile flips the holder Settings flips (MapLook,SatelliteLayer,Traffic,TransitLayer,Topography,Buildings3d,GoogleFree). The chosen or on tile has a 2.5 dpprimaryring on its picture and aprimarylabel. Map type is one choice: picking a look while satellite is on turns satellite off, and the satellite tile toggles. A look's picture is drawn in Compose from that look's own land, water, park, building and road colors (the Vela look's follow the map theme: light, dark or AMOLED); satellite is a drawn green and gray patch; a detail tile is the app's glyph for it on a disc that fillsprimarywhile on. The button takesprimarywhile satellite, traffic, transit or terrain is on. The gate that shows the button stays inMapScreen. VelaProgressBar(ui/VelaProgress.kt) is the only progress bar: rounded ends, null progress means indeterminate.VelaProgressBarOftakes the value as a lambda, so an animating bar is read in the draw phase.- The replay controls have a grab bar and drag up and down the screen.
CategoryChipsPref (Settings > Map): the chip row, one "Categories" chip that opens them in a
VelaMenu, or none. Decided inside CategoryChips. The row shows QuickCategories.all() in
the user's order and ends with a More chip (MoreCategoriesChip), a VelaMenu of every chip in
the catalog, the ones switched off included; a pick runs that search. The one-button menu lists
all() only.
Drive chrome¶
- The nav bar is flush with the screen's bottom edge, top corners rounded.
navBarLook()sets its colors: white with dark inks in the light theme,NavBarColor(#101214) with light inks in the dark themes, the theme'ssurfaceContainerHighwith its own inks under wallpaper colors. The step sheet it opens into follows throughLocalStepsOnDark. - The bar holds End, the trip figures and a right slot. End and Pause are 60 dp ringed
NavBarButtons.FitDurationsets the time's digits semibold and its units regular and shrinks to fit, with distance and arrival beneath. The handle is a flat grab bar that also opens the step list on a tap. - The floating buttons (
NavFab: overview, mute, search) andNavRecenterPillwear the bar's colors, orprimaryContainerwhenwallpaperColorsInUse()is true. That requires the Material You setting on and a phone scheme that passed the sanity check. Where the scheme fell back to Vela's own, a wallpaper-colored button would come out teal. - Pause sits in the bar's right slot when
PauseInBaris on (prefnav_pause_in_bar, default on) and the device is not keypad-first. The right-edge stack then has the speaker button (NavVoiceButton): the glyph is the voice mode, and a tap slides the three choices out beside it for 6 s, the current one filled. - The step-list button takes the slot when
PreferButtonsis on (prefprefer_buttons, default off) or the device is keypad-first. With both wanted the bar carries both and the figures shrink. With neither, the slot is a 54 dp spacer that keeps the figures centered against End. - With pause out of the bar, the stack has
NavHoldControls: one 56 dp button for pause and mute. On a running drive the first tap slides the three voice choices out beside it forOPEN_MS(6 s), on, alerts only and off with the current one filled, and a second tap pauses. While paused, one tap resumes. A long press steps the voice (on, alerts only, off). The slide-out is the key path to the voice. The glyph shows pause or resume, the accent fill a held drive, a crossed speaker a muted one, a bell "Alerts only" (4.9). - The "Then" tab hangs off the turn card's lower left in the card's color and names the next step. The card's lower-left corner is square while the tab shows, and the lower-right too when the tab is as wide as the card. Both widths are measured.
- In portrait the turn card and its "Then" tab stay within
BANNER_MAX_FRACTION(a third) of the screen height. Past it the card's font scale steps down, byBANNER_FIT_STEP(0.9) or down toBANNER_FIT_MIN_STEP(0.7) for a card far over, never below the default text size, and tries one step back up at each new maneuver, never within one, so it cannot flip between two sizes. The distance is one line that shrinks to fit beside the road's shield (FitText, started over when its length changes, not on every tick). The instruction stops atBANNER_HEADLINE_LINES(3) lines. - Route shields (
RouteShield) grow with the font scale up toSHIELD_MAX_SCALE(1.6), badge and number together, so a number fits its badge at any text size. A fixed badge with font-scaled digits cut "113" to "11" at 2.0. - Away from the car (panned, pinched, previewing a step),
NavRecenterPilltakes the speed box's place and the road name hides. - The road name (
RoadLabel, prefroad_label) defaults toPUCK: a pill under the arrow, clamped to the window, and kept right of the speed readout (speedBoxRightPxplus 8 dp) whenever its top is above the readout's bottom: with large text the readout is wide and the arrow low enough that a long name slid behind it. The other values areBAR(centered above the bar),IN_BAR(the bar's handle row) andOFF. - What it says is
core/nav/roadLabelAt, on the phone and in the car.roadLabel(name, ref, heading)picks the road's own name when it has one, and its number on an Interstate, on a named freeway (isFreewayName: the name ends in Freeway or Motorway, or starts with Autoroute, Autostrada, Autopista, Autovia or Autobahn), or where the name only says the number again ("State Route 9"). An expressway, a parkway or a turnpike keeps its name. The number stays on the turn card as the current road's chip. With Road numbers first (RoadNumbers, issue #836) the number wherever there is one. - The road a direction names ("Turn right onto X") is
instructionRoad(name, ref): the name, the number where there is no name, and the number wherever there is one with Road numbers first.RouteGeometry,LineNamerandObfRouteEnginecall it as they phrase a step, so the switch reaches the directions from the next route on and the pill at once. - A number is followed by a compass letter when a guide sign gave one: "I 80 E".
signedHeadingreads it from the text of the step that entered the road ("toward I 80 East: Sacramento"), else from the steps before it that are unnamed or already on that route, up toSIGN_LOOKBACK(8) steps. The word before the number must be a route prefix. A router that sends "I 80 East" as the number or the name is read the same way, as is a name that restates the number with a direction. A sign that names both directions ("I 5 North, I 5 South") is settled by the leg's bearing, which must be withinHEADING_PICK_DEG(60) of one of them. No letter shows after a plain turn onto a numbered road, or when the leg runs more thanHEADING_MAX_OFF_DEG(135) from the one signed direction. Bearings are only read on a leg ofHEADING_CHECK_MIN_M(300 m) or more. The letter is never taken from the bearing alone: a route signed east can run north. A name never gets a letter. - "Searching for GPS" sits above the arrow, with bottom center as the fallback before a puck position exists.
- Landscape: the turn card and the bar sit in the left column,
NAV_LAND_EDGE_DP(8 dp) from the safe edge. The speed box and the Re-center pill sit just right of the bar's measured right edge (navBarRightPx). The step list's height floor is 64 dp (200 dp in portrait), so it stops under the banner. - The route bar (
RouteBarStrip) draws in portrait only and never in PiP. It shows the nextRouteBar.WINDOW_M(5,000 m): scaled to a long trip, nearby marks collapse into one pixel. Congestion is painted on the track by level; a light and a stop sign are the map's own bitmaps (trafficLightBitmap,stopSignBitmap) on the track,MINI(16 dp) tall; cameras, crossings and humps areBADGE(26 dp) discs beside it with their glyphs (issue #828). - Search along the route is a page (
NavSearchChips): the whole screen in portrait, the left column over a dimmed map in landscape, where a tap on the dimmed part closes it. It has a search field,QuickCategories.forDrive()as tiles three to a row with fuel and charging first, and the six most recent searches. It is drawn last inMapScreen. -
The drive buttons and the speed box use
Modifier.popIn()(a short scale and fade) when they return after the step list closes. -
Road-name pill: its width is the room between the speed readout's right edge (
speedBoxRightPx) plus 8 dp and the FAB column, at least 96 dp. Every name is shortened byRoadNameShort("W Covell Blvd"), and the text shrinks to 80 percent before it is ellipsized. The turn card and its "then" line shorten the road inside their text the same way (RoadNameShort.inText, the maneuver'sroad), and so does the car's step and its "Continue on" (issue #837). The voice keeps the full words: it speaksmaneuverText, not the card.
Route picker¶
RoutePicker.googleStyle(prefroute_picker_google, Settings > Navigation) is on by default. A choice made under the old keyexp_google_choosercarries over. The calibration fieldclassicRoutePickersets the default for anyone who never touched the switch.- On:
GoogleStyleDirectionsPanel(ui/place/GoogleChooser.kt). The mode is the title, the mode tabs carry each mode's time, one summary shows the selected route with the alternates behind an "other routes" line and as time bubbles on the map, and a bottom bar has Start and Add stops (Share is the header's round button alone, issue #814). It has three states: minimized, summary and list. Tapping a step in the list drops the picker to the summary, so the map shows the step, andstartNavclears the previewed step. - Off: the classic
DirectionsPanel, which lists every route. Transit always uses it. - Swap (
swapDirections) flipsdirectionsReversed: the place becomes the start anddirectionsOrigin(or your position) the end, so on a swapped trip the End row edits the origin. "Choose on map" keeps the end as shown inpickOnMap(shownPick), so the banner and its button name the end that was tapped, andapplyMapPickflips it back to the end to set (issue #839). A long press in the pick does the same. - In drive mode both pickers show one "Avoid" label and four chips: Tolls, Highways, Ferries,
Cameras. Cameras is the
FlockRouteAlertswitch and refetches throughRouteActions.camerasChanged. - The endpoints card (
RouteTopCard) menu has "Add to home screen". Its dialog takes a name (24 characters), a glyph (PoiIcons.SHORTCUT_ICON_KEYS) and a themed look that copies the launcher's themed icons (preftrip_shortcut_themed), then pins the trip throughTripShortcut.pin(5.7).
Spoken street names¶
Settings > Voice "Say street names" (ui/SpokenRoadNames, pref spoken_road_names, default on)
is mirrored into the :core flag nav/SpokenRoadNames, which NavEngine reads. Off, the voice
announces the turn without the street. The banner, the step list and the road pill keep the name.
Maneuver.instructionNoRoadis built by the same per-language template asinstructionwith the road left out, so the word order stays right. The OSRM, Valhalla, obf andLineNamerbuilders fill it. It is null for Google's abbreviated steps, where speech keeps the full instruction.- Every spoken site reads
Maneuver.spokenInstruction(): the calls inNavEngine, plus the nav opener and the faster-route line inNavSession. Those two keep the named form for their banner and card. - Code that rewrites an instruction after the router built it rewrites both forms, or the switch
undoes the rewrite.
consolidateExitsdoes. The traffic-light cue is added at speak time to whichever form is spoken (NavEngine.lightLead).SpokenRoadNamesTestpins both.
Live update notification¶
On API 36 and above the nav notification asks to be promoted to a live update
(promoteToLiveUpdate in service/NavigationService.kt), which puts the drive in the status
bar chip and on the lock screen.
- It is a
ProgressStylescaled to the route's length in meters. The tracker is the nav puck, the maneuver glyph is the large icon, the segments are the route's traffic spans, each remaining stop is a point, and the chip's critical text is the distance to the next turn. - Below API 36, with no route, or if anything throws, the notification is unchanged.
- The system raises the chip only while the app holds
android.permission.POST_PROMOTED_NOTIFICATIONS, which the user can turn off in the app's notification settings. Without it the notification still posts in the shade. - The channel
vela_nav_drivehas DEFAULT importance with no sound and no vibration. A LOW channel is filed as silent, and a phone that hides silent notifications on the lock screen would hide the drive there. A channel's importance is fixed once it exists, so the old LOW channel is deleted on first run.
10.3 D-pad operation¶
The whole UI works with a five-key D-pad and no touchscreen.
- Every interactive element is a focus target with a visible ring in key-driven input
(
Modifier.dpadHighlight), and every gesture has a key path. - Every screen opens with something focused (
rememberDpadAutoFocus), because Compose's own focus recovery is nondeterministic. Two exceptions: the bare map opens unfocused, and when Settings is the first thing in a session to take focus the first key press lands on Back. - A Compose
DropdownMenupopup and anAlertDialogcannot be pre-focused.VelaMenurenders a rawDialogwith its first item focused on a D-pad-first device and the ordinaryDropdownMenuunder touch, capped at 70% of the screen height so a long one scrolls instead of running under the navigation bar.VelaDialogis a rawDialogthat focuses the dismiss button. Their items take focus through.focusable()plus.onKeyEventpluspointerInput, because the nested focusable inside.clickabledoes not acceptrequestFocusin a dialog window. Modifier.dpadFieldEscapemakes up and down leave a text field.- D-pad code calls the touch paths (the same tap lambda, gesture flags and zoom override), and
every D-pad affordance is gated on
dpadModeornoTouch, so touch behavior does not change. - A device is D-pad-first (
rememberDpadFirstDevice) only with no touchscreen or with a physical, non-virtualSOURCE_DPADdevice. The framework's virtual input device reportsKEYBOARD | DPADon nearly every phone, and counting it breaks the search bar. A keypad phone with a fake touchscreen gets D-pad behavior on its first key press throughrememberDpadMode. AdaptiveDensity.wrap, chained first in bothattachBaseContexts, shrinks the density so a narrow screen reportsMIN_WIDTH_DP(360 dp) of width. At 360 dp and above it does nothing.adb shell input textandkeyeventflip the live input mode to Keyboard, which disables the unarmed search field. That is the test tool's effect.- Zoom keys (
ui/ZoomKeys, prefszoom_key_inandzoom_key_out, 0 for none): two key codes set in Settings > Navigation by pressing the key.MainActivity.dispatchKeyEventzooms one level on the key's first down while the map is showing. A printing key is offered aftersuper, so a text field keeps it. A non-printing key is offered before. The arrows, OK, Enter, Back, Home, Menu and Power cannot be assigned.
Per-surface audits and the contributor procedure are in docs/dpad.md. The regression suite is
dpad_test_suite/ (run_all.sh, audit_static.sh, audit_dynamic.sh). CI runs
audit_static.sh, which reads the source and needs no device.
10.4 Settings¶
Settings is hub and spoke. SettingsScreen hosts a Navigation Compose NavHost with the map and
one destination per SettingsSection. SettingsHub holds the category rows and the search.
SettingsScaffold holds the focus plumbing every page builds on.
- The map is
MAP_ROUTE(main/map), a transparent destination over the composed map, so the camera and the sharedMapViewModelsurvive. Each page issettings/<section>in locale-independent lowercase. Navigation matches routes case-insensitively, so the map and Map settings have distinct paths. - Back from a spoke returns to the hub, then the map. Opening Voice from Offline replaces the spoke. The voice-library shortcut puts the hub under Voice. The host is composed after the map, so its back handling wins while Settings is open.
QUICK_CHIPS(Settings > Search > Quick search buttons) is the one page under another: it is pushed on top of Search with nopopUpTo, has no hub row, and Back returns to Search. Each row is a chip inQuickCategories.arranged()with a switch (QuickChipsPref.setShown) and aReorderHandle(QuickCategories.move, one row per row height dragged; focused, Up and Down move it and OK flips the switch). Rows are keyed on the chip so a moved row keeps focus. "Reset to default" clears both keys and is dimmed while nothing is customized.- The search is a static
SEARCH_INDEXof label resource to section. A match opens the spoke and scrolls to the row (Modifier.settingsAnchor(label)plusLocalSettingsHighlight). A new row label goes in the index. A group whose rows can be empty still renders, with an empty-state hint, or its index entry leads to nothing. - A page requests keypad focus only once its entry is RESUMED (
LocalSettingsPageActive), so a page sliding in does not take focus from the one being left. - Settings > Places leads with "Place icons on the map" (
MapPoiPrefs.placesSource, 5.1), then what the map draws for places, then the place-page toggles (10.8). - No blocking IPC or IO runs in a composable body. A
PackageManagerquery in composition re-runs on every recomposition. Load such data withproduceStatepluswithContext(IO).
Page transitions and predictive back¶
PageTransitions(prefpage_transitionsinvela_settings, default on, Settings > Appearance) switches off every animation in this list. Back still works, and dragging and detent settling are unaffected.- Settings pages slide in over 250 ms while the outgoing page moves a quarter width. Back reverses it, mirrored for RTL. Navigation Compose owns predictive back progress, completion and cancellation.
BottomOverlay.ofmapsMapUiStateto one stable key:ARRIVAL,NAV_STOPS,STEPS,NAV_STOP_OFFER,NAV_CONTROLS,TRIP_EDITOR,DIRECTIONS,CLASSIC_DIRECTIONS,PLACE,SHAPES,RESULTSorNONE.SheetTransitionkeeps the outgoingMapUiStatesnapshot (BottomOverlayFrame) until its exit ends. Content slides up over 250 ms and down over 200 ms, by its measured height. A detail fetch or a place change under the same key does not replay the entrance.STEPS,SHAPESandNONEdo not slide, andSTEPSto or fromNAV_CONTROLSis not animated here. The nav bar and the step list share one height animation inStepsSheet, whose back handler finishes the close animation before clearing the state.- Transit guidance and the transit route-detail sheet use
SheetTransitiontoo. The guidance pane's last card, "You have arrived", carries Done in place of Next and ends the guidance (issue #811). Which itineraries are expanded in the directions panel is held inTransitExpanded, keyed by the itinerary, so an expanded route survives the panel dropping to its card (issue #812); a new set of results prunes the keys. - Outgoing content ignores pointer input, is hidden from accessibility, and reads
LocalSheetActiveas false, which disables its own back handlers. - Predictive back translates the current sheet by its measured height times the gesture progress. Completion settles to the bottom over 160 ms, runs the close action and skips the ordinary exit. Cancellation returns over 180 ms and changes no selection, route or guidance state. Gesture state belongs to the content key, so a reopened sheet starts at zero.
- Area picking, pick-on-map, transit guidance, open search, the open alternatives list and a
minimized route picker keep their own back priority, as do the place sheet and the step list
during a drive. A minimized route picker restores itself on Back (
RoutePanelBack) and the route closes on the next. Back during a drive always asks before ending it.NavEndConfirmdecides only whether the End button asks. NavigationChromeTransitionkeeps the outgoing top chrome when browsing and navigation swap. The search bar and the turn banner fade and slide over 220 ms on entry and 160 ms on exit. The map, the camera controller and the guidance session stay live.- The manifest sets
enableOnBackInvokedCallback. Android 13 and 14 need the system developer option to show predictive back. - Sheet cards have 4 dp shadow elevation, the nav bar and the driving step sheet 6 dp. Close and
share actions on the pickers and the step list are
HeaderCircleButton: a 36 dp circle with an 18 dp icon.
10.5 Full-screen viewers¶
The photo gallery and the full reviews page render in the activity's own edge-to-edge window. A
Compose Dialog window re-asserts inset-fitted params, so it cannot cover the system bars, and
it keeps stale bounds after a rotation. A call site posts a request to GalleryOverlay or
FullReviewsOverlay (ui/place/PlaceSheet.kt), and PlaceOverlays(), the last child of
VelaRoot's root box, draws it above the map, the sheets and Settings. The gallery is drawn
after the reviews page, so a review photo opens on top of it. The gallery sets white status bar
icons while it is up and draws a top gradient under the status bar.
10.6 Android Auto¶
app/car/ is a navigation-category CarAppService (VelaCarAppService): the manifest service
with the NAVIGATION and FEATURE_CLUSTER categories, automotive_app_desc.xml with
<uses name="template"/>, the androidx.car.app.* permissions and minCarApiLevel=1. It uses
the same :core singletons as the phone (CarDeps).
- The host validator is
ALLOW_ALL_HOSTS_VALIDATOR. The gate is on the phone: on connect the Android Auto app asks the Play Store for the app's owners and denies a package Play never installed (CAR.VALIDATOR: Package DENIED). The "Unknown sources" developer setting and the install fields do not change that. On a stock Pixel an install routed through Google's own package installer passes. The desktop head unit skips the check. - A car with an instrument cluster opens a second session (
DISPLAY_TYPE_CLUSTER). It getsClusterSession, one bareNavigationTemplate, because that display rejects the place-list template. Its content comes fromupdateTrip(). VelaCarSessionruns its own AOSP location feed into the sharedNavSession(GPS fixes at 50 m accuracy or better, or the simulated position), so navigation runs with the phone UI closed. It handlesandroidx.car.app.action.NAVIGATEgeo intents: coordinates open the route preview, and a free-textq=opensSearchCarScreenon that query, submitted, over the landing list. A drive started from the car speaks with the Piper voice when it is installed and chosen (the service attaches the synth).VelaCarSessionis the one place that pushesActiveNavCarScreen: it watchesNavSession.stateand, when a drive starts on the car or on the phone, pops to the landing screen and pushes the drive screen.onCreateScreenreturns the drive screen over the landing screen when the car connects during a drive.- Screens:
MainCarScreen(PlaceListNavigationTemplate) toSearchCarScreen(SearchTemplate) toRoutePreviewCarScreen(RoutePreviewNavigationTemplate) toActiveNavCarScreen(NavigationTemplate). The landing strip also opensDriveCarScreen(drive mode, below),SavedCarScreen(Home, Work and every saved place, capped at the host's list limit) andCarSettingsScreen(spoken directions, the tolls, highways and ferries avoids, and the Traffic layer, written to the phone'svela_settingsprefs,RoutingPrefsandTraffic). The route preview passes theRoutingPrefsavoids todirections. - The landing list has six rows. At most
MAX_DESTINATIONS(3) are destinations. Nearby categories fill the rest (NearbyCarScreen.driving(): gas, EV charging, restaurants, coffee, parking), ending in "More nearby" when they do not all fit.NearbyCarScreenlists the six nearest results with a distance span (a gas station's price on a second line, 5.8), and a row previews a route. Each row carries a numbered pin (CarMapRenderer.pinBitmap), andshowResultsdraws the same pins on the map and frames them with the car until the screen is left. A category row's marker is aRow.IMAGE_TYPE_SMALLimage, because the host tints an icon to one color. - Location permission can be missing when a car connects before onboarding ran. The session's
feed and the renderer wait on
CarLocationAccess.granted, the landing list leads with an "Allow location" row that callsCarContext.requestPermissions, and the renderer draws a world view (WORLD_CENTER20,0 atWORLD_ZOOM1.5) until the first fix. With no center the car map stays black. - The turn card needs
NavigationManager.navigationStarted(),updateTrip(), and an icon on the step'sManeuver: Android Auto draws no card for a maneuver without one.updateTrip()is sent when the step, its shown distance, the minutes left or the distance left (in 100 m) changes, and at most once a second (TRIP_MIN_GAP_MS). The host drops faster updates.ManeuverMappermaps Vela maneuvers to carManeuver,StepandTrip, sets the phone's glyph as the icon (NavGlyphs.bitmap), and reads the roundabout direction and exit number from the route's geometry. The destination estimate's time left takes the route line's traffic colors fromRoute.trafficRatio: red over 1.4, yellow over 1.15 (the car API allows only its standard colors here), green below, and no color when the route has no live traffic. With a stop ahead the stop's time takes the same color: it describes the route, as the line does. - On the drive screen a paused drive shows a
MessageInfo("Paused") in place of the turn card, and the strip has Pause/Resume. A turn farther thanCONTINUE_FAR_M(1,500 m) leads the card with "Continue on" the current road (Maneuver.roadAt) under a straight arrow and shows the turn as the next step. A search icon opensAlongRouteCarScreen: the quick categories as rows, a pick searches around the car, and a result becomes the NEXT stop throughNavSession.addStop(atEnd = false): the car has no stops editor to move it with. - The preview draws the selected route in blue over the other listed routes in gray
(
showPreview(route, others)), with a red dot at the destination. The drive draws the same dot, and the line ahead in the phone's paused lavender while the drive is paused. - Map action strips: recenter, zoom in, zoom out on the landing map; overview (re-frame the
selected route), zoom in, zoom out on the preview; recenter and an overview toggle
(
toggleOverview, exempt from the pan auto-recenter) on the drive. The drive's top strip is mute and end alone (user 2026-10-15, after a side-by-side with Google's car screen): pause and the search along the route went, they stay on the phone, and the drive's zoom buttons went with them; a pinch zooms where the unit takes one. The route line on the car is the phone's blue (#1f6feb) at 20 px, the driven part 18 px gray, alternates 14 px. CarBridgecarries the phone controller's spoken alerts (cameras, speeding, closing soon) to aCarToast, and the route's lights, stop signs and speed cameras to the renderer. A drive started with the phone UI closed has no controller and gets neither.- Settings > Navigation "Show speed and speed limit" (
SpeedDisplay, default on) hides the speed badge on the phone and the car, and skips the car's limit lookup. Nested under it, "Your speed on the car screen" (CarSpeed,car_speed_on, default off, user 2026-10-15) draws the car's own badge; off, the car shows the limit sign alone, in the badge's corner, since a car has a speedometer. The spoken speeding alert is a separate setting. The car's limit sign follows the phone's: the "SPEED LIMIT" rectangle in miles, the red-ring disc in kilometers, and a red number past 3 mph or 5 km/h over. - The guidance voice is band-limited by the protocol: the Android Auto guidance stream is 16 kHz mono.
The map:
- The map is MapLibre's public
MapSnapshotterrendered to a bitmap and drawn on the car surface. OneCarMapRendererlives for the session. A renderer per screen freezes the map. onSurfaceAvailablereleases theSurfaceit held before taking the new one. A screen change delivers a new object for the same buffer queue, and the old object keeps the queue's CPU connection until it is released or collected. Until thenlockCanvasfails on the new one and no frame is drawn. A failed lock logs once underVelaCar.- It resolves the same patched style file as the phone map (a plain style URL leaves the car on
Noto) and takes the phone's palette through the
StyleLayersinterface (applyMapTheme(SnapshotterHost(...), dark, amoled)). The palette is applied from the first snapshot callback, because the style observer never fires for a style handed over as JSON, and that first frame is discarded. It is re-applied when the car's day/night changes. - The snapshotter cannot add a layer or a source, so the layers the phone's
ensureLayersadds to Liberty at runtime are written into the patched style's JSON before it loads (CarStyle.inject): the flatvela-wetlandandvela-plazatwins over the hidden patterned originals,vela-pitchandvela-commercialabovepark,vela-trailsandvela-bikeroutesbelowroad_minor, the style light atLIGHT_INTENSITY(0.25, the phone'sB3D_LIGHT), and Google's traffic raster (vela-traffic-src, the phone'sTRAFFIC_TILES,raster-opacity0.6, no fade) above the topmost building layer with visibilitynone. The ids are the phone's, so the palette functions color them. On a look Vela does not paint only the raster goes in (twins = look.painted). The twins' filters and anchors are kept the same asensureLayersby hand. While the patched style does not exist yet the plain URL loads, without them; the next render after the file appears rebuilds the snapshotter on it (reloadIfPatched), so the Traffic switch and the fills do not wait for the next connection. applyOverlaysruns before each themed render: the traffic layer is visible with no route when the phone's Traffic layer is on and "Use Vela without Google" is off, as on the phone, and the basemap place icon tiers take the phone'sapplyPoiTierFilters(vegetation out; fuel only during a drive). Each is set again only when its state changes.- Each snapshot's time, zoom, tilt, traffic state and speed are logged under
VelaCarat debug level (setprop log.tag.VelaCar DEBUGon the phone), the measure of what a raster or a tilt costs per frame. QuietSnapshotterdrops the library's overlay, and the renderer draws its own single OpenStreetMap credit. The credit and the speed badge stay inside the host's stable area, or the visible area when the host reports no usable stable area.- The renderer takes GPS fixes, the simulated position and a demo drive's or replay's fixes,
snaps the puck to the route during a drive, glides it between the roughly 1 Hz fixes with
FollowEstimator, and eases the heading (BEARING_EASE0.22 perTICK_MS70 ms tick), the camera bearing (CAM_BEARING_EASE0.3, then equal to the heading), the tilt (TILT_EASE0.05) and the zoom (ZOOM_EASE0.06). A fix with no speed takes the distance since the last fix over the time between them (0.2 to 5 s apart), capped atFIX_SPEED_MAX_MPS(70): read as parked, it held the zoom at its closest. A fix with no bearing takes the direction from the last fix once it has movedFIX_COURSE_MIN_M(3 m). - The arrow's heading is the GPS course above
STOPPED_MPS(1 m/s) with a bearing accuracy of 45 degrees or better, a fix wider thanStillness.ACC_TRUST_M(30 m) counting only fromStillness.SLOW_MPS(3 m/s); else, while moving or before any heading is known, the route's direction at the engine's own progress along it (NavState.traveledM, the way OsmAnd and Organic Maps anchor the arrow to the route rather than to the fix), the segment nearest the fix only off the route; stopped, the last heading, so a wide fix at a light before a turn no longer swings the arrow between the two streets. A crawl under 3 m/s on a wide fix, or while the phone is at rest (Stillness), is a speed of 0. The heading is kept in every view, so a north-up map still turns the arrow. - The view is heading-up (
headingUp) while following with no preview and no overview, the phone'sNorthLockoff, and either a drive or the free-drive latch: the smoothed speed (DRIVE_SPEED_TAU_S1 s) pastDRIVE_LATCH_MPS(2.5) with a course known. The latch holds through a stop and lets go when the follow ends (a pan, a zoom button, the overview); recenter sets it again at once when the car is already moving. Heading-up, the camera bearing is the heading, the tilt isCarFraming.NAV_TILT_DEG(55) and the arrow sits atPUCK_DOWN(0.72) of the visible area's height. Otherwise the view is north-up, flat and centered on the arrow. - Zoom follows speed whenever the view follows a moving car, drive or not:
CarFraming.navZoom,ZOOM_NEAR(17.2) at rest toZOOM_FAR(15.0) atZOOM_FAR_KMH(110) and above, a straight line between. In a drive with the phone's "Zoom to the next turn" on, the zoom is the lesser of that and the zoom that frames the next maneuverTURN_MARGIN_PX(40) under the top of the visible area, with the phone's floor, the camera turns toward the maneuver byNavFraming.turnYaw, and the tilt flattens with the zoom (4.7, Framing). The maneuver isNavTurnTarget.pointForon the session's route and step, cached per step. Otherwise the zoom is the user's. - The arrow lands on the wanted pixel two ways. Down the screen the camera target is moved:
CarFraming.targetOffsetgives the ground offset in pixels at the center's scale, the flat screen offset at tilt 0, and under tilt the solution of MapLibre's perspective (camera distance0.5 * height / tan(FOV / 2),FOV_RAD0.6435), where the ground nearer the camera draws larger. Meters per pixel assume 512 px tiles. Across the screen the camera's center of perspective is moved instead, with left or right camera padding of twice the arrow column's distance from the surface's middle. A tilted camera draws the road straight ahead straight up only through that center, and with the target moved across, a straight road through an arrow 234 px right of the middle of a 1280 px surface leaned 14 degrees toward it. - The route, its driven part, the destination and the dots along it are drawn on the snapshot
with
MapSnapshot.pixelForLatLng, and only for ground in front of the camera. Tilted, the camera has ground behind it, and the projection answers for a point there with its mirror image through the screen.FrontClip(CarFraming.kt), built with the camera each snapshot is taken from, keeps the points no more thanCarFraming.behindLimitPxbehind the target:(1 - FRONT_MARGIN) * cameraDistance / sin(tilt), withFRONT_MARGIN0.15, which at the drive tilt lands about six screen heights below the center.projectdrops a point past it, andpathOfends the line at the crossing and picks it up where it comes back. Flat, there is no limit. - The arrow is the phone's puck bitmap, turned to its heading as the map draws it: a point
PUCK_AIM_PX(40) ground pixels ahead of it along the heading is projected, and the arrow points at it. The heading minus the snapshot's bearing is the flat answer and the fallback; tilted, a turn on the ground is a wider turn in the picture. - A pan moves the center by the finger's travel in meters (
shiftCenter). Reading the new center off the last snapshot'slatLngForPixeladds the visible-area offset to every scroll event. A pinch keeps the point under the fingers in place. A fling decays exponentially (FLING_TAU_S0.35 s, stops underFLING_STOP_PX_S40 px/s), stepped by the render ticker and stopped by recenter, zoom, overview and route preview. The map recentersRECENTER_MS(6 s) after a pan. - From z13.5 the renderer draws the
CarBridgelights and stop signs as the phone's glyphs (trafficLightBitmap,stopSignBitmap; issue #844), and rail crossings, speed humps, speed cameras and the plate cameras along the route from the bundled set as dots. A stop sign iscontrolGlyphPx: a twentieth of the screen's short side, scaled with zoom as the phone scales its glyphs (0.7 at z14, 1 at z15.5, 1.3 at z17), between 16 and 56 px; a light isLIGHT_TALL(1.4) times that tall. - The speed badge and the limit sign draw during a drive and on the drive-mode screen
(
setDriveScreen), withSpeedDisplayon. They scale with the screen (issue #817): the badge's radius is a 18th of the shorter side, 22 to 46 px, and the text, the sign and its strokes follow by the same factor, so on an 800 by 480 unit they are three fifths of the old fixed size and at 828 px and up the old size.
Drive mode (DriveCarScreen, a NavigationTemplate with no navigation info): the map alone, no
route and no list, opened from the landing strip's Drive action. Its strip holds search, saved
places and a list action that pops back to the landing screen; the map strip is recenter and
zoom. A drive started anywhere replaces it with the drive screen through VelaCarSession.
10.7 Street View¶
The panorama is rendered in-app (app/streetview/, ui/place/StreetViewScreen.kt). Google's
WebGL embed serves a stripped shell that renders black on ANGLE. Do not retry it.
Requests¶
- Metadata by location is a POST to
Calibration.STREETVIEW_SEARCH_URL(Google'sMapsJsInternalService/SingleImageSearch, content typeapplication/json+protobuf) with the JSON bodystreetViewSearchBody({LAT},{LNG},{RADIUS}; remotely replaceable). It is asked at 50 m, then 200 m (STREETVIEW_RADII_M): a store behind its lot has imagery within that. The body asks for Google's own imagery only ([2,1,2]), because the tile loader cannot show user photo spheres. The reply is bare JSON. - The old GET,
GeoPhotoService.SingleImageSearch, has answered "decommissioned" since 2026-10-05 and is tried only after the POST fails. Builds from before that date lack the POST and cannot be repaired remotely. - Metadata by pano id comes from
photometa/v1, whose response nests the pano node one level deeper and carries a)]}'guard. Both lookups are authorized by aReferer: https://www.google.com/maps/header. The address, copyright and position are inside the pano node, not at the root. - Tiles come from
streetviewpixels-pa.googleapis.com/v1/tile. The/v1/thumbnailpath answers only with the full parameter set Google's own pages send (cb_client, size, yaw, pitch, field of view) and a browserUser-Agent(the calibrated one, which the app's image loader sends to that host; no referer is needed, checked 2026-10-10). Bare, it returns 403.
Rendering¶
StreetViewTilesstitches the highest level at most 4096 px wide andPanoramaViewtextures it onto a GLES2 sphere. Never stitch the full 16384x8192 level: about 400 MB of texture.- Beside it, the level at most
PREVIEW_W(1024 px, two tiles on a modern pano) loads too and is shown first when it lands before the full one, which then fades in over it. Two more tile requests per pano, for the pano already being fetched. Only the full picture is cached. - The tile pyramid is not one shape. Modern panoramas are
512 * 2^zwide. Captures from before about 2016 are416 * 2^zand some have only four levels. The grid is sized from the panorama's own level dimensions, or the loader requests tiles past the edge and paints black bands. A stitch that is not 4096x2048 is scaled to it, which is exact for an equirect. - The sphere is viewed from inside (culling off) with natural U (
uv = u). A flipped U mirrors the panorama, which reads as backwards signage. - Compass frame: Google puts the capture heading at the texture center (u = 0.5) and the
renderer's yaw 0 looks at u = 0.75, so compass bearing B is renderer yaw
B - captureHeading - 90. UsesetCompass(panoHeading, faceCompass). Never pass a compass bearing as a raw yaw, and never overwrite the pano's ownheadingDeg, which is the texture reference. - Zoom is the horizontal field of view. A fixed vertical field of view narrows the view when the pane grows.
Which panorama¶
- The search response's Street View thumbnail URL carries the pano id and the camera yaw, and
both are used as given. For an entry with no thumbnail the fallback is geometric: the nearest
pano, and when that is not on the address's street, probes at
STREET_PROBE_RADII_M(24 m and 40 m) along both perpendiculars for one that is. Geometry alone mis-picks. - Walking fetches the neighbor by pano id, never by nearest location, or a walk lands on a different-year capture at the same spot. Time travel resolves the historical pano's own metadata, because epochs differ in pyramid shape and in heading by up to 180 degrees.
Viewer¶
- Walk arrows are chevrons lying on the road (
GroundArrows): 6 m out along each neighbor's bearing, seen from 2.5 m up, projected through the panorama's own camera (yaw, pitch, horizontal field of view), so they turn and foreshorten as the view moves and drop off the bottom when it looks up. A tap within 72 dp of a chevron walks there (PanoramaView.onTap); invisible 56 dp boxes on them carry TalkBack's label and D-pad focus. - A walk moves at once: the view zooms in up to 14 degrees over 450 ms while the next pano
loads, and the next pano fades in over 350 ms from that zoom, easing back out. It faces the
compass direction you were looking, as Google's does. Its heading and texture land on the same
GL frame (
setPanorama(bitmap, heading, face)), since aiming first turned the old picture by the new pano's heading at every corner. The spinner waits 700 ms on a step. - The viewer is a top-aligned pane over the live map (0.55 of the height, or full screen), not a dialog. It reports its pose so the map draws the puck and a view cone. The camera eases to the panorama on each hop only, never per yaw frame. A tap on the visible map moves the panorama there.
- A
SurfaceView's window hole does not follow a pure-Compose resize, so the full-screen toggle recreates the view (remember(full)insidekey(view) { AndroidView(...) }) and re-feeds the texture and the current yaw. - Viewed panoramas are kept in
core/data/StreetViewCache(files/svcache: one metadata JSON and one stitched JPEG per pano,MAX_BYTES150 MB, oldest dropped) under the "keep viewed places" setting (OfflinePlaces). The network is asked first and the saved copy is used only when it gives nothing. Deciding "offline" up front showed "no imagery" on streets that have it whenever the offline guess was wrong. With neither, an offline phone is told the spot was not viewed before. The cache is cleared by its own button, by "Clear history" and by "Delete all offline data", and is read off the main thread. - A preview floats on the map for an open place whose search reply names a pano
(
StreetViewThumbinMapFloaters): above the card's left corner in portrait, beside the panel in landscape. It is one/v1/thumbnailrequest with the reply's pano id and yaw. It follows the photo settings, and it is not drawn with Google off, offline, when the picture fails to load, or while the place sheet itself is off screen (SheetEdge.shown, set by the sheet's own position reports and cleared when it leaves: the search page keeps the place selected). - The pano comes from the place's first search reply, else from its details reply
(
PlaceDetails.svPanoId, carried over inmergeDetailswith its own yaw), else, for a Google listing only, from the nearest-pano lookup the Street View button makes, faced at the place (MapViewModel.thumbPano, once the details are in; 2026-10-18, some businesses had no thumbnail). Google was already asked about that listing by name, so the lookup's point tells it nothing new. A tapped building, a dropped pin and a saved point never trigger it. - With no picture to load by itself (no pano, Load photos off or on tap, or the picture failed),
the window still shows, as the Street View figure over "360°" on the dark fill, and a tap
opens the viewer through
openStreetView, the card button's lookup; nothing is requested before the tap (user 2026-10-18). Not for a drawn shape, and not with Google off or offline.
10.8 Content gating¶
ShowReviews and LoadPhotos (ui/PlaceContent.kt) gate the fetch as well as the render, so
off means no scrape traffic. HideAdult sets the :core CategoryFilter flag, which filters at
the search and nearbyPlaces seam on category only, never name, with multilingual keyword
lists. It also drops the bars chip from the quick categories, which the filter would empty.
HideExternalLinks hides the website pill and row, the OpenStreetMap link on the source line and
the book/order action. The Street View pill opens the in-app viewer, so that switch leaves it
alone. It is hidden only when Google is off. A new review, photo or external-link surface goes
behind the matching holder.
11. Remote resilience¶
At launch CalibrationStore loads its cached bundle, then fetches calibration.json and the
detached calibration.json.sig from
https://raw.githubusercontent.com/PimpinPumpkin/Vela/main/, and when that does not answer
(no reply, a transport error, or a copy whose signature does not verify) from the copy on the
website, https://velamaps.org/calibration.json (VelaLinks, 11.4). It adopts the remote
bundle only if:
- the signature verifies (ECDSA P-256 with SHA-256 against
PINNED_PUBLIC_KEY); - every endpoint host is
google.comorwww.google.com; versionis higher than the active one (Calibration.DEFAULT.versionstays 1).
Otherwise the active bundle stands. A cache that fails the same checks falls back to
Calibration.DEFAULT for one launch.
parseBundle takes the compiled default for a missing key. A Calibration field it does not
read is not remote, so grep CalibrationStore for a new field's name. The bundle carries:
- Requests: endpoint URLs, pb templates,
photosProto,reviewFeedProto,streetViewSearchBody, the search-as-you-type request (suggestEndpoint,suggestPbwith{SPAN} {LNG} {LAT} {W} {H}) and the RPC header valuerpcContext. - Positions:
paths,directionsPaths,suggestPaths,stopBoardIndices. - The browser identity fields.
- Word tables:
statusClosedWords,statusOpenWords,transitCategoryWords,transitExcludeWords,reviewWords, and the review scrape's CSSreviewSelectors. - Fleet defaults:
defaultVoiceId,defaultVoiceSpeaker,defaultVoiceSpeed,defaultMapPalette,defaultPlacesSource,classicRoutePicker. tuning: name-to-number dials read withCalibration.tune(key, compiledDefault). View code readsCalibrationStore.latest. A switch that opens the app for inspection readsAppTune.localOn, the adb property alone, so no bundle can set it.notices:id,level,title,body,url. Levelurgentis a modal dialog, any other a dismissable card on the map.transformsJs: JavaScript run byJsSandboxin Rhino withoptimizationLevel = -1(ART cannot run Rhino's bytecode),initSafeStandardObjects(no Java or IO) and a 2 s kill switch. Keep rules are incore/consumer-rules.pro.JsTransformsexposesparseSearch(rawResponse)andtransformPlaces(placesJson)over the flatPlaceJsoncontract. No script, a missing function or any error leaves the compiled Kotlin result. Logic it cannot express ships as a release.
Daily health check¶
.github/workflows/google-health.yml runs at 14:20 UTC and on dispatch. A failed scheduled run
mails the maintainer. Nothing is posted.
GoogleHealthProbeTestruns the app's request builders and parsers with the repository'scalibration.jsonfrom the Davis fixture (search, directions with and without avoid-highways, autocomplete, the review feed, photos) and printsHEALTH|check|OK|BLOCKED|DRIFT|detail.DRIFT(an unreadable answer, or the avoid flag ignored) fails the run.BLOCKED(403, 429, the sorry page, a consent wall: a datacenter IP's treatment) is a warning.- The review-feed check retries after 3 s and 8 s. A withheld reply (a payload ending
true,[true]) isBLOCKED. scripts/check-chrome-ua.pyfails the workflow when the claimed Chrome major is behind a Windows stable major that has been out 7 days, or ahead of stable.
Locally: ./gradlew :core:testDebugUnitTest --tests '*GoogleHealthProbeTest' -DvelaLive=true --rerun-tasks.
11.4 The project's own links¶
Every address the app has of its own project is in core/config/VelaLinks: the repository,
its API, the download releases, the raw files on main, the website (site, velamaps.org), the
GitHub Pages address (pages, where the map fonts, the F-Droid repository and the docs live)
and the donate page, and the files derived from them (the settings file, each data manifest,
the world basemap, the map fonts, the speech models, the UK fuel file, the painted roads).
The website and the Pages address are separate keys on purpose: the site can move without
touching what installed apps fetch. Settings > About offers both the website and the
repository, each through its own key, so either host can go away without the other door
closing. Nothing else in the code holds
one of these as a literal. A signed bundle's links object replaces any of them by name:
pushing releases alone moves every file under it, pushing one key moves that one. Only https
links under known names are accepted; anything else rejects the bundle. A build's own link
(-PobfManifestUrl= for a local server) wins over the default and loses to a pushed one.
The settings file is asked for where the last bundle said it lives, then where the build was
compiled to look, then at the website's copy (calibrationMirror, pushed then compiled; the
site workflow publishes calibration.json and its signature to velamaps.org on every change
to them). Moving the project: push a bundle whose links name the new places while the old
ones still answer; each app keeps that bundle and applies it at the next launch, so it asks
the new places from then on, the settings file included; then change the defaults in
VelaLinks for the next release. If GitHub stops answering before that push, the website's
copy is where the bundle goes. The browser identity for the project's own requests
(VelaConfig.VELA_UA) carries the repository link and follows it.
12. Degoogled constraints¶
Regressing one of these blocks a release.
- Location is AOSP
LocationManager, neverFusedLocationProviderClient. LocationListeneris an explicit object, never a SAM lambda. On Android 10 and below the other three methods have no defaults, and a present-but-disabled provider throwsAbstractMethodErrorat launch.- Voice is AOSP
TextToSpeechwith a selectable engine, or the bundled neural voice. Google TTS is never required. - Dictation is on-device or an installed recognizer app, never a cloud speech API.
- No GMS: no FCM, Firebase, Play Integrity or fused location. Push, if ever, is UnifiedPush.
- No static Google API key in any build variant.
- EU consent:
SOCSandCONSENTare pre-seeded, and aSet-Cookiethat would downgradeCONSENTtoPENDINGis dropped. - The hidden WebViews run Google's JavaScript with no account, for data only a browser engine is served. No sign-in is offered.
- Onboarding is welcome, the Google choice, location, notifications, voice. The choice page
(
GoogleChoiceinWelcomeScreen.kt) setsGoogleFreebeforeMapScreenis composed, so no request to Google is made before the answer. "Use Google" is preselected. "Choose what Google is used for" under Continue opensGoogleUsesSectionas a first-run page, with the same switches as Settings > Privacy. The same page asks about plate cameras (CameraChoices): "Route around them" setsFlockRouteAlert, "Warn me as I get close" sets the card and the spoken warning ofFlockNavAlert. Both start off and are written on Continue. The card starts with the plate camera badge as the map draws it (PlateCameraBadge, the map's ownalprCameraBitmap), and Settings > Navigation shows the plate and speed camera badges before their rows (ToggleRow'sleadingslot), so the badge is explained where it is turned on and never drawn a second way. - The same page asks about saved drives (
TripChoices): "Save my drives on this phone" writestrip_recording_onand "Delete drives after 30 days" writestrip_auto_clear(MapViewModel.TRIP_AUTO_CLEAR), both on, written on Continue; the second shows only while the first is on. Installs from before it keeptrip_recording_onas it was and readtrip_auto_clearas off, so no saved drive is deleted on update. With it on,TripStore.pruneExpireddeletes drives whose file was last written more thanTripRetention.KEEP_DAYS(30) days ago, never the one recording, at launch (MapViewModel.pruneOldTrips, which opens the prefs itself: it runs from the constructor beforesettingsPrefsis assigned, and reading that field there crashed every launch on a test build) and at each drive's start; turning it on under Settings > Diagnostics prunes at once. - Settings > Privacy lists every switch that decides what Google is asked
(
GoogleUsesSection, shown while Google is on): the place source, what a place page loads, and what a route and a drive ask. Each row is a shared composable inui/settings/sections/GoogleUses.kt, drawn again on its own page with its explanation. The list shows labels only. - Permissions are asked in context. A coarse-only grant gets a one-time explainer and a true accuracy circle. Navigation needs fine location and offers an upgrade dialog. A permanently denied locate tap opens system settings.
MemoryPressurepassesonTrimMemoryto registered releasers, and a new large or native allocation registers one. The speech model goes on a severe trim and after 120 s idle, never during a decode, where freeing it is a use-after-free. The neural voice goes on a critical trim only, since a reload mid-drive delays a prompt. MapLibre's native caches, every hidden WebView and the image cache go on a severe trim.MemoryPressure.lowRamselects a smaller image cache, no speech warm-up, no speculative WebView warm-up and an 8-term ambient fan-out. It isLowRamMode.classify: a Go-configured device, a 32-bit process (the limit is address space, whatever the RAM), a heap class up to 128 MB, total RAM up to 2048 MB, or both of those unreadable.ConstrainedNetworkreadsNET_CAPABILITY_NOT_BANDWIDTH_CONSTRAINEDandTRANSPORT_SATELLITEby name through reflection. A platform without them reports false. On a constrained link the photo walk is skipped and the ambient fan-out takes the lean path.
13. Performance model¶
MapLibre's render thread serializes symbol placement, every setGeoJson and setProperties,
and drawing. The main thread hosts the camera tickers, all JNI style calls and Compose
recomposition. Neither can be parallelized, so the rules send each less work.
- Identity-gate every source upload and property write, and reset the gate holders on style reload.
- Never move route geometry per frame or on a short timer (section 4.8).
- Never re-place a layer for an unchanged value. A
setFilterre-lays the whole source, and asetGeoJsonre-places its whole layer. - Per-frame work goes in the layout or draw phase, never composition. A value read per frame
lives in a
mutableFloatStateOfholder, notMapUiState. - Gate high-frequency writes to
MapUiState. The scale bar reports past a 1 percent change, the compass heading past 2 degrees and at most every 200 ms. - A
queryRenderedFeaturescall in a dense view costs 37 to 55 ms even when it returns nothing. Debounce it, gate it on camera stillness, and never run it unthrottled from an idle event. - A dense GeoJSON source needs a high
maxzoom(section 5.3). Ambient places, traffic controls (up to 800 on a route), transit stops and result markers are 18, the camera layers 16, the accuracy circle 14, and the puck, parking, saved places and Street View 12. - Build release for anything a person will feel. On a Pixel 4a the same place tap, sheet drag and review scroll gave 14.8 percent janky frames (90th percentile 69 ms) in debug and 1.1 percent (28 ms) in release.
dumpsys gfxinfocounts the Compose chrome and cannot see the map, which draws on its own GL thread.VelaMapViewlogs the map's frames once a second underVelaFpswhen the system propertydebug.vela.fpsis set (read at map creation, so restart).scripts/map-fps.shruns the loop and prints min, p10, median and max. A Pixel 4a holds 40 to 55 fps panning at browse zoom.- A phone throttles after a few minutes. Check
dumpsys thermalserviceand alternate A and B runs. :app:generateBaselineProfile(baseline-profile.yml) writesapp/src/release/generated/baselineProfiles/baseline-prof.txton a Gradle-managed emulator, and a release build bakes in the profile it finds there. Never run it on a connected phone: the harness uninstalls the app, which deletes saved places, trips and grants.- A changed profile is pushed to a
baseline-profile-refresh-<date>branch. The repository does not let Actions open pull requests, so the run ends with a warning that links the branch, and the pull request is opened by hand. - The journey (
BaselineProfileGenerator) grants the app's permissions, leaves the welcome screen, takes the "no" side of each first-run prompt, pans the map and walks Settings. A prompt left up covers the map and the run records that prompt alone. After changing the journey, check that the file hasMapScreenandSettingsHubentries. - On a Pixel 4a a cold start reaches its first frame in about 1,100 ms with nothing compiled
and 830 to 900 ms with the profile compiled. The libraries' own rules give most of that. The
app's rules add about 50 ms and take the 99th-percentile frame of a first Settings visit from
62 ms to 53 ms. GrapheneOS compiles the whole app at install (
speed), so there the profile changes nothing.
14. Privacy, diagnostics and location hygiene¶
14.1 What leaves the phone¶
PRIVACY.md is the user-facing accounting and must agree with section 1.4. In the default
configuration browsing the map does not contact Google. Search, opening a place, a driving route
and transit directions do. Routes also reach FOSSGIS, transit boards Transitous, reverse
geocoding Nominatim. A UK gas station without a price makes the phone fetch the fuel price file
from GitHub (5.8). With "Use Vela without Google" on, only the open services are asked.
14.1a State files¶
- The offline stores'
index.json,revs.jsonanddead.json, the region catalog cache and the diagnostics trim are written withcore/util/AtomicFiles(temp file,fsync, rename). A torn index would read as nothing installed and the next write would save that. Readers see the old file or the new one, which coversObfRouteEnginereadingobf/index.jsonwithout the store's lock. - The closed-open-places set is capped at
CLOSED_OPEN_PLACES_CAP(2000, oldest dropped): every id is in a filter the places layers evaluate per feature. - Viewed places (
files/placecache,core/data/PlaceCache: one JSON per place, 400 files, 30 days) and viewed panoramas (files/svcache) are plain files under one setting. An offline search result has no Google id, so a saved copy also matches on the same normalized name withinSAME_SPOT_M(60 m). Nothing is saved while Google is off. "Clear history" and "Delete all offline data" empty both.
14.2 Diagnostics¶
DiagLogis an opt-in breadcrumb ring, off by default, kept in a boundedfilesDir/diag_log.jsonlso a report survives the process death that usually precedes it. The file is trimmed to the ring at load and everyCAP(300) appends, and deleted on opt-out.DiagExportershares it as a JSON file when the user asks. Nothing is uploaded.DiagScrub: a plain export rounds coordinate-shaped decimals to 2 places (about 1 km). "Redact places in exports" rounds to 1 place (about 10 km), replaces quoted text, drops a navigation start's destination label, keeps only the host of a URL, blankscidvalues and drops page-text detail. Counts, zoom levels and error text stay. A breadcrumb that can carry a name or an address needs a case inDiagScrubTest.- A page probe logs the path only up to
/@, where Google puts a coordinate derived from the session. SettingsDump.lineputs the settings on one line in a crash report and at the start of a recorded drive: switches, numbers and short option names. Free text and any key that could hold a position, an address, a contact, a name, a provider or a font are skipped.SettingsDump.locationis the drive's third note,location:: the providers that are on, and on GrapheneOS itsSettings.Globalchoicesnetwork_location(off, apple, grapheneos_proxy, apple_china),force_disable_supl(standard, off, grapheneos_proxy),psds_server(grapheneos, standard, off) andgeocoder(off, openstreetmap, grapheneos), absent elsewhere. Words only.- The debug export's
inputfield (SettingsDump.input):touchscreen=yes|no,keypadFirst=yes|no(isDpadFirstDevice) anddpadDevices=, the driver names of the physical input devices that report a D-pad, so a report where taps do nothing (a head unit's hardware buttons taken for a keypad, issue #744) shows whether Vela is waiting for keys. - A recorded drive's notes say what it ran on and fetched.
data:(at the start and on change) lists which of routing, the map, places, buildings, addresses, speed limits and signs come from the phone and which are streamed, as counts with no region named.net 10 s:counts the map's network requests by host, or by release for Vela's own files (diag/NetCount, an interceptor after the local-tile hook, never a path).signs:says whether the route's own set or the whole-view fallback filled the layer. - Speed-limit and building overlays are not streamed where the phone has the data
(
refreshMaxspeedOverlay,refreshBuildingOverlays), and during a drive the whole-view sign path draws only what is on the route (controlsOnRoute). NavTrace(off by default) records one row per navigation frame: time, along-route progress, speed, bearing window, chord bearing, display bearing, camera bearing, frame dt. It holds no position, so unlike a recorded trip it can be attached to a public issue.
14.3 Sharing a trip¶
TripScrub trims a shared trip. Every fix within the chosen radius (200, 400 or 800 m,
DEFAULT_RADIUS_M 400) of the start, the end, the destination and the user's Home and Work is
deleted, and the middle keeps full precision. Rounding would protect the ends weakly and destroy
the geometry.
- An endpoint appears in six places and all are handled: the fixes, the
METAdestination, theMETAlabel, the maneuvers, the route polyline's start and the spoken lines. - Timestamps rebase to zero.
- An
Sline survives only if a fix withinEVENT_NEAR_MS(3 s) survived: it is the spoken text and names the street. NandRClines are dropped: they hold positions.K,JandBlines are kept for the whole drive, the trimmed ends included. They hold no position, name or spoken text, and the start of a drive is where its route is planned and named. One from before the first surviving fix has a negative time. They show how long the drive spent inside a trimmed end, not where.- A route block whose polyline trims to nothing drops its
RDandMlines. - A trip that trims to nothing is never sent raw. A batch share leaves it out and counts it.
- "Save to phone" in the one-trip dialog writes the full trace, untrimmed, into a file the user
picks with the system's save dialog (
CreateDocument("text/csv"),MapViewModel.saveTripTo, named as the full share is,tripFullFileName). The file stays on the phone, so nothing is trimmed; it is how a trip reaches a computer over USB (adb pullfrom Downloads) without passing through another app. Added 2026-10-18. - The batch dialog has the same two: "Save to phone" writes the picked trips' full traces as one
zip (
MapViewModel.saveTripsTo,CreateDocument("application/zip")), and "Share full traces" sends that zip (shareFullTripsZipIntent). Each entry is named as a single full trace is (vela-trip-<stamp>-full.csv).
14.4 Location hygiene¶
Test coordinates, screenshot corners, sample addresses and "checked on a drive to X" lines add up, in permanent public history, to where the author lives. Before a place, address or coordinate enters the repository, ask whether it was chosen for a reason anyone could have. A place that is the subject of a report, such as the business whose hours parse wrong, is fine.
- Locality is input, never output. Use it to reason, query and reproduce, and write up the mechanism only. A bug that cannot be explained without the place is not root-caused yet.
- Fixtures: Davis and Sacramento, California (box
38.30,-122.00to38.90,-121.20, address1451 W Covell Blvd, Davis, CA 95616), San Francisco (37.7749,-122.4194) for a big city,37.0,-122.0for an abstract grid. Another area needs a reason, and a grid at the author's own latitude is not one. - Screenshots use Simulate my location and Simulate driving. Check the corners: recents, place labels and street names.
- Recorded trips, diagnostics exports and adb dumps hold raw GPS. Never attach them to an issue, a commit or a CI artifact.
.github/workflows/location-guard.ymlscans added diff lines and commit messages against the repository secretLOCATION_TERMS(one term per line) and never prints the matched text.scripts/check-location.shruns the same scan before a push. Neither sees issue bodies, comments, release notes or screenshots.
14.5 Attribution¶
No commit message, pull request body, issue comment, release note or file carries an AI
co-author trailer, a "generated with" line or any other AI attribution. This overrides any
tooling default. scripts/check-writing.sh checks commit messages for it, in the pre-push hook
and in location-guard.yml.
15. Build, release and distribution¶
- Toolchain: AGP 9.4.1 (Kotlin built in, no
kotlin-androidplugin), Kotlin 2.4.20, KSP 2.3.12, Gradle 9.8.0, Hilt 2.60.1, OkHttp 5.5.0, MapLibre 13.6.1, Compose, Java 17, compileSdk 37 in every module, targetSdk 35, minSdk 26, a version catalog, R8 in thereleasebuild type. The rootbuild.gradle.ktspins the build tools' own libraries, none of which is in the app. CI validates the Gradle wrapper jar. - Channels. A push to
mainorcanarybuilds and tests only. The nightly prereleasev0.5.<run>is cut byci.ymlat 10:30 UTC whenmainhas moved in a file that can reach the app (scripts/app-changed.sh; a dispatch only needsmainto have moved), titledVela <version> nightlywith notes that open "Nightly build."promote-stable.yml(Mondays 16:00 UTC) promotes the newest nightly to stable: same tag, same signed APK, no rebuild, retitledVela <version>with the notes regenerated. Each push tocanaryreplaces the one release on the fixed tagcanary, which is not av0.*tag. Its notes carry theversionCode:line the updater reads. release.ymlis the manual path to a channel: inputchannelnightly dispatchesci.ymlonmainand waits for the nightly, and stable then callspromote-stable.ymlwith that tag. It refuses any ref butmain, amainthat moved after the run started, and amainthat is not at the optionalsha.promote-stable.ymltakestag(the nightly expected to be newest; another one stops the run) andwhats_new(the hand-written list that leads the notes). The run ends by dispatchingfdroid-repo.yml, which its own token's releases would not trigger.- versionName is
0.5.<run>(0.4.<run>until 2026-10-08; the minor is a name, and the run number orders releases across minors) and versionCode(2000 + run) * 10plus a chip digit. The run number must stay inci.yml: another workflow would restart the count. - Never name a release
v0.5.0. The updater takes the run number from the tag, reads code 2000 and never offers it. Keep local development builds below versionCode 1000. - Release notes are the commit subjects since the previous
v0.[0-9]*tag (scripts/changelog.sh, which leaves out docs-only commits). The in-app dialog shows the body as it is, so a stable's notes lead with a hand-written "What's new" list. - Docs-only pushes skip CI (
paths-ignore). A mixed push builds. Anfdroid/metadatachange alone also starts no index rebuild. - Nightlies keep a rolling 30. Stables are never pruned: they are the changelog, the bisect range and the record of reach.
One APK per chip type¶
ABI_SPLITS is true since 2026-10-22 (issue #680). With the repository variable ABI_SPLITS
true, CI builds with -PabiSplits and a release
carries <prefix>-arm64.apk, -armv7.apk, -x86.apk, -x86_64.apk and <prefix>-all.apk
(prefix vela-maps or vela-maps-canary, scripts/stage-apks.sh). Without it, one APK.
- Chip digit on the versionCode: all-in-one 0, armv7 1, arm64 2, x86 3, x86_64 4, so moving from the all-in-one APK to a chip APK of the same build is an upgrade.
- The all-in-one name sorts first: GitHub lists assets by name and updaters older than
update/ApkChoicetake the first.apk. - Obtainium picks the chip file itself from 1.6.16 (September 2026), which reads
arm64andarmv7as the Android chip names; an older Obtainium shows every file, the all-in-one first. Its x86 match also takesx86_64names, so a 32-bit x86 phone may be offered the x86_64 file. - The single APK leaves out Cronet's x86 libraries (108.4 MB). A per-chip build keeps them: arm64 74.3 MB, armv7 35.4, x86 41.2, x86_64 41.5, all-in-one 121.9.
In-app updater¶
SelfUpdatercompares on the scale2000 + run.legacyCodedivides a code of 20000 or more by ten.- Stable reads
releases/latest, nightly lists tags throughgit/matching-refs/tags/v0.(once per check;appReleaseTagskeeps each run's real tag name) and readsreleases/tags/<tag>, canary reads its rolling tag. The releases list is never fetched: the data releases carry about 450 assets each and made a check 4 to 9 MB. - Canary takes the newest nightly in its place only when the nightly's code is higher and it
holds canary's commit (
canaryPick):compare/<nightly commit>...<canary commit>?per_page=1&page=2answersbehindoridentical. The commits are the releases'target_commitish. Page 2 leaves out the file list (about 10 KB; page 1 for a canary 26 commits ahead ofmainwas 450 KB). A failed compare keeps canary, and an unreadable canary release offers nothing. A nightly cut from amainthat lacks canary's commits has the higher run number whenever it was cut after canary's last push. - A stable check with nothing newer is 1 request. Nightly and canary checks are 2 to 4, and a
canary check adds the compare when the nightly's code is higher. An
offered update adds at most
HISTORY_MAX_RELEASES(8) for the notes of the versions between installed and offered. Every check logs oneVelaUpdateline, and the compare one more. ApkChoicepicks the file forBuild.SUPPORTED_ABIS. The download uses a client with no call timeout.ApkCheckrequires the zip magic bytes, the release's size and its SHA-256 when GitHub publishes one.- The system installer gets the file through the FileProvider and enforces same package and same signature.
- The launch check (pref
self_update_check) runs at most every 20 hours. "Not now" pins the dismissed code inupdate_dismissed_code. InstallSource: Android Auto lists a sideloaded navigation app only when its install source is Play, which AAEnabler and King Installer set and a self-install overwrites. When the installing or initiating package is Play, the downloaded APK is offered as a file for that tool. "Update anyway" installs it and loses the listing.
F-Droid and GitHub Pages¶
fdroid-repo.ymlrebuilds the signed repository (latest stable plus the newest nightly) and deploys it to GitHub Pages.CurrentVersionCodeis pinned to the stable's highest versionCode, read off its APKs, so default clients update weekly.- Files are renamed by tag, and the all-in-one APK is dropped where chip APKs exist.
fdroidservercomes fromtools/fdroid-requirements.txt, which fixes every version, because the job holds the index key.- It triggers on
workflow_runof CI and the promotion: a release created by CI's own token fires no event for other workflows. - The landing page and the press page (
site/), the press kit (zipped by the workflow fromdocs/screenshots, the logo andsite/press-kit/FACTS.md), the map fonts and the docs site ride the same Pages artifact. The landing page, the press page, the privacy page (scripts/build-site-privacy.pyrendersPRIVACY.mdinto the site's layout at deploy time) and the press kit are also published to velamaps.org on Cloudflare Pages by the same workflow;site/_redirectssends velamaps.org/docs to the GitHub Pages docs. A failed velamaps.org deploy does not stop the GitHub Pages one: thewebsitejob turns the run red after Pages has deployed. "Invalid access token" in the log meansCLOUDFLARE_API_TOKENhas expired or been revoked. Never add a second Pages workflow, sinceactions/deploy-pagesreplaces the whole site. Never re-run only a failed deploy job. Dispatch a fresh run. - The docs site (
/Vela/docs/) is the repository's Markdown built with MkDocs Material byscripts/build-docs-site.py --strictandsite/mkdocs.yml, toolchain pinned insite/requirements-docs.txt(MkDocs 2 drops the plugin and theme system). A page is published only if it is inPAGESand in the nav. No request leaves the site: system fonts, norepo_url, a local search index.?q=opens search. A push tomainthat changes Markdown,docs/**orsite/**redeploys.
Keys¶
The release keystore is outside the repository (~/.vela-signing/), with CI secrets
VELA_KEYSTORE_BASE64, VELA_KEYSTORE_PASSWORD, VELA_KEY_ALIAS. Losing it means installed
builds can never update. The certificate's SHA-256 is in README and FDROID.md
(apksigner verify --print-certs) and is not the F-Droid index fingerprint. The calibration key
is separate and also never committed. The MAPTILER_KEY secret reaches BuildConfig only.
Other workflows¶
weblate-automerge.ymlmerges a Weblate pull request once CI passes andscripts/weblate-automerge-check.pyfinds onlystrings.xmltranslations with matching placeholders. Anything else waits for a person. Off switch: repository variableWEBLATE_AUTOMERGE=off.security.ymlruns mobsfscan, exports an SBOM and reviews new dependencies on pull requests. Likeci.yml, it skips a push that only touches the docs.scorecard.ymlruns OpenSSF Scorecard. Neither gates a release. The SBOM export is tried three times and then ends in a warning: GitHub builds the file on request and can time out.- The canary publish step checks that
canarystill points at the commit it built. An overtaken build skips the publish. When the newer push changed a workflow file GitHub refused the older run's tag with HTTP 403 on every retry. issue-triage.ymlcomments on a new issue with earlier ones that share its wording and labels a bug report from an outdated buildincomplete. It never closes one.download-stats.ymlsnapshots release download counts, repository traffic and per-region asset counts weekly intodocs/stats(scripts/download-stats.sh). They are byproducts of hosting and they expire.docs/stats/README.mdsays how to read them.bake-conductor.ymlstarts the data bakes (section 7.3).fuel-gb.ymlpublishes the UK fuel prices hourly on its own cron (section 5.8), and opens an issue when their source stops updating.old-android-smoke.ymlinstalls a release build on Android 8.0 (API 26, the minimum) and Android 9 emulators and checks that it starts, loads Cronet, runs a search and opens a place without a crash. It runs every Sunday, the day before the weekly promotion to stable, from the Actions tab, and on a push to the branchold-android-smoke.review-feed-probe.ymlasks Google's review feed from a clean GitHub machine (a new address and session, nothing of the maintainer's) and uploads the raw replies. It runs from the Actions tab and on a push to the branchfeed-probe.- Those two branches are triggers. They hold no work of their own, so they read as fully merged; deleting one removes that way of starting its test and nothing else.
quarterly-data-refresh.ymldispatches the rebakes of the building, address and speed limit overlays every quarter. Routing is not in it, and place packs have their own monthly cron.
On a device¶
Build release at the installed build's version code (-PappVersionCode=), adb install -r,
then am force-stop before am start: installing over a running app keeps the old dex. Never
adb uninstall. It deletes saved trips and grants.
MapScreen size limits¶
MapScreen is at the JVM's 64 KB method limit and at ART's lower verifier limit. Direct
composable calls and their arguments count. Content lambdas do not.
- A debug compile failing with "method too large" is fixed by moving a call with a long argument list into a private composable.
- Past the verifier's limit the release build compiles and fails on the phone:
VerifyError: Verifier rejected classat launch on Android 14, and on Android 16MapScreenstops recomposing after its first frame with nothing logged. After changing its direct calls, install a release build and read the log forVerifyError, or dispatchold-android-smoke.yml. - Split out so far, private composables in
MapScreen.kt:MapSurface,BoxScope.BuildingDebugBadge,BoxScope.NavTurnBanner,SearchEntryHost,PipNavOverlay. A split block takes its locals as parameters, and a value one child needs is resolved in the child (isMapDark()inMapSurfaceandScaleBarReader).
16. Where the rest lives¶
| File | Holds |
|---|---|
README.md |
What Vela is, what reaches Google, install |
FEATURES.md |
A short list of what the app does |
SPEC.md |
This reference |
docs/README.md |
The docs site's index page |
docs/book/ |
Each subsystem explained, 13 chapters |
ROADMAP.md, docs/ROADMAP-HISTORY.md |
Open work; what shipped or was dropped |
PRIVACY.md |
What each service receives |
SECURITY.md |
Security checks, reporting a vulnerability |
CONTRIBUTING.md |
How to contribute |
FDROID.md |
The F-Droid repository |
CLAUDE.md |
Maintainer rules and traps |
docs/FAQ.md |
First questions |
docs/BUILDING.md |
Building from source |
docs/TRANSLATING.md |
Languages and translating |
docs/dpad.md |
Use without a touchscreen |
docs/ANDROID-AUTO.md |
Android Auto for users |