tilefetch 0.1.0__py3-none-any.whl

tilefetch/tiles.py

@@ -0,0 +1,469 @@
+"""Web Mercator tile math: XYZ/TMS addressing, quadkeys, bounds and coverage.
+
+All tiles use the "Google" XYZ convention (origin at the top-left, y grows
+southwards) unless a function says otherwise. Longitudes and latitudes are in
+degrees (EPSG:4326); projected coordinates are EPSG:3857 metres.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from typing import Any, Iterable, Iterator, NamedTuple, Sequence, Union
+
+__all__ = [
+    "EARTH_RADIUS",
+    "ORIGIN_SHIFT",
+    "MAX_LATITUDE",
+    "Tile",
+    "BBox",
+    "lonlat_to_mercator",
+    "mercator_to_lonlat",
+    "lonlat_to_tile",
+    "tile_bounds_mercator",
+    "tile_bounds_lonlat",
+    "resolution",
+    "flip_y",
+    "tile_to_quadkey",
+    "quadkey_to_tile",
+    "parse_bbox",
+    "parse_zoom",
+    "bbox_to_mercator",
+    "tiles_for_bbox",
+    "tiles_for_geometry",
+    "tiles_for_polygons",
+    "load_geometry",
+    "geometry_bbox",
+    "tile_count",
+]
+
+EARTH_RADIUS = 6378137.0
+#: Half the width of the Web Mercator world, in metres.
+ORIGIN_SHIFT = math.pi * EARTH_RADIUS  # 20037508.342789244
+#: Latitude at which the Web Mercator square ends.
+MAX_LATITUDE = math.degrees(2.0 * math.atan(math.exp(math.pi)) - math.pi / 2.0)  # 85.0511287798
+#: Highest zoom level accepted anywhere in the package.
+MAX_ZOOM = 30
+
+
+class Tile(NamedTuple):
+    """An XYZ tile address (top-left origin)."""
+
+    z: int
+    x: int
+    y: int
+
+    @property
+    def tms_y(self) -> int:
+        """Row in the TMS scheme (bottom-left origin), as used by MBTiles."""
+        return flip_y(self.z, self.y)
+
+    @property
+    def quadkey(self) -> str:
+        return tile_to_quadkey(self)
+
+
+class BBox(NamedTuple):
+    """A bounding box ``(minx, miny, maxx, maxy)``."""
+
+    minx: float
+    miny: float
+    maxx: float
+    maxy: float
+
+
+BBoxLike = Union[BBox, Sequence[float], str]
+ZoomLike = Union[int, str, Iterable[int]]
+
+
+def _check_zoom(z: int) -> None:
+    if not isinstance(z, int) or isinstance(z, bool) or z < 0 or z > MAX_ZOOM:
+        raise ValueError(f"zoom must be an integer between 0 and {MAX_ZOOM}, got {z!r}")
+
+
+def _clamp_lat(lat: float) -> float:
+    return max(-MAX_LATITUDE, min(MAX_LATITUDE, lat))
+
+
+def lonlat_to_mercator(lon: float, lat: float) -> tuple[float, float]:
+    """Project longitude/latitude (degrees) to EPSG:3857 metres.
+
+    Latitudes beyond +/-85.0511 degrees are clamped to the edge of the square.
+    """
+    lat = _clamp_lat(lat)
+    x = math.radians(lon) * EARTH_RADIUS
+    y = math.log(math.tan(math.pi / 4.0 + math.radians(lat) / 2.0)) * EARTH_RADIUS
+    return x, y
+
+
+def mercator_to_lonlat(x: float, y: float) -> tuple[float, float]:
+    """Inverse of :func:`lonlat_to_mercator`."""
+    lon = math.degrees(x / EARTH_RADIUS)
+    lat = math.degrees(2.0 * math.atan(math.exp(y / EARTH_RADIUS)) - math.pi / 2.0)
+    return lon, lat
+
+
+def resolution(z: int, tile_size: int = 256) -> float:
+    """Ground resolution in metres per pixel (EPSG:3857 units) at zoom ``z``."""
+    _check_zoom(z)
+    return 2.0 * ORIGIN_SHIFT / (tile_size * (1 << z))
+
+
+def lonlat_to_tile(lon: float, lat: float, z: int) -> Tile:
+    """Return the tile containing a point. Points on the east/south edge of
+    the world map to the last tile instead of falling outside the grid."""
+    _check_zoom(z)
+    n = 1 << z
+    x, y = lonlat_to_mercator(lon, lat)
+    fx = (x + ORIGIN_SHIFT) / (2.0 * ORIGIN_SHIFT) * n
+    fy = (ORIGIN_SHIFT - y) / (2.0 * ORIGIN_SHIFT) * n
+    tx = min(n - 1, max(0, int(math.floor(fx))))
+    ty = min(n - 1, max(0, int(math.floor(fy))))
+    return Tile(z, tx, ty)
+
+
+def tile_bounds_mercator(tile: Tile | tuple[int, int, int]) -> BBox:
+    """EPSG:3857 bounds ``(minx, miny, maxx, maxy)`` of an XYZ tile."""
+    z, x, y = tile
+    _check_zoom(z)
+    size = 2.0 * ORIGIN_SHIFT / (1 << z)
+    minx = -ORIGIN_SHIFT + x * size
+    maxy = ORIGIN_SHIFT - y * size
+    return BBox(minx, maxy - size, minx + size, maxy)
+
+
+def tile_bounds_lonlat(tile: Tile | tuple[int, int, int]) -> BBox:
+    """Longitude/latitude bounds ``(west, south, east, north)`` of an XYZ tile."""
+    b = tile_bounds_mercator(tile)
+    w, s = mercator_to_lonlat(b.minx, b.miny)
+    e, n = mercator_to_lonlat(b.maxx, b.maxy)
+    return BBox(w, s, e, n)
+
+
+def flip_y(z: int, y: int) -> int:
+    """Convert a row between the XYZ and TMS schemes (the operation is its own inverse)."""
+    _check_zoom(z)
+    return (1 << z) - 1 - y
+
+
+def tile_to_quadkey(tile: Tile | tuple[int, int, int]) -> str:
+    """Bing-style quadkey of an XYZ tile (empty string at zoom 0)."""
+    z, x, y = tile
+    _check_zoom(z)
+    digits = []
+    for i in range(z, 0, -1):
+        mask = 1 << (i - 1)
+        d = 0
+        if x & mask:
+            d += 1
+        if y & mask:
+            d += 2
+        digits.append(str(d))
+    return "".join(digits)
+
+
+def quadkey_to_tile(quadkey: str) -> Tile:
+    """Inverse of :func:`tile_to_quadkey`."""
+    x = y = 0
+    z = len(quadkey)
+    _check_zoom(z)
+    for i, ch in enumerate(quadkey):
+        mask = 1 << (z - i - 1)
+        if ch == "1":
+            x |= mask
+        elif ch == "2":
+            y |= mask
+        elif ch == "3":
+            x |= mask
+            y |= mask
+        elif ch != "0":
+            raise ValueError(f"invalid quadkey digit {ch!r} in {quadkey!r}")
+    return Tile(z, x, y)
+
+
+def parse_bbox(bbox: BBoxLike) -> BBox:
+    """Normalise a bbox given as a sequence or a ``"minx,miny,maxx,maxy"`` string.
+
+    For lon/lat boxes ``minx > maxx`` is allowed and means the box crosses the
+    antimeridian. ``miny`` must not exceed ``maxy``.
+    """
+    if isinstance(bbox, str):
+        parts = [p for p in bbox.replace(" ", ",").split(",") if p]
+        values = [float(p) for p in parts]
+    else:
+        values = [float(v) for v in bbox]
+    if len(values) != 4:
+        raise ValueError(f"bbox needs 4 numbers (minx, miny, maxx, maxy), got {len(values)}")
+    if any(math.isnan(v) or math.isinf(v) for v in values):
+        raise ValueError("bbox values must be finite")
+    b = BBox(*values)
+    if b.miny > b.maxy:
+        raise ValueError(f"bbox miny ({b.miny}) is greater than maxy ({b.maxy})")
+    return b
+
+
+def parse_zoom(zoom: ZoomLike) -> list[int]:
+    """Parse ``12``, ``"12"``, ``"12-15"``, ``"10,12,14"`` or ``[12, 13]`` into a sorted list."""
+    levels: set[int] = set()
+    if isinstance(zoom, bool):
+        raise ValueError("zoom must be an int, a range string or a list of ints")
+    if isinstance(zoom, int):
+        levels.add(zoom)
+    elif isinstance(zoom, str):
+        for part in zoom.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            if "-" in part:
+                a, b = part.split("-", 1)
+                lo, hi = int(a), int(b)
+                if lo > hi:
+                    raise ValueError(f"empty zoom range {part!r}")
+                levels.update(range(lo, hi + 1))
+            else:
+                levels.add(int(part))
+    else:
+        levels.update(int(z) for z in zoom)
+    if not levels:
+        raise ValueError("no zoom levels given")
+    for z in levels:
+        _check_zoom(z)
+    return sorted(levels)
+
+
+def _split_antimeridian(b: BBox) -> list[BBox]:
+    if b.minx <= b.maxx:
+        return [b]
+    return [BBox(b.minx, b.miny, 180.0, b.maxy), BBox(-180.0, b.miny, b.maxx, b.maxy)]
+
+
+def bbox_to_mercator(bbox: BBoxLike) -> BBox:
+    """Project a lon/lat bbox to EPSG:3857 (latitudes clamped to the Mercator square)."""
+    b = parse_bbox(bbox)
+    if b.minx > b.maxx:
+        raise ValueError("bbox crosses the antimeridian; split it before projecting")
+    x0, y0 = lonlat_to_mercator(b.minx, b.miny)
+    x1, y1 = lonlat_to_mercator(b.maxx, b.maxy)
+    return BBox(x0, y0, x1, y1)
+
+
+def _tile_range(b: BBox, z: int, crs: str) -> tuple[int, int, int, int]:
+    """Inclusive (xmin, ymin, xmax, ymax) tile indices covering a bbox at zoom z."""
+    n = 1 << z
+    if crs == "EPSG:3857":
+        mb = b
+    else:
+        x0, y0 = lonlat_to_mercator(b.minx, b.miny)
+        x1, y1 = lonlat_to_mercator(b.maxx, b.maxy)
+        mb = BBox(x0, y0, x1, y1)
+    size = 2.0 * ORIGIN_SHIFT / n
+    eps = 1e-9 * size
+
+    def col(x: float, upper: bool) -> int:
+        f = (x + ORIGIN_SHIFT) / size
+        # A box edge exactly on a tile edge must not pull in the neighbour tile.
+        i = math.ceil(f - eps) - 1 if upper else math.floor(f + eps)
+        return min(n - 1, max(0, int(i)))
+
+    def row(y: float, upper: bool) -> int:
+        f = (ORIGIN_SHIFT - y) / size
+        i = math.ceil(f - eps) - 1 if upper else math.floor(f + eps)
+        return min(n - 1, max(0, int(i)))
+
+    xmin, xmax = col(mb.minx, False), col(mb.maxx, True)
+    ymin, ymax = row(mb.maxy, False), row(mb.miny, True)
+    # Degenerate (zero-width) boxes still cover one tile.
+    xmax = max(xmax, xmin)
+    ymax = max(ymax, ymin)
+    return xmin, ymin, xmax, ymax
+
+
+def _normalise_crs(crs: str | int) -> str:
+    s = str(crs).upper().replace("EPSG:", "")
+    if s in ("4326", "CRS84", "OGC:CRS84"):
+        return "EPSG:4326"
+    if s in ("3857", "900913", "3785", "102100"):
+        return "EPSG:3857"
+    raise ValueError(f"unsupported CRS {crs!r}; use EPSG:4326 or EPSG:3857")
+
+
+def _iter_bbox_tiles(bbox: BBoxLike, zooms: list[int], crs: str) -> Iterator[Tile]:
+    b = parse_bbox(bbox)
+    boxes = _split_antimeridian(b) if crs == "EPSG:4326" else [b]
+    if crs == "EPSG:3857" and b.minx > b.maxx:
+        raise ValueError("EPSG:3857 bbox must have minx <= maxx")
+    for z in zooms:
+        seen: set[tuple[int, int]] = set()
+        for part in boxes:
+            xmin, ymin, xmax, ymax = _tile_range(part, z, crs)
+            for x in range(xmin, xmax + 1):
+                for y in range(ymin, ymax + 1):
+                    if (x, y) not in seen:
+                        seen.add((x, y))
+                        yield Tile(z, x, y)
+
+
+def tile_count(bbox: BBoxLike, zoom: ZoomLike, crs: str | int = "EPSG:4326") -> int:
+    """Number of tiles covering a bbox, without materialising the list."""
+    zooms = parse_zoom(zoom)
+    c = _normalise_crs(crs)
+    b = parse_bbox(bbox)
+    total = 0
+    for z in zooms:
+        cols: set[int] = set()
+        rows = 0
+        for part in _split_antimeridian(b) if c == "EPSG:4326" else [b]:
+            xmin, ymin, xmax, ymax = _tile_range(part, z, c)
+            cols.update(range(xmin, xmax + 1))
+            rows = ymax - ymin + 1
+        total += len(cols) * rows
+    return total
+
+
+def tiles_for_bbox(bbox: BBoxLike, zoom: ZoomLike, crs: str | int = "EPSG:4326") -> list[Tile]:
+    """All XYZ tiles intersecting a bbox at the given zoom level(s).
+
+    ``bbox`` is ``(west, south, east, north)`` in degrees by default, or EPSG:3857
+    metres with ``crs="EPSG:3857"``. Lon/lat boxes with ``west > east`` cross
+    the antimeridian. Tiles are ordered by zoom, then column, then row.
+    """
+    return list(_iter_bbox_tiles(bbox, parse_zoom(zoom), _normalise_crs(crs)))
+
+
+# ---------------------------------------------------------------------------
+# GeoJSON polygons
+# ---------------------------------------------------------------------------
+
+Ring = list[tuple[float, float]]
+Polygon = list[Ring]  # exterior ring followed by holes
+
+
+def load_geometry(geojson: Any) -> list[Polygon]:
+    """Read Polygon/MultiPolygon geometry from a GeoJSON object, string or file path.
+
+    Accepts a geometry, a Feature, a FeatureCollection or a path to a
+    ``.geojson`` file. Coordinates are longitude/latitude (RFC 7946).
+    Returns a list of polygons, each a list of rings of ``(lon, lat)``.
+    """
+    obj = geojson
+    if isinstance(obj, (str, os.PathLike)):
+        text = str(obj)
+        if text.lstrip().startswith("{"):
+            obj = json.loads(text)
+        else:
+            with open(obj, encoding="utf-8") as fh:
+                obj = json.load(fh)
+    if not isinstance(obj, dict):
+        raise ValueError("GeoJSON must be a dict, a JSON string or a file path")
+    polygons: list[Polygon] = []
+
+    def walk(o: dict[str, Any]) -> None:
+        t = o.get("type")
+        if t == "FeatureCollection":
+            for f in o.get("features", []):
+                walk(f)
+        elif t == "Feature":
+            if o.get("geometry"):
+                walk(o["geometry"])
+        elif t == "GeometryCollection":
+            for g in o.get("geometries", []):
+                walk(g)
+        elif t == "Polygon":
+            polygons.append(
+                [[(float(p[0]), float(p[1])) for p in ring] for ring in o["coordinates"]]
+            )
+        elif t == "MultiPolygon":
+            for poly in o["coordinates"]:
+                polygons.append([[(float(p[0]), float(p[1])) for p in ring] for ring in poly])
+        else:
+            raise ValueError(f"unsupported GeoJSON type {t!r}; expected (Multi)Polygon")
+
+    walk(obj)
+    if not polygons:
+        raise ValueError("GeoJSON contains no polygons")
+    return polygons
+
+
+def geometry_bbox(polygons: list[Polygon]) -> BBox:
+    """Lon/lat bounds of the exterior rings of a list of polygons."""
+    xs = [p[0] for poly in polygons for p in poly[0]]
+    ys = [p[1] for poly in polygons for p in poly[0]]
+    return BBox(min(xs), min(ys), max(xs), max(ys))
+
+
+def _point_in_ring(x: float, y: float, ring: Ring) -> bool:
+    inside = False
+    n = len(ring)
+    j = n - 1
+    for i in range(n):
+        xi, yi = ring[i]
+        xj, yj = ring[j]
+        if (yi > y) != (yj > y):
+            xc = (xj - xi) * (y - yi) / (yj - yi) + xi
+            if x < xc:
+                inside = not inside
+        j = i
+    return inside
+
+
+def _point_in_polygon(x: float, y: float, poly: Polygon) -> bool:
+    if not _point_in_ring(x, y, poly[0]):
+        return False
+    return not any(_point_in_ring(x, y, hole) for hole in poly[1:])
+
+
+def _segment_hits_rect(a: tuple[float, float], b: tuple[float, float], r: BBox) -> bool:
+    """Liang-Barsky clip test: does segment ab touch rectangle r?"""
+    x0, y0 = a
+    dx, dy = b[0] - x0, b[1] - y0
+    t0, t1 = 0.0, 1.0
+    for p, q in ((-dx, x0 - r.minx), (dx, r.maxx - x0), (-dy, y0 - r.miny), (dy, r.maxy - y0)):
+        if p == 0:
+            if q < 0:
+                return False
+        else:
+            t = q / p
+            if p < 0:
+                t0 = max(t0, t)
+            else:
+                t1 = min(t1, t)
+            if t0 > t1:
+                return False
+    return True
+
+
+def _poly_hits_rect(poly: Polygon, r: BBox) -> bool:
+    for ring in poly:
+        for i in range(len(ring) - 1):
+            if _segment_hits_rect(ring[i], ring[i + 1], r):
+                return True
+    cx, cy = (r.minx + r.maxx) / 2.0, (r.miny + r.maxy) / 2.0
+    # Rectangle entirely inside the polygon (and not inside a hole).
+    return _point_in_polygon(cx, cy, poly)
+
+
+def tiles_for_geometry(geojson: Any, zoom: ZoomLike) -> list[Tile]:
+    """Tiles that intersect GeoJSON (Multi)Polygon geometry.
+
+    Polygon edges are treated as straight lines in Web Mercator, which is the
+    space the tiles live in. Candidate tiles from the bbox are tested exactly
+    against every polygon (including holes).
+    """
+    return tiles_for_polygons(load_geometry(geojson), zoom)
+
+
+def tiles_for_polygons(polygons: list[Polygon], zoom: ZoomLike) -> list[Tile]:
+    """Like :func:`tiles_for_geometry` for polygons already read by :func:`load_geometry`."""
+    merc = [
+        [[lonlat_to_mercator(lon, lat) for lon, lat in ring] for ring in poly] for poly in polygons
+    ]
+    bounds = geometry_bbox(polygons)
+    out: list[Tile] = []
+    for t in _iter_bbox_tiles(bounds, parse_zoom(zoom), "EPSG:4326"):
+        r = tile_bounds_mercator(t)
+        for poly in merc:
+            if _poly_hits_rect(poly, r):
+                out.append(t)
+                break
+    return out