From cf11fb1a751540fcad2faf87e733c44d20217110 Mon Sep 17 00:00:00 2001 From: Francesco Castrovilli <27171200+fcastrovilli@users.noreply.github.com> Date: Mon, 2 Nov 2026 12:54:07 +0100 Subject: [PATCH 1/3] Show supplied-height buildings during first-person guidance A hidden native fill-extrusion layer (avoid_building_3d) from zoom 17, made visible by guidance through the adopted-layer mechanism used for one-way chevrons. Browsing, planning and transit rides stay flat. OpenFreeMap's Planetiler OpenMapTiles profile writes render_height as ceil(height ?? building:height ?? levels * 3.66 ?? 5) with no provenance field, so the filter drops the 5 m default bucket, missing or non-numeric fields, tops not above their base and hide_3d outlines. Flat footprints stay beneath at every zoom. The extrusion sits after the flat footprints and before boundaries, labels and the guidance route anchor, so the route, junction arrow, puck and labels are drawn over buildings. --- docs/development/navigation.md | 2 + docs/development/ux.md | 2 +- docs/research/online-services.md | 2 + src/features/map/GuidanceMapLayers.tsx | 14 +++-- src/features/map/MapCanvas.native.tsx | 3 +- src/features/map/guidance-basemap.test.ts | 28 +++++++++ src/features/map/guidance-basemap.ts | 21 +++++++ src/theme/brand-basemap.ts | 46 +++++++++++++- src/theme/map-style.test.ts | 75 +++++++++++++++++++++++ src/theme/map-styles/NOTICE.md | 1 + src/theme/map-styles/notices.json | 2 +- 11 files changed, 185 insertions(+), 11 deletions(-) create mode 100644 src/features/map/guidance-basemap.test.ts create mode 100644 src/features/map/guidance-basemap.ts diff --git a/docs/development/navigation.md b/docs/development/navigation.md index b8de3aa..6dfb7a6 100644 --- a/docs/development/navigation.md +++ b/docs/development/navigation.md @@ -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 whenever the first-person camera runs (road modes and transit walks with a usable fix), 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. MapLibre draws style layers in order, so these later layers paint over buildings; the guarantee is this order, not depth testing. 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 diff --git a/docs/development/ux.md b/docs/development/ux.md index b7eacc5..0a91bf1 100644 --- a/docs/development/ux.md +++ b/docs/development/ux.md @@ -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 the first-person camera (road modes and transit walks) shows subtle grey building volumes, only for buildings whose tiles carry a supplied height; others stay flat footprints. The route, junction arrow, puck and labels are drawn over buildings and never hidden behind them. Browsing, planning, overview zooms 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). diff --git a/docs/research/online-services.md b/docs/research/online-services.md index 6dc01df..ab9963b 100644 --- a/docs/research/online-services.md +++ b/docs/research/online-services.md @@ -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/` 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 diff --git a/src/features/map/GuidanceMapLayers.tsx b/src/features/map/GuidanceMapLayers.tsx index a863970..034fffe 100644 --- a/src/features/map/GuidanceMapLayers.tsx +++ b/src/features/map/GuidanceMapLayers.tsx @@ -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' }, @@ -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 {POI_LAYERS.map(layer => layer.type === 'circle' ? : )} + ; } diff --git a/src/features/map/MapCanvas.native.tsx b/src/features/map/MapCanvas.native.tsx index 2fe9b4c..176a42d 100644 --- a/src/features/map/MapCanvas.native.tsx +++ b/src/features/map/MapCanvas.native.tsx @@ -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'; @@ -100,7 +101,7 @@ export default function MapCanvas({ center, zoom = 14.5, cameraRevision, routeFi } - + {route && guidance?.route ? : null} {route && !guidance?.route && diff --git a/src/features/map/guidance-basemap.test.ts b/src/features/map/guidance-basemap.test.ts new file mode 100644 index 0000000..ec7011f --- /dev/null +++ b/src/features/map/guidance-basemap.test.ts @@ -0,0 +1,28 @@ +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 supplied-height buildings in every camera mode', () => { + assert.deepEqual(guidanceBasemap({ mode: 'walk' }), { reduceBusinesses: false, oneWayArrows: false, buildings: true }); + assert.deepEqual(guidanceBasemap({ mode: 'bicycle' }), { reduceBusinesses: true, oneWayArrows: false, buildings: true }); + assert.deepEqual(guidanceBasemap({ mode: 'car' }), { reduceBusinesses: true, oneWayArrows: true, buildings: true }); +}); + +test('a transit ride framed without a walking camera stays flat', () => { + assert.deepEqual(guidanceBasemap({ mode: null }), { 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'); + } +}); diff --git a/src/features/map/guidance-basemap.ts b/src/features/map/guidance-basemap.ts new file mode 100644 index 0000000..2481a4f --- /dev/null +++ b/src/features/map/guidance-basemap.ts @@ -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 extrusion of supplied building heights. */ +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; + /** Supplied-height buildings while the first-person camera runs (road modes and transit walks). */ + buildings: boolean; +} + +/** Basemap adjustments for the current guidance state; browsing and planning keep the flat, complete basemap. */ +export function guidanceBasemap(guidance: Pick | null | undefined): GuidanceBasemap { + const mode = guidance?.mode ?? null; + return { reduceBusinesses: mode === 'car' || mode === 'bicycle', oneWayArrows: mode === 'car', buildings: mode !== null }; +} diff --git a/src/theme/brand-basemap.ts b/src/theme/brand-basemap.ts index dacf8f0..652b998 100644 --- a/src/theme/brand-basemap.ts +++ b/src/theme/brand-basemap.ts @@ -21,6 +21,8 @@ export interface BasemapInk { waterLabel: string; building: string; buildingEdge: string; + /** Navigation-only extrusions of supplied building heights (see `suppliedHeight`). */ + buildingExtrusion: string; /** Pedestrian squares and areas. */ plaza: string; path: string; @@ -70,6 +72,7 @@ export const basemapInks: Record = { waterLabel: '#92959C', building: '#141416', buildingEdge: '#1A1A1D', + buildingExtrusion: '#1C1C1F', plaza: '#1A1A1D', path: '#3A3A40', pathCasing: '#1A1A1D', @@ -113,6 +116,7 @@ export const basemapInks: Record = { waterLabel: '#52565C', building: '#E9E9E8', buildingEdge: '#DCDCDB', + buildingExtrusion: '#E3E3E2', plaza: '#ECECEB', path: '#C6C6CB', pathCasing: '#FFFFFF', @@ -182,6 +186,26 @@ const transitClass = ['match', poiClass, ['bus', 'railway'], true, false]; /** Generic POIs need a name or a key category; unnamed benches, bins and bollards add only noise. */ const visiblePoi = ['all', ['!', transitClass], ['any', ['has', 'name'], hasCategory]]; +/** + * Buildings whose OpenMapTiles height comes from supplied OSM data. planetiler-openmaptiles (which builds + * the OpenFreeMap tiles) writes `render_height = ceil(height ?? building:height ?? building:levels × 3.66 ?? 5)` + * and `render_min_height = floor(min_height ?? building:min_level × 3.66 ?? 0)`, with no field naming the + * source. A missing height therefore always arrives as exactly 5. Supplied data reaches 5 only through a + * mapped height above 4 m up to 5 m or a fractional level count (one level is 4, two are 8). Excluding + * 5 drops every default and those few real low buildings, which stay flat footprints. Levels-derived + * heights are an approximation from supplied levels, not a default; the schema cannot separate them from + * measured heights. `hide_3d` marks outlines whose `building:part`s carry the shape. + */ +export const suppliedHeight = ['all', + ['!', ['has', 'hide_3d']], + ['==', ['typeof', ['get', 'render_height']], 'number'], + ['==', ['typeof', ['get', 'render_min_height']], 'number'], + ['!=', ['get', 'render_height'], 5], + ['>', ['get', 'render_height'], ['get', 'render_min_height']], +]; +/** Navigation buildings appear only at the close first-person zooms, fading in over half a zoom level. */ +export const BUILDING_EXTRUSION_MINZOOM = 17; + const regular = ['Noto Sans Regular']; const bold = ['Noto Sans Bold']; const linear = (stops: number[]) => ['interpolate', ['linear'], ['zoom'], ...stops]; @@ -239,13 +263,30 @@ export function brandRecipe(scheme: ColorScheme): StyleRecipe { 'natural_earth', // One-way arrows matter to drivers, not to pedestrians or passengers. 'road_one_way_arrow', 'road_one_way_arrow_opposite', - // Extrusions shade buildings into the foreground; flat footprints stay at every zoom instead. + // Upstream extrudes every building, the 5 m default included; `avoid_building_3d` replaces it. 'building-3d', // United States shields never match Italian roads and draw coloured sprite badges. 'highway-shield-us-interstate', 'road_shield_us', ], keep: [], insert: [ + { + // Navigation only (hidden otherwise): subtle grey extrusions of supplied heights over the flat + // footprints. Drawn before road names, so the guidance route, its junction arrow and every app + // overlay (all later in the layer order) are painted over buildings, never hidden behind them. + before: 'boundary_3', + layer: { + id: 'avoid_building_3d', type: 'fill-extrusion', source: 'openmaptiles', 'source-layer': 'building', + minzoom: BUILDING_EXTRUSION_MINZOOM, filter: suppliedHeight, + layout: { visibility: 'none' }, + paint: { + 'fill-extrusion-color': ink.buildingExtrusion, + 'fill-extrusion-height': ['get', 'render_height'], + 'fill-extrusion-base': ['get', 'render_min_height'], + 'fill-extrusion-opacity': linear([BUILDING_EXTRUSION_MINZOOM, 0, BUILDING_EXTRUSION_MINZOOM + 0.5, 0.55]), + }, + }, + }, { // Driving guidance shows one-way chevrons (app image `oneway-`); hidden otherwise. before: 'highway-name-path', @@ -374,7 +415,8 @@ export function brandRecipe(scheme: ColorScheme): StyleRecipe { bridge_transit_rail: line(ink.transit), bridge_transit_rail_hatching: line(ink.transit), - // Upstream hands footprints over to `building-3d` at z14; flat footprints continue instead. + // Upstream hands footprints over to `building-3d` at z14; flat footprints continue at every zoom, + // also beneath navigation extrusions, so buildings without a supplied height still show. building: { ...fill(ink.building, { 'fill-outline-color': ink.buildingEdge }), maxzoom: null }, boundary_3: line(ink.boundary), boundary_2: line(ink.boundary), diff --git a/src/theme/map-style.test.ts b/src/theme/map-style.test.ts index d32e597..1968acd 100644 --- a/src/theme/map-style.test.ts +++ b/src/theme/map-style.test.ts @@ -234,3 +234,78 @@ test('one-way chevrons cover both directions: oneway 1 along the line, -1 turned assert.equal(rotate.value.evaluate({ zoom: 16 }, feature(-1)), 270); } }); + +/** The guidance route, its casing and the junction arrow are inserted directly before this basemap layer. */ +const ROUTE_ANCHOR = 'highway-name-path'; +const EXTRUSION = 'avoid_building_3d'; + +test('navigation buildings: a hidden, greyscale extrusion from z17 above flat footprints and below the route', () => { + for (const scheme of schemes) { + const style = mapStyleFor(scheme); + const ids = style.layers.map(layer => layer.id); + const layer = layerOf(style, EXTRUSION); + assert.ok(layer, `${scheme} defines ${EXTRUSION}`); + assert.equal(layer.type, 'fill-extrusion'); + assert.equal(layer.source, 'openmaptiles'); + assert.equal(layer['source-layer'], 'building'); + assert.ok((layer.minzoom ?? 0) >= 17, 'extrusions start at z17 or later'); + assert.equal(layer.layout?.visibility, 'none', 'hidden until navigation shows it: browsing and planning stay flat'); + assert.ok(!ids.includes('building-3d'), 'the unfiltered upstream extrusion stays removed'); + // Flat footprints remain at every zoom, so a building without a supplied height still shows. + assert.equal(layerOf(style, 'building')?.maxzoom, undefined); + assert.ok(ids.indexOf('building') < ids.indexOf(EXTRUSION), 'extrusions stand on the flat footprints'); + // MapLibre draws later layers over earlier ones, so the route and arrow (inserted before the + // anchor) and every app overlay appended after the basemap are never hidden by a building. + assert.ok(ids.indexOf(EXTRUSION) < ids.indexOf(ROUTE_ANCHOR), 'extrusions are drawn before the route anchor'); + assert.ok(ids.indexOf(EXTRUSION) < ids.indexOf('highway-name-minor') && ids.indexOf(EXTRUSION) < ids.indexOf('poi_r20'), 'labels stay above buildings'); + // Greyscale and uniform: the OpenMapTiles `colour` field never tints a building. + const color = layer.paint?.['fill-extrusion-color']; + assert.equal(typeof color, 'string'); + assert.equal(String(color).toLowerCase(), basemapInks[scheme].buildingExtrusion.toLowerCase()); + assert.ok(!JSON.stringify(layer.paint).includes('colour')); + assert.deepEqual(layer.paint?.['fill-extrusion-height'], ['get', 'render_height']); + assert.deepEqual(layer.paint?.['fill-extrusion-base'], ['get', 'render_min_height']); + const opacity = createExpression(layer.paint?.['fill-extrusion-opacity'], latest['paint_fill-extrusion']['fill-extrusion-opacity'] as never); + assert.equal(opacity.result, 'success'); + if (opacity.result !== 'success') continue; + const at = (zoom: number) => opacity.value.evaluate({ zoom }, undefined as never) as number; + assert.ok(at(17) <= 0.05 && at(18) > 0.3 && at(20) <= 0.7, `${scheme} extrusions fade in and stay translucent: ${at(17)}, ${at(18)}, ${at(20)}`); + } +}); + +test('navigation buildings extrude only supplied heights, never the OpenMapTiles 5 m default', () => { + // planetiler-openmaptiles Building.java: render_height = ceil(height ?? building:height ?? levels * 3.66 ?? 5), + // render_min_height = floor(min_height ?? min_level * 3.66 ?? 0). A missing height therefore arrives as + // exactly 5; height tags and levels are integers other than 5 (one level is 4, two are 8). + const layer = layerOf(mapStyleFor('light'), EXTRUSION); + const filter = createExpression(layer?.filter, { type: 'boolean' } as never); + assert.equal(filter.result, 'success'); + if (filter.result !== 'success') return; + const extruded = (properties: Record) => filter.value.evaluate({ zoom: 18 }, { type: 'Polygon', properties } as never); + assert.equal(extruded({ render_height: 5, render_min_height: 0 }), false, 'no height, building:height or levels: the 5 m default'); + assert.equal(extruded({ render_height: 5, render_min_height: 3 }), false, 'a part with only a minimum height keeps the default top'); + assert.equal(extruded({ render_height: 19, render_min_height: 0 }), true); + assert.equal(extruded({ render_height: 4, render_min_height: 0 }), true, 'one supplied level'); + assert.equal(extruded({ render_height: 31, render_min_height: 12 }), true, 'a building part above the ground'); + assert.equal(extruded({ render_height: 19, render_min_height: 0, hide_3d: true }), false, 'an outline whose parts carry the 3D shape'); + assert.equal(extruded({ render_min_height: 0 }), false, 'no height field'); + assert.equal(extruded({ render_height: 19 }), false, 'no base field'); + assert.equal(extruded({ render_height: '19', render_min_height: 0 }), false, 'non-numeric height'); + assert.equal(extruded({ render_height: 0, render_min_height: 0 }), false, 'zero height'); + assert.equal(extruded({ render_height: 8, render_min_height: 8 }), false, 'top not above base'); +}); + +for (const scheme of schemes) { + test(`avoid-${scheme}: the route, arrow and position stay readable over navigation buildings`, () => { + const ink = basemapInks[scheme]; + const overlay = mapColorsFor(scheme); + // The route line, the arrow outline (route-line colour) and the map puck's dot are drawn over buildings. + for (const [label, color] of [['route line', overlay.routeLine], ['location dot', overlay.userLocation]] as const) { + const ratio = contrastRatio(color, ink.buildingExtrusion); + assert.ok(ratio >= AA_NON_TEXT, `${scheme} ${label} on a building: ${ratio.toFixed(2)}`); + } + // Subtle: walls separate a little from the flat footprints and the land, never as strongly as roads. + const lift = contrastRatio(ink.buildingExtrusion, ink.land); + assert.ok(lift >= 1.05 && lift < contrastRatio(ink.minor, ink.land) + 0.2, `${scheme} building lift ${lift.toFixed(2)}`); + }); +} diff --git a/src/theme/map-styles/NOTICE.md b/src/theme/map-styles/NOTICE.md index 09f0d18..7b4f8c3 100644 --- a/src/theme/map-styles/NOTICE.md +++ b/src/theme/map-styles/NOTICE.md @@ -15,6 +15,7 @@ The file is the unmodified response body. At retrieval, [hyperknot/openfreemap-s - replace POI sprite icons with small circle layers and text, and transit icons with stop and station rings and text; key amenities show an Italian category word; - remove the place-dot, airport and road-shield sprite icons, keeping their text; - remove the shaded-relief raster, one-way arrows, 3D building extrusions and United States shield layers; flat building footprints continue at all zooms; +- add hidden layers that only active guidance shows: one-way chevrons drawn from an app image, and a greyscale building extrusion from zoom 17 limited to OpenMapTiles heights that do not equal the 5 m default written for buildings without height or level tags; - add dedicated stop and station layers for OpenMapTiles' `railway` POI class, which Liberty's transit layer does not match. Sources, tile URLs, sprite and glyph endpoints are unchanged. diff --git a/src/theme/map-styles/notices.json b/src/theme/map-styles/notices.json index 94de667..2a156c7 100644 --- a/src/theme/map-styles/notices.json +++ b/src/theme/map-styles/notices.json @@ -3,7 +3,7 @@ "id": "NOTICE.md", "title": "Stili della mappa: provenienza e modifiche", "url": "https://github.com/hyperknot/openfreemap-styles", - "text": "# Bundled basemap style\n\nThe app's two basemaps, `avoid-dark` and `avoid-light`, are derivative works of OpenFreeMap Liberty. The upstream document is bundled verbatim so a remote style edit cannot change the app's map, and both brand styles are generated from it in code at startup. Vector tiles, sprites, glyphs and the TileJSON attribution string still come from the public OpenFreeMap service at `tiles.openfreemap.org`; the map's attribution control continues to show **OpenFreeMap © OpenMapTiles Data from OpenStreetMap**.\n\n| File | Source URL | Retrieved | SHA-256 |\n| --- | --- | --- | --- |\n| `openfreemap-liberty.json` | https://tiles.openfreemap.org/styles/liberty | 2026-11-01 | `408245464e76791801a64393c403433d09e8110eb9516040f8dc2b62584eee2a` |\n\nThe file is the unmodified response body. At retrieval, [hyperknot/openfreemap-styles](https://github.com/hyperknot/openfreemap-styles) `main` was commit `006ea5796803ba2df4330888836cb0a8f17473b4`. `map-style.test.ts` checks this hash.\n\n**Modifications.** `brandRecipe` in [`../brand-basemap.ts`](../brand-basemap.ts) describes every change and `transformStyle` in [`../map-style-transform.ts`](../map-style-transform.ts) applies it. The recipe must account for every upstream layer (patched, kept or removed), and every property it replaces or drops must exist upstream, so a refreshed document with added, renamed or missing layers, or with changes to the properties the recipe touches, fails to build. Properties the recipe does not mention pass through; `map-style.test.ts` therefore also fails if any colour in the derived styles is outside the greyscale bound or any layer draws a sprite icon or pattern. The derived styles:\n\n- replace Liberty's colours with greyscale palettes (`basemapInks`), with a faint green hint on parks;\n- use local OpenStreetMap names instead of English names;\n- replace POI sprite icons with small circle layers and text, and transit icons with stop and station rings and text; key amenities show an Italian category word;\n- remove the place-dot, airport and road-shield sprite icons, keeping their text;\n- remove the shaded-relief raster, one-way arrows, 3D building extrusions and United States shield layers; flat building footprints continue at all zooms;\n- add dedicated stop and station layers for OpenMapTiles' `railway` POI class, which Liberty's transit layer does not match.\n\nSources, tile URLs, sprite and glyph endpoints are unchanged.\n\n## Licences\n\n- **OpenFreeMap styles repository:** MIT License, Copyright (c) 2023 Zsolt Ero.\n- **Liberty:** fork of [maputnik/osm-liberty](https://github.com/maputnik/osm-liberty), itself a fork of OSM Bright, derived from Mapbox Open Styles. Code: BSD 3-Clause. Design: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with the look and feel inherited from Mapbox Open Styles under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). The avoid maps styles adapt this design as described above.\n- **OpenMapTiles schema:** code BSD 3-Clause, design CC BY 4.0.\n- **Map data:** © OpenStreetMap contributors, [ODbL](https://www.openstreetmap.org/copyright).\n- **Fonts:** Noto Sans, SIL Open Font License 1.1. **Sprite:** Maki icons, CC0 1.0 (still referenced by the style; the derived layers draw no sprite images). **Natural Earth:** public domain (the derived styles no longer draw its raster).\n\nThe complete upstream licence texts, including copyright notices, redistribution conditions and disclaimers, are reproduced verbatim in [`LICENSES/`](LICENSES): `openfreemap-styles.md` (MIT), `osm-liberty.md` and `mapbox-gl-styles.md` (Liberty's BSD code licence, Mapbox Open Styles copyright (c) 2014 Mapbox, and its inherited CC BY 3.0 design notice). Retrieved 2026-11-01 from each repository's default branch. The app bundles this notice and these texts unchanged in `notices.json` and shows them offline under **Privacy e fonti › Fonti e licenze › Stili della mappa**; `map-style.test.ts` checks that the copies match these files.\n\nThese notices are separate from the application-source licence.\n" + "text": "# Bundled basemap style\n\nThe app's two basemaps, `avoid-dark` and `avoid-light`, are derivative works of OpenFreeMap Liberty. The upstream document is bundled verbatim so a remote style edit cannot change the app's map, and both brand styles are generated from it in code at startup. Vector tiles, sprites, glyphs and the TileJSON attribution string still come from the public OpenFreeMap service at `tiles.openfreemap.org`; the map's attribution control continues to show **OpenFreeMap © OpenMapTiles Data from OpenStreetMap**.\n\n| File | Source URL | Retrieved | SHA-256 |\n| --- | --- | --- | --- |\n| `openfreemap-liberty.json` | https://tiles.openfreemap.org/styles/liberty | 2026-11-01 | `408245464e76791801a64393c403433d09e8110eb9516040f8dc2b62584eee2a` |\n\nThe file is the unmodified response body. At retrieval, [hyperknot/openfreemap-styles](https://github.com/hyperknot/openfreemap-styles) `main` was commit `006ea5796803ba2df4330888836cb0a8f17473b4`. `map-style.test.ts` checks this hash.\n\n**Modifications.** `brandRecipe` in [`../brand-basemap.ts`](../brand-basemap.ts) describes every change and `transformStyle` in [`../map-style-transform.ts`](../map-style-transform.ts) applies it. The recipe must account for every upstream layer (patched, kept or removed), and every property it replaces or drops must exist upstream, so a refreshed document with added, renamed or missing layers, or with changes to the properties the recipe touches, fails to build. Properties the recipe does not mention pass through; `map-style.test.ts` therefore also fails if any colour in the derived styles is outside the greyscale bound or any layer draws a sprite icon or pattern. The derived styles:\n\n- replace Liberty's colours with greyscale palettes (`basemapInks`), with a faint green hint on parks;\n- use local OpenStreetMap names instead of English names;\n- replace POI sprite icons with small circle layers and text, and transit icons with stop and station rings and text; key amenities show an Italian category word;\n- remove the place-dot, airport and road-shield sprite icons, keeping their text;\n- remove the shaded-relief raster, one-way arrows, 3D building extrusions and United States shield layers; flat building footprints continue at all zooms;\n- add hidden layers that only active guidance shows: one-way chevrons drawn from an app image, and a greyscale building extrusion from zoom 17 limited to OpenMapTiles heights that do not equal the 5 m default written for buildings without height or level tags;\n- add dedicated stop and station layers for OpenMapTiles' `railway` POI class, which Liberty's transit layer does not match.\n\nSources, tile URLs, sprite and glyph endpoints are unchanged.\n\n## Licences\n\n- **OpenFreeMap styles repository:** MIT License, Copyright (c) 2023 Zsolt Ero.\n- **Liberty:** fork of [maputnik/osm-liberty](https://github.com/maputnik/osm-liberty), itself a fork of OSM Bright, derived from Mapbox Open Styles. Code: BSD 3-Clause. Design: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with the look and feel inherited from Mapbox Open Styles under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). The avoid maps styles adapt this design as described above.\n- **OpenMapTiles schema:** code BSD 3-Clause, design CC BY 4.0.\n- **Map data:** © OpenStreetMap contributors, [ODbL](https://www.openstreetmap.org/copyright).\n- **Fonts:** Noto Sans, SIL Open Font License 1.1. **Sprite:** Maki icons, CC0 1.0 (still referenced by the style; the derived layers draw no sprite images). **Natural Earth:** public domain (the derived styles no longer draw its raster).\n\nThe complete upstream licence texts, including copyright notices, redistribution conditions and disclaimers, are reproduced verbatim in [`LICENSES/`](LICENSES): `openfreemap-styles.md` (MIT), `osm-liberty.md` and `mapbox-gl-styles.md` (Liberty's BSD code licence, Mapbox Open Styles copyright (c) 2014 Mapbox, and its inherited CC BY 3.0 design notice). Retrieved 2026-11-01 from each repository's default branch. The app bundles this notice and these texts unchanged in `notices.json` and shows them offline under **Privacy e fonti › Fonti e licenze › Stili della mappa**; `map-style.test.ts` checks that the copies match these files.\n\nThese notices are separate from the application-source licence.\n" }, { "id": "LICENSES/openfreemap-styles.md", From ae272fc808c09ead2564fbc9701845fbbd7f341a Mon Sep 17 00:00:00 2001 From: Francesco Castrovilli <27171200+fcastrovilli@users.noreply.github.com> Date: Mon, 2 Nov 2026 13:06:51 +0100 Subject: [PATCH 2/3] Keep navigation overview flat at every zoom --- docs/development/navigation.md | 2 +- docs/development/ux.md | 2 +- src/features/map/guidance-basemap.test.ts | 20 ++++++++++++++++---- src/features/map/guidance-basemap.ts | 6 +++--- src/theme/brand-basemap.ts | 3 ++- src/theme/map-style.test.ts | 4 ++-- 6 files changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/development/navigation.md b/docs/development/navigation.md index 6dfb7a6..83cf853 100644 --- a/docs/development/navigation.md +++ b/docs/development/navigation.md @@ -35,7 +35,7 @@ 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 whenever the first-person camera runs (road modes and transit walks with a usable fix), 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. MapLibre draws style layers in order, so these later layers paint over buildings; the guarantee is this order, not depth testing. 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. +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. diff --git a/docs/development/ux.md b/docs/development/ux.md index 0a91bf1..90b5b26 100644 --- a/docs/development/ux.md +++ b/docs/development/ux.md @@ -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. From zoom 17 the first-person camera (road modes and transit walks) shows subtle grey building volumes, only for buildings whose tiles carry a supplied height; others stay flat footprints. The route, junction arrow, puck and labels are drawn over buildings and never hidden behind them. Browsing, planning, overview zooms and transit rides stay flat. +- **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 subtle grey building volumes, only for buildings whose tiles carry a supplied height; others 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). diff --git a/src/features/map/guidance-basemap.test.ts b/src/features/map/guidance-basemap.test.ts index ec7011f..44d7750 100644 --- a/src/features/map/guidance-basemap.test.ts +++ b/src/features/map/guidance-basemap.test.ts @@ -10,13 +10,13 @@ test('browsing and planning keep the basemap flat and complete', () => { }); test('first-person guidance shows supplied-height buildings in every camera mode', () => { - assert.deepEqual(guidanceBasemap({ mode: 'walk' }), { reduceBusinesses: false, oneWayArrows: false, buildings: true }); - assert.deepEqual(guidanceBasemap({ mode: 'bicycle' }), { reduceBusinesses: true, oneWayArrows: false, buildings: true }); - assert.deepEqual(guidanceBasemap({ mode: 'car' }), { reduceBusinesses: true, oneWayArrows: true, buildings: true }); + 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 }), { reduceBusinesses: false, oneWayArrows: false, buildings: false }); + 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', () => { @@ -26,3 +26,15 @@ test('the adopted layer and the route anchor exist in both basemaps, in drawing 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); +}); diff --git a/src/features/map/guidance-basemap.ts b/src/features/map/guidance-basemap.ts index 2481a4f..c9b35f1 100644 --- a/src/features/map/guidance-basemap.ts +++ b/src/features/map/guidance-basemap.ts @@ -10,12 +10,12 @@ export interface GuidanceBasemap { reduceBusinesses: boolean; /** One-way chevrons while driving. */ oneWayArrows: boolean; - /** Supplied-height buildings while the first-person camera runs (road modes and transit walks). */ + /** 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 | null | undefined): GuidanceBasemap { +export function guidanceBasemap(guidance: Pick | null | undefined): GuidanceBasemap { const mode = guidance?.mode ?? null; - return { reduceBusinesses: mode === 'car' || mode === 'bicycle', oneWayArrows: mode === 'car', buildings: mode !== null }; + return { reduceBusinesses: mode === 'car' || mode === 'bicycle', oneWayArrows: mode === 'car', buildings: mode !== null && guidance?.intent !== 'overview' }; } diff --git a/src/theme/brand-basemap.ts b/src/theme/brand-basemap.ts index 652b998..5edc69f 100644 --- a/src/theme/brand-basemap.ts +++ b/src/theme/brand-basemap.ts @@ -273,7 +273,8 @@ export function brandRecipe(scheme: ColorScheme): StyleRecipe { { // Navigation only (hidden otherwise): subtle grey extrusions of supplied heights over the flat // footprints. Drawn before road names, so the guidance route, its junction arrow and every app - // overlay (all later in the layer order) are painted over buildings, never hidden behind them. + // overlay follow the extrusion. Native disables depth testing for subsequent 2D layers; + // verify actual route visibility on Android rather than inferring it from this order alone. before: 'boundary_3', layer: { id: 'avoid_building_3d', type: 'fill-extrusion', source: 'openmaptiles', 'source-layer': 'building', diff --git a/src/theme/map-style.test.ts b/src/theme/map-style.test.ts index 1968acd..2f96f42 100644 --- a/src/theme/map-style.test.ts +++ b/src/theme/map-style.test.ts @@ -254,8 +254,8 @@ test('navigation buildings: a hidden, greyscale extrusion from z17 above flat fo // Flat footprints remain at every zoom, so a building without a supplied height still shows. assert.equal(layerOf(style, 'building')?.maxzoom, undefined); assert.ok(ids.indexOf('building') < ids.indexOf(EXTRUSION), 'extrusions stand on the flat footprints'); - // MapLibre draws later layers over earlier ones, so the route and arrow (inserted before the - // anchor) and every app overlay appended after the basemap are never hidden by a building. + // Native disables depth testing for 2D layers after the first 3D layer. Keep the route and + // arrow after the extrusion; actual Android compositing still needs visual verification. assert.ok(ids.indexOf(EXTRUSION) < ids.indexOf(ROUTE_ANCHOR), 'extrusions are drawn before the route anchor'); assert.ok(ids.indexOf(EXTRUSION) < ids.indexOf('highway-name-minor') && ids.indexOf(EXTRUSION) < ids.indexOf('poi_r20'), 'labels stay above buildings'); // Greyscale and uniform: the OpenMapTiles `colour` field never tints a building. From 6b5bccc2fc05e57df7ca540e644a3daafd1b53e4 Mon Sep 17 00:00:00 2001 From: Francesco Castrovilli <27171200+fcastrovilli@users.noreply.github.com> Date: Mon, 2 Nov 2026 13:21:37 +0100 Subject: [PATCH 3/3] Document approximate building heights and native verification --- docs/development/delivery.md | 8 ++++++++ docs/development/ux.md | 2 +- src/features/map/guidance-basemap.test.ts | 2 +- src/features/map/guidance-basemap.ts | 2 +- src/theme/brand-basemap.ts | 10 +++++----- src/theme/map-style.test.ts | 2 +- src/theme/map-styles/NOTICE.md | 2 +- src/theme/map-styles/notices.json | 2 +- 8 files changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/development/delivery.md b/docs/development/delivery.md index b655f24..483518e 100644 --- a/docs/development/delivery.md +++ b/docs/development/delivery.md @@ -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). diff --git a/docs/development/ux.md b/docs/development/ux.md index 90b5b26..de8bd57 100644 --- a/docs/development/ux.md +++ b/docs/development/ux.md @@ -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. From zoom 17 road guidance and transit walks (including a freely panned or paused road map) show subtle grey building volumes, only for buildings whose tiles carry a supplied height; others 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. +- **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). diff --git a/src/features/map/guidance-basemap.test.ts b/src/features/map/guidance-basemap.test.ts index 44d7750..ccf9802 100644 --- a/src/features/map/guidance-basemap.test.ts +++ b/src/features/map/guidance-basemap.test.ts @@ -9,7 +9,7 @@ test('browsing and planning keep the basemap flat and complete', () => { } }); -test('first-person guidance shows supplied-height buildings in every camera mode', () => { +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 }); diff --git a/src/features/map/guidance-basemap.ts b/src/features/map/guidance-basemap.ts index c9b35f1..fbd73bc 100644 --- a/src/features/map/guidance-basemap.ts +++ b/src/features/map/guidance-basemap.ts @@ -2,7 +2,7 @@ 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 extrusion of supplied building heights. */ +/** The brand basemap's hidden navigation-only approximate building extrusion. */ export const BUILDING_EXTRUSION_LAYER = 'avoid_building_3d'; export interface GuidanceBasemap { diff --git a/src/theme/brand-basemap.ts b/src/theme/brand-basemap.ts index 5edc69f..1776968 100644 --- a/src/theme/brand-basemap.ts +++ b/src/theme/brand-basemap.ts @@ -21,7 +21,7 @@ export interface BasemapInk { waterLabel: string; building: string; buildingEdge: string; - /** Navigation-only extrusions of supplied building heights (see `suppliedHeight`). */ + /** Navigation-only approximate building volumes (see `nonDefaultBuildingHeight`). */ buildingExtrusion: string; /** Pedestrian squares and areas. */ plaza: string; @@ -187,8 +187,8 @@ const transitClass = ['match', poiClass, ['bus', 'railway'], true, false]; const visiblePoi = ['all', ['!', transitClass], ['any', ['has', 'name'], hasCategory]]; /** - * Buildings whose OpenMapTiles height comes from supplied OSM data. planetiler-openmaptiles (which builds - * the OpenFreeMap tiles) writes `render_height = ceil(height ?? building:height ?? building:levels × 3.66 ?? 5)` + * Approximate buildings from OSM height tags or mapped floor counts, excluding the tile default. + * planetiler-openmaptiles (which builds the OpenFreeMap tiles) writes `render_height = ceil(height ?? building:height ?? building:levels × 3.66 ?? 5)` * and `render_min_height = floor(min_height ?? building:min_level × 3.66 ?? 0)`, with no field naming the * source. A missing height therefore always arrives as exactly 5. Supplied data reaches 5 only through a * mapped height above 4 m up to 5 m or a fractional level count (one level is 4, two are 8). Excluding @@ -196,7 +196,7 @@ const visiblePoi = ['all', ['!', transitClass], ['any', ['has', 'name'], hasCate * heights are an approximation from supplied levels, not a default; the schema cannot separate them from * measured heights. `hide_3d` marks outlines whose `building:part`s carry the shape. */ -export const suppliedHeight = ['all', +export const nonDefaultBuildingHeight = ['all', ['!', ['has', 'hide_3d']], ['==', ['typeof', ['get', 'render_height']], 'number'], ['==', ['typeof', ['get', 'render_min_height']], 'number'], @@ -278,7 +278,7 @@ export function brandRecipe(scheme: ColorScheme): StyleRecipe { before: 'boundary_3', layer: { id: 'avoid_building_3d', type: 'fill-extrusion', source: 'openmaptiles', 'source-layer': 'building', - minzoom: BUILDING_EXTRUSION_MINZOOM, filter: suppliedHeight, + minzoom: BUILDING_EXTRUSION_MINZOOM, filter: nonDefaultBuildingHeight, layout: { visibility: 'none' }, paint: { 'fill-extrusion-color': ink.buildingExtrusion, diff --git a/src/theme/map-style.test.ts b/src/theme/map-style.test.ts index 2f96f42..5c9a147 100644 --- a/src/theme/map-style.test.ts +++ b/src/theme/map-style.test.ts @@ -273,7 +273,7 @@ test('navigation buildings: a hidden, greyscale extrusion from z17 above flat fo } }); -test('navigation buildings extrude only supplied heights, never the OpenMapTiles 5 m default', () => { +test('navigation buildings accept tagged or floor-derived heights but exclude the tile default', () => { // planetiler-openmaptiles Building.java: render_height = ceil(height ?? building:height ?? levels * 3.66 ?? 5), // render_min_height = floor(min_height ?? min_level * 3.66 ?? 0). A missing height therefore arrives as // exactly 5; height tags and levels are integers other than 5 (one level is 4, two are 8). diff --git a/src/theme/map-styles/NOTICE.md b/src/theme/map-styles/NOTICE.md index 7b4f8c3..78e1fbd 100644 --- a/src/theme/map-styles/NOTICE.md +++ b/src/theme/map-styles/NOTICE.md @@ -15,7 +15,7 @@ The file is the unmodified response body. At retrieval, [hyperknot/openfreemap-s - replace POI sprite icons with small circle layers and text, and transit icons with stop and station rings and text; key amenities show an Italian category word; - remove the place-dot, airport and road-shield sprite icons, keeping their text; - remove the shaded-relief raster, one-way arrows, 3D building extrusions and United States shield layers; flat building footprints continue at all zooms; -- add hidden layers that only active guidance shows: one-way chevrons drawn from an app image, and a greyscale building extrusion from zoom 17 limited to OpenMapTiles heights that do not equal the 5 m default written for buildings without height or level tags; +- add hidden layers that only active guidance shows: one-way chevrons drawn from an app image, and a greyscale building extrusion from zoom 17 using approximate heights from mapped height tags or floor counts, excluding the 5 m default (and genuine 5 m buildings, which the tiles cannot distinguish); - add dedicated stop and station layers for OpenMapTiles' `railway` POI class, which Liberty's transit layer does not match. Sources, tile URLs, sprite and glyph endpoints are unchanged. diff --git a/src/theme/map-styles/notices.json b/src/theme/map-styles/notices.json index 2a156c7..cd3e385 100644 --- a/src/theme/map-styles/notices.json +++ b/src/theme/map-styles/notices.json @@ -3,7 +3,7 @@ "id": "NOTICE.md", "title": "Stili della mappa: provenienza e modifiche", "url": "https://github.com/hyperknot/openfreemap-styles", - "text": "# Bundled basemap style\n\nThe app's two basemaps, `avoid-dark` and `avoid-light`, are derivative works of OpenFreeMap Liberty. The upstream document is bundled verbatim so a remote style edit cannot change the app's map, and both brand styles are generated from it in code at startup. Vector tiles, sprites, glyphs and the TileJSON attribution string still come from the public OpenFreeMap service at `tiles.openfreemap.org`; the map's attribution control continues to show **OpenFreeMap © OpenMapTiles Data from OpenStreetMap**.\n\n| File | Source URL | Retrieved | SHA-256 |\n| --- | --- | --- | --- |\n| `openfreemap-liberty.json` | https://tiles.openfreemap.org/styles/liberty | 2026-11-01 | `408245464e76791801a64393c403433d09e8110eb9516040f8dc2b62584eee2a` |\n\nThe file is the unmodified response body. At retrieval, [hyperknot/openfreemap-styles](https://github.com/hyperknot/openfreemap-styles) `main` was commit `006ea5796803ba2df4330888836cb0a8f17473b4`. `map-style.test.ts` checks this hash.\n\n**Modifications.** `brandRecipe` in [`../brand-basemap.ts`](../brand-basemap.ts) describes every change and `transformStyle` in [`../map-style-transform.ts`](../map-style-transform.ts) applies it. The recipe must account for every upstream layer (patched, kept or removed), and every property it replaces or drops must exist upstream, so a refreshed document with added, renamed or missing layers, or with changes to the properties the recipe touches, fails to build. Properties the recipe does not mention pass through; `map-style.test.ts` therefore also fails if any colour in the derived styles is outside the greyscale bound or any layer draws a sprite icon or pattern. The derived styles:\n\n- replace Liberty's colours with greyscale palettes (`basemapInks`), with a faint green hint on parks;\n- use local OpenStreetMap names instead of English names;\n- replace POI sprite icons with small circle layers and text, and transit icons with stop and station rings and text; key amenities show an Italian category word;\n- remove the place-dot, airport and road-shield sprite icons, keeping their text;\n- remove the shaded-relief raster, one-way arrows, 3D building extrusions and United States shield layers; flat building footprints continue at all zooms;\n- add hidden layers that only active guidance shows: one-way chevrons drawn from an app image, and a greyscale building extrusion from zoom 17 limited to OpenMapTiles heights that do not equal the 5 m default written for buildings without height or level tags;\n- add dedicated stop and station layers for OpenMapTiles' `railway` POI class, which Liberty's transit layer does not match.\n\nSources, tile URLs, sprite and glyph endpoints are unchanged.\n\n## Licences\n\n- **OpenFreeMap styles repository:** MIT License, Copyright (c) 2023 Zsolt Ero.\n- **Liberty:** fork of [maputnik/osm-liberty](https://github.com/maputnik/osm-liberty), itself a fork of OSM Bright, derived from Mapbox Open Styles. Code: BSD 3-Clause. Design: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with the look and feel inherited from Mapbox Open Styles under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). The avoid maps styles adapt this design as described above.\n- **OpenMapTiles schema:** code BSD 3-Clause, design CC BY 4.0.\n- **Map data:** © OpenStreetMap contributors, [ODbL](https://www.openstreetmap.org/copyright).\n- **Fonts:** Noto Sans, SIL Open Font License 1.1. **Sprite:** Maki icons, CC0 1.0 (still referenced by the style; the derived layers draw no sprite images). **Natural Earth:** public domain (the derived styles no longer draw its raster).\n\nThe complete upstream licence texts, including copyright notices, redistribution conditions and disclaimers, are reproduced verbatim in [`LICENSES/`](LICENSES): `openfreemap-styles.md` (MIT), `osm-liberty.md` and `mapbox-gl-styles.md` (Liberty's BSD code licence, Mapbox Open Styles copyright (c) 2014 Mapbox, and its inherited CC BY 3.0 design notice). Retrieved 2026-11-01 from each repository's default branch. The app bundles this notice and these texts unchanged in `notices.json` and shows them offline under **Privacy e fonti › Fonti e licenze › Stili della mappa**; `map-style.test.ts` checks that the copies match these files.\n\nThese notices are separate from the application-source licence.\n" + "text": "# Bundled basemap style\n\nThe app's two basemaps, `avoid-dark` and `avoid-light`, are derivative works of OpenFreeMap Liberty. The upstream document is bundled verbatim so a remote style edit cannot change the app's map, and both brand styles are generated from it in code at startup. Vector tiles, sprites, glyphs and the TileJSON attribution string still come from the public OpenFreeMap service at `tiles.openfreemap.org`; the map's attribution control continues to show **OpenFreeMap © OpenMapTiles Data from OpenStreetMap**.\n\n| File | Source URL | Retrieved | SHA-256 |\n| --- | --- | --- | --- |\n| `openfreemap-liberty.json` | https://tiles.openfreemap.org/styles/liberty | 2026-11-01 | `408245464e76791801a64393c403433d09e8110eb9516040f8dc2b62584eee2a` |\n\nThe file is the unmodified response body. At retrieval, [hyperknot/openfreemap-styles](https://github.com/hyperknot/openfreemap-styles) `main` was commit `006ea5796803ba2df4330888836cb0a8f17473b4`. `map-style.test.ts` checks this hash.\n\n**Modifications.** `brandRecipe` in [`../brand-basemap.ts`](../brand-basemap.ts) describes every change and `transformStyle` in [`../map-style-transform.ts`](../map-style-transform.ts) applies it. The recipe must account for every upstream layer (patched, kept or removed), and every property it replaces or drops must exist upstream, so a refreshed document with added, renamed or missing layers, or with changes to the properties the recipe touches, fails to build. Properties the recipe does not mention pass through; `map-style.test.ts` therefore also fails if any colour in the derived styles is outside the greyscale bound or any layer draws a sprite icon or pattern. The derived styles:\n\n- replace Liberty's colours with greyscale palettes (`basemapInks`), with a faint green hint on parks;\n- use local OpenStreetMap names instead of English names;\n- replace POI sprite icons with small circle layers and text, and transit icons with stop and station rings and text; key amenities show an Italian category word;\n- remove the place-dot, airport and road-shield sprite icons, keeping their text;\n- remove the shaded-relief raster, one-way arrows, 3D building extrusions and United States shield layers; flat building footprints continue at all zooms;\n- add hidden layers that only active guidance shows: one-way chevrons drawn from an app image, and a greyscale building extrusion from zoom 17 using approximate heights from mapped height tags or floor counts, excluding the 5 m default (and genuine 5 m buildings, which the tiles cannot distinguish);\n- add dedicated stop and station layers for OpenMapTiles' `railway` POI class, which Liberty's transit layer does not match.\n\nSources, tile URLs, sprite and glyph endpoints are unchanged.\n\n## Licences\n\n- **OpenFreeMap styles repository:** MIT License, Copyright (c) 2023 Zsolt Ero.\n- **Liberty:** fork of [maputnik/osm-liberty](https://github.com/maputnik/osm-liberty), itself a fork of OSM Bright, derived from Mapbox Open Styles. Code: BSD 3-Clause. Design: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with the look and feel inherited from Mapbox Open Styles under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). The avoid maps styles adapt this design as described above.\n- **OpenMapTiles schema:** code BSD 3-Clause, design CC BY 4.0.\n- **Map data:** © OpenStreetMap contributors, [ODbL](https://www.openstreetmap.org/copyright).\n- **Fonts:** Noto Sans, SIL Open Font License 1.1. **Sprite:** Maki icons, CC0 1.0 (still referenced by the style; the derived layers draw no sprite images). **Natural Earth:** public domain (the derived styles no longer draw its raster).\n\nThe complete upstream licence texts, including copyright notices, redistribution conditions and disclaimers, are reproduced verbatim in [`LICENSES/`](LICENSES): `openfreemap-styles.md` (MIT), `osm-liberty.md` and `mapbox-gl-styles.md` (Liberty's BSD code licence, Mapbox Open Styles copyright (c) 2014 Mapbox, and its inherited CC BY 3.0 design notice). Retrieved 2026-11-01 from each repository's default branch. The app bundles this notice and these texts unchanged in `notices.json` and shows them offline under **Privacy e fonti › Fonti e licenze › Stili della mappa**; `map-style.test.ts` checks that the copies match these files.\n\nThese notices are separate from the application-source licence.\n" }, { "id": "LICENSES/openfreemap-styles.md",