← Open Navigator

NAVIGATOR / ENGINEERING RECORD / 0.2

Real streets. A bounded world.

An OSM first-person exploration PWA designed around a small working set. Prototype A proves the rendering and manual controls; Prototype B tethers the camera to real GPS fixes and the compass, one square at a time (800 m walking, up to 2 km and centred ahead when driving), with manual controls kept as the fallback. Prototype D adds a user-observed shadow alignment and optional temporary heading offset; camera correction and route navigation remain later stages.

System architecture

The full target architecture below is a plan. Only the items marked “implemented” are present in this release.

ImplementedSmall OSM areaBundled OSM snapshot. Explicit live Overpass refresh, with direct OSM API fallback. Fixed Los Angeles box or, with GPS enabled, one square around the fix: 800 m at walking pace, up to 2 km and led along the course at speed; response capped at 8 MiB, stepping down 800 m → 500 m when oversized or dense. Up to eight parsed squares are kept for the session.
→
ImplementedWorker processingJSON parsing → OSM conversion → verified precomputed street-sector graph and chunk memberships (radius/bucket fallback for live areas) → bounded chunk cache and batched geometry buffers.
→
ImplementedFirst-person rendererMapLibre camera + a shared Three.js custom layer. 1.65 m eye height, three world draw calls plus four chevron calls, depth testing, shader fog, 180 m fragment cutoff.
Planned · ingest toolingGeofabrik extractsPlanetiler/Tilemaker processing plus a separate ingest step that produces a spatial index and street-block sector graph. These graph outputs are not assumed to exist in standard tiles.
→
Planned · local world storePMTiles + index + graphOPFS or IndexedDB persistence. PMTiles byte-range reads through a local Source adapter. Quota estimate, explicit download size confirmation, versioned manifests.
→
Planned · workersBounded streamingCurrent sector + graph neighbors. Directional prefetch, geometry disposal, reusable buffers. Near-field first; far-field silhouettes later.
Implemented · permission gesturePosition & observationsOpt-in Geolocation watch and absolute device orientation (iOS webkitCompassHeading after requestPermission() in the tap). Implemented: explicit user shadow alignment. Planned: ephemeral camera samples.
→
Implemented · filteringPosition & heading estimateFixes worse than ±60 m or implying more than max(15 m/s, 1.5 × the receiver's reported speed) are rejected; position eases (τ 0.55 s, snap above max(45 m, three fix intervals of travel)), heading eases on the circle (τ 0.22 s). Above 3 m/s the target is dead-reckoned along the GPS course for up to 2 s and the heading blends from compass to course (fully at 7 m/s or with compass accuracy worse than 25°); walking pace is unchanged. Manual controls cover any missing sensor. Prototype D: optional shadow-derived offset before heading smoothing. Planned: worker vanishing-point analysis and its 180° ambiguity handling.
→
Implemented · presentationCamera & 3D chevronFiltered heading drives the chevron and default view direction. Optional GPS free look allows independent drag/turn for the camera; compass and GPS observations continue unchanged. GPS travel course remains separate. Heading is distinct from a planned route; there is no route engine.
Offline shell · implemented

Service worker caches the built app, icons, architecture document, and bundled OSM snapshot. Same-origin requests only; live building refreshes and GPS squares are session-only. OSM road packages use a separate persistent IndexedDB cache. The supplied reference image is excluded from offline precaching.

GPS area anchoring · implemented (Prototype B)

The local metre frame is anchored to the loaded area's origin. On each accepted fix the app checks whether the 180 m view radius still lies inside the loaded bounding box. If not, it loads the square for the fix (800 m centred on it at walking pace; up to 2 km led along the course at speed), reusing a square the worker already holds this session or the bundled snapshot when the fix lies inside the fixed LA box, re-projects the player and GPS target into the new origin, and disposes the old geometry. Above 3 m/s the next square is prefetched into the session cache eight seconds before the edge, so the swap needs no download. Downloads are serialised and back off 30 s after a failure, doubling to 5 min with jitter and honouring Retry-After; a rate limit never switches provider. This is a proposed adaptation of the later sector-streaming design, not that design: one source square is active at a time. Leaving a square before its download completes still shows fog with no geometry beyond the loaded data. While any area downloads, parses or builds, and from the GPS enabling tap until the first accepted fix, the notice pill shows a progress strip with bytes, rate, an elapsed clock and the current phase; the bar is determinate only while the declared Content-Length is trustworthy.

Decisions and corrections

Budgets and measurement

These are enforced implementation limits, not observed performance promises.

The Performance panel reports the observed animation-frame interval while moving, world draw calls, loaded building count, submitted vertices, typed-array bytes, fetch + worker latency, loaded area, optional JS heap, reported GPS accuracy with used/rejected fix counts, fix interval, and compass accuracy where the platform reports it (iOS only). Frame interval is not GPU render time. GPU memory is marked unavailable rather than estimated from unrelated counters.

OSM building styles

Seven procedural styles share the existing batch: neutral, small home, apartments, storefront, office, utility and civic. Explicit building tags take priority; use/amenity/shop tags resolve generic footprints. Residential, retail and industrial land-use polygons provide a conservative fallback only for unspecified buildings; without one, a small untagged footprint on a residential or service street in a mostly-small-footprint square is drawn as a home. Generic commercial and city names do not imply office. A shop in apartments affects only one nearby street-facing ground-floor wall. Unknown types remain neutral.

Classification happens at area load, with bounded neighborhood and frontage checks. The worker carries two extra bytes per building vertex for style and floor height; cache/transfer memory accounting includes them. No textures, extra material batches or draw calls are added. Existing footprints remain; untagged small footprints in residential context default to two storeys and rectangular homes get a gable. These are illustrative façades, not surveyed architecture. The live request includes bounded land-use data under the existing 8 MiB cap. See README for inference limits and reproducible GPU fixtures.

Autumn lighting and inexpensive material cues

Warm directional wall lighting, cool ambient shade, recessed pane edges and base darkening use the existing fragment shader. Glass approximates a sky/ground environment with view-dependent tint and a sun highlight. Roads have a restrained grazing sheen and distance/footprint-filtered grain. A static CSS sky gradient adds a blue zenith and warm horizon. These cues are illustrative, independent of actual sunlight and the compass cross-check; they do not reflect nearby scene geometry or cast building shadows.

No texture downloads, extra meshes, render targets, shadow maps or post-processing passes are added. Geometry buffers and seven world/chevron draw calls remain unchanged; shader arithmetic increases. Physical-phone GPU measurements remain outstanding.

Local OSM road packages

OSM highway geometry and names download from public Overpass into compressed, validated IndexedDB packages. A 25-mile target recenters after 12.5 miles, reusing completed overlap. Completed areas resume after reload; dense areas subdivide; requests are serial with timeouts and backoff. One tab owns downloads through a Web Lock. The field guide provides pause, retry and clear.

Limits: 128 MiB stored payloads, 4 MiB per response, 16 MiB per decoded package, and 2,400 nearby active segments. Metadata and browser/transient/GPU overhead are additional. Maintenance after approximately 25 m movement (four seconds of travel above 5 m/s) removes whole packages whose retained bounds extend beyond the current radius; conservative edge eviction can remove in-range data too. In-range packages are decoded and verified once per session and kept parsed in the worker; the plan record is written only when it changes. Enabling GPS above 8 m/s before a GPS-centred plan exists holds the bulk download until a minute of standstill or an explicit tap. The footer reports actual progress and partial coverage. A public service cannot guarantee full-radius startup coverage. Full-radius transfer and physical-phone walking remain unmeasured. Organic Maps inspired durable queues, validation, atomic installation and cleanup; Navigator uses OSM query areas, not native .mwm binaries or byte-range resumption.

Privacy and platform behavior

Sensors are off until the user taps “Use my location” and confirms a prompt that names what is requested and why. Prototype B then requests Geolocation and, on iOS, motion & orientation; it never requests microphone or camera. Raw readings are held in memory (src/positioning.js); derived road coverage centers and OSM packages are stored locally in IndexedDB, and nothing is sent to any server of ours; no account, analytics, or server-side application code exists. Enabling GPS downloads an 800 m to 2 km square around or ahead of the fix from Overpass or the OSM API, which tells that service the user's approximate area and exposes ordinary network metadata such as IP address; the prompt says so. Road downloads request areas within a 25-mile target from public Overpass, which sees those areas. GitHub receives normal hosting requests and no downloaded road packages. “No app tracking” does not mean a third-party host has no access logs.

Sensors require HTTPS and user consent. iOS orientation permission must be requested from a user gesture, so DeviceOrientationEvent.requestPermission() is called synchronously inside the enabling tap before any await; generic alpha is not an absolute compass heading and is ignored unless the event is marked absolute. Desktop browsers usually deliver no orientation events at all; the app declares the compass unavailable after 4 s and keeps manual look. Hiding the tab clears the position watch and orientation listener. Later camera samples must stay in memory, be processed at low duty cycle, and have no storage, network, recording, or persistent queue path. Browser storage can be evicted; persistence requests are not guarantees.

Reference orientation

Supplied concept reference rotated 90 degrees clockwise, with the street at the bottom and buildings upright

The original asset is preserved byte-for-byte. This document rotates its display exactly 90° clockwise. The reference establishes the cool gray streetscape, restrained instrument overlay, and cyan accent. The in-world chevron follows the resolved viewing heading. Shadow alignment is available in Prototype D; camera heading correction remains a later stage.

Build sequence

  1. Architecture — this document.
  2. Prototype A — released. Fixed OSM area, manual controls, bounded geometry and fog.
  3. Prototype B — implemented. Opt-in GPS and compass tethering, fix filtering and smoothing, 800 m square re-anchoring, manual fallback per sensor.
  4. Prototype C — released. Eye-height chevron consumes the resolved camera heading. Automated depth checks cover full and partial occlusion and real OSM geometry through the production renderer.
  5. Prototype D — included in v0.1.1. NOAA solar prediction plus explicit shadow alignment, disagreement indicator, optional temporary offset and automatic expiry.
  6. Prototype E — included in v0.1.1. Radius-based geometry cache, four directional prefetch chunks, 28 resident cap, batched rendering, disposal and live memory estimates.
  7. Prototype F — included in v0.1.1. Ingest-time street-face graph and chunk memberships for the bundled source; verified radius fallback for live areas; measured lookup comparison and optional GPS free look.
  8. Prototype G — implemented in v0.1.18, awaiting device confirmation. Per-chunk LOD: full extrusion to 120 m (24 m hysteresis), flat-shaded silhouette prisms to 300 m in one extra draw call, façade detail faded 90–150 m, over-budget near chunks downgraded rather than omitted. Silhouettes, not textured billboards, are a deliberate adaptation.
  9. Tier 2 — vanishing-point correction and frame-persistence audit.
  10. Bulk downloads — quota and explicit size confirmation.
  11. Local PMTiles byte ranges — compare memory footprint.
  12. Worker consolidation — stress-test frame stability.
  13. Fallbacks — denied sensors, lost location, missing area.
  14. Final PWA validation — physical iPhone and Android testing, offline walking and 15–20 minute continuous sessions. Basic packaging is already included to make Prototype A installable.

Acceptance for Prototype B

On a phone outdoors: enable location, confirm the view appears on your actual street within a few seconds of the first fix, walk a block and confirm the camera follows without jumps larger than the reported accuracy, turn and confirm the view turns with you (iPhone and Android Chrome; desktop has no compass), and note the Performance panel's fix interval and accuracy. Then walk out of the loaded square and confirm a new square downloads. Record fps and accuracy; Chromium-driven checks in docs/validation.md are not a substitute for this. Without an applied shadow alignment, heading remains uncorrected.

Hovering direction guide

The thin cyan chevron hovers parallel to the ground at 0.75 m, 4.5 m ahead of the view; the camera stays at 1.65 m. A bounded translucent street/path pill floats above it, using nearby OSM geometry in demo and GPS modes. The pill does not intercept gestures, hides near the upper sightline and bottom controls, and reports unnamed or unavailable geometry explicitly. It is a screen overlay, not a route instruction or a confirmed road match. A separate confidence-gated pill appears when an accepted GPS fix lies at least 0.3 accuracy radii inside a loaded footprint (“may be inside”; “probably inside” at one radius or more), computed in the worker once per fix; it is a footprint hint, not indoor positioning. Floating overlays never stack: a pure layout resolver keeps each pill at its designed position when free, moves it to the nearest free slot in its column otherwise, and shrinks it (to no less than 60 %) only when no slot fits. It follows the resolved compass heading while GPS is active, including during free look, or the manual viewing heading otherwise. Prototype D optionally applies a shadow-alignment offset; camera correction remains a later stage. Body, edges, glow and shadow all use scene depth testing. Four additional draw calls bring the total budget to seven; the main mesh has 132 vertices. This indicates compass or manual heading, not measured travel direction or a planned route.

Design ideas: reusable arrow geometry and separate direction state from the Organic Maps Project. No Organic Maps code, assets or map files were copied.

Prototype D: shadow alignment

Hold the phone flat, screen up, aligned from an upright object's base toward the tip of its clear shadow on level ground. Record the alignment, compare raw compass to predicted shadow bearing, then optionally apply the offset to both camera and chevron. A difference of 15° or more is flagged; it can include magnetic declination, interference or alignment error. This user-observed adaptation is not continuous drift detection. Cloudy, indoor, low-sun and near-zenith conditions leave the ordinary compass available.

The session-only check expires after 10 minutes, 100 m displacement, stale sensors, rotation or hiding the app. It adds no camera use, storage or network calls. Inputs must include recent GPS and compass, a flat phone and a short stable heading window. NOAA's approximate calculation is an established technique; alignment gates and the temporary offset policy are prototype design choices, not validated accuracy bounds. See README and docs/validation.md for thresholds, measurements and remaining physical-device tests.

Prototype E: bounded chunk streaming

The worker indexes the current downloaded area into 128 m buckets, selects up to 24 active chunks intersecting the 180 m view radius plus a 12 m margin, and prepares up to four chunks ahead of travel. Existing cached geometry is reused; chunks outside the working set lose cache references. Active buildings and roads share batched meshes, keeping seven draw calls; replaced GPU buffers are disposed. Global building/road caps and the fixed shader cutoff remain enforced. Under pressure, simplification and omissions take precedence over exceeding those caps.

The performance panel reports resident counts, promotions, evictions, GPU mesh disposal counters, typed-array bytes, source-coordinate payload estimate and chunk update latency. The CPU/GPU geometry estimate excludes temporary allocations and browser/driver overhead. Source OSM for one area remains parsed in the worker. Prototype F adds an offline-generated street-face graph over these chunks for the bundled source. Live areas retain uniform buckets; PMTiles byte-range reads remain later work. Prefetch here prepares geometry already downloaded; it adds no network requests.

Prototype F: precomputed street sectors and GPS free look

The bundled graph contains 14 street-derived faces, 28 adjacency edges and memberships for 60 chunks. Offline Shapely/GEOS polygonization uses ground-level street centerlines plus the source-envelope boundary. This rendering-sector adaptation includes fringe faces; it does not claim surveyed blocks, collision or pedestrian connectivity. The worker verifies the graph against the source hash and structure, locates the player with a precomputed cell table and traverses face adjacency before applying the established chunk bounds and budgets. Live data without a matching graph retains radius lookup; no graph is generated on-device.

The graph and radius paths returned identical candidates at 441 benchmark positions. One local benchmark measured 0.0115 ms per graph query versus 0.0075 ms for the radius scan, so this small dataset shows no speedup. The startup query visits all 14 sectors and collects all 60 chunks. The Performance panel exposes the active lookup path and measured cost; the benchmark is repeatable with npm run bench:sectors.

Compass-follow remains the default. Dragging temporarily looks around through an unlimited yaw angle; a sweep across 80% of the viewport covers 360°. Release or cancellation smoothly returns to the latest resolved phone heading, while GPS and compass continue updating. While GPS is enabled, tap “View: compass” to switch to free look; drag or turn with the controls while GPS keeps moving position and the chevron keeps the resolved compass bearing. The sensor bearing is unchanged. Tap again to ease back to compass-follow. Stopping GPS resets this option; denied/absent compass keeps the existing manual fallback.

Primary references