mirrorworld 0.1.0__py3-none-any.whl

mirrorworld/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mirrorworld/aerial/__init__.py

@@ -0,0 +1,16 @@
+# Mirrorworld addition (not in upstream streetlevel).
+"""
+Aerial and satellite orthoimagery from web map tile services.
+
+One subpackage per provider, following the layout of the street-level providers
+(``api.py`` builds and sends requests, ``<provider>.py`` holds the public functions,
+``util.py`` holds provider-specific helpers). Shared tile math, stitching and saving
+live in :mod:`mirrorworld.aerial.util`.
+
+Usage::
+
+    from mirrorworld.aerial import bing
+
+    image = bing.get_image(47.6070, -122.3345, 47.6055, -122.3320, zoom=20)
+    bing.download_image(47.6070, -122.3345, 47.6055, -122.3320, "seattle.jpg", zoom=20)
+"""

mirrorworld/aerial/__main__.py

@@ -0,0 +1,62 @@
+# Mirrorworld addition (not in upstream streetlevel).
+"""
+Command line entry point::
+
+    python -m mirrorworld.aerial PROVIDER NORTH WEST SOUTH EAST OUT [--zoom Z | --resolution M] [--max-zoom]
+
+PROVIDER is one of bing, google, esri, usgs. ``--max-zoom`` only prints the highest available zoom level
+at the center of the box.
+"""
+import argparse
+import importlib
+import json
+
+from .util import ground_resolution, zoom_for_resolution
+
+PROVIDERS = ("bing", "google", "esri", "usgs")
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="python -m mirrorworld.aerial",
+                                     description="Download aerial imagery for a bounding box.")
+    parser.add_argument("provider", choices=PROVIDERS)
+    parser.add_argument("north", type=float)
+    parser.add_argument("west", type=float)
+    parser.add_argument("south", type=float)
+    parser.add_argument("east", type=float)
+    parser.add_argument("out", nargs="?", help="output .jpg, .png or .tif")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--zoom", type=int, help="zoom level")
+    group.add_argument("--resolution", type=float, help="target ground resolution in m/px; picks the zoom level")
+    group.add_argument("--max-zoom", action="store_true", help="print the highest available zoom level and exit")
+    parser.add_argument("--max-tiles", type=int, default=20000)
+    parser.add_argument("--max-concurrency", type=int, default=8)
+    args = parser.parse_args()
+
+    provider = importlib.import_module(f"mirrorworld.aerial.{args.provider}")
+    lat, lon = (args.north + args.south) / 2, (args.west + args.east) / 2
+
+    if args.max_zoom:
+        zoom = provider.find_max_zoom(lat, lon)
+        res = None if zoom is None else round(ground_resolution(lat, zoom), 4)
+        print(json.dumps({"provider": provider.PROVIDER, "max_zoom": zoom, "ground_resolution_m": res}))
+        return
+    if not args.out:
+        parser.error("OUT is required unless --max-zoom is given")
+
+    zoom = args.zoom
+    if args.resolution is not None:
+        zoom = zoom_for_resolution(lat, args.resolution)
+    aerial = provider.download_image(args.north, args.west, args.south, args.east, args.out, zoom=zoom,
+                                     max_tiles=args.max_tiles, max_concurrency=args.max_concurrency)
+    print(json.dumps({"provider": aerial.provider, "zoom": aerial.zoom,
+                      "ground_resolution_m": round(aerial.ground_resolution, 4),
+                      "size_px": list(aerial.image.size), "tiles": aerial.tile_count,
+                      "missing_tiles": len(aerial.missing_tiles), "metadata": aerial.metadata}))
+    if aerial.missing_tiles:
+        print(f"warning: {len(aerial.missing_tiles)} of {aerial.tile_count} tiles have no imagery "
+              f"at zoom {aerial.zoom} (left black)")
+
+
+if __name__ == "__main__":
+    main()

mirrorworld/aerial/arcgis.py

