Apollo Map Studio
A browser-based HD map editor for the Apollo autonomous driving platform. Draw lanes, junctions, signals, and all other map elements visually, then export Apollo-compatible binary map files directly from your browser -- no C++ toolchain required.
Why
Apollo requires three binary map files to operate:
| File | Purpose |
|---|---|
base_map.bin |
Full HD map with all elements and metadata |
sim_map.bin |
Downsampled version for Dreamview visualization |
routing_map.bin |
Topological graph used by the routing module |
Traditionally, generating these files requires the Apollo C++ build environment. Apollo Map Studio replaces that entire workflow with a web app -- open it in a browser, draw your map, click Export.
Features
- Interactive drawing -- lanes, junctions, crosswalks, signals, stop signs, speed bumps, clear areas, parking spaces
- Real-time boundary rendering -- left/right lane boundaries computed and rendered as you draw, with correct dash styles per boundary type
- Lane topology editor -- connect predecessor/successor lanes, set left/right neighbors, with endpoint snapping
- Road grouping -- assign lanes to named roads with type (highway, city road, park), color-coded visualization
- Element list explorer -- browse, search, and select all map elements from a filterable panel
- Map validation -- pre-export validation report detecting orphan lanes, missing connections, and structural issues
- Properties panel -- edit speed limit, lane type, turn direction, boundary types per element
- Binary export -- produces all three Apollo
.binfiles in the browser via protobufjsbase_map.binwith full overlap computation (lane - signal, crosswalk, junction, etc.)sim_map.binusing the same downsampling algorithm assim_map_generator.ccrouting_map.binwith node/edge costs matchingtopo_creatorexactly
- Binary import -- load an existing
base_map.binand continue editing it, including road assignments - Undo / Redo -- full history via Zustand temporal middleware
- Layer toggles -- show/hide any element type
- Offline capable -- blank map background, no tile server or external API needed
Tech Stack
| Concern | Library |
|---|---|
| Map rendering | MapLibre GL |
| Drawing tools | @mapbox/mapbox-gl-draw |
| Spatial math | @turf/turf |
| Protobuf encode/decode | protobufjs |
| Coordinate projection | proj4 (WGS84 - ENU) |
| State management | Zustand + immer + zundo |
| Build | Vite + TypeScript |
Getting Started
# Clone and install
git clone https://github.com/SakuraPuare/apollo-map-studio
cd apollo-map-studio
npm install
# Start dev server
npm run dev
git clone https://github.com/SakuraPuare/apollo-map-studio
cd apollo-map-studio
npm install
# Start dev server
npm run dev
Open http://localhost:5173 in your browser.
First map
- Click New Project, enter a name and the origin coordinates (lat/lon) of your map area
- Select Draw Lane from the toolbar and click to place lane centerline points
- Double-click to finish drawing a lane
- Use the Properties panel on the right to set speed limit, type, boundary styles, etc.
- Select Connect Lanes to link predecessor/successor relationships between lanes
- Add junctions, signals, crosswalks, etc. using the corresponding toolbar buttons
- Click Export to download
base_map.bin,sim_map.bin, androuting_map.bin
Import existing map
Click Import and drop a base_map.bin file. The editor will decode it and restore all elements for further editing.
Project Structure
src/
+-- types/
| +-- apollo-map.ts # Apollo proto type mirrors (Map, Lane, Road, ...)
| +-- apollo-routing.ts # Routing graph types (TopoNode, TopoEdge, ...)
| +-- editor.ts # GeoJSON-based editor types (LaneFeature, ...)
|
+-- store/
| +-- mapStore.ts # Map element state + actions (Zustand + immer + undo)
| +-- uiStore.ts # Draw mode, selection, layer visibility
|
+-- geo/
| +-- projection.ts # proj4: WGS84 - ENU coordinate conversion
| +-- laneGeometry.ts # turf: boundary offset, width sampling, headings
| +-- overlapCalc.ts # turf: lane/element intersection - Overlap proto
| +-- snapEndpoints.ts # Lane endpoint snapping for connect mode
|
+-- proto/
| +-- loader.ts # protobufjs: dynamic .proto loading
| +-- codec.ts # encode/decode Map + Graph, download as .bin
|
+-- export/
| +-- buildBaseMap.ts # Assemble full Apollo Map proto object
| +-- buildSimMap.ts # Downsample (port of sim_map_generator.cc)
| +-- buildRoutingMap.ts # Build topo graph (port of topo_creator)
|
+-- import/
| +-- parseBaseMap.ts # Decode base_map.bin - editor GeoJSON state
|
+-- validation/
| +-- mapValidator.ts # Pre-export map validation rules
|
+-- components/
+-- MapEditor/ # MapLibre GL container, draw control, layer rendering
+-- Toolbar/ # Draw mode buttons (lucide-react icons)
+-- PropertiesPanel/ # Per-element attribute forms
+-- ElementListPanel/ # Element browser with search and selection
+-- NewProjectDialog/ # Project name + origin coordinate setup (with presets)
+-- ExportDialog/ # Export all three .bin files
+-- ImportDialog/ # Import base_map.bin
+-- ValidationDialog/ # Map validation report
+-- StatusBar/ # Status messages and undo/redo controls
+-- ui/ # shadcn/ui base components (Button, Dialog, ...)
public/proto/ # Apollo .proto files served statically
Export Accuracy
The export engine is a direct port of the Apollo C++ source:
sim_map.bin-- replicates theDownsampleByAngle+DownsampleByDistancepasses frompoints_downsampler.hrouting_map.bin-- replicates node/edge cost formulas fromnode_creator.ccandedge_creator.cc:- Node cost:
length x (base_speed / speed_limit)+ turn penalty - Lane-change edge cost:
500 x (changing_length / 50)^-1.5 - Lane changes only allowed across dotted boundaries
- Node cost:
Development
npm run dev # start dev server with HMR
npm run build # production build
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier format all files
npm run format:check # Prettier check (CI)
npm run build # production build
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier format all files
npm run format:check # Prettier check (CI)
Pre-commit hooks (Husky + lint-staged) run ESLint and Prettier automatically on every commit.
Roadmap
- Road grouping UI (assign lanes to named roads)
- Snap-to-endpoint when connecting lanes
- Map validation report (orphan lanes, missing overlaps, ID conflicts)
- OSM tile background option
- Multi-select and bulk property editing
- Export to Apollo text proto format (
.txt) for inspection
License
This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).
Commercial use of this project is prohibited.
Third-Party Code
This project includes protocol buffer definitions and algorithm ports from the Apollo autonomous driving platform, which is licensed under the Apache License 2.0. Specifically:
public/proto/-- Protocol buffer definitions from Apollosrc/export/-- TypeScript ports of Apollo'ssim_map_generatorandtopo_creator
These portions remain subject to the Apache License 2.0. See the LICENSE file for full details.