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

⚠️ Not all tile providers allow caching or storing tiles on disk! Please check the terms of use of the tile provider before using this feature.

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

⚠️ Some tile providers like Google Maps, Bing Maps and MapBox charge payment for tile requests. We are not responsible for charges incured when using this library!

⚠️ This library does not enforce usage limits. Make to sure to stay within the allowed quota for each tile provider!

⚠️ Some tile providers like Google Maps and Bing Maps require attribution when using/ displaying images (see e.g. this).

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.

• 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}
}