meshos-mapgen is a production-quality, cross-platform CLI application designed to generate offline OpenStreetMap raster tiles for MeshCore MeshOS running on the LilyGO T-Deck.
It automatically fetches Geofabrik OSM extracts, merges state PBF datasets, renders standard OpenStreetMap Carto XYZ PNG tiles inside a Docker container, losslessly optimizes PNGs with oxipng, and outputs a ready-to-use tiles/ directory formatted specifically for your T-Deck micro SD card.
- MeshOS Compatible: Generates standard XYZ PNG tiles in
tiles/{zoom}/{x}/{y}.pngformat expected by MeshCore MeshOS on LilyGO T-Deck. - Cross-Platform: Full support for Linux (Ubuntu, Debian, Mint, Arch, Fedora), macOS, and Windows (via WSL2 / Docker Desktop).
- Auto-Installer & Portable Fallbacks: Automatically detects missing system tools (
osmium-tool,oxipng) and prompts to install them via system package manager (apt,brew,pacman,dnf), or falls back seamlessly to Docker containers and native Python libraries. - Smart Downloads: Auto-downloads Geofabrik extracts for New England states (MA, CT, RI, VT, NH, ME) with ETag / Last-Modified caching, HTTP Range resume, and SHA256 checksum verification.
- Seamless Docker Integration: Automatically handles dataset merging and OpenStreetMap Carto container rendering with zero manual Mapnik or PostGIS setup.
- Layered Zoom & Regions: Multi-layered rendering with bounding box presets (
western-mass-max,western-massachusetts,massachusetts,new-england,southern-vermont,southern-new-hampshire) or custom bounding boxes. - Resumable & Efficient: Skips existing valid PNG tiles and already-optimized files automatically if interrupted or re-run.
- Lossless PNG Optimization: Runs
oxipngautomatically to minimize SD card storage footprint while retaining 100% visual quality. - Rich Terminal UI: Live resource monitoring (CPU usage %, disk space, remaining SD capacity, render speed, and ETA).
Via uv (Recommended / Fastest):
uv tool install git+https://github.com/JustACluelessKidAtSchool/meshos-mapgen.gitVia pipx:
pipx install git+https://github.com/JustACluelessKidAtSchool/meshos-mapgen.gitOr install from source:
git clone https://github.com/JustACluelessKidAtSchool/meshos-mapgen.git
cd meshos-mapgen
uv pip install . # or pip install .- Initialize Configuration:
meshos-mapgen initCreates a default config.yaml using the built-in western-mass-max profile.
- Estimate Requirements:
meshos-mapgen estimate config.yamlPreviews total tile counts, estimated disk space, and estimated render time without rendering.
- Build Maps:
meshos-mapgen build config.yamlDownloads extracts, merges PBF data, renders tiles, optimizes PNGs, and saves output to ~/MeshOS-Tiles/tiles/.
- Copy to SD Card:
Copy the generated
tiles/directory directly to the root of your LilyGO T-Deck micro SD card.
style: osm-carto
output: ~/MeshOS-Tiles
threads: auto
optimize_png: true
regions:
- name: new-england
zoom: 5-12
- name: massachusetts
zoom: 13-16
- name: western-massachusetts
zoom: 17
- name: southern-vermont
zoom: 16-17
- name: southern-new-hampshire
zoom: 16-17Pre-configured presets available for use in config.yaml:
western-massachusetts:[-73.55, 41.95, -71.55, 42.90]massachusetts:[-73.5081, 41.2379, -69.9284, 42.8868]new-england:[-73.7278, 40.9801, -66.9499, 47.4597]southern-vermont:[-73.44, 42.74, -72.45, 43.50]southern-new-hampshire:[-72.56, 42.70, -70.70, 43.50]
Distributed under the MIT License.