@@ -0,0 +1,74 @@
+# Mirrorworld addition (not in upstream streetlevel).
+"""Requests against ArcGIS MapServer tile caches, shared by the Esri and USGS providers."""
+from typing import Set, Tuple
+
+from aiohttp import ClientSession
+
+from .util import HEADERS, TILE_SIZE
+
+TILEMAP_BLOCK = 64
+"""Largest tilemap window the server answers without shrinking it."""
+
+
+def build_tile_url(service_url: str, x: int, y: int, zoom: int) -> str:
+    return f"{service_url}/tile/{zoom}/{y}/{x}"
+
+
+def build_tilemap_url(service_url: str, x: int, y: int, zoom: int, width: int, height: int) -> str:
+    return f"{service_url}/tilemap/{zoom}/{y}/{x}/{height}/{width}"
+
+
+def tile_exists(service_url: str, x: int, y: int, zoom: int, session=None) -> bool:
+    """
+    Asks the tile cache whether a tile exists at this zoom level, without downloading it.
+    """
+    import requests
+    requester = session if session else requests
+    response = requester.get(build_tilemap_url(service_url, x, y, zoom, 1, 1), headers=HEADERS, timeout=60)
+    if response.status_code != 200:
+        # USGS answers 422 "Tiles not present" for zoom levels outside its cache.
+        return False
+    data = response.json()
+    return bool(data.get("data") and data["data"][0])
+
+
+async def tile_exists_async(service_url: str, x: int, y: int, zoom: int, session: ClientSession) -> bool:
+    """
+    Asks the tile cache whether a tile exists at this zoom level, without downloading it.
+    """
+    async with session.get(build_tilemap_url(service_url, x, y, zoom, 1, 1), headers=HEADERS) as response:
+        if response.status != 200:
+            # USGS answers 422 "Tiles not present" for zoom levels outside its cache.
+            return False
+        data = await response.json(content_type=None)
+        return bool(data.get("data") and data["data"][0])
+
+
+async def find_missing_tiles_async(service_url: str, left: int, top: int, right: int, bottom: int,
+                                   zoom: int, session: ClientSession) -> Set[Tuple[int, int]]:
+    """
+    Lists the tiles inside a global pixel window that the cache does not have, using the tilemap endpoint,
+    which answers for a block of up to 64x64 tiles per request.
+
+    :return: X/Y coordinates of missing tiles.
+    """
+    tx0, ty0 = left // TILE_SIZE, top // TILE_SIZE
+    tx1, ty1 = (right - 1) // TILE_SIZE, (bottom - 1) // TILE_SIZE
+    missing = set()
+    for by in range(ty0, ty1 + 1, TILEMAP_BLOCK):
+        for bx in range(tx0, tx1 + 1, TILEMAP_BLOCK):
+            width = min(TILEMAP_BLOCK, tx1 - bx + 1)
+            height = min(TILEMAP_BLOCK, ty1 - by + 1)
+            url = build_tilemap_url(service_url, bx, by, zoom, width, height)
+            async with session.get(url, headers=HEADERS) as response:
+                if response.status != 200:
+                    missing.update((bx + i, by + j) for j in range(height) for i in range(width))
+                    continue
+                data = await response.json(content_type=None)
+            flags = data.get("data") or []
+            for j in range(height):
+                for i in range(width):
+                    k = j * width + i
+                    if k >= len(flags) or not flags[k]:
+                        missing.add((bx + i, by + j))
+    return missing

mirrorworld/aerial/bing/__init__.py

@@ -0,0 +1,3 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from .bing import *
+from .util import *

mirrorworld/aerial/bing/api.py

@@ -0,0 +1,22 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from aiohttp import ClientSession
+from requests import Session
+
+from .util import to_quadkey
+from ..util import TileResponse, get_tile_response, get_tile_response_async
+
+DEFAULT_GENERATION = 15000
+"""Imagery generation (``g`` parameter). Requests without one are rejected with HTTP 400."""
+
+
+def build_tile_url(x: int, y: int, zoom: int, generation: int = DEFAULT_GENERATION) -> str:
+    return f"https://ecn.t{(x + y) % 4}.tiles.virtualearth.net/tiles/a{to_quadkey(x, y, zoom)}.jpeg" \
+           f"?g={generation}"
+
+
+def get_tile(x: int, y: int, zoom: int, session: Session = None) -> TileResponse:
+    return get_tile_response(build_tile_url(x, y, zoom), x, y, session)
+
+
+async def get_tile_async(x: int, y: int, zoom: int, session: ClientSession) -> TileResponse:
+    return await get_tile_response_async(build_tile_url(x, y, zoom), x, y, session)

