pygmt.Figure.tilemap

Figure.tilemap(region, zoom='auto', source=None, lonlat=True, wait=0, max_retries=2, zoom_adjust=None, headers=None, monochrome=False, no_clip=False, projection=None, frame=False, verbose=False, panel=False, perspective=False, transparency=None, *, dpi=None, shading=None, nan_transparent=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:CRS84) 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

  • E = dpi

  • I = shading

  • Q = nan_transparent

  • B = frame

  • J = projection

  • M = monochrome

  • N = no_clip

  • V = verbose

  • c = panel

  • p = perspective

  • t = transparency

Parameters:

  • region (Sequence[float]) – 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 | 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://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.

  • headers (dict[str, str] | None, default: None) –

    HTTP headers to include with requests to the tile server. This can be useful for authentication or to set a custom User-Agent. When supported by contextily (>=1.7.0), PyGMT sets a default User-Agent header like PyGMT/X.Y.Z (+https://www.pygmt.org).

    Note

    Requires contextily>=1.7.0.

  • monochrome (bool, default: False) – Force conversion to monochrome image using the (television) YIQ transformation.

  • no_clip (bool, default: False) – Do not clip the tiles at the frame boundaries, so that the full extent of the downloaded tiles is plotted [Default is False].

  • projection (str | None, default: None) – projcode[projparams/]width|scale. Select map projection.

  • frame (Frame | Axis | Literal['none'] | str | Sequence[str] | bool, default: False) – Set frame and axes attributes for the plot. It can be a bool, "none", a pygmt.params.Frame or pygmt.params.Axis object. Raw GMT strings or sequences of strings are also supported for backward compatibility. If frame=True, the frame will be drawn with the default attributes. If frame="none", no frame will be drawn. Use a pygmt.params.Frame or pygmt.params.Axis object for more control over the attributes of the frame and axes. A tutorial is available at frame and axes attributes. Full documentation is at https://docs.generic-mapping-tools.org/6.7/gmt.html#b-full.

  • verbose (Literal['quiet', 'error', 'warning', 'timing', 'info', 'compat', 'debug'] | bool, default: False) – Select verbosity level [Full usage].

  • panel (int | Sequence[int] | bool, default: False) –

    Select a specific subplot panel. Only allowed when used in Figure.subplot mode.

    • True to advance to the next panel in the selected order.

    • index to specify the index of the desired panel.

    • (row, col) to specify the row and column of the desired panel.

    The panel order is determined by the Figure.subplot method. row, col and index all start at 0.

  • perspective (float | Sequence[float] | str | bool, default: False) –

    Select perspective view and set the azimuth and elevation of the viewpoint.

    Accepts a single value or a sequence of two or three values: azimuth, (azimuth, elevation), or (azimuth, elevation, zlevel).

    • azimuth: Azimuth angle of the viewpoint in degrees [Default is 180, i.e., looking from south to north].

    • elevation: Elevation angle of the viewpoint above the horizon [Default is 90, i.e., looking straight down at nadir].

    • zlevel: Z-level at which 2-D elements (e.g., the plot frame) are drawn. Only applied when used together with zsize or zscale. [Default is at the bottom of the z-axis].

    Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method, or pass a string following the full GMT syntax for finer control (e.g., adding +w or +v modifiers to select an axis location other than the plot origin). See https://docs.generic-mapping-tools.org/6.7/gmt.html#perspective-full for details.

  • transparency (float | None, default: None) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

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

Examples

>>> import contextily
>>> import pygmt

Plot a tile map of Honolulu, Hawaii using the default OpenStreetMap Humanitarian web tiles:

>>> fig = pygmt.Figure()
>>> fig.tilemap(
...     region=[-157.84, -157.8, 21.255, 21.285], projection="M12c", frame=True
... )
>>> fig.show()

Use the Esri World Imagery satellite tiles provided via the contextily library at a specified zoom level:

>>> fig = pygmt.Figure()
>>> fig.tilemap(
...     region=[-157.84, -157.8, 21.255, 21.285],
...     projection="M12c",
...     zoom=14,
...     source=contextily.providers.Esri.WorldImagery,
...     frame=True,
... )
>>> fig.show()

Examples using pygmt.Figure.tilemap

Tile maps

Tile maps