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

path: maplibra/modules/MVF Loading.md

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

MVF Loading

Purpose: Parses MVF (Map View Format) ZIP bundles and exposes metadata plus per-floor payload loading.

Related: ../Home.md, ../Architecture.md, ./Asset System.md, ./Map Rendering.md, ./Pathfinding.md

What It Does

The MVF loader reads a ZIP file containing building geometry, floor definitions, styles, connections, and routing data. It parses the bundle in a Web Worker to avoid blocking the main thread, then exposes methods to load individual floor data on demand.

MVF Bundle Structure

See ./MVF Format.md for the complete bundle structure and per-file documentation.

Loading Modes

1. URL Load (createMVFLoader(url))

• Fetches ZIP from URL with Cache API fallback
• Parses in Web Worker (src/workers/mvf-worker.js)
• Returns metadata + lazy floor loading

2. File Upload (createMVFLoaderFromFile(file))

• Reads uploaded ZIP file via FileReader + JSZip
• Same parsing path as URL load

3. Asset Root (createMVFLoaderFromAssetRoot(root))

• Assumes MVF files are unpacked on server
• Uses network fetch instead of ZIP parsing

4. Cache Restore (createCachedMVFLoader(entry))

• Restores MVF from IndexedDB cache
• Uses src/app/cached-mvf-loader.js

Worker Protocol

The MVF worker (src/workers/mvf-worker.js) uses a simple request/response protocol:

• Input: { type, id, payload }
• Output: { id, success, data?, error? }

The incrementing id lets multiple floor loads share one worker safely.

Floor Data Loading

After the initial bundle parse, individual floors are loaded lazily:

• mvfLoader.loadFloorData(floorId) reads geometry, styles, entrance IDs, and locations for that floor
• Results are cached by FloorDataManager (see ./Map Rendering.md)

Important Files

• src/mvf-loader.js — Main loader, ZIP parsing, Web Worker coordination
• src/workers/mvf-worker.js — Web Worker for ZIP parsing
• src/app/cached-mvf-loader.js — IndexedDB cache restoration
• src/app/startup-routing-assets.js — Prepare routing assets after MVF load

How It Connects

• MVF loader is called by script.js during startup

• Parsed data is passed to FloorDataManager for rendering

• Connections and locations are passed to PathfindingController for routing

• ZIP blob is cached in IndexedDB for fast re-opens

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