mirrorworld/aerial/bing/bing.py

@@ -0,0 +1,135 @@
+# Mirrorworld addition (not in upstream streetlevel).
+"""Bing Maps aerial imagery, worldwide."""
+from typing import Optional
+
+from PIL import Image
+from aiohttp import ClientSession
+from requests import Session
+
+from . import api
+from ..dataclasses import AerialImage
+from ..util import TileResponse, get_tiled_image_async, run_sync, save_aerial_image, tile_to_image, \
+    get_header, wgs84_to_pixel, TILE_SIZE, DEFAULT_MAX_TILES, DEFAULT_MAX_CONCURRENCY
+
+PROVIDER = "Bing Maps"
+MAX_ZOOM = 21
+METADATA_HEADERS = ("X-VE-TILEMETA-CaptureDatesRange", "X-VE-TILEMETA-Product-IDs")
+
+
+def get_tile(x: int, y: int, zoom: int, session: Session = None) -> Optional[Image.Image]:
+    """
+    Downloads one aerial tile.
+
+    :param x: X coordinate of the tile.
+    :param y: Y coordinate of the tile.
+    :param zoom: Zoom level.
+    :param session: *(optional)* A requests session.
+    :return: The tile as PIL image, or None if Bing has no imagery for it at this zoom level.
+    """
+    response = api.get_tile(x, y, zoom, session)
+    return None if _is_missing(response) else tile_to_image(response)
+
+
+async def get_tile_async(x: int, y: int, zoom: int, session: ClientSession) -> Optional[Image.Image]:
+    response = await api.get_tile_async(x, y, zoom, session)
+    return None if _is_missing(response) else tile_to_image(response)
+
+
+def find_max_zoom(lat: float, lon: float, session: Session = None) -> Optional[int]:
+    """
+    Finds the highest zoom level with imagery at a location.
+
+    :param lat: Latitude.
+    :param lon: Longitude.
+    :param session: *(optional)* A requests session.
+    :return: The zoom level, e.g. 20 (≈0.10 m/px) in Seattle, or None if there is no imagery.
+    """
+    for zoom in range(MAX_ZOOM, 0, -1):
+        x, y = _tile_at(lat, lon, zoom)
+        if not _is_missing(api.get_tile(x, y, zoom, session)):
+            return zoom
+    return None
+
+
+async def find_max_zoom_async(lat: float, lon: float, session: ClientSession) -> Optional[int]:
+    for zoom in range(MAX_ZOOM, 0, -1):
+        x, y = _tile_at(lat, lon, zoom)
+        if not _is_missing(await api.get_tile_async(x, y, zoom, session)):
+            return zoom
+    return None
+
+
+def get_image(north: float, west: float, south: float, east: float, zoom: int = None,
+              max_tiles: int = DEFAULT_MAX_TILES,
+              max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    """
+    Downloads the aerial imagery inside a bounding box and stitches it into one image.
+
+    Capture date ranges reported by Bing are collected in ``AerialImage.metadata``.
+
+    :param north: Latitude of the top edge.
+    :param west: Longitude of the left edge.
+    :param south: Latitude of the bottom edge.
+    :param east: Longitude of the right edge.
+    :param zoom: *(optional)* Zoom level. Defaults to the highest one available at the center of the box.
+    :param max_tiles: *(optional)* Refuse requests covering more tiles than this. Defaults to 20000.
+    :param max_concurrency: *(optional)* Maximum number of simultaneous requests. Defaults to 8.
+    :return: The stitched image.
+    """
+    return run_sync(get_image_async, north, west, south, east, zoom=zoom, max_tiles=max_tiles,
+                    max_concurrency=max_concurrency)
+
+
+async def get_image_async(north: float, west: float, south: float, east: float, session: ClientSession,
+                          zoom: int = None, max_tiles: int = DEFAULT_MAX_TILES,
+                          max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    if zoom is None:
+        zoom = await find_max_zoom_async((north + south) / 2, (west + east) / 2, session)
+        if zoom is None:
+            raise ValueError("No imagery at the center of the bounding box")
+    return await get_tiled_image_async(
+        north, west, south, east, zoom, PROVIDER,
+        lambda x, y: api.build_tile_url(x, y, zoom), _is_missing, session,
+        metadata_headers=METADATA_HEADERS, max_tiles=max_tiles, max_concurrency=max_concurrency)
+
+
+def download_image(north: float, west: float, south: float, east: float, path: str, zoom: int = None,
+                   pil_args: dict = None, max_tiles: int = DEFAULT_MAX_TILES,
+                   max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    """
+    Downloads the aerial imagery inside a bounding box to a georeferenced file
+    (world file, ``.aux.xml`` and ``.json`` beside it; see :func:`mirrorworld.aerial.util.save_aerial_image`).
+
+    :param north: Latitude of the top edge.
+    :param west: Longitude of the left edge.
+    :param south: Latitude of the bottom edge.
+    :param east: Longitude of the right edge.
+    :param path: Output path.
+    :param zoom: *(optional)* Zoom level. Defaults to the highest one available at the center of the box.
+    :param pil_args: *(optional)* Additional arguments for PIL's ``Image.save`` method.
+    :param max_tiles: *(optional)* Refuse requests covering more tiles than this. Defaults to 20000.
+    :param max_concurrency: *(optional)* Maximum number of simultaneous requests. Defaults to 8.
+    :return: The stitched image.
+    """
+    aerial = get_image(north, west, south, east, zoom, max_tiles, max_concurrency)
+    save_aerial_image(aerial, path, pil_args)
+    return aerial
+
+
+async def download_image_async(north: float, west: float, south: float, east: float, path: str,
+                               session: ClientSession, zoom: int = None, pil_args: dict = None,
+                               max_tiles: int = DEFAULT_MAX_TILES,
+                               max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    aerial = await get_image_async(north, west, south, east, session, zoom, max_tiles, max_concurrency)
+    save_aerial_image(aerial, path, pil_args)
+    return aerial
+
+
+def _is_missing(response: TileResponse) -> bool:
+    # Bing answers 200 with a placeholder PNG and flags it in a header.
+    return get_header(response.headers, "X-VE-Tile-Info") == "no-tile"
+
+
+def _tile_at(lat: float, lon: float, zoom: int):
+    px, py = wgs84_to_pixel(lat, lon, zoom)
+    return int(px // TILE_SIZE), int(py // TILE_SIZE)

mirrorworld/aerial/bing/util.py

@@ -0,0 +1,45 @@
+# Mirrorworld addition (not in upstream streetlevel).
+def to_quadkey(x: int, y: int, zoom: int) -> str:
+    """
+    Converts XYZ tile coordinates to a Bing Maps quadkey.
+
+    :param x: X coordinate.
+    :param y: Y coordinate.
+    :param zoom: Zoom level.
+    :return: The quadkey, which has one digit per zoom level.
+    """
+    digits = []
+    for i in range(zoom, 0, -1):
+        mask = 1 << (i - 1)
+        digits.append(str((1 if x & mask else 0) + (2 if y & mask else 0)))
+    return "".join(digits)
+
+
+def from_quadkey(quadkey: str):
+    """
+    Converts a Bing Maps quadkey to XYZ tile coordinates.
+
+    :param quadkey: The quadkey.
+    :return: X, Y and zoom.
+    """
+    x = y = 0
+    zoom = len(quadkey)
+    for i, digit in enumerate(quadkey):
+        mask = 1 << (zoom - i - 1)
+        if digit in "13":
+            x |= mask
+        if digit in "23":
+            y |= mask
+    return x, y, zoom
+
+
+def build_permalink(lat: float, lon: float, zoom: int = 18) -> str:
+    """
+    Creates a Bing Maps link showing aerial imagery at a location.
+
+    :param lat: Latitude.
+    :param lon: Longitude.
+    :param zoom: *(optional)* Zoom level. Defaults to 18.
+    :return: A Bing Maps URL.
+    """
+    return f"https://www.bing.com/maps?cp={lat}%7E{lon}&lvl={zoom}&style=a"

mirrorworld/aerial/dataclasses.py

@@ -0,0 +1,47 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from dataclasses import dataclass, field
+from typing import List, Tuple
+
+from PIL import Image
+
+
+@dataclass
+class AerialImage:
+    """
+    A stitched aerial image covering a bounding box, with the information needed to georeference it.
+
+    The image is in Web Mercator (EPSG:3857). Its edges lie on pixel boundaries of the tile grid at ``zoom``,
+    so ``north``/``west``/``south``/``east`` can differ from the requested box by less than one pixel.
+    """
+
+    image: Image.Image
+    """The stitched image."""
+    provider: str
+    """Name of the imagery provider."""
+    zoom: int
+    """Zoom level of the tiles the image was stitched from."""
+
+    north: float
+    """Latitude of the top edge."""
+    west: float
+    """Longitude of the left edge."""
+    south: float
+    """Latitude of the bottom edge."""
+    east: float
+    """Longitude of the right edge."""
+
+    origin_x: float
+    """X coordinate of the top left corner in EPSG:3857 meters."""
+    origin_y: float
+    """Y coordinate of the top left corner in EPSG:3857 meters."""
+    mercator_resolution: float
+    """Pixel size in EPSG:3857 meters. Larger than the ground resolution away from the equator."""
+    ground_resolution: float
+    """Approximate pixel size on the ground in meters at the center of the image."""
+
+    tile_count: int
+    """Number of tiles the image was stitched from."""
+    missing_tiles: List[Tuple[int, int]] = field(default_factory=list)
+    """X/Y coordinates of tiles the provider has no imagery for at this zoom level. These areas are black."""
+    metadata: dict = field(default_factory=dict)
+    """Provider-specific metadata, e.g. capture date ranges reported by Bing."""

mirrorworld/aerial/esri/__init__.py

@@ -0,0 +1,3 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from .esri import *
+from .util import *

mirrorworld/aerial/esri/api.py

@@ -0,0 +1,35 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from typing import Set, Tuple
+
+from aiohttp import ClientSession
+from requests import Session
+
+from .. import arcgis
+from ..util import TileResponse, get_tile_response, get_tile_response_async
+
+SERVICE_URL = "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"
+
+
+def build_tile_url(x: int, y: int, zoom: int) -> str:
+    return arcgis.build_tile_url(SERVICE_URL, x, y, zoom)
+
+
+def get_tile(x: int, y: int, zoom: int, session: Session = None) -> TileResponse:
+    return get_tile_response(build_tile_url(x, y, zoom), x, y, session)
+
+
+async def get_tile_async(x: int, y: int, zoom: int, session: ClientSession) -> TileResponse:
+    return await get_tile_response_async(build_tile_url(x, y, zoom), x, y, session)
+
+
+def tile_exists(x: int, y: int, zoom: int, session: Session = None) -> bool:
+    return arcgis.tile_exists(SERVICE_URL, x, y, zoom, session)
+
+
+async def tile_exists_async(x: int, y: int, zoom: int, session: ClientSession) -> bool:
+    return await arcgis.tile_exists_async(SERVICE_URL, x, y, zoom, session)
+
+
+async def find_missing_tiles_async(left: int, top: int, right: int, bottom: int, zoom: int,
+                                   session: ClientSession) -> Set[Tuple[int, int]]:
+    return await arcgis.find_missing_tiles_async(SERVICE_URL, left, top, right, bottom, zoom, session)

mirrorworld/aerial/esri/esri.py

@@ -0,0 +1,139 @@
+# Mirrorworld addition (not in upstream streetlevel).
+"""Esri World Imagery (a mosaic of satellite and aerial imagery), worldwide."""
+from typing import Optional
+
+from PIL import Image
+from aiohttp import ClientSession
+from requests import Session
+
+from . import api
+from ..dataclasses import AerialImage
+from ..util import TileResponse, bbox_to_pixels, get_tiled_image_async, run_sync, save_aerial_image, \
+    tile_to_image, wgs84_to_pixel, TILE_SIZE, DEFAULT_MAX_TILES, DEFAULT_MAX_CONCURRENCY
+
+PROVIDER = "Esri World Imagery"
+MAX_ZOOM = 23
+
+
+def get_tile(x: int, y: int, zoom: int, session: Session = None) -> Optional[Image.Image]:
+    """
+    Downloads one aerial tile.
+
+    :param x: X coordinate of the tile.
+    :param y: Y coordinate of the tile.
+    :param zoom: Zoom level.
+    :param session: *(optional)* A requests session.
+    :return: The tile as PIL image, or None if Esri has no imagery for it at this zoom level.
+    """
+    if not api.tile_exists(x, y, zoom, session):
+        return None
+    response = api.get_tile(x, y, zoom, session)
+    return None if _is_missing(response) else tile_to_image(response)
+
+
+async def get_tile_async(x: int, y: int, zoom: int, session: ClientSession) -> Optional[Image.Image]:
+    # Beyond its coverage the server returns a "Map data not yet available" placeholder with status 200,
+    # so availability is checked with the tilemap endpoint first.
+    if not await api.tile_exists_async(x, y, zoom, session):
+        return None
+    response = await api.get_tile_async(x, y, zoom, session)
+    return None if _is_missing(response) else tile_to_image(response)
+
+
+def find_max_zoom(lat: float, lon: float, session: Session = None) -> Optional[int]:
+    """
+    Finds the highest zoom level with imagery at a location.
+
+    :param lat: Latitude.
+    :param lon: Longitude.
+    :param session: *(optional)* A requests session.
+    :return: The zoom level, e.g. 19 (≈0.20 m/px) in Seattle, or None if there is no imagery.
+    """
+    for zoom in range(MAX_ZOOM, -1, -1):
+        x, y = _tile_at(lat, lon, zoom)
+        if api.tile_exists(x, y, zoom, session):
+            return zoom
+    return None
+
+
+async def find_max_zoom_async(lat: float, lon: float, session: ClientSession) -> Optional[int]:
+    for zoom in range(MAX_ZOOM, -1, -1):
+        x, y = _tile_at(lat, lon, zoom)
+        if await api.tile_exists_async(x, y, zoom, session):
+            return zoom
+    return None
+
+
+def get_image(north: float, west: float, south: float, east: float, zoom: int = None,
+              max_tiles: int = DEFAULT_MAX_TILES,
+              max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    """
+    Downloads the aerial imagery inside a bounding box and stitches it into one image.
+
+    :param north: Latitude of the top edge.
+    :param west: Longitude of the left edge.
+    :param south: Latitude of the bottom edge.
+    :param east: Longitude of the right edge.
+    :param zoom: *(optional)* Zoom level. Defaults to the highest one available at the center of the box.
+    :param max_tiles: *(optional)* Refuse requests covering more tiles than this. Defaults to 20000.
+    :param max_concurrency: *(optional)* Maximum number of simultaneous requests. Defaults to 8.
+    :return: The stitched image.
+    """
+    return run_sync(get_image_async, north, west, south, east, zoom=zoom, max_tiles=max_tiles,
+                    max_concurrency=max_concurrency)
+
+
+async def get_image_async(north: float, west: float, south: float, east: float, session: ClientSession,
+                          zoom: int = None, max_tiles: int = DEFAULT_MAX_TILES,
+                          max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    if zoom is None:
+        zoom = await find_max_zoom_async((north + south) / 2, (west + east) / 2, session)
+        if zoom is None:
+            raise ValueError("No imagery at the center of the bounding box")
+    left, top, right, bottom = bbox_to_pixels(north, west, south, east, zoom)
+    missing = await api.find_missing_tiles_async(left, top, right, bottom, zoom, session)
+    return await get_tiled_image_async(
+        north, west, south, east, zoom, PROVIDER,
+        lambda x, y: api.build_tile_url(x, y, zoom), _is_missing, session,
+        skip_tiles=missing, max_tiles=max_tiles, max_concurrency=max_concurrency)
+
+
+def download_image(north: float, west: float, south: float, east: float, path: str, zoom: int = None,
+                   pil_args: dict = None, max_tiles: int = DEFAULT_MAX_TILES,
+                   max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    """
+    Downloads the aerial imagery inside a bounding box to a georeferenced file
+    (world file, ``.aux.xml`` and ``.json`` beside it; see :func:`mirrorworld.aerial.util.save_aerial_image`).
+
+    :param north: Latitude of the top edge.
+    :param west: Longitude of the left edge.
+    :param south: Latitude of the bottom edge.
+    :param east: Longitude of the right edge.
+    :param path: Output path.
+    :param zoom: *(optional)* Zoom level. Defaults to the highest one available at the center of the box.
+    :param pil_args: *(optional)* Additional arguments for PIL's ``Image.save`` method.
+    :param max_tiles: *(optional)* Refuse requests covering more tiles than this. Defaults to 20000.
+    :param max_concurrency: *(optional)* Maximum number of simultaneous requests. Defaults to 8.
+    :return: The stitched image.
+    """
+    aerial = get_image(north, west, south, east, zoom, max_tiles, max_concurrency)
+    save_aerial_image(aerial, path, pil_args)
+    return aerial
+
+
+async def download_image_async(north: float, west: float, south: float, east: float, path: str,
+                               session: ClientSession, zoom: int = None, pil_args: dict = None,
+                               max_tiles: int = DEFAULT_MAX_TILES,
+                               max_concurrency: int = DEFAULT_MAX_CONCURRENCY) -> AerialImage:
+    aerial = await get_image_async(north, west, south, east, session, zoom, max_tiles, max_concurrency)
+    save_aerial_image(aerial, path, pil_args)
+    return aerial
+
+
+def _is_missing(response: TileResponse) -> bool:
+    return response.status == 404
+
+
+def _tile_at(lat: float, lon: float, zoom: int):
+    px, py = wgs84_to_pixel(lat, lon, zoom)
+    return int(px // TILE_SIZE), int(py // TILE_SIZE)

mirrorworld/aerial/esri/util.py

@@ -0,0 +1,12 @@
+# Mirrorworld addition (not in upstream streetlevel).
+def build_permalink(lat: float, lon: float, zoom: int = 18) -> str:
+    """
+    Creates a link to Esri World Imagery Wayback, which shows the current World Imagery
+    and its earlier releases, at a location.
+
+    :param lat: Latitude.
+    :param lon: Longitude.
+    :param zoom: *(optional)* Zoom level. Defaults to 18.
+    :return: A Wayback URL.
+    """
+    return f"https://livingatlas.arcgis.com/wayback/#mapCenter={lon}%2C{lat}%2C{zoom}"

mirrorworld/aerial/google/__init__.py

@@ -0,0 +1,3 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from .google import *
+from .util import *

mirrorworld/aerial/google/api.py

@@ -0,0 +1,18 @@
+# Mirrorworld addition (not in upstream streetlevel).
+from aiohttp import ClientSession
+from requests import Session
+
+from ..util import TileResponse, get_tile_response, get_tile_response_async
+
+
+def build_tile_url(x: int, y: int, zoom: int) -> str:
+    # lyrs=s: satellite/aerial without labels.
+    return f"https://mt{(x + y) % 4}.google.com/vt/lyrs=s&x={x}&y={y}&z={zoom}"
+
+
+def get_tile(x: int, y: int, zoom: int, session: Session = None) -> TileResponse:
+    return get_tile_response(build_tile_url(x, y, zoom), x, y, session)
+
+
+async def get_tile_async(x: int, y: int, zoom: int, session: ClientSession) -> TileResponse:
+    return await get_tile_response_async(build_tile_url(x, y, zoom), x, y, session)