Tile-Generator (v0.5.0)

C++ toolset for generating optimized vector map tiles from OpenStreetMap PBF files, targeting ESP32-based GPS navigators.

Features

• Pure Hilbert Indexing (New): Uses a space-filling curve for both data ordering and indexing, ensuring maximum spatial locality and optimized SD card seek patterns.
• Binary Tile Deduplication (New): Identifies identical tiles (e.g., land/ocean background) and reuses data blocks, significantly reducing final file size.
• High-Performance C++ Engine: OSM PBF parsing and tile generation using GEOS, GDAL, and Libosmium.
• Efficient Binary Format: Packed NPK2 containers with Delta+ZigZag+VarInt coordinate encoding.
• Memory-Mapped Storage: Uses mmap for feature storage, allowing processing of large PBF files with minimal RAM.
• Multi-threaded Processing: Parallel tile generation leveraging all available CPU cores.
• Z-Order Management: 4-pass rendering pipeline supported in binary format.

Generation Process

The generator operates in multiple passes to ensure topological consistency and optimal packaging:

1. Pass 1 (Relations): Scans PBF for administrative boundaries and water multipolygons.
2. Pass 2 (Features): Extracts nodes and ways, applying semantic filtering and layer assignment.
3. Pass 3 (Water): Integrates global water polygons from external Shapefiles (using GDAL/OGR).
4. Pass 4 (Tiles): Parallel clipping, simplification (GEOS), and NPK2-Hilbert packaging.

Dependencies & Installation

Required Libraries

• Libosmium: PBF parsing.
• GEOS: Geometry operations (clipping, simplification, unions).
• GDAL/OGR: Shapefile support for ocean water polygons.
• Protozero: Low-level OSM data handling.
• C++17 Compiler: GCC 9+ or Clang.

Installation (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y build-essential cmake \
    libosmium2-dev libgeos-dev libgdal-dev \
    libbz2-dev zlib1g-dev libexpat1-dev

Compilation

mkdir build && cd build
cmake ..
make -j$(nproc)

Usage

./nav_generator <osm_pbf_file> <output_dir> <features_json> [--zoom min-max]

Example

./nav_generator andorra-latest.osm.pbf ./NAVMAP features.json --zoom 10-15

Visualization & Debugging

The project includes a Python-based simulator to validate maps before flashing them to the ESP32.

Prerequisites

• Python 3.x
• Pygame: pip install pygame

Usage

python3 tile_viewer.py <output_dir> --lat <latitude> --lon <longitude> --config features.json

Key Commands

• Arrows / Mouse Drag: Pan map.
• [ / ]: Zoom control.
• H: Toggle Hilbert Path (verify spatial locality).
• G: Toggle Tile Grid.
• S / L: Toggle Stats and Legend panels.

Internal Format Details

• Container: NPK2-Hilbert (Flat Hilbert Index).
• Internal Format: NAV1 (Geometry + Text labels).
• Coordinates: Web Mercator, 12-bit tile-relative space (0-4096).

For detailed binary format specifications, see docs/bin_tile_format.md.

---

Author

Jordi Gauchía (jgauchia@jgauchia.com)