Image tile identification and fetching

Implements image tile identification and fetching from various sources.

The Matplotlib interface can make use of tile objects (defined below) via the cartopy.mpl.geoaxes.GeoAxes.add_image() method. For example, to add a MapQuest Open Aerial tileset to an existing axes at zoom level 2, do ax.add_image(MapQuestOpenAerial(), 2). An example of using tiles in this way can be found at examples-eyja_volcano.

class cartopy.io.img_tiles.GoogleTiles(desired_tile_form='RGB', style='street', url='https://mts0.google.com/vt/lyrs={style}@177000000&hl=en&src=api&x={x}&y={y}&z={z}&s=G')[source]

Implement web tile retrieval using the Google WTS coordinate system.

A “tile” in this class refers to the coordinates (x, y, z).

Parameters:
  • desired_tile_form (optional) – Defaults to ‘RGB’.
  • style (optional) – The style for the Google Maps tiles. One of ‘street’, ‘satellite’, ‘terrain’, and ‘only_streets’. Defaults to ‘street’.
  • url (optional) – URL pointing to a tile source and containing {x}, {y}, and {z}. Such as: (‘https://server.arcgisonline.com/ArcGIS/rest/services/’ ‘World_Shaded_Relief/MapServer/tile/{z}/{y}/{x}.jpg’)
find_images(target_domain, target_z, start_tile=(0, 0, 0))

Target domain is a shapely polygon in native coordinates.

tile_bbox(x, y, z, y0_at_north_pole=True)[source]

Return the (x0, x1), (y0, y1) bounding box for the given x, y, z tile position.

Parameters:
  • x – The x tile coordinate in the Google tile numbering system.
  • y – The y tile coordinate in the Google tile numbering system.
  • z – The z tile coordinate in the Google tile numbering system.
  • y0_at_north_pole (optional) – Boolean representing whether the numbering of the y coordinate starts at the north pole (as is the convention for Google tiles) or not (in which case it will start at the south pole, as is the convention for TMS). Defaults to True.
tileextent(x_y_z)[source]

Return extent tuple (x0,x1,y0,y1) in Mercator coordinates.

class cartopy.io.img_tiles.MapQuestOSM(desired_tile_form='RGB', style='street', url='https://mts0.google.com/vt/lyrs={style}@177000000&hl=en&src=api&x={x}&y={y}&z={z}&s=G')[source]
Parameters:
  • desired_tile_form (optional) – Defaults to ‘RGB’.
  • style (optional) – The style for the Google Maps tiles. One of ‘street’, ‘satellite’, ‘terrain’, and ‘only_streets’. Defaults to ‘street’.
  • url (optional) – URL pointing to a tile source and containing {x}, {y}, and {z}. Such as: (‘https://server.arcgisonline.com/ArcGIS/rest/services/’ ‘World_Shaded_Relief/MapServer/tile/{z}/{y}/{x}.jpg’)
class cartopy.io.img_tiles.MapQuestOpenAerial(desired_tile_form='RGB', style='street', url='https://mts0.google.com/vt/lyrs={style}@177000000&hl=en&src=api&x={x}&y={y}&z={z}&s=G')[source]
Parameters:
  • desired_tile_form (optional) – Defaults to ‘RGB’.
  • style (optional) – The style for the Google Maps tiles. One of ‘street’, ‘satellite’, ‘terrain’, and ‘only_streets’. Defaults to ‘street’.
  • url (optional) – URL pointing to a tile source and containing {x}, {y}, and {z}. Such as: (‘https://server.arcgisonline.com/ArcGIS/rest/services/’ ‘World_Shaded_Relief/MapServer/tile/{z}/{y}/{x}.jpg’)
class cartopy.io.img_tiles.MapboxTiles(access_token, map_id)[source]

Implement web tile retrieval from Mapbox.

For terms of service, see https://www.mapbox.com/tos/.

Set up a new Mapbox tiles instance.

Access to Mapbox web services requires an access token and a map ID. See https://www.mapbox.com/api-documentation/ for details.

Parameters:
  • access_token – A valid Mapbox API access token.
  • map_id – A map ID for a publically accessible map. This is the map whose tiles will be retrieved through this process.
class cartopy.io.img_tiles.OSM(desired_tile_form='RGB', style='street', url='https://mts0.google.com/vt/lyrs={style}@177000000&hl=en&src=api&x={x}&y={y}&z={z}&s=G')[source]
Parameters:
  • desired_tile_form (optional) – Defaults to ‘RGB’.
  • style (optional) – The style for the Google Maps tiles. One of ‘street’, ‘satellite’, ‘terrain’, and ‘only_streets’. Defaults to ‘street’.
  • url (optional) – URL pointing to a tile source and containing {x}, {y}, and {z}. Such as: (‘https://server.arcgisonline.com/ArcGIS/rest/services/’ ‘World_Shaded_Relief/MapServer/tile/{z}/{y}/{x}.jpg’)
class cartopy.io.img_tiles.QuadtreeTiles(desired_tile_form='RGB', style='street', url='https://mts0.google.com/vt/lyrs={style}@177000000&hl=en&src=api&x={x}&y={y}&z={z}&s=G')[source]

Implement web tile retrieval using the Microsoft WTS quadkey coordinate system.

A “tile” in this class refers to a quadkey such as “1”, “14” or “141” where the length of the quatree is the zoom level in Google Tile terms.

Parameters:
  • desired_tile_form (optional) – Defaults to ‘RGB’.
  • style (optional) – The style for the Google Maps tiles. One of ‘street’, ‘satellite’, ‘terrain’, and ‘only_streets’. Defaults to ‘street’.
  • url (optional) – URL pointing to a tile source and containing {x}, {y}, and {z}. Such as: (‘https://server.arcgisonline.com/ArcGIS/rest/services/’ ‘World_Shaded_Relief/MapServer/tile/{z}/{y}/{x}.jpg’)
find_images(target_domain, target_z, start_tile=None)[source]

Find all the quadtrees at the given target zoom, in the given target domain.

target_z must be a value >= 1.

tileextent(quadkey)[source]

Return extent tuple (x0,x1,y0,y1) in Mercator coordinates.

class cartopy.io.img_tiles.StamenTerrain(desired_tile_form='RGB', style='street', url='https://mts0.google.com/vt/lyrs={style}@177000000&hl=en&src=api&x={x}&y={y}&z={z}&s=G')[source]

Terrain tiles defined for the continental United States, and include land color and shaded hills. The land colors are a custom palette developed by Gem Spear for the National Atlas 1km land cover data set, which defines twenty-four land classifications including five kinds of forest, combinations of shrubs, grasses and crops, and a few tundras and wetlands. The colors are at their highest contrast when fully zoomed-out to the whole U.S., and they slowly fade out to pale off-white as you zoom in to leave room for foreground data and break up the weirdness of large areas of flat, dark green.

Additional info: http://mike.teczno.com/notes/osm-us-terrain-layer/background.html http://maps.stamen.com/ https://wiki.openstreetmap.org/wiki/List_of_OSM_based_Services https://github.com/migurski/DEM-Tools

Parameters:
  • desired_tile_form (optional) – Defaults to ‘RGB’.
  • style (optional) – The style for the Google Maps tiles. One of ‘street’, ‘satellite’, ‘terrain’, and ‘only_streets’. Defaults to ‘street’.
  • url (optional) – URL pointing to a tile source and containing {x}, {y}, and {z}. Such as: (‘https://server.arcgisonline.com/ArcGIS/rest/services/’ ‘World_Shaded_Relief/MapServer/tile/{z}/{y}/{x}.jpg’)