A lightweight Python helper for downloading raster map tiles and stitching them into a single image.
pyMap converts a geographic bounding box or an explicit tile range into Web Mercator tile coordinates, downloads missing tiles into a local cache, and mosaics the cached tiles into a PNG output.
- 🧭 Two download modes: geographic coordinates or tile numbers.
- 🧩 Tile mosaic output: merges 256x256 tiles into one PNG image.
- 💾 Local tile cache: skips tiles that already exist under
tiles/. - 🗺️ Built-in map sources: Gaode, Tianditu, Google satellite, Esri satellite, and custom URL templates.
- 🧪 Unit-tested core flow: coordinate conversion, validation, download dispatch, cache skip, and file writing.
- 📝 Typed and documented code: core functions include Python type hints and docstrings.
- 🧰 Installable CLI: exposes
pymap/pyMapcommands for third-party usage.
Install the published package from PyPI:
pip install pymap-tileAfter installation, use the CLI directly:
pymap --help
pymap sourcesInstall from a local checkout when developing:
pip install -e .This project is intended for learning, research, and personal tooling. Please respect map provider terms of service, copyright, rate limits, and local laws. Do not use it for unauthorized commercial map downloads.
- Python 3.5+
requestsfor HTTP downloadsPillowfor image compositiontqdmfor progress output
Download with a geographic bounding box:
pymap latlng 22.456671 113.889962 22.345576 114.212686 13 --output sample --maptype gaodeDownload with tile-number bounds:
pymap tilenum 1566 1788 1976 2149 9 --output overlay --maptype defaultRun from a config file:
pymap config --file config.confList built-in sources:
pymap sourcesThe historical direct script style is still supported:
python pyMap.py 22.456671 113.889962 22.345576 114.212686 13 sample gaodeLegacy arguments:
| # | Name | Description |
|---|---|---|
| 1 | north | Northwest latitude |
| 2 | west | Northwest longitude |
| 3 | south | Southeast latitude |
| 4 | east | Southeast longitude |
| 5 | zoom | Web Mercator tile zoom level |
| 6 | output | Output image name; saved as output/<name>.png |
| 7 | map type | Built-in source key or custom tile URL template |
pyMap.py reads config.conf when run directly without arguments. You can also run the same flow through the CLI:
pymap config --file config.conf[config]
下载方式 = 瓦片编码
左上横轴 = 803
左上纵轴 = 984
右下横轴 = 857
右下纵轴 = 1061
级别 = 8
项目名 = test
地图地址 = default[config]
下载方式 = 地理编码
左上横轴 = 113.889962
左上纵轴 = 22.456671
右下横轴 = 114.212686
右下纵轴 = 22.345576
级别 = 13
项目名 = sample
地图地址 = gaodeDownload by geographic coordinates:
from pyMap import process_latlng
process_latlng(
north=22.456671,
west=113.889962,
south=22.345576,
east=114.212686,
zoom=13,
output="sample",
maptype="gaode",
)Download by tile numbers:
from pyMap import process_tilenum
process_tilenum(
left=1566,
right=1788,
top=1976,
bottom=2149,
zoom=9,
output="overlay",
maptype="default",
)Built-in source keys are defined in pyMap.py:
gaodegaode.imagegaode.roadtianditutianditusattianditu.roadgooglesatesrisatdefaultszbuildingszbase
You can also pass a custom URL template with {x}, {y}, and {z} placeholders:
process_tilenum(
1,
2,
3,
4,
5,
output="custom",
maptype="https://example.com/tiles/{z}/{x}/{y}.png",
)tiles/<cache-name>/<zoom>/<x>/<y>.png
output/<output-name>.png
For built-in map sources, <cache-name> is the source key. For custom URL templates, <cache-name> is the output value.
Install development dependencies first if needed:
pip install -r requirements.txtRun the standard-library test suite:
python3 -m unittest discover -s tests -vIf pytest is available, the suite also works through:
pytest- brandonxiang/pyMap - Raster map download helper in Python.
- brandonxiang/pyMap_GFW - Selenium/PhantomJS-based raster map helper.
- brandonxiang/pyMap_webapp - Web app version of pyMap.
- brandonxiang/nodemap_spider - Electron crawler for raster maps.
- brandonxiang/nodemap - Electron app for nodemap_spider.