https://github.com/jgauchia/tile-generator
This repository contains a Python script for generating vector map tiles from OpenStreetMap (OSM) data in a custom binary format.
https://github.com/jgauchia/tile-generator
esp32 gps icenav osm tile
Last synced: 3 months ago
JSON representation
This repository contains a Python script for generating vector map tiles from OpenStreetMap (OSM) data in a custom binary format.
- Host: GitHub
- URL: https://github.com/jgauchia/tile-generator
- Owner: jgauchia
- License: gpl-3.0
- Created: 2025-08-09T22:14:41.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-10T17:47:20.000Z (11 months ago)
- Last Synced: 2025-08-10T19:26:36.309Z (11 months ago)
- Topics: esp32, gps, icenav, osm, tile
- Language: Python
- Homepage:
- Size: 143 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tile-Generator (v0.4.0)
C++ toolset for generating optimized vector map tiles from OpenStreetMap PBF files, targeting ESP32-based GPS navigators.
## Features
- **High-Performance C++ Engine**: OSM PBF parsing and tile generation using GEOS, Osmium, and GDAL.
- **Four-Pass Rendering Pipeline**: Road casings, bridge decks, and layered text labels.
- **Smart Text Labels (GEOM_TEXT)**: Collision detection and population-based filtering for place names and road labels.
- **Packed Binary Containers (NPK2)**: Tiles consolidated into single `Zxx.nav` files per zoom level with Y-table index for O(1) row lookup.
- **Ocean Water Polygons**: Optional loading of pre-computed water polygons from [osmdata.openstreetmap.de](https://osmdata.openstreetmap.de) shapefiles, with spatial filtering on the PBF bounding box.
- **Memory Optimized**: POSIX `mmap` feature storage for country-scale processing with low RAM footprint.
- **Advanced Aesthetics**:
- **Multi-Level Boundaries**: International, regional, and municipal borders.
- **Smart Filtering**: Automatic removal of tunnels, subway lines, and underground polygons.
- **Dynamic Styles**: Line widths (0.5px units) and 16-level priorities via `features.json`.
- **ESP32 Ready**: VarInt/ZigZag delta encoding and streaming-ready structures.
- **PC Simulator**: Pygame-based viewer with 4-pass rendering simulation.
---
## Getting Started
### 1. Requirements
Install the necessary libraries (Ubuntu/Debian):
```bash
sudo apt-get install libosmium2-dev libgeos-dev nlohmann-json3-dev libgdal-dev libboost-dev
```
### 2. Building the Generator
```bash
mkdir build && cd build
cmake ..
make -j$(nproc)
```
### 3. Generating Maps
```bash
./nav_generator features.json [--zoom 6-17] [--water-shp ]
```
### 4. Ocean Water Polygons (optional)
Download the pre-computed water polygons shapefile (once, ~540 MB):
```bash
wget https://osmdata.openstreetmap.de/download/water-polygons-split-4326.zip
unzip water-polygons-split-4326.zip
```
Generate with oceans:
```bash
./nav_generator input.pbf output features.json --zoom 6-17 \
--water-shp water-polygons-split-4326/water_polygons.shp
```
The generator reads the PBF bounding box and only loads water polygons intersecting the extract area. See [WATER.md](WATER.md) for details.
### 5. Viewing Maps (PC)
```bash
python tile_viewer.py --lat --lon [--zoom ] --config features.json
```
---
## Processing Pipeline
```
1. Config loading (features.json)
2. Pass 1: RelationScanner (boundaries, water multipolygon relations)
3. Pass 2: PBF feature extraction (ways, areas → MappedStore)
4. Pass 3: Water polygon loading from shapefile (optional, --water-shp)
5. TileProcessor: clip, merge, simplify, emit for all zoom levels → NPK2 packs
```
---
## Technical Standards
- **Container Format**: NPK2 with Y-table index for O(1) row lookup + binary search within rows.
- **Tile Format**: NAV1, 13-byte feature header with casing flags and 0.5px width units.
- **Z-Order**: 16 priority levels (0-15) mapped to a 4-pass rendering pipeline.
- **Coordinate System**: Web Mercator, 12-bit tile-relative space (0-4096), delta VarInt/ZigZag encoding.
For detailed binary format specifications, see [`docs/bin_tile_format.md`](docs/bin_tile_format.md).
---
## Author
**Jordi Gauchía** (jgauchia@jgauchia.com)