"/home/yossef/notes/git/projects/maplibra/modules/MVF Format.md"

path: maplibra/modules/MVF Format.md

- **fileName**: MVF Format
- **Created on**: 2026-06-16 00:48:42

MVF Format

Purpose: Documents the Map Vector Format (MVF) data bundle structure.

Related: ../Home.md, ../Architecture.md, ../flows/Graph Construction.md

What It Is

MVF = Map Vector Format. A ZIP archive containing per-floor GeoJSON geometry, walkable areas, classification metadata, and cross-floor connection definitions. Parsed by src/workers/mvf-worker.js.

Bundle Structure

bundle.zip/
  manifest.geojson          → Building metadata + floor list
  floors.geojson            → Floor definitions with elevation
  connections.json          → Stairs, elevators, doors, ramps
  default-style.json        → Rendering styles + inaccessible room anchors
  locations.json            → Named POIs / searchable locations
  navigationFlags.json      → Optional routing flags
  geometry/{floorId}.geojson    → All polygons/lines for a floor
  walkable/{floorId}.geojson    → Positive-space walkable polygons
  kinds/{floorId}.json          → { geometryId: "wall"|"object"|"room" }
  nonwalkable/{floorId}.json    → { geometryId: true } explicitly blocked
  entrance-aesthetic/{floorId}.json → Entrance node positions
  annotations/{floorId}.json    → Floor annotations

Key Files Explained

walkable/{floorId}.geojson

FeatureCollection of Polygon/MultiPolygon features defining where people can walk. Only points INSIDE these polygons are considered valid path locations.

kinds/{floorId}.json

Maps geometry IDs to classification strings:

• "wall" → buffered by 0.6m for clearance
• "object" → buffered by 0.4m for clearance
• "room" → used for room containment logic

nonwalkable/{floorId}.json

Explicit blocklist. Any geometry ID listed here is treated as an obstacle with 0.4m buffer regardless of its kind.

connections.json

Array of connection records:

{
  "id": "conn-1",
  "type": "stairs|elevator|ramp|escalator|door",
  "entrances": [{ "floorId": "L1", "geometryId": "geo-123" }],
  "exits": [{ "floorId": "L2", "geometryId": "geo-456" }],
  "entryCost": 0,
  "floorCostMultiplier": 1
}

Runtime Loading

1. mvf-worker.js receives ZIP blob via INIT message
2. Returns: manifest, styles, locations, floors, connections, navigationFlags
3. Per-floor data loaded on demand via LOAD_FLOOR_DATA message
4. Returns: geometryRaw, entranceRaw, kindsRaw, nonwalkableRaw, annotationsRaw, walkableRaw
5. Controller promotes data into hot caches (geometryCache.js)

Important Files

• src/workers/mvf-worker.js — ZIP parser worker

• src/pathfinding/geometry-cache.js — Lazy floor data promotion

• src/pathfinding/walkable-areas.js — Walkable polygon queries

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