33:class:`xarray.DataArray`.
44"""
55
6- from __future__ import annotations
6+ from typing import Literal
77
88from packaging .version import Version
99
1010try :
1111 import contextily
12+ from xyzservices import TileProvider
1213
1314 _HAS_CONTEXTILY = True
1415except ImportError :
16+ TileProvider = None
1517 _HAS_CONTEXTILY = False
1618
1719import numpy as np
2123
2224
2325def load_tile_map (
24- region ,
25- zoom = "auto" ,
26- source = None ,
27- lonlat = True ,
28- wait = 0 ,
29- max_retries = 2 ,
26+ region : list ,
27+ zoom : int | Literal [ "auto" ] = "auto" ,
28+ source : TileProvider | str | None = None ,
29+ lonlat : bool = True ,
30+ wait : int = 0 ,
31+ max_retries : int = 2 ,
3032 zoom_adjust : int | None = None ,
31- ):
33+ ) -> xr . DataArray :
3234 """
3335 Load a georeferenced raster tile map from XYZ tile providers.
3436
3537 The tiles that compose the map are merged and georeferenced into an
36- :class:`xarray.DataArray` image with 3 bands (RGB). Note that the returned
37- image is in a Spherical Mercator (EPSG:3857) coordinate reference system.
38+ :class:`xarray.DataArray` image with 3 bands (RGB). Note that the returned image is
39+ in a Spherical Mercator (EPSG:3857) coordinate reference system.
3840
3941 Parameters
4042 ----------
41- region : list
42- The bounding box of the map in the form of a list [*xmin*, *xmax*,
43- *ymin*, *ymax*]. These coordinates should be in longitude/latitude if
44- ``lonlat=True`` or Spherical Mercator (EPSG:3857) if ``lonlat=False``.
45-
46- zoom : int or str
47- Optional. Level of detail. Higher levels (e.g. ``22``) mean a zoom
48- level closer to the Earth's surface, with more tiles covering a smaller
49- geographical area and thus more detail. Lower levels (e.g. ``0``) mean
50- a zoom level further from the Earth's surface, with less tiles covering
51- a larger geographical area and thus less detail [Default is
52- ``"auto"`` to automatically determine the zoom level based on the
53- bounding box region extent].
43+ region
44+ The bounding box of the map in the form of a list [*xmin*, *xmax*, *ymin*,
45+ *ymax*]. These coordinates should be in longitude/latitude if ``lonlat=True`` or
46+ Spherical Mercator (EPSG:3857) if ``lonlat=False``.
47+ zoom
48+ Level of detail. Higher levels (e.g. ``22``) mean a zoom level closer to the
49+ Earth's surface, with more tiles covering a smaller geographical area and thus
50+ more detail. Lower levels (e.g. ``0``) mean a zoom level further from the
51+ Earth's surface, with less tiles covering a larger geographical area and thus
52+ less detail. Default is ``"auto"`` to automatically determine the zoom level
53+ based on the bounding box region extent.
5454
5555 .. note::
5656 The maximum possible zoom level may be smaller than ``22``, and depends on
5757 what is supported by the chosen web tile provider source.
58-
59- source : xyzservices.TileProvider or str
60- Optional. The tile source: web tile provider or path to a local file.
61- Provide either:
62-
63- - A web tile provider in the form of a
64- :class:`xyzservices.TileProvider` object. See
65- :doc:`Contextily providers <contextily:providers_deepdive>` for a
66- list of tile providers [Default is
67- ``xyzservices.providers.OpenStreetMap.HOT``, i.e. OpenStreetMap
68- Humanitarian web tiles].
69- - A web tile provider in the form of a URL. The placeholders for the
70- XYZ in the URL need to be {x}, {y}, {z}, respectively. E.g.
58+ source
59+ The tile source: web tile provider or path to a local file. Provide either:
60+
61+ - A web tile provider in the form of a :class:`xyzservices.TileProvider` object.
62+ See :doc:`Contextily providers <contextily:providers_deepdive>` for a list of
63+ tile providers. Default is ``xyzservices.providers.OpenStreetMap.HOT``, i.e.
64+ OpenStreetMap Humanitarian web tiles.
65+ - A web tile provider in the form of a URL. The placeholders for the XYZ in the
66+ URL need to be {x}, {y}, {z}, respectively. E.g.
7167 ``https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png``.
72- - A local file path. The file is read with
73- :doc:`rasterio <rasterio:index>` and all bands are loaded into the
74- basemap. See
68+ - A local file path. The file is read with :doc:`rasterio <rasterio:index>` and
69+ all bands are loaded into the basemap. See
7570 :doc:`contextily:working_with_local_files`.
7671
7772 .. important::
7873 Tiles are assumed to be in the Spherical Mercator projection (EPSG:3857).
79-
80- lonlat : bool
81- Optional. If ``False``, coordinates in ``region`` are assumed to be
82- Spherical Mercator as opposed to longitude/latitude [Default is
83- ``True``].
84-
85- wait : int
86- Optional. If the tile API is rate-limited, the number of seconds to
87- wait between a failed request and the next try [Default is ``0``].
88-
89- max_retries : int
90- Optional. Total number of rejected requests allowed before contextily
91- will stop trying to fetch more tiles from a rate-limited API [Default
92- is ``2``].
93-
74+ lonlat
75+ If ``False``, coordinates in ``region`` are assumed to be Spherical Mercator as
76+ opposed to longitude/latitude.
77+ wait
78+ If the tile API is rate-limited, the number of seconds to wait between a failed
79+ request and the next try.
80+ max_retries
81+ Total number of rejected requests allowed before contextily will stop trying to
82+ fetch more tiles from a rate-limited API.
9483 zoom_adjust
9584 The amount to adjust a chosen zoom level if it is chosen automatically. Values
9685 outside of -1 to 1 are not recommended as they can lead to slow execution.
@@ -100,15 +89,15 @@ def load_tile_map(
10089
10190 Returns
10291 -------
103- raster : xarray.DataArray
92+ raster
10493 Georeferenced 3-D data array of RGB values.
10594
10695 Raises
10796 ------
10897 ImportError
109- If ``contextily`` is not installed or can't be imported. Follow
110- :doc:`install instructions for contextily <contextily:index>`, (e.g.
111- via ``python -m pip install contextily``) before using this function.
98+ If ``contextily`` is not installed or can't be imported. Follow the
99+ :doc:`install instructions for contextily <contextily:index>`, (e.g. via
100+ ``python -m pip install contextily``) before using this function.
112101
113102 Examples
114103 --------
0 commit comments