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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/development/delivery.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Android build verification

## Unreleased: navigation buildings

Navigation now shows restrained grey building volumes from zoom 17, using the existing OpenFreeMap tiles. Heights can come from mapped height tags or estimates from floor counts; they are approximate map context, not surveyed measurements. The 5 m tile default is excluded conservatively, also hiding genuine 5 m buildings. Browsing, planning, transit rides and route overview at every zoom keep flat footprints. No provider, dependency, permission or native code changed.

Android 16 AOSP development-client evidence with 1 Hz synthetic walking fixes covers building rendering beside a central Turin route, visible route/casing, junction arrow and puck, live light/dark changes, panning, overview/recenter and Stop returning to flat planning. Screenshots and a recording are retained outside Git. Unit regressions cover guidance modes and the close-zoom overview bug (red before the fix, green after). Physical-device readability, GPS, frame pacing and battery remain field checks; cycling/driving and transit walking rendering have not been separately replayed for this increment. The emulator's sparse Android UI frame sample does not establish map-renderer performance or physical smoothness.

Next beta field checklist: compare buildings and route visibility in both themes; check a short-route overview stays flat; pan/recenter and stop guidance; check street recognition, outdoor readability and sustained performance.

## Field-test pre-release: 0.2.0-beta.2

Version **0.2.0-beta.2 / Android code 13** is a second GitHub pre-release (not marked latest). It adds first-person guidance: an app-controlled, course-up, pitched follow camera driven only by accepted native fixes, an original directional puck, turn framing ahead of each maneuver, a maneuver banner with glyphs and "Poi …", a compact bottom strip, traveled/remaining route rendering with a junction arrow, and a walking camera for transit access walks. Emulator replays verified anchor placement, framing timing, stationary stability, pan/recenter intent and degraded states; physical GPS course quality, frame pacing, screen-off guidance, voice timing and battery remain field-test checks. The navigation source archive is unchanged (same SHA-256).
Expand Down
2 changes: 2 additions & 0 deletions docs/development/navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ The camera planner (`src/features/navigation/guidance-camera.ts`) produces one f

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

Navigation buildings (`avoid_building_3d` in `src/theme/brand-basemap.ts`) are a hidden native MapLibre `fill-extrusion` layer that guidance makes visible through the same adopted-layer mechanism as the one-way chevrons (`src/features/map/guidance-basemap.ts`). They show in road guidance and transit walks, including free-camera and paused road guidance, but are explicitly hidden in overview, start at zoom 17, fade in over half a zoom level to at most 55% opacity and use one grey per scheme; the tiles' `colour` field is ignored. Height provenance: OpenFreeMap tiles come from Planetiler's OpenMapTiles profile, whose `building` layer carries only `render_height`, `render_min_height`, `colour` and `hide_3d`. `render_height` is `ceil(height ?? building:height ?? building:levels × 3.66 ?? 5)`, so a building without any height or level tag arrives as exactly 5 m, with no field naming the source. The filter drops every feature at 5 m (the default, plus the few real 4–5 m heights, which stay flat), non-numeric or missing fields, tops not above their base and `hide_3d` outlines. No height is ever invented for a missing value. The schema cannot separate measured `height` tags from level-derived approximations (3.66 m per supplied level); both are extruded. The flat footprint layer stays beneath at every zoom. Route visibility comes from layer order: the extrusion sits directly after the flat footprints and before boundaries and labels, the guidance route, casing and junction arrow are inserted before `highway-name-path`, and the map puck, markers and the follow-mode puck image come later still. The pinned MapLibre Native renderer disables depth testing for 2D layers after the first 3D layer (see `PaintParameters::depthModeForSublayer` in Native 13.6.1); this supports placing route layers after the extrusion. Layer-order fixtures alone do not establish actual Android visibility. The order, filter, fade, greyscale and contrast are fixture-tested (`src/theme/map-style.test.ts`, `src/features/map/guidance-basemap.test.ts`). Rendering, occlusion, frame pacing and theme switches with buildings visible need a device or emulator check.

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

## Android acceptance
Expand Down
2 changes: 1 addition & 1 deletion docs/development/ux.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Road guidance is first-person: a flush banner in the chrome colour on top, the m

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

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

