Offline Maps Guide

ezOS includes an offline map viewer for navigation without cellular or internet connectivity.

Maps are stored as .tdmap files on the SD card.

Quick Start

1. Download source data: Get a PMTiles file from Protomaps

2. Convert to TDMAP format:

   cd tools/maps
   pip install -r requirements.txt
   python pmtiles_to_tdmap.py input.pmtiles -o map.tdmap
   

3. Copy to SD card: Place map.tdmap in the root of your SD card

4. Open in ezOS: Navigate to Menu → Map Viewer

Conversion Options

Basic Usage

python pmtiles_to_tdmap.py input.pmtiles -o output.tdmap

Limit to Specific Region

python pmtiles_to_tdmap.py input.pmtiles \
    --bounds 4.0,52.0,5.5,52.5 \
    --zoom 10,14 \
    -o netherlands.tdmap

Options:

• --bounds WEST,SOUTH,EAST,NORTH: Limit to bounding box (decimal degrees)
• --zoom MIN,MAX: Zoom levels to include (default: all available)
• --resume: Resume interrupted conversion

Large Regions

For large areas, the conversion saves checkpoints every 500 tiles. If interrupted,

simply run the same command again to resume.

TDMAP Format

The TDMAP format is optimized for the ESP32's limited memory:

• 8-color semantic palette: Land, water, parks, buildings, roads, railways
• RLE compression: Typically 5-20x smaller than raw pixels
• Binary search index: Fast tile lookup without loading entire file
• Labels: Place names with coordinates and zoom ranges

File Size Estimates

Map Settings

Configure the map viewer in Settings → Map:

• Theme: Light or dark color scheme
• Pan Speed: Trackball movement sensitivity

Troubleshooting

"No map file found"

Ensure map.tdmap is in the root of the SD card and the card is properly inserted.

Slow loading

Large map files may take a few seconds to index on first load. The index is cached

for subsequent accesses.

Missing areas

Check your --bounds parameters. The conversion only includes tiles that intersect

the bounding box.

See Also

• tools/maps/README.md - Conversion tool documentation
• Settings Reference - Map viewer settings