Max Zoom Levels
The --max-zoom option controls the maximum detail level. Each additional zoom level roughly quadruples the number of tiles.
| Max Zoom | Approx. Tile Count (planet) | Typical Output Size | Use Case |
|---|---|---|---|
| 6 | ~5,000 | ~50 MB | World overview, continental boundaries |
| 8 | ~85,000 | ~500 MB | Country-level detail |
| 10 | ~1.3 million | ~5 GB | Regional roads and land use |
| 12 | ~22 million | ~30 GB | City blocks visible |
| 14 | ~350 million | ~200 GB | Full detail, individual buildings |
| 15 | ~1.4 billion | ~500+ GB | Maximum detail (large output) |
Output sizes are approximate and vary by region density. Urban areas produce more tiles than oceans due to deduplication of empty tiles.
Choosing the Right Zoom Level
- Zoom 14 is the default and recommended for most use cases. It provides full building-level detail without excessive output size.
- Zoom 10–12 is a good choice for overview maps or when storage is limited.
- Zoom 15 should only be used when maximum detail is required and storage is not a concern.
Disk Space Estimates
Plan for these storage requirements:
| Component | Size Estimate | Notes |
|---|---|---|
| Input data (Overture) | ~200 GB (planet) | Downloaded GeoParquet files |
| Temporary sort files | ~1.5× input size | LZ4 compressed, stored in --tmpdir |
| Output PMTiles | ~1× input size | After deduplication (30–50% savings) |
| Total disk needed | ~3.5× input size | Input + temp + output |
For a full planet build at zoom 14:
Input: ~200 GB
Temp: ~300 GB
Output: ~200 GB
─────────────────
Total: ~700 GB free disk space recommended
Ensure your --tmpdir has enough space for temporary files. Running out of disk during the sort phase will cause the build to fail.
Thread Count
The --threads option controls parallelism for feature processing (Phase 1).
| Threads | Best For |
|---|---|
| Default (all cores) | Dedicated build machine, fastest processing |
| Half cores | Shared machine, leaves headroom for other tasks |
| 4–8 | Laptops or machines with limited cooling |
# Use 8 threads on a 16-core machine
geolith --data ./overture-data --output planet.pmtiles --threads 8
Memory usage scales roughly linearly with thread count due to per-thread buffers. If you're memory-constrained, reducing threads can help.
Temporary Directory
The --tmpdir option controls where external sort files are written. This is the most I/O-intensive part of the pipeline.
Recommendations:
- Use the fastest available disk (NVMe SSD preferred)
- Avoid network-mounted filesystems (NFS, SMB)
- Avoid the same physical disk as
--dataif possible (reduces I/O contention) - Ensure 1.5× the input data size is available
# Use a dedicated fast SSD for temp files
geolith \
--data /mnt/data/overture \
--output /mnt/data/planet.pmtiles \
--tmpdir /mnt/fast-nvme/tmp
Optimal Configuration Summary
For a dedicated planet build on a capable machine:
geolith \
--data /mnt/data/overture-2025.01.0 \
--output /mnt/data/planet.pmtiles \
--max-zoom 14 \
--tmpdir /mnt/nvme/tmp \
--threads $(nproc)
| Setting | Value | Why |
|---|---|---|
--max-zoom 14 | Full building detail | Good balance of detail and size |
--tmpdir on NVMe | Fastest sort phase | External sort is I/O bound |
--threads $(nproc) | All cores | Maximize parallelism |
| Separate disks for data/tmp/output | Reduced I/O contention | Parallel reads and writes |