tilefetch 0.1.0__py3-none-any.whl

tilefetch/providers.py

@@ -0,0 +1,137 @@
+"""Built-in provider registry.
+
+Only services whose published terms allow scripted, offline use are listed.
+Each entry carries its terms URL and the attribution its operator asks for,
+plus conservative per-job limits that stay well inside those terms. Limits on
+built-in providers cannot be raised from the API or the CLI; they can only be
+lowered.
+
+Popular community tile servers (tile.openstreetmap.org, OpenTopoMap, ...)
+are deliberately absent: their policies forbid bulk or offline downloading.
+For those data, run your own tile server or use a commercial plan that
+permits it, and pass its URL template to :func:`tilefetch.fetch`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .sources import TileSource
+
+__all__ = ["PROVIDERS", "get_provider", "list_providers", "register_provider"]
+
+_USGS_ATTRIBUTION = (
+    "Map services and data available from U.S. Geological Survey, National Geospatial Program."
+)
+_USGS_TERMS = (
+    "https://www.usgs.gov/faqs/what-are-terms-uselicensing-map-services-and-data-national-map"
+)
+_GIBS_ATTRIBUTION = (
+    "Imagery provided by services from NASA's Global Imagery Browse Services (GIBS), part of "
+    "NASA's Earth Science Data and Information System (ESDIS)."
+)
+_GIBS_TERMS = "https://nasa-gibs.github.io/gibs-api-docs/map-library-usage/#bulk-downloading"
+_GIBS = "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best"
+
+# USGS states there are "no restrictions" on The National Map services; GIBS
+# defines a bulk download as > 1,000,000 tiles in 24 h and asks for advance
+# coordination above that. The caps below keep one job far from either limit.
+_USGS_LIMITS: dict[str, Any] = {"max_tiles": 50_000, "max_rate": 8.0, "max_threads": 4}
+_GIBS_LIMITS: dict[str, Any] = {"max_tiles": 100_000, "max_rate": 16.0, "max_threads": 8}
+
+_US_BOUNDS = (-180.0, -15.0, 180.0, 72.0)
+
+PROVIDERS: dict[str, TileSource] = {}
+
+
+def register_provider(source: TileSource, *, overwrite: bool = False) -> TileSource:
+    """Add a source to the registry under ``source.name``."""
+    if source.name in PROVIDERS and not overwrite:
+        raise ValueError(f"provider {source.name!r} is already registered")
+    PROVIDERS[source.name] = source
+    return source
+
+
+def get_provider(name: str) -> TileSource:
+    """Look up a registered provider by name."""
+    try:
+        return PROVIDERS[name]
+    except KeyError:
+        raise KeyError(
+            f"unknown provider {name!r}; known: {', '.join(sorted(PROVIDERS))}"
+        ) from None
+
+
+def list_providers() -> list[TileSource]:
+    """All registered providers, sorted by name."""
+    return [PROVIDERS[k] for k in sorted(PROVIDERS)]
+
+
+def _usgs(name: str, service: str, description: str) -> TileSource:
+    return TileSource(
+        name=name,
+        url=f"https://basemap.nationalmap.gov/arcgis/rest/services/{service}/MapServer/tile/{{z}}/{{y}}/{{x}}",
+        attribution=_USGS_ATTRIBUTION,
+        terms_url=_USGS_TERMS,
+        description=description + " United States and territories; public domain.",
+        min_zoom=0,
+        max_zoom=16,
+        format="jpg",
+        bounds=_US_BOUNDS,
+        builtin=True,
+        **_USGS_LIMITS,
+    )
+
+
+def _gibs(
+    name: str, layer: str, matrix_set: str, max_zoom: int, description: str, time: str | None = None
+) -> TileSource:
+    if time is None:
+        url = f"{_GIBS}/{layer}/default/default/{matrix_set}/{{z}}/{{y}}/{{x}}.jpeg"
+        params: dict[str, str] = {}
+    else:
+        url = f"{_GIBS}/{layer}/default/{{time}}/{matrix_set}/{{z}}/{{y}}/{{x}}.jpg"
+        params = {"time": time}
+    return TileSource(
+        name=name,
+        url=url,
+        params=params,
+        attribution=_GIBS_ATTRIBUTION,
+        terms_url=_GIBS_TERMS,
+        description=description,
+        min_zoom=0,
+        max_zoom=max_zoom,
+        format="jpg",
+        builtin=True,
+        **_GIBS_LIMITS,
+    )
+
+
+for _src in (
+    _usgs("usgs-topo", "USGSTopo", "USGS Topo base map (The National Map)."),
+    _usgs("usgs-imagery", "USGSImageryOnly", "USGS orthoimagery base map (The National Map)."),
+    _usgs("usgs-shaded-relief", "USGSShadedReliefOnly", "USGS shaded relief (The National Map)."),
+    _gibs(
+        "nasa-bluemarble",
+        "BlueMarble_NextGeneration",
+        "GoogleMapsCompatible_Level8",
+        8,
+        "NASA Blue Marble: Next Generation global true-colour mosaic (500 m).",
+    ),
+    _gibs(
+        "nasa-bluemarble-relief",
+        "BlueMarble_ShadedRelief_Bathymetry",
+        "GoogleMapsCompatible_Level8",
+        8,
+        "NASA Blue Marble with shaded relief and bathymetry.",
+    ),
+    _gibs(
+        "nasa-modis-terra",
+        "MODIS_Terra_CorrectedReflectance_TrueColor",
+        "GoogleMapsCompatible_Level9",
+        9,
+        "NASA MODIS Terra daily corrected reflectance (true colour). Set params time=YYYY-MM-DD.",
+        time="2024-06-01",
+    ),
+):
+    register_provider(_src)

tilefetch/sources.py

@@ -0,0 +1,546 @@
+"""Tile sources: URL templates, WMTS capabilities parsing and usage policy.
+
+A :class:`TileSource` turns an XYZ tile address into a URL and carries the
+rules that govern its use: attribution, terms URL, a hard cap on tiles per
+job, a request-rate limit and a thread limit.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import math
+import re
+import urllib.parse
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from .tiles import ORIGIN_SHIFT, Tile, flip_y, tile_bounds_mercator, tile_to_quadkey
+
+__all__ = [
+    "TileSource",
+    "PolicyError",
+    "TileLimitError",
+    "RESTRICTED_HOSTS",
+    "check_url_policy",
+    "WMTSLayerInfo",
+    "parse_wmts_capabilities",
+    "wmts_source",
+    "DEFAULT_CUSTOM_MAX_TILES",
+    "DEFAULT_CUSTOM_MAX_RATE",
+]
+
+#: Tile cap applied to user-supplied URL templates unless raised explicitly.
+DEFAULT_CUSTOM_MAX_TILES = 10_000
+#: Default request rate (requests per second) for user-supplied URL templates.
+DEFAULT_CUSTOM_MAX_RATE = 10.0
+
+
+class PolicyError(RuntimeError):
+    """The request conflicts with the tile provider's usage policy."""
+
+
+class TileLimitError(PolicyError):
+    """The job needs more tiles than the provider allows per job."""
+
+
+#: Hosts whose operators forbid bulk / offline downloading by third-party tools.
+#: Matching is by host suffix. tilefetch refuses these outright; run your own
+#: tile server (or use one whose terms allow bulk use) instead.
+RESTRICTED_HOSTS: dict[str, tuple[str, str]] = {
+    "tile.openstreetmap.org": (
+        "The OSMF Tile Usage Policy forbids bulk downloading and offline use of "
+        "tile.openstreetmap.org tiles.",
+        "https://operations.osmfoundation.org/policies/tiles/",
+    ),
+    "tile.osm.org": (
+        "The OSMF Tile Usage Policy forbids bulk downloading and offline use of OSMF tiles.",
+        "https://operations.osmfoundation.org/policies/tiles/",
+    ),
+    "opentopomap.org": (
+        "OpenTopoMap asks users not to overload its server with mass downloads.",
+        "https://opentopomap.org/about",
+    ),
+    "google.com": (
+        "The Google Maps Platform terms forbid pre-fetching, caching or bulk download of tiles.",
+        "https://cloud.google.com/maps-platform/terms",
+    ),
+    "googleapis.com": (
+        "The Google Maps Platform terms forbid pre-fetching, caching or bulk download of tiles.",
+        "https://cloud.google.com/maps-platform/terms",
+    ),
+    "virtualearth.net": (
+        "The Microsoft Bing Maps terms forbid bulk download and offline caching of imagery.",
+        "https://www.microsoft.com/en-us/maps/bing-maps/product",
+    ),
+    "arcgisonline.com": (
+        "Esri basemap tiles may only be taken offline through Esri's own export tools "
+        "under an ArcGIS licence that allows it.",
+        "https://www.esri.com/en-us/legal/terms/full-master-agreement",
+    ),
+}
+
+
+def check_url_policy(url: str) -> None:
+    """Raise :class:`PolicyError` if ``url`` points at a host that forbids bulk use."""
+    host = (urllib.parse.urlsplit(url).hostname or "").lower()
+    # Templates may carry a subdomain placeholder such as "{s}.tile...".
+    host = re.sub(r"^\{[^}]*\}\.", "", host)
+    for suffix, (reason, terms) in RESTRICTED_HOSTS.items():
+        if host == suffix or host.endswith("." + suffix):
+            raise PolicyError(
+                f"{reason} tilefetch will not bulk-download from {host}. "
+                f"Terms: {terms}. Use a tile server you operate or one whose terms allow "
+                "bulk/offline use."
+            )
+
+
+_PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
+_BUILTIN_KEYS = {
+    "z",
+    "x",
+    "y",
+    "-y",
+    "q",
+    "quadkey",
+    "s",
+    "bbox",
+    "bbox-epsg-3857",
+    "TileMatrix",
+    "TileRow",
+    "TileCol",
+}
+
+
+@dataclass
+class TileSource:
+    """A tile endpoint and the rules for using it.
+
+    ``url`` is a template with any of these placeholders:
+
+    ``{z} {x} {y}``
+        XYZ address (``{y}`` is flipped when ``scheme="tms"``).
+    ``{-y}``
+        TMS row (always flipped, regardless of ``scheme``).
+    ``{q}`` / ``{quadkey}``
+        Bing-style quadkey.
+    ``{s}``
+        One of ``subdomains`` (chosen deterministically per tile).
+    ``{bbox}`` / ``{bbox-epsg-3857}``
+        Tile bounds ``minx,miny,maxx,maxy`` in EPSG:3857, for WMS GetMap URLs.
+    ``{TileMatrix} {TileRow} {TileCol}``
+        WMTS addressing (see :func:`wmts_source`).
+
+    Any other ``{name}`` must be supplied in ``params`` (API keys, dates, ...).
+    """
+
+    url: str
+    name: str = "custom"
+    attribution: str = ""
+    terms_url: str | None = None
+    description: str = ""
+    min_zoom: int = 0
+    max_zoom: int = 22
+    tile_size: int = 256
+    scheme: str = "xyz"
+    subdomains: tuple[str, ...] = ()
+    headers: dict[str, str] = field(default_factory=dict)
+    params: dict[str, str] = field(default_factory=dict)
+    max_tiles: int | None = DEFAULT_CUSTOM_MAX_TILES
+    max_rate: float | None = DEFAULT_CUSTOM_MAX_RATE
+    max_threads: int = 4
+    builtin: bool = False
+    format: str | None = None
+    bounds: tuple[float, float, float, float] | None = None
+    matrix_ids: dict[int, str] = field(default_factory=dict)
+    matrix_offsets: dict[int, tuple[int, int]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.scheme not in ("xyz", "tms"):
+            raise ValueError("scheme must be 'xyz' or 'tms'")
+        if self.min_zoom > self.max_zoom:
+            raise ValueError("min_zoom is greater than max_zoom")
+        self.subdomains = tuple(self.subdomains)
+        missing = [
+            k
+            for k in _PLACEHOLDER.findall(self.url)
+            if k not in _BUILTIN_KEYS and k not in self.params
+        ]
+        if missing:
+            raise ValueError(
+                f"URL template has placeholders without values: {sorted(set(missing))}; "
+                "pass them in params"
+            )
+        if "{s}" in self.url and not self.subdomains:
+            raise ValueError("URL template uses {s} but no subdomains were given")
+        if "://" in self.url:
+            check_url_policy(self.url)
+
+    @classmethod
+    def from_url(cls, url: str, **kwargs: Any) -> TileSource:
+        """Build a custom source from a URL template (``{z}/{x}/{y}`` etc.)."""
+        if "subdomains" not in kwargs and "{s}" in url:
+            kwargs["subdomains"] = ("a", "b", "c")
+        return cls(url=url, **kwargs)
+
+    def replace(self, **changes: Any) -> TileSource:
+        """Copy of this source with some fields changed."""
+        return dataclasses.replace(self, **changes)
+
+    @property
+    def cache_key(self) -> str:
+        """Filesystem-safe identifier used for the on-disk cache."""
+        import hashlib
+
+        h = hashlib.sha256(self.url.encode("utf-8"))
+        for k in sorted(self.params):
+            h.update(f"\0{k}={self.params[k]}".encode())
+        return re.sub(r"[^A-Za-z0-9_.-]", "_", self.name)[:40] + "-" + h.hexdigest()[:12]
+
+    def tile_url(self, tile: Tile | tuple[int, int, int]) -> str:
+        """URL of one tile."""
+        z, x, y = tile
+        if z < self.min_zoom or z > self.max_zoom:
+            raise ValueError(
+                f"zoom {z} is outside {self.name!r} range {self.min_zoom}-{self.max_zoom}"
+            )
+        if self.matrix_ids and z not in self.matrix_ids:
+            raise ValueError(f"the tile matrix set of {self.name!r} has no matrix for zoom {z}")
+        dx, dy = self.matrix_offsets.get(z, (0, 0))
+        values: dict[str, str] = {
+            "z": str(z),
+            "x": str(x),
+            "y": str(flip_y(z, y) if self.scheme == "tms" else y),
+            "-y": str(flip_y(z, y)),
+            "TileMatrix": self.matrix_ids.get(z, str(z)),
+            "TileRow": str(y - dy),
+            "TileCol": str(x - dx),
+        }
+        url = self.url
+        if "{q" in url:
+            values["q"] = values["quadkey"] = tile_to_quadkey((z, x, y))
+        if "{bbox" in url:
+            b = tile_bounds_mercator((z, x, y))
+            values["bbox"] = values["bbox-epsg-3857"] = ",".join(
+                repr(round(v, 6)) for v in (b.minx, b.miny, b.maxx, b.maxy)
+            )
+        if self.subdomains:
+            values["s"] = self.subdomains[(x + y) % len(self.subdomains)]
+        values.update(self.params)
+        return _PLACEHOLDER.sub(lambda m: values[m.group(1)], url)
+
+    def summary(self) -> dict[str, Any]:
+        """Plain-dict description (used by ``tilefetch providers``)."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "url": self.url,
+            "zoom": f"{self.min_zoom}-{self.max_zoom}",
+            "attribution": self.attribution,
+            "terms_url": self.terms_url,
+            "max_tiles": self.max_tiles,
+            "max_rate": self.max_rate,
+            "max_threads": self.max_threads,
+        }
+
+
+# ---------------------------------------------------------------------------
+# WMTS
+# ---------------------------------------------------------------------------
+
+#: OGC "standardized rendering pixel size" in metres (WMTS 1.0.0, 6.1).
+_PIXEL_SIZE = 0.00028
+_MERCATOR_CRS = re.compile(
+    r"(?:EPSG(?::[\d.]*)?:+(?:3857|900913|3785|102100)$)|GoogleMapsCompatible", re.I
+)
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _child(el: ET.Element, name: str) -> ET.Element | None:
+    for c in el:
+        if _local(c.tag) == name:
+            return c
+    return None
+
+
+def _children(el: ET.Element, name: str) -> list[ET.Element]:
+    return [c for c in el if _local(c.tag) == name]
+
+
+def _text(el: ET.Element | None, name: str, default: str = "") -> str:
+    if el is None:
+        return default
+    c = _child(el, name)
+    return (c.text or "").strip() if c is not None and c.text else default
+
+
+@dataclass
+class WMTSLayerInfo:
+    """What :func:`parse_wmts_capabilities` found for one layer."""
+
+    identifier: str
+    title: str
+    formats: list[str]
+    styles: list[str]
+    default_style: str | None
+    tile_matrix_sets: list[str]
+    resource_urls: list[tuple[str, str]]  # (format, template)
+    dimensions: dict[str, str]  # identifier -> default value
+
+
+@dataclass
+class _MatrixSet:
+    identifier: str
+    crs: str
+    # zoom -> (matrix identifier, tile size, (col offset, row offset))
+    zooms: dict[int, tuple[str, int, tuple[int, int]]]
+    skipped: list[str]
+
+
+def _parse_matrix_set(el: ET.Element) -> _MatrixSet:
+    ident = _text(el, "Identifier")
+    crs = _text(el, "SupportedCRS")
+    zooms: dict[int, tuple[str, int, tuple[int, int]]] = {}
+    skipped: list[str] = []
+    for tm in _children(el, "TileMatrix"):
+        mid = _text(tm, "Identifier")
+        try:
+            scale = float(_text(tm, "ScaleDenominator"))
+            tw = int(_text(tm, "TileWidth", "256"))
+            th = int(_text(tm, "TileHeight", "256"))
+            tlx, tly = (float(v) for v in _text(tm, "TopLeftCorner").split()[:2])
+        except ValueError:
+            skipped.append(mid)
+            continue
+        span = scale * _PIXEL_SIZE * tw  # metres covered by one tile
+        zf = math.log2(2.0 * ORIGIN_SHIFT / span)
+        z = round(zf)
+        if tw != th or abs(zf - z) > 0.01 or z < 0:
+            skipped.append(mid)
+            continue
+        # The top-left corner must sit on the global tile grid.
+        cf = (tlx + ORIGIN_SHIFT) / span
+        rf = (ORIGIN_SHIFT - tly) / span
+        if abs(cf - round(cf)) > 0.01 or abs(rf - round(rf)) > 0.01:
+            skipped.append(mid)
+            continue
+        zooms[z] = (mid, tw, (round(cf), round(rf)))
+    return _MatrixSet(ident, crs, zooms, skipped)
+
+
+def parse_wmts_capabilities(xml: str | bytes) -> tuple[dict[str, WMTSLayerInfo], dict[str, Any]]:
+    """Parse a WMTS 1.0.0 GetCapabilities document.
+
+    Returns ``(layers, extra)`` where ``layers`` maps layer identifiers to
+    :class:`WMTSLayerInfo` and ``extra`` holds ``kvp_url`` (the GetTile KVP
+    endpoint, if advertised), ``rest`` (whether RESTful encoding is
+    advertised) and ``matrix_sets`` (parsed tile matrix sets).
+    """
+    root = ET.fromstring(xml)
+    if _local(root.tag) != "Capabilities":
+        raise ValueError("not a WMTS Capabilities document")
+    contents = _child(root, "Contents")
+    if contents is None:
+        raise ValueError("WMTS capabilities has no Contents element")
+    layers: dict[str, WMTSLayerInfo] = {}
+    for lay in _children(contents, "Layer"):
+        styles = []
+        default_style = None
+        for st in _children(lay, "Style"):
+            sid = _text(st, "Identifier")
+            styles.append(sid)
+            if st.get("isDefault", "").lower() == "true":
+                default_style = sid
+        dims = {}
+        for d in _children(lay, "Dimension"):
+            dims[_text(d, "Identifier")] = _text(d, "Default") or _text(d, "Value")
+        info = WMTSLayerInfo(
+            identifier=_text(lay, "Identifier"),
+            title=_text(lay, "Title"),
+            formats=[(f.text or "").strip() for f in _children(lay, "Format")],
+            styles=styles,
+            default_style=default_style or (styles[0] if styles else None),
+            tile_matrix_sets=[
+                _text(link, "TileMatrixSet") for link in _children(lay, "TileMatrixSetLink")
+            ],
+            resource_urls=[
+                (r.get("format", ""), r.get("template", ""))
+                for r in _children(lay, "ResourceURL")
+                if r.get("resourceType", "tile") == "tile"
+            ],
+            dimensions=dims,
+        )
+        layers[info.identifier] = info
+    matrix_sets = {}
+    for tms in _children(contents, "TileMatrixSet"):
+        ms = _parse_matrix_set(tms)
+        matrix_sets[ms.identifier] = ms
+    kvp_url = None
+    rest = False
+    for op in root.iter():
+        if _local(op.tag) != "Operation" or op.get("name") != "GetTile":
+            continue
+        for get in op.iter():
+            if _local(get.tag) != "Get":
+                continue
+            href = get.get("{http://www.w3.org/1999/xlink}href", "")
+            values = [
+                (v.text or "").strip().upper() for v in get.iter() if _local(v.tag) == "Value"
+            ]
+            if "KVP" in values or not values:
+                kvp_url = kvp_url or href
+            if "RESTFUL" in values:
+                rest = True
+    return layers, {"kvp_url": kvp_url, "rest": rest, "matrix_sets": matrix_sets}
+
+
+def _fetch_text(url: str, headers: Mapping[str, str], timeout: float) -> bytes:
+    import urllib.request
+
+    from ._version import __version__
+
+    h = {"User-Agent": f"tilefetch/{__version__}"}
+    h.update(headers)
+    req = urllib.request.Request(url, headers=h)
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 - user URL
+        data: bytes = resp.read()
+        return data
+
+
+_EXT = {"image/png": "png", "image/jpeg": "jpg", "image/jpg": "jpg", "image/webp": "webp"}
+
+
+def wmts_source(
+    capabilities: str | bytes,
+    layer: str,
+    *,
+    tile_matrix_set: str | None = None,
+    style: str | None = None,
+    format: str | None = None,
+    dimensions: Mapping[str, str] | None = None,
+    encoding: str = "auto",
+    attribution: str = "",
+    terms_url: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = 30.0,
+    **kwargs: Any,
+) -> TileSource:
+    """Build a :class:`TileSource` for a WMTS layer.
+
+    ``capabilities`` is a GetCapabilities URL, a local file path or the XML
+    itself. A Web Mercator tile matrix set is chosen automatically (or pass
+    ``tile_matrix_set``); its matrices are mapped to XYZ zoom levels by scale
+    denominator, so matrix identifiers such as ``"EPSG:3857:12"`` and matrix
+    sets with a smaller extent (offset top-left corner) both work.
+    ``encoding`` is ``"rest"``, ``"kvp"`` or ``"auto"`` (REST when the layer
+    has a ResourceURL template). ``dimensions`` overrides defaults such as
+    ``{"Time": "2024-06-01"}``.
+    """
+    hdrs = dict(headers or {})
+    if isinstance(capabilities, bytes):
+        xml: str | bytes = capabilities
+    elif capabilities.lstrip().startswith("<"):
+        xml = capabilities
+    elif re.match(r"^https?://", capabilities):
+        check_url_policy(capabilities)
+        xml = _fetch_text(capabilities, hdrs, timeout)
+    else:
+        with open(capabilities, "rb") as fh:
+            xml = fh.read()
+    layers, extra = parse_wmts_capabilities(xml)
+    if layer not in layers:
+        raise ValueError(f"layer {layer!r} not found; available: {sorted(layers)[:20]}")
+    info = layers[layer]
+    matrix_sets: dict[str, _MatrixSet] = extra["matrix_sets"]
+
+    candidates = [tile_matrix_set] if tile_matrix_set else info.tile_matrix_sets
+    chosen: _MatrixSet | None = None
+    for name in candidates:
+        ms = matrix_sets.get(name or "")
+        if ms is None:
+            if tile_matrix_set:
+                raise ValueError(f"tile matrix set {tile_matrix_set!r} not found")
+            continue
+        if _MERCATOR_CRS.search(ms.crs) or _MERCATOR_CRS.search(ms.identifier):
+            if ms.zooms:
+                chosen = ms
+                break
+        elif tile_matrix_set:
+            raise ValueError(
+                f"tile matrix set {tile_matrix_set!r} uses {ms.crs}; only Web Mercator "
+                "(EPSG:3857) matrix sets are supported"
+            )
+    if chosen is None:
+        raise ValueError(
+            f"layer {layer!r} has no Web Mercator (EPSG:3857) tile matrix set "
+            f"(links: {info.tile_matrix_sets})"
+        )
+    sizes = {size for _, size, _ in chosen.zooms.values()}
+    if len(sizes) != 1:
+        raise ValueError("tile matrices with mixed tile sizes are not supported")
+
+    fmt = format or (info.formats[0] if info.formats else "image/png")
+    sty = style or info.default_style or "default"
+    dims = dict(info.dimensions)
+    dims.update(dimensions or {})
+
+    use_rest = encoding == "rest" or (encoding == "auto" and bool(info.resource_urls))
+    if encoding not in ("auto", "rest", "kvp"):
+        raise ValueError("encoding must be 'auto', 'rest' or 'kvp'")
+    if use_rest:
+        templates = [t for f, t in info.resource_urls if f == fmt] or [
+            t for _, t in info.resource_urls
+        ]
+        if not templates:
+            raise ValueError(f"layer {layer!r} has no ResourceURL for REST access")
+        url = templates[0]
+        fixed = {"TileMatrixSet": chosen.identifier, "Style": sty, "style": sty}
+        fixed.update(dims)
+
+        def sub(m: re.Match[str]) -> str:
+            key = m.group(1)
+            if key in ("TileMatrix", "TileRow", "TileCol"):
+                return m.group(0)
+            for k, v in fixed.items():
+                if k.lower() == key.lower():
+                    return urllib.parse.quote(v, safe=":-_.")
+            raise ValueError(f"no value for WMTS template variable {{{key}}}; pass dimensions")
+
+        url = _PLACEHOLDER.sub(sub, url)
+    else:
+        base = extra["kvp_url"]
+        if not base:
+            raise ValueError("capabilities advertise no KVP GetTile endpoint")
+        query = {
+            "SERVICE": "WMTS",
+            "REQUEST": "GetTile",
+            "VERSION": "1.0.0",
+            "LAYER": layer,
+            "STYLE": sty,
+            "TILEMATRIXSET": chosen.identifier,
+            "FORMAT": fmt,
+        }
+        query.update(dims)
+        qs = urllib.parse.urlencode(query, safe=":/")
+        qs += "&TILEMATRIX={TileMatrix}&TILEROW={TileRow}&TILECOL={TileCol}"
+        sep = "" if base.endswith(("?", "&")) else ("&" if "?" in base else "?")
+        url = base + sep + qs
+
+    zooms = sorted(chosen.zooms)
+    kwargs.setdefault("name", f"wmts:{layer}")
+    return TileSource(
+        url=url,
+        attribution=attribution,
+        terms_url=terms_url,
+        headers=hdrs,
+        min_zoom=zooms[0],
+        max_zoom=zooms[-1],
+        tile_size=sizes.pop(),
+        format=_EXT.get(fmt.split(";")[0].strip().lower()),
+        matrix_ids={z: v[0] for z, v in chosen.zooms.items()},
+        matrix_offsets={z: v[2] for z, v in chosen.zooms.items() if v[2] != (0, 0)},
+        **kwargs,
+    )