TiledWebMaps
A lightweight library for retrieving map images from a tile provider with arbitrary resolution, location and bearing.
Install
pip install tiledwebmaps
Usage
Example
import tiledwebmaps as twm
tileloader = twm.Http("https://tiles.arcgis.com/tiles/hGdibHYSPO59RG1h/arcgis/rest" \
"/services/orthos2021/MapServer/tile/{zoom}/{y}/{x}") # MassGIS
image = tileloader.load(
latlon=(42.360995, -71.051685), # Center of the image
bearing=0.0, # Bearing pointing upwards in the image
meters_per_pixel=0.5,
shape=(512, 512),
zoom=20, # Zoom level of the fetched tiles
)
import imageio
imageio.imwrite("map.jpg", image)
The tileloader fetches multiple tiles from MassGIS and combines and transforms them to the correct location, bearing and resolution. This creates the following image (same location in Bing Maps):
Caching
Tiles can be saved on disk to avoid downloading the same tile multiple times:
http_tileloader = twm.Http("https://tiles.arcgis.com/tiles/hGdibHYSPO59RG1h/arcgis/rest" \
"/services/orthos2021/MapServer/tile/{zoom}/{y}/{x}")
cached_tileloader = twm.DiskCached(http_tileloader, "/path/to/map/folder")
cached_tileloader
will check if a tile is already present on disk before calling http_tileloader
.
Tiles can also be cached in memory using an LRU cache:
cached_tileloader = twm.LRUCached(http_tileloader, size=100)
Finding tile providers
Tile providers can for example be found at https://osmlab.github.io/editor-layer-index [1]. The url to the tile server contains placeholders that are replaced with the tile parameters when the http request is made.
Some examples:
-
US / MassGIS 2021 Aerial Imagery [1]:
tileloader = twm.Http("https://tiles.arcgis.com/tiles/hGdibHYSPO59RG1h/arcgis/rest/services/orthos2021/MapServer/tile/{zoom}/{y}/{x}")
-
US / StratMap CapArea, Brazos & Kerr Imagery (Natural Color 2021) [1]:
tileloader = twm.Http("https://imagery.tnris.org/server/services/StratMap/StratMap21_NCCIR_CapArea_Brazos_Kerr/ImageServer/WMSServer?FORMAT=image/jpeg&VERSION=1.3.0&SERVICE=WMS&REQUEST=GetMap&LAYERS=0&STYLES=&CRS={proj}&WIDTH={width}&HEIGHT={height}&BBOX={bbox}")
-
Google Maps Static API:
tileloader = twm.Http("https://maps.googleapis.com/maps/api/staticmap?center={lat_center},{lon_center}&size={width}x{height}&zoom={zoom}&maptype=satellite&key=YOUR_API_KEY")
- This requires an API key and a billing-enabled account as outlined here.
- Make sure to follow Google Map's Terms of Service, usage limits and geo guidelines.
- This will include the Google logo and copyright on every fetched tile.
-
Bing Maps:
tileloader = twm.bingmaps(key="YOUR_API_KEY")
- Accessing Bing Maps tiles requires fetching the correct url from their REST service first as outlined here. We provide the utility function
twm.bingmaps
for this purpose. - This requires an API key as outlined here. Bing Maps provides API keys for educational/ non-profit use with a daily free quota. See https://www.bingmapsportal.com/Application for more information.
- Make sure to follow Bing Map's Terms of Use and usage limits.
- Accessing Bing Maps tiles requires fetching the correct url from their REST service first as outlined here. We provide the utility function
-
MapBox Raster Tiles API:
tileloader = twm.Http("https://api.mapbox.com/v4/mapbox.satellite/{zoom}/{x}/{y}.png?access_token=YOUR_MAPBOX_TOKEN")
- This requires an API token as outlined here. MapBox has a daily free use quota as outlined here.
- Make sure to follow MapBox's Terms of Service and restrictions and limits.
-
For map tiles already stored on disk, use:
tileloader = twm.Disk("/path/{zoom}/{x}/{y}.jpg")
Notes
- The GIL is released for all operations, such that multiple calls can be made concurrently.
Paper
If you find this library useful for your research, please consider citing:
@InProceedings{Fervers_2023_CVPR,
author = {Fervers, Florian and Bullinger, Sebastian and Bodensteiner, Christoph and Arens, Michael and Stiefelhagen, Rainer},
title = {Uncertainty-Aware Vision-Based Metric Cross-View Geolocalization},
booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
month = {June},
year = {2023},
pages = {21621-21631}
}