Expand Down
2 changes: 2 additions & 0 deletions docs/research/online-services.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ The [privacy policy](https://openfreemap.org/privacy/), updated October 8, 2026,

On 2026-11-01, the Liberty, Positron, Bright, Dark and Fiord style documents at `https://tiles.openfreemap.org/styles/<name>` returned HTTP 200. All five reference the same `openmaptiles` vector TileJSON, versioned sprites and Noto Sans glyphs. The TileJSON supplies the attribution string **OpenFreeMap © OpenMapTiles Data from OpenStreetMap**. The [styles repository](https://github.com/hyperknot/openfreemap-styles) is MIT-licensed. Upstream designs are BSD-3-Clause code with CC BY 4.0 design; Liberty's look and feel is inherited from Mapbox Open Styles under CC BY 3.0, and Positron derives from CC BY 3.0 CartoDB Basemaps. The app bundles Liberty verbatim, with its hash, and derives its light and dark brand styles from it through a documented transform; tiles, sprites and glyphs remain remote. See the [bundled-style notice](../../src/theme/map-styles/NOTICE.md). The README marks Dark and Fiord as unmodified upstream forks, outside the Quick Start set.

Building heights: on 2026-11-02 the TileJSON (tile build `20261025_080012_pt`) listed only `colour`, `hide_3d`, `render_height` and `render_min_height` for the `building` layer, at zooms 13–14 (overzoomed beyond). OpenFreeMap pins Planetiler commit `655572f3`, whose OpenMapTiles submodule (`60b0ea87`) computes `render_height = ceil(height ?? building:height ?? building:levels × 3.66 ?? 5)` and `render_min_height = floor(min_height ?? building:min_level × 3.66 ?? 0)`. A missing height is therefore a 5 m default indistinguishable by field from a supplied 5 m. Level-derived heights are approximations, also not marked. Four decoded central Turin z14 tiles contained only these fields; 8 of 132 merged building features carried exactly 5 m. The app's navigation extrusion excludes 5 m rather than inventing provenance ([navigation](../development/navigation.md#first-person-guidance-presentation)).

Direct HTTP page reads returned 403 during research, but the official site/privacy policy loaded in a browser. This is not an observed failure of map tiles. Integration instructions: https://openfreemap.org/quick_start/ . Actual native rendering remains a build test.

## Photon: geocoding
Expand Down
14 changes: 8 additions & 6 deletions src/features/map/GuidanceMapLayers.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@ import type { MapColors } from '../../theme';
import type { ColorScheme } from '../../theme/palette';
import type { ManeuverArrow } from '../navigation/guidance-route';
import { remainingGradient } from '../navigation/guidance-route';
import { BUILDING_EXTRUSION_LAYER, GUIDANCE_ROUTE_BEFORE as BELOW_LABELS, type GuidanceBasemap } from './guidance-basemap';

/** Route and turn arrow sit under street names, so labels stay readable over the line. */
const BELOW_LABELS = 'highway-name-path';
/** Generic business dots and labels: hidden while driving or cycling; street names stay. */
const POI_LAYERS: { id: string; type: 'circle' | 'symbol' }[] = [
{ id: 'avoid_poi_dot_r1', type: 'circle' }, { id: 'avoid_poi_dot_r7', type: 'circle' }, { id: 'avoid_poi_dot_r20', type: 'circle' },
Expand All @@ -16,18 +15,21 @@ const POI_LAYERS: { id: string; type: 'circle' | 'symbol' }[] = [

const EMPTY = { type: 'FeatureCollection' as const, features: [] };
/**
* Basemap adjustments during guidance: generic business dots and labels hidden while driving or
* cycling, one-way chevrons (a hidden brand-basemap layer) shown while driving. The style layers are
* adopted as children of an empty app source because MapLibre RN re-adds sources, and with them
* Basemap adjustments during guidance (see `guidanceBasemap`): generic business dots and labels hidden
* while driving or cycling, one-way chevrons shown while driving and supplied-height building extrusions
* shown under the first-person camera; the last two are hidden brand-basemap layers. The style layers
* are adopted as children of an empty app source because MapLibre RN re-adds sources, and with them
* their layers, after every style load (a live theme switch); standalone adopted layers would go stale.
* This component stays mounted: unmounting an adopted layer removes it from the style.
*/
export function BasemapGuidanceAdjustments({ reduceBusinesses, oneWayArrows }: { reduceBusinesses: boolean; oneWayArrows: boolean }) {
export function BasemapGuidanceAdjustments({ reduceBusinesses, oneWayArrows, buildings }: GuidanceBasemap) {
const visibility = reduceBusinesses ? 'none' : 'visible';
return <GeoJSONSource id="avoid-basemap-adjustments" data={EMPTY}>
{POI_LAYERS.map(layer => layer.type === 'circle'
? <Layer key={layer.id} id={layer.id} type="circle" layout={{ visibility }} />
: <Layer key={layer.id} id={layer.id} type="symbol" layout={{ visibility }} />)}
<Layer id="avoid_oneway" type="symbol" layout={{ visibility: oneWayArrows ? 'visible' : 'none' }} />
<Layer id={BUILDING_EXTRUSION_LAYER} type="fill-extrusion" layout={{ visibility: buildings ? 'visible' : 'none' }} />
</GeoJSONSource>;
}

Expand Down
3 changes: 2 additions & 1 deletion src/features/map/MapCanvas.native.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { createOnceFraming, createRouteFraming, frameCamera } from './map-presen
import { lineLayout, markerLabelLayout, overlayPaint } from './map-overlay-style';
import { GUIDANCE_IMAGES, puckImage, puckLayout } from './guidance-puck';
import { BasemapGuidanceAdjustments, GuidanceRouteLayers } from './GuidanceMapLayers';
import { guidanceBasemap } from './guidance-basemap';
import { useGuidanceCameraDriver } from './useGuidanceCameraDriver';
import { createOrientationReset } from './orientation-reset';

Expand Down Expand Up @@ -100,7 +101,7 @@ export default function MapCanvas({ center, zoom = 14.5, cameraRevision, routeFi
<Layer id="local-coverage-fill" type="fill" paint={paint.coverageFill} />
<Layer id="local-coverage-line" type="line" paint={paint.coverageLine} />
</GeoJSONSource>}
<BasemapGuidanceAdjustments reduceBusinesses={guidance?.mode === 'car' || guidance?.mode === 'bicycle'} oneWayArrows={guidance?.mode === 'car'} />
<BasemapGuidanceAdjustments {...guidanceBasemap(guidance)} />
{route && guidance?.route ? <GuidanceRouteLayers route={route} fraction={guidance.route.fraction} arrow={guidance.route.arrow} colors={theme.map} scheme={theme.scheme} /> : null}
{route && !guidance?.route && <GeoJSONSource id="journey" data={{ type: 'Feature', geometry: route, properties: {} }}>
<Layer id="journey-casing" type="line" paint={paint.routeCasing} layout={lineLayout} />
Expand Down
40 changes: 40 additions & 0 deletions src/features/map/guidance-basemap.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { mapStyleFor } from '../../theme/map-style';
import { BUILDING_EXTRUSION_LAYER, GUIDANCE_ROUTE_BEFORE, guidanceBasemap } from './guidance-basemap';

test('browsing and planning keep the basemap flat and complete', () => {
for (const guidance of [null, undefined]) {
assert.deepEqual(guidanceBasemap(guidance), { reduceBusinesses: false, oneWayArrows: false, buildings: false });
}
});

test('first-person guidance shows approximate buildings in every camera mode', () => {
assert.deepEqual(guidanceBasemap({ mode: 'walk', intent: 'follow' }), { reduceBusinesses: false, oneWayArrows: false, buildings: true });
assert.deepEqual(guidanceBasemap({ mode: 'bicycle', intent: 'follow' }), { reduceBusinesses: true, oneWayArrows: false, buildings: true });
assert.deepEqual(guidanceBasemap({ mode: 'car', intent: 'follow' }), { reduceBusinesses: true, oneWayArrows: true, buildings: true });
});

test('a transit ride framed without a walking camera stays flat', () => {
assert.deepEqual(guidanceBasemap({ mode: null, intent: 'follow' }), { reduceBusinesses: false, oneWayArrows: false, buildings: false });
});

test('the adopted layer and the route anchor exist in both basemaps, in drawing order', () => {
for (const scheme of ['light', 'dark'] as const) {
const ids = mapStyleFor(scheme).layers.map(layer => layer.id);
assert.ok(ids.includes(BUILDING_EXTRUSION_LAYER) && ids.includes(GUIDANCE_ROUTE_BEFORE));
assert.ok(ids.indexOf(BUILDING_EXTRUSION_LAYER) < ids.indexOf(GUIDANCE_ROUTE_BEFORE), 'the route is drawn after the buildings');
}
});

test('overview stays flat even when a short remaining route fits above z17', () => {
for (const mode of ['walk', 'bicycle', 'car'] as const) {
assert.equal(guidanceBasemap({ mode, intent: 'follow' }).buildings, true);
assert.equal(guidanceBasemap({ mode, intent: 'overview' }).buildings, false);
assert.equal(guidanceBasemap({ mode, intent: 'follow' }).buildings, true, 'recenter restores navigation buildings');
}
});

test('panning during navigation keeps static buildings available', () => {
assert.equal(guidanceBasemap({ mode: 'walk', intent: 'free' }).buildings, true);
});
21 changes: 21 additions & 0 deletions src/features/map/guidance-basemap.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import type { GuidanceMapState } from '../navigation/useGuidanceCamera';

/** Guidance route, casing and turn arrow sit directly before street names, so labels stay readable over the line. */
export const GUIDANCE_ROUTE_BEFORE = 'highway-name-path';
/** The brand basemap's hidden navigation-only approximate building extrusion. */
export const BUILDING_EXTRUSION_LAYER = 'avoid_building_3d';

export interface GuidanceBasemap {
/** Generic business dots and labels hidden while driving or cycling; street names stay. */
reduceBusinesses: boolean;
/** One-way chevrons while driving. */
oneWayArrows: boolean;
/** Navigation buildings in road modes and transit walks; overview stays flat. */
buildings: boolean;
}

/** Basemap adjustments for the current guidance state; browsing and planning keep the flat, complete basemap. */
export function guidanceBasemap(guidance: Pick<GuidanceMapState, 'mode' | 'intent'> | null | undefined): GuidanceBasemap {
const mode = guidance?.mode ?? null;
return { reduceBusinesses: mode === 'car' || mode === 'bicycle', oneWayArrows: mode === 'car', buildings: mode !== null && guidance?.intent !== 'overview' };
}
Loading
Loading