See it in action
Loads on request · 4.7 MB
Recorded exploration and instruction previews in the included synthetic Meridian Park campus. It shows the actual application, not live handset localization or an AR field test.
More screenshots and results
A campus-to-room route in the same synthetic venue. The interface explicitly says that the user's position is not yet being tracked.
What I wanted to solve
A route is not useful if it belongs to a different map version, assumes an unavailable lift works, or keeps giving directions after the app loses track of the visitor. I started with one compiled model for every view, then built the installation, policy, and location checks needed to keep those assumptions visible during a trip.
What made it difficult
- A multi-floor route has to respect its accessibility profile and the current closures.
- An inaccessible or restricted edge must be treated as unavailable when its state is uncertain.
- An offline package needs an integrity check and a safe way to roll back.
- Cached map data alone is not enough: the application code must also survive a cold start without the network.
- Closure information can expire while someone is already following a route.
- Route progress cannot look confident when the localization estimate is not.
- The 2D plan, 3D twin, search index, and routing worker must agree on the package identity.
- A printed check-in code is trustworthy only when it was generated from the package and physically placed at the declared anchor.
- A real deployment needs venue data that is authorized and physically verified.
How it works
- 1
Venue source
Authored sources describe outdoor walks, buildings, floors, spaces, portals, destinations, accessibility attributes, and check-in anchors.
- 2
Schema and compiler
The compiler checks geometry, connectivity, reachability, and operational attributes before the package reaches a client.
- 3
Content-addressed package
One reproducible artifact feeds routing, search, the 2D plan, and the 3D viewer.
- 4
Routing worker
A Web Worker runs multi-floor A* for standard and wheelchair profiles, applying closures and fail-closed exclusions.
- 5
Verified package registry
The registry checks SHA-256 digests and keeps the active and previous packages atomically in IndexedDB.
- 6
Offline application shell
The service worker verifies release-cache bytes so a previously installed visitor app can cold-start offline. Missing or corrupt bytes must be repaired from matching content.
- 7
QR check-in
Package-generated codes resolve to declared anchors on the correct floor without a beacon, fingerprint database, or lookup service.
- 8
Localization runtime
The runtime replays observations in a stable order, tracks covariance-aware quality states, and pauses route matching when uncertainty is too high.
- 9
Journey presentation
One journey feeds written and spoken directions, 2D/3D maps, and optional camera guidance. Previewing a route does not count as physically walking it.
Choices I made
Compile topology before runtime
I make the compiler responsible for malformed geometry and missing connectivity. A client either receives a valid package or receives nothing; it does not repair the building on its own.
Share one artifact across every client surface
Routing, search, 2D, and 3D all derive from the same hashed package. That keeps a view from quietly drifting to different topology.
Fail closed for accessibility and restrictions
An unavailable lift or excluded edge cannot become an accessible shortcut. Imported closure policy is checked at decision time and can expire mid-trip. Guidance then pauses until policy and the start position are renewed; losing the network is not evidence that all routes are open.
Emit route receipts
Each result records the package hash, routing profile, applied closures, chosen connectors, and exclusion counts. That is enough to explain and reproduce the route.
Make localization uncertainty explicit
I use covariance-aware quality states to gate route matching. An unstable estimate triggers recovery instead of being shown as reliable guidance.
Generate check-in codes from the package
The printable code sheet is derived from compiled venue anchors and round-trip tested through the decoder. Placement remains a physical field procedure, so the software does not pretend to verify where a sign was mounted.
Test offline startup, not just offline map access
I exercise the production app after closing it and removing network access. The first visit still needs a connection, and storage must remain available. During updates, retaining older cache bytes is a recovery measure, not a claim that the previous service worker has automatically been restored.
Treat the drawn route as another checked output
The route graphic is checked against authored space boundaries and portal openings. If its width does not fit, the app keeps written directions but withholds that graphic; an inconsistent centerline rejects the route. These are checks against the map, not measurements of real wheelchair clearance.
Let the map have the small screen
Search and journey panels collapse without losing the destination or trip. Safety warnings, recovery controls, and the exit remain available. Operator panels use the same approach, but the public visitor build excludes those authoring tools.
How I tested it
- The repository check runs linting, type checking, tests, package reproducibility checks, replay verification, and the production build.
- Committed building packages are recompiled and compared with their stored versions.
- Reference localization replay output is compared byte for byte.
- The directions audit checks 7,238 standard and step-free journeys across four bundled synthetic venues, looking for missing or undrawable routes, turn-backs, and repeated instructions.
- The main benchmark tests standard and wheelchair routing during a reproducible public-lift outage.
- Generated check-in codes are checked against published package anchors and round-trip tested through the decoder used by the client.
- Production-browser tests cover cold-offline startup, cache repair, update lifecycles, and policy expiry during a journey.
- The publication workflow requires quality and browser checks for the same selected commit that is used to build the release.
Known failure modes
- A wheelchair route is rejected when its required lift is unavailable and there is no accessible alternative.
- Invalid topology stops compilation; the browser does not try to repair it.
- Tampered packages fail digest verification.
- Expired imported policy pauses an active journey; an offline restart does not silently discard the closure requirement.
- If release bytes cannot be verified or repaired, offline availability is reported as unavailable rather than assumed.
- High localization uncertainty stops confident route matching and invokes the recovery rules.
- A code from an old package or one mounted at the wrong junction can produce a bad physical check-in even when its payload is valid.
What works now
- The bundled fixtures now include a campus: a route can cross the grounds, enter a building, and continue through its rooms.
- Multi-floor A* supports standard and wheelchair routing profiles.
- A verified online installation supports cold-offline reload while its application and package caches remain intact.
- The compiled package drives search, the architectural plan, and the 3D spatial twin.
- Localization observations can be replayed with explicit uncertainty states.
- A QR code can establish a floor-aware position fix against the package without an online positioning service.
- Supported WebXR devices can use an experimental tracked-guidance path after floor confirmation; loss of usable pose pauses guidance. The ordinary camera view remains an estimated overlay.
- Visitor and operator builds are separated; deferred map/camera modules and startup-JavaScript budgets keep the initial visitor load bounded.
What it doesn't do yet
- All four bundled venues are synthetic. The route audit and browser tests do not establish real-building positioning accuracy or handset reliability.
- Deployment would require authorized building data, calibrated coordinate transforms, checked accessibility attributes, and physical route testing.
- Ordinary camera guidance uses an estimated floor and field of view. The separate WebXR path is experimental, not a surveyed world-anchored navigation system.
- Motion tracking, heading, and floor alignment still need physical-device and venue qualification.
- The repository's camera showcase uses generated corridor backgrounds and simulated sensor states. Those images demonstrate the UI, not measured real-world alignment.
- There is no production live closure feed or authenticated policy-publication backend; imported policy is a narrower feature.
- The first installation needs the network. Cache eviction can remove offline availability.
- Authored graphic-clearance checks do not detect moving obstacles or prove real-world traversability.