Basemap

Add web-tile basemaps (OpenStreetMap and other XYZ providers) under a plotted raster or vector.

• get_provider — resolve a tile provider by name.
• add_basemap — draw a basemap onto a matplotlib axes.

See the Basemap example for a runnable walkthrough. Requires the [viz] extra.

pyramids.basemap.get_provider(name=None)

Resolve a web-tile provider by name.

Thin wrapper over :func:cleopatra.tiles.get_provider.

Parameters:

Name	Type	Description	Default
name	str or None	Dot-separated provider name (e.g. "OpenStreetMap.Mapnik", "CartoDB.Positron", "Esri.WorldImagery"). None returns the default (OpenStreetMap.Mapnik).	None

Returns:

Type	Description
Any	xyzservices.TileProvider: The resolved tile provider object (URL template + attribution).

Raises:

Type	Description
OptionalPackageDoesNotExist	If the cleopatra [tiles] extra is not installed.
ValueError	If the provider name cannot be resolved.

Examples:

• Resolve the default OpenStreetMap provider:

  >>> provider = get_provider()
  >>> provider.name
  'OpenStreetMap.Mapnik'
  

• Resolve a specific provider and inspect its URL:

  >>> provider = get_provider("CartoDB.Positron")
  >>> "basemaps.cartocdn.com" in provider.url
  True
  

• Invalid provider name raises ValueError:

  >>> get_provider("NonExistent.Provider")  # doctest: +SKIP
  Traceback (most recent call last):
      ...
  ValueError: ...
  

See Also

add_basemap: Uses get_provider internally (via cleopatra) when source is a string. cleopatra.tiles.get_provider: The underlying implementation.

Source code in src/pyramids/basemap/basemap.py

def get_provider(name: str | None = None) -> Any:
    """Resolve a web-tile provider by name.

    Thin wrapper over :func:`cleopatra.tiles.get_provider`.

    Args:
        name (str or None, optional):
            Dot-separated provider name (e.g. ``"OpenStreetMap.Mapnik"``,
            ``"CartoDB.Positron"``, ``"Esri.WorldImagery"``). ``None``
            returns the default (``OpenStreetMap.Mapnik``).

    Returns:
        xyzservices.TileProvider:
            The resolved tile provider object (URL template + attribution).

    Raises:
        OptionalPackageDoesNotExist: If the cleopatra ``[tiles]`` extra is
            not installed.
        ValueError: If the provider name cannot be resolved.

    Examples:
        - Resolve the default OpenStreetMap provider:
            ```python
            >>> provider = get_provider()
            >>> provider.name
            'OpenStreetMap.Mapnik'

            ```
        - Resolve a specific provider and inspect its URL:
            ```python
            >>> provider = get_provider("CartoDB.Positron")
            >>> "basemaps.cartocdn.com" in provider.url
            True

            ```
        - Invalid provider name raises ``ValueError``:
            ```python
            >>> get_provider("NonExistent.Provider")  # doctest: +SKIP
            Traceback (most recent call last):
                ...
            ValueError: ...

            ```

    See Also:
        add_basemap: Uses ``get_provider`` internally (via cleopatra) when
            ``source`` is a string.
        cleopatra.tiles.get_provider: The underlying implementation.
    """
    import_basemap(_BASEMAP_MSG)
    from cleopatra.tiles import get_provider as _get_provider

    return _get_provider(name)

pyramids.basemap.add_basemap(ax, crs=3857, source=None, zoom='auto', alpha=1.0, attribution=True, zorder=-1, interpolation='bilinear', timeout=10, retries=2)

Add a web-tile basemap underneath the data plotted on ax.

Thin wrapper over :func:cleopatra.tiles.add_tiles: fetches XYZ web tiles for the axes' geographic extent, stitches them into a single image, reprojects to the data's CRS via GDAL when crs is not Web Mercator, and renders the image beneath the data layer.

Parameters:

Name	Type	Description	Default
ax	Axes	The axes to add the basemap to. Must have data already plotted so that the axis limits define the geographic extent.	required
crs	int or str	CRS of the data on the axes — an EPSG integer (e.g. 4326) or a WKT/proj4 string. Default is 3857 (Web Mercator, no warping needed).	3857
source	str, TileProvider, or None	Tile provider. None defaults to OpenStreetMap.Mapnik; a dot-separated string like "CartoDB.Positron" is resolved via cleopatra's provider lookup; an xyzservices.TileProvider object is used directly.	None
zoom	int or 'auto'	Tile zoom level. "auto" computes it from the axes extent. Default is "auto".	'auto'
alpha	float	Opacity of the basemap (0.0 transparent, 1.0 opaque). Default is 1.0.	1.0
attribution	str or bool	True adds the provider's default attribution text; a string uses that text; False adds none. Default is True.	True
zorder	int	Matplotlib zorder. -1 places the basemap behind all data. Default is -1.	-1
interpolation	str	Interpolation method for ax.imshow(). Default is "bilinear".	'bilinear'
timeout	int	HTTP request timeout in seconds per tile. Default is 10.	10
retries	int	Number of retry attempts per failed tile. Default is 2.	2

Returns:

Type	Description
Any	matplotlib.axes.Axes: The axes with the basemap added (whatever :func:cleopatra.tiles.add_tiles returns).

Raises:

Type	Description
OptionalPackageDoesNotExist	If the cleopatra [tiles] extra is not installed.
TypeError	If ax is not a matplotlib Axes instance.
ValueError	If the axes have no data extent, the extent is degenerate, or zoom/crs is invalid.
ConnectionError	If tiles cannot be fetched from the provider.

Examples:

• Add a default OpenStreetMap basemap to a Dataset plot (+SKIP — needs a real raster, the [viz] extra, and network access to the tile provider):

  >>> from pyramids.basemap import add_basemap
  >>> from pyramids.dataset import Dataset
  >>> ds = Dataset.read_file("dem.tif")           # doctest: +SKIP
  >>> glyph = ds.plot(band=0)                     # doctest: +SKIP
  >>> add_basemap(glyph.ax, crs=ds.epsg)          # doctest: +SKIP
  

• Use a different tile provider with transparency:

  >>> add_basemap(                                # doctest: +SKIP
  ...     glyph.ax,
  ...     crs=ds.epsg,
  ...     source="CartoDB.Positron",
  ...     alpha=0.5,
  ... )
  

See Also

get_provider: Resolve a tile provider name to a TileProvider. cleopatra.tiles.add_tiles: The underlying implementation.

Source code in src/pyramids/basemap/basemap.py

def add_basemap(
    ax: Any,
    crs: int | str = 3857,
    source: str | Any | None = None,
    zoom: int | str = "auto",
    alpha: float = 1.0,
    attribution: str | bool = True,
    zorder: int = -1,
    interpolation: str = "bilinear",
    timeout: int = 10,
    retries: int = 2,
) -> Any:
    """Add a web-tile basemap underneath the data plotted on ``ax``.

    Thin wrapper over :func:`cleopatra.tiles.add_tiles`: fetches XYZ web
    tiles for the axes' geographic extent, stitches them into a single
    image, reprojects to the data's CRS via GDAL when ``crs`` is not Web
    Mercator, and renders the image beneath the data layer.

    Args:
        ax (matplotlib.axes.Axes):
            The axes to add the basemap to. Must have data already plotted
            so that the axis limits define the geographic extent.
        crs (int or str, optional):
            CRS of the data on the axes — an EPSG integer (e.g. ``4326``)
            or a WKT/proj4 string. Default is ``3857`` (Web Mercator, no
            warping needed).
        source (str, TileProvider, or None, optional):
            Tile provider. ``None`` defaults to ``OpenStreetMap.Mapnik``;
            a dot-separated string like ``"CartoDB.Positron"`` is resolved
            via cleopatra's provider lookup; an ``xyzservices.TileProvider``
            object is used directly.
        zoom (int or "auto", optional):
            Tile zoom level. ``"auto"`` computes it from the axes extent.
            Default is ``"auto"``.
        alpha (float, optional):
            Opacity of the basemap (``0.0`` transparent, ``1.0`` opaque).
            Default is ``1.0``.
        attribution (str or bool, optional):
            ``True`` adds the provider's default attribution text; a string
            uses that text; ``False`` adds none. Default is ``True``.
        zorder (int, optional):
            Matplotlib zorder. ``-1`` places the basemap behind all data.
            Default is ``-1``.
        interpolation (str, optional):
            Interpolation method for ``ax.imshow()``. Default is
            ``"bilinear"``.
        timeout (int, optional):
            HTTP request timeout in seconds per tile. Default is ``10``.
        retries (int, optional):
            Number of retry attempts per failed tile. Default is ``2``.

    Returns:
        matplotlib.axes.Axes: The axes with the basemap added (whatever
            :func:`cleopatra.tiles.add_tiles` returns).

    Raises:
        OptionalPackageDoesNotExist: If the cleopatra ``[tiles]`` extra is
            not installed.
        TypeError: If ``ax`` is not a matplotlib ``Axes`` instance.
        ValueError: If the axes have no data extent, the extent is
            degenerate, or ``zoom``/``crs`` is invalid.
        ConnectionError: If tiles cannot be fetched from the provider.

    Examples:
        - Add a default OpenStreetMap basemap to a Dataset plot
          (``+SKIP`` — needs a real raster, the ``[viz]`` extra, and
          network access to the tile provider):
            ```python
            >>> from pyramids.basemap import add_basemap
            >>> from pyramids.dataset import Dataset
            >>> ds = Dataset.read_file("dem.tif")           # doctest: +SKIP
            >>> glyph = ds.plot(band=0)                     # doctest: +SKIP
            >>> add_basemap(glyph.ax, crs=ds.epsg)          # doctest: +SKIP

            ```
        - Use a different tile provider with transparency:
            ```python
            >>> add_basemap(                                # doctest: +SKIP
            ...     glyph.ax,
            ...     crs=ds.epsg,
            ...     source="CartoDB.Positron",
            ...     alpha=0.5,
            ... )

            ```

    See Also:
        get_provider: Resolve a tile provider name to a ``TileProvider``.
        cleopatra.tiles.add_tiles: The underlying implementation.
    """
    import_basemap(_BASEMAP_MSG)
    from cleopatra.tiles import add_tiles

    result = add_tiles(
        ax,
        source=source,
        crs=crs,
        zoom=zoom,
        alpha=alpha,
        attribution=attribution,
        zorder=zorder,
        interpolation=interpolation,
        timeout=timeout,
        retries=retries,
    )
    return result