pygmt.Figure.tilemap

Figure.tilemap(region, zoom='auto', source=None, lonlat=True, wait=0, max_retries=2, zoom_adjust=None, **kwargs)

Plot 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 (Union[int, Literal['auto']], default: 'auto') –

    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 (TileProvider | str | None, default: None) –

    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.OpenStreetMap.HOT, i.e. OpenStreetMap Humanitarian 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, default: True) – If False, coordinates in region are assumed to be Spherical Mercator as opposed to longitude/latitude.

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

  • max_retries (int, default: 2) – Total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API.

  • zoom_adjust (int | None, default: None) –

    The amount to adjust a chosen zoom level if it is chosen automatically. Values outside of -1 to 1 are not recommended as they can lead to slow execution.

    Note

    The zoom_adjust parameter requires contextily>=1.5.0.

  • 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