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 the Map tile acquisition example.

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]
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.GoogleWTS(desired_tile_form='RGB', user_agent='CartoPy/0.18.0')[source]

Implement web tile retrieval using the Google WTS coordinate system.

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

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', user_agent='CartoPy/0.18.0')[source]
class cartopy.io.img_tiles.MapQuestOpenAerial(desired_tile_form='RGB', user_agent='CartoPy/0.18.0')[source]
class cartopy.io.img_tiles.MapboxStyleTiles(access_token, username, map_id)[source]

Implement web tile retrieval from a user-defined Mapbox style. For more details on Mapbox styles, see https://www.mapbox.com/studio-manual/overview/map-styling/.

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

Set up a new instance to retrieve tiles from a Mapbox style.

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.

  • username – The username for the Mapbox user who defined the Mapbox style.

  • map_id – A map ID for a map defined by a Mapbox style. This is the map whose tiles will be retrieved through this process. Note that this style may be private and if your access token does not have permissions to view this style, then map tile retrieval will fail.

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 – An ID for a publicly accessible map (provided by Mapbox). This is the map whose tiles will be retrieved through this process.

class cartopy.io.img_tiles.OSM(desired_tile_form='RGB', user_agent='CartoPy/0.18.0')[source]
class cartopy.io.img_tiles.OrdnanceSurvey(apikey, layer='Road', desired_tile_form='RGB')[source]

Implement web tile retrieval from Ordnance Survey map data. To use this tile image source you will need to obtain an API key from Ordnance Survey.

For more details on Ordnance Survey layer styles, see https://apidocs.os.uk/docs/map-styles.

For the API framework agreement, see https://developer.ordnancesurvey.co.uk/os-api-framework-agreement.

Parameters

  • apikey (required) – The authentication key provided by OS to query the maps API

  • layer (optional) –

    The style of the Ordnance Survey map tiles. One of ‘Outdoor’, ‘Road’, ‘Light’, ‘Night’, ‘Leisure’. Defaults to ‘Road’. Details about the style of layer can be found at:

  • desired_tile_form (optional) – Defaults to ‘RGB’.

class cartopy.io.img_tiles.QuadtreeTiles(desired_tile_form='RGB', user_agent='CartoPy/0.18.0')[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.

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.Stamen(style='toner', desired_tile_form='RGB')[source]

Retrieves tiles from maps.stamen.com. Styles include terrain-background, terrain, toner and watercolor.

For a full reference on the styles available please see http://maps.stamen.com. Of particular note are the sub-styles that are made available (e.g. terrain and terrain-background). To determine the name of the particular [sub-]style you want, follow the link on http://maps.stamen.com to your desired style and observe the style name in the URL. Your style name will be in the form of: http://maps.stamen.com/{STYLE_NAME}/#9/37/-122.

Except otherwise noted, the Stamen map tile sets are copyright Stamen Design, under a Creative Commons Attribution (CC BY 3.0) license.

Please see the attribution notice at http://maps.stamen.com on how to attribute this imagery.

class cartopy.io.img_tiles.StamenTerrain[source]

DEPRECATED: This class is deprecated. Please use Stamen('terrain-background') instead.

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.

References