pygmt.Figure.tilemap

Figure.tilemap(region, zoom='auto', source=None, lonlat=True, wait=0, max_retries=2, *, frame=None, dpi=None, shading=None, projection=None, monochrome=None, no_clip=None, nan_transparent=None, verbose=None, panel=None, perspective=None, transparency=None, **kwargs)

Plots an XYZ tile map.

This method loads XYZ tile maps from a tile server or local file using pygmt.datasets.load_tile_map into a georeferenced form, and plots the tiles as a basemap or overlay using pygmt.Figure.grdimage.

Note: By default, standard web map tiles served in a Spherical Mercator (EPSG:3857) Cartesian format will be reprojected to a geographic coordinate reference system (OGC:WGS84) and plotted with longitude/latitude bounds when lonlat=True. If reprojection is not desired, please set lonlat=False and provide Spherical Mercator (EPSG:3857) coordinates to the region parameter.

Aliases:

  • B = frame

  • E = dpi

  • I = shading

  • J = projection

  • M = monochrome

  • N = no_clip

  • Q = nan_transparent

  • V = verbose

  • c = panel

  • p = perspective

  • t = transparency

Parameters

  • region (list) – The bounding box of the map in the form of a list [xmin, xmax, ymin, ymax]. These coordinates should be in longitude/latitude if lonlat=True or Spherical Mercator (EPSG:3857) if lonlat=False.

  • zoom (int or str) –

    Optional. Level of detail. Higher levels (e.g. 22) mean a zoom level closer to the Earth’s surface, with more tiles covering a smaller geographical area and thus more detail. Lower levels (e.g. 0) mean a zoom level further from the Earth’s surface, with less tiles covering a larger geographical area and thus less detail [Default is "auto" to automatically determine the zoom level based on the bounding box region extent].

    Note: The maximum possible zoom level may be smaller than 22, and depends on what is supported by the chosen web tile provider source.

  • source (xyzservices.TileProvider or str) –

    Optional. The tile source: web tile provider or path to a local file. Provide either:

    • A web tile provider in the form of a xyzservices.TileProvider object. See Contextily providers for a list of tile providers [Default is xyzservices.providers.Stamen.Terrain, i.e. Stamen Terrain web tiles].

    • A web tile provider in the form of a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. E.g. https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png.

    • A local file path. The file is read with rasterio and all bands are loaded into the basemap. See Working with local files.

    IMPORTANT: Tiles are assumed to be in the Spherical Mercator projection (EPSG:3857).

  • lonlat (bool) – Optional. If False, coordinates in region are assumed to be Spherical Mercator as opposed to longitude/latitude [Default is True].

  • wait (int) – Optional. If the tile API is rate-limited, the number of seconds to wait between a failed request and the next try [Default is 0].

  • max_retries (int) – Optional. Total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API [Default is 2].

  • kwargs (dict) – Extra keyword arguments to pass to pygmt.Figure.grdimage.

Raises

ImportError – If rioxarray is not installed. Follow install instructions for rioxarray, (e.g. via python -m pip install rioxarray) before using this function.

Examples using pygmt.Figure.tilemap

Tile maps

Tile maps