"/home/yossef/notes/git/projects/maplibra/modules/Outdoor Routing.md"

path: maplibra/modules/Outdoor Routing.md

- **fileName**: Outdoor Routing
- **Created on**: 2026-06-16 00:48:42

Outdoor Routing

Purpose: Stitches indoor routes with outdoor street routes for campus-scale navigation.

Related: ../Home.md, ../Architecture.md, ./Pathfinding.md, ../flows/Outdoor Route.md, ./MVF Format.md

What It Does

Outdoor routing allows the app to compute routes that start or end outside the building. It finds the nearest road, fetches a street route via OSRM-like APIs, and stitches it to the indoor pathfinding graph.

Key Concepts

• Building footprint: Largest floor polygon used to determine if a point is inside or outside
• Outdoor location: A point outside the building footprint (or beyond a threshold from the nearest graph node)
• Street route: Outdoor walking route fetched from a routing API
• Stitching: Connecting the outdoor street route to indoor entrance nodes

Route Stitching Flow

1. Detect if start or target is outside the building
2. Find nearest road point (or nearest entrance node for indoor side)
3. Fetch street route between outdoor points
4. Build a unified graph combining indoor nodes + outdoor segment
5. Run A* on the unified graph
6. Smooth the combined route

Configuration

outdoorRouting settings in PathfindingController options:

• allowNetwork — enable network-based outdoor routing
• useNearestRoad — fetch nearest road point from API
• routeTimeoutMs — timeout for outdoor API calls
• entranceMode — how to select building entrances (any, primary, secondary)
• requireBoundaryEntrance — require route to enter through a building entrance
• directThresholdMeters — threshold for direct outdoor route (skip indoor)
• roadMaxLengthRatio — max ratio of road length to direct distance

Direct Outdoor Route

When no street route is available or desirable, a direct outdoor route solver walks around the building footprint:

• directClearanceMeters — buffer around building
• directStepMeters — step size for pathfinding around building
• directAllowDoorCutout — allow cutting through door openings

Caching

Outdoor route results are cached in outdoorCache with provider-specific keys (profile, base URL, radius):

• nearest cache — nearest road lookups
• route cache — street route results

Important Files

• src/outdoor/outdoor-routing.js — Main outdoor routing mixin (2287 lines)
• src/outdoor/outdoor-router.js — OSRM API calls, nearest road, street route
• src/pathfinding/campus-routing.js — Campus-scale multi-building routing
• src/pathfinding/unified-graph.js — Combined indoor + outdoor graph
• src/pathfinding/outdoor-loading-ui.js — Outdoor loading UI overlay

How It Connects

• Outdoor routing is a mixin on PathfindingController (assigned to prototype)

• RoutingController calls outdoor routing methods when start/target are outside

• outdoor-router.js makes network calls to external routing APIs

• Results are stitched into the unified graph before A* runs

• The outdoor segment is rendered alongside indoor segments by PathRenderer

  continue:[[]]
  before:[[]]