Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
39.0 KB
Raw Blame
"""Tile math and crop stitching (offline: injected fake tile fetcher)."""

import dataclasses
import io
import math

import httpx
import pytest
from PIL import Image

from azimut import config
from azimut.engine import geo, tiles


def test_project_roundtrip():
    lat, lon = 50.4501, 30.5234
    for zoom in (3, 10, 17):
        x, y = tiles.project(lat, lon, zoom)
        lat2, lon2 = tiles.unproject(x, y, zoom)
        assert math.isclose(lat, lat2, abs_tol=1e-6)
        assert math.isclose(lon, lon2, abs_tol=1e-6)


def test_project_known_values():
    # (0,0) is the center of the tile grid
    x, y = tiles.project(0, 0, 1)
    assert (x, y) == (1.0, 1.0)


def test_fetch_crop_stitches_and_records_provenance():
    provider = tiles.BUILTIN_PROVIDERS[0]
    fetched_urls = []

    def fake_fetch(client, url):
        fetched_urls.append(url)
        return Image.new("RGB", (256, 256), (10, 120, 10))

    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider, fetch_tile=fake_fetch
    )
    assert img.size == (640, 480)
    assert prov["provider"] == "esri-world-imagery"
    assert prov["attribution"]
    assert prov["tiles"] == len(fetched_urls)
    assert prov["tiles_missing"] == 0
    assert prov["meters_per_pixel"] > 0
    # crosshair drew white pixels at center
    assert img.getpixel((320 - 10, 240)) == (255, 255, 255)


def test_fetch_crop_marker_offset_moves_crosshair_and_records_pin():
    provider = tiles.BUILTIN_PROVIDERS[0]

    def fake(client, url):
        return Image.new("RGB", (256, 256), (10, 120, 10))

    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider,
        marker_x=120, marker_y=-60, marker_lat=48.86, marker_lon=2.30,
        fetch_tile=fake,
    )
    # crosshair arm sits at the offset point, not the center
    assert img.getpixel((320 + 120 - 10, 240 - 60)) == (255, 255, 255)
    assert img.getpixel((320 - 10, 240)) == (10, 120, 10)  # center untouched
    # recorded coords are the pin; center is remembered separately
    assert (prov["lat"], prov["lon"]) == (48.86, 2.30)
    assert (prov["center_lat"], prov["center_lon"]) == (48.8584, 2.2945)
    assert prov["marker_style"] == "crosshair"


def test_fetch_crop_none_marker_leaves_center_clean():
    provider = tiles.BUILTIN_PROVIDERS[0]
    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 256, 256, provider, marker_style="none",
        fetch_tile=lambda c, u: Image.new("RGB", (256, 256), (10, 120, 10)),
    )
    assert img.getpixel((128, 128)) == (10, 120, 10)
    assert prov["marker_style"] == "none"
    assert prov["crosshair"] is False


def test_fetch_crop_missing_tiles_dont_fail():
    provider = tiles.BUILTIN_PROVIDERS[0]

    img, prov = tiles.fetch_crop(
        10.0, 10.0, 15, 512, 512, provider, marker_style="none",
        fetch_tile=lambda client, url: None,
    )
    assert prov["tiles_missing"] == prov["tiles"] > 0
    assert img.size == (512, 512)


def test_fetch_crop_bearing_rotates_and_fills_corners():
    provider = tiles.BUILTIN_PROVIDERS[0]
    tile_colour = (10, 120, 10)

    calls = {"north": 0, "rotated": 0}

    def count(key):
        def fetch(client, url):
            calls[key] += 1
            return Image.new("RGB", (256, 256), tile_colour)

        return fetch

    north, _ = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider, marker_style="none",
        fetch_tile=count("north"),
    )
    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider, marker_style="none", bearing=45,
        fetch_tile=count("rotated"),
    )

    assert img.size == (640, 480)
    assert prov["bearing"] == 45.0
    # a rotated crop stitches a bigger north-up source → strictly more tiles
    assert calls["rotated"] > calls["north"]
    # corners stay covered by imagery, not the gray background fill
    for corner in ((1, 1), (638, 1), (1, 478), (638, 478)):
        assert img.getpixel(corner) == tile_colour


def test_fetch_crop_bearing_zero_matches_unrotated():
    provider = tiles.BUILTIN_PROVIDERS[0]
    fetched = []

    def fetch(client, url):
        fetched.append(url)
        return Image.new("RGB", (256, 256), (10, 120, 10))

    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider, marker_style="none", bearing=0,
        fetch_tile=fetch,
    )
    assert img.size == (640, 480)
    assert prov["bearing"] == 0.0
    assert prov["tiles"] == len(fetched)


def test_fetch_crop_tile_cap():
    provider = tiles.BUILTIN_PROVIDERS[0]
    try:
        tiles.fetch_crop(
            0, 0, 19, tiles.SIZE_MAX, tiles.SIZE_MAX, provider,
            fetch_tile=lambda c, u: None,
        )
    except tiles.TileFetchError as exc:
        assert "tiles" in str(exc)
    else:  # pragma: no cover
        raise AssertionError("expected TileFetchError for oversized crop")


def test_opentopomap_is_a_keyless_builtin(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    otm = next(p for p in tiles.all_providers() if p.id == "opentopomap")
    assert otm.needs_key is False  # core features never require a key
    assert otm.meter is None  # free: no billing counter to keep
    # CC-BY-SA makes the attribution a condition of the licence, not a courtesy
    assert "OpenTopoMap" in otm.attribution and "CC-BY-SA" in otm.attribution
    assert "OpenStreetMap" in otm.attribution and "SRTM" in otm.attribution
    # a topographic base map, not imagery: the labels overlay would double its labels
    assert otm.imagery is False
    # the server itself answers deeper zooms with a "max zoom layer = 17" placard
    assert otm.max_zoom == 17
    # no {s}: the capture path formats only x/y/z and would raise on a subdomain
    assert "{s}" not in otm.url


def test_fetch_crop_never_requests_past_opentopomap_max_zoom(monkeypatch, tmp_path):
    """A capture must never ask OpenTopoMap for z >= 18.

    Deeper zooms come back as a constant "max zoom layer = 17" placard, so
    stitching one would put that placard into a proof. fetch_crop clamps to the
    provider max instead — and records the honest zoom in provenance.
    """
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    otm = next(p for p in tiles.all_providers() if p.id == "opentopomap")
    seen: list[int] = []

    def fake_fetch(client, url):
        seen.append(int(url.split("/")[-3]))
        return Image.new("RGB", (256, 256), (200, 180, 140))

    _, prov = tiles.fetch_crop(45.92, 6.87, 19, 512, 512, otm, fetch_tile=fake_fetch)
    assert seen and max(seen) == 17
    assert prov["zoom"] == 17
    # m/px must describe the zoom actually captured, not the one asked for
    assert prov["meters_per_pixel"] == round(tiles.meters_per_pixel(45.92, 17), 3)


def test_all_providers_omits_keyed_providers_without_keys(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    ids = {p.id for p in tiles.all_providers()}
    assert "mapbox-satellite" not in ids
    assert "google-satellite" not in ids


def test_all_providers_adds_mapbox_when_keyed(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {"mapbox": "pk.test123"}})
    mapbox = next(p for p in tiles.all_providers() if p.id == "mapbox-satellite")
    assert "pk.test123" in mapbox.url
    assert "{key}" not in mapbox.url
    assert mapbox.capturable is True
    assert mapbox.cacheable is True
    assert mapbox.attribution_burn is False
    assert mapbox.session is None
    assert mapbox.max_zoom == 22


def test_all_providers_adds_google_when_keyed(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {"google": "AIza.test123"}})
    google = next(p for p in tiles.all_providers() if p.id == "google-satellite")
    assert "AIza.test123" in google.url
    assert "{session}" in google.url  # resolved at fetch time (§3), not here
    assert google.capturable is True
    assert google.cacheable is False
    assert google.attribution_burn is True
    assert google.session == "google"
    assert google.tile_size == 1024  # hi-DPI 4x session (1/16th the billed requests)


def test_all_providers_adds_sentinelhub_when_keyed(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {"sentinelhub": "inst-uuid"}})
    s2 = next(p for p in tiles.all_providers() if p.id == "sentinel2")
    assert "inst-uuid" in s2.url
    assert "{key}" not in s2.url  # the instance id is the whole credential
    assert "TIME=" not in s2.url  # omitted: the layer's own default window applies
    assert s2.capturable is True
    assert s2.cacheable is True  # open data — no anti-cache clause to respect
    assert s2.attribution_burn is False
    assert s2.session is None
    assert s2.tile_size == 512  # one 512px tile == exactly 1 processing unit
    # 10 m/px native: requests stop at z14 (deeper is upsampling we'd pay for),
    # the view runs to z18 on magnified native tiles — free, since nothing new
    # is fetched
    assert s2.max_native_zoom == 14
    assert s2.max_zoom == 18
    # its own eco threshold: the global z15 sits above its native ceiling, so
    # sharing it would swap Sentinel-2 away at most zooms it can actually serve
    assert s2.eco_max_zoom == 7


def test_sentinelhub_names_its_zoom_level_by_resolution(monkeypatch, tmp_path):
    """WMTS numbers 512px levels by resolution where Mapbox numbers them by grid
    width: tile indices valid at grid level 13 belong to TILEMATRIX=14."""
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {"sentinelhub": "inst-uuid"}})
    s2 = next(p for p in tiles.all_providers() if p.id == "sentinel2")
    url = tiles.tile_url(s2.url, 13, 4151, 2818, s2.zoom_offset)
    assert "TILEMATRIX=14" in url
    assert "TILECOL=4151" in url and "TILEROW=2818" in url


def _sentinel(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {"sentinelhub": "inst-uuid"}})
    return next(p for p in tiles.all_providers() if p.id == "sentinel2")


def test_get_provider_resolves_a_sentinel_variant(monkeypatch, tmp_path):
    _sentinel(monkeypatch, tmp_path)
    p = tiles.get_provider("sentinel2~SWIR~2026-05-01~2026-05-31")
    assert "LAYER=SWIR" in p.url
    assert "TIME=2026-05-01/2026-05-31" in p.url
    assert "inst-uuid" in p.url  # the credential survives the rebuild
    assert "{key}" not in p.url
    # the id is the variant, so the disk cache keys on it: two windows can never
    # collide in the cache, which is the trap docs/IMAGERY_PROVIDERS.md names
    assert p.id == "sentinel2~SWIR~2026-05-01~2026-05-31"
    assert p.meter == "sentinelhub"  # still the same quota
    assert p.max_native_zoom == 14 and p.max_zoom == 18
    assert "SWIR" in p.label and "2026-05-01" in p.label


def test_get_provider_variant_without_a_window_keeps_the_default_time(monkeypatch, tmp_path):
    _sentinel(monkeypatch, tmp_path)
    p = tiles.get_provider("sentinel2~FALSE_COLOR")
    assert "LAYER=FALSE_COLOR" in p.url
    assert "TIME=" not in p.url


def test_get_provider_carries_the_cloud_ceiling_into_the_url(monkeypatch, tmp_path):
    provider = _sentinel(monkeypatch, tmp_path)
    # the plain basemap states the default explicitly: without it the instance's
    # own filter applies and cloudy passes render as nothing
    assert "MAXCC=100" in provider.url
    p = tiles.get_provider("sentinel2~TRUE_COLOR~2026-05-01~2026-05-01~CC20")
    assert "MAXCC=20" in p.url
    assert "TIME=2026-05-01/2026-05-01" in p.url
    # the ceiling changes the pixels, so it is in the id the cache and a
    # capture's provenance key on
    assert p.id == "sentinel2~TRUE_COLOR~2026-05-01~2026-05-01~CC20"
    assert "≤20% cloud" in p.label


def test_get_provider_refuses_a_malformed_variant(monkeypatch, tmp_path):
    _sentinel(monkeypatch, tmp_path)
    for bad in ("sentinel2~../etc", "sentinel2~SWIR~2026-99-01~2026-05-31", "sentinel2~a b",
                "sentinel2~SWIR~CC101"):
        with pytest.raises(KeyError):
            tiles.get_provider(bad)


def test_get_provider_refuses_variants_on_providers_that_have_none(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings(config.DEFAULT_SETTINGS)
    with pytest.raises(KeyError):
        tiles.get_provider("esri-world-imagery~SWIR")


def test_fetch_crop_past_native_zoom_magnifies_instead_of_paying(monkeypatch, tmp_path):
    """Sentinel-2 views run to z18 but its pixels stop at z14: the deepest real
    tiles are fetched and magnified. Asking Sentinel Hub for z18 would buy its
    upsampling of the same pixels, 16× the tiles, every one billed."""
    provider = _sentinel(monkeypatch, tmp_path)
    urls = []

    def fetch(client, url):
        urls.append(url)
        return Image.new("RGB", (512, 512), (10, 120, 10))

    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 18, 512, 512, provider, marker_style="none", fetch_tile=fetch
    )
    # every request is at the native level (grid 13 → TILEMATRIX 14), none deeper
    assert urls and all("TILEMATRIX=14" in u for u in urls)
    # one native tile now covers 16× the canvas, so a 512px crop needs 1–4 of
    # them — not the 16× more a real z18 grid would have cost
    assert len(urls) <= 4
    assert config.load_settings()["usage"]["sentinelhub"][config.month_key()] == len(urls)
    assert img.size == (512, 512)
    # the canvas is fully covered — the magnified grid must still tile seamlessly
    for xy in ((0, 0), (511, 0), (0, 511), (511, 511), (256, 256)):
        assert img.getpixel(xy) == (10, 120, 10)
    # provenance tells the truth twice: the view is z18, the pixels are z14
    assert prov["zoom"] == 18
    assert prov["native_zoom"] == 14
    assert prov["upscaled"] is True
    assert prov["native_meters_per_pixel"] > prov["meters_per_pixel"]


def test_fetch_crop_at_native_zoom_is_not_marked_upscaled(monkeypatch, tmp_path):
    provider = _sentinel(monkeypatch, tmp_path)

    def fetch(client, url):
        return Image.new("RGB", (512, 512), (10, 120, 10))

    _, prov = tiles.fetch_crop(
        48.8584, 2.2945, 14, 512, 512, provider, marker_style="none", fetch_tile=fetch
    )
    assert prov["zoom"] == 14 and prov["native_zoom"] == 14
    assert prov["upscaled"] is False
    assert prov["native_meters_per_pixel"] == prov["meters_per_pixel"]


def test_fetch_crop_of_a_variant_requests_that_layer_and_window(monkeypatch, tmp_path):
    _sentinel(monkeypatch, tmp_path)
    provider = tiles.get_provider("sentinel2~SWIR~2026-05-01~2026-05-31")
    urls = []

    def fetch(client, url):
        urls.append(url)
        return Image.new("RGB", (512, 512), (10, 120, 10))

    _, prov = tiles.fetch_crop(
        48.8584, 2.2945, 14, 512, 512, provider, marker_style="none", fetch_tile=fetch
    )
    assert all("LAYER=SWIR" in u and "TIME=2026-05-01/2026-05-31" in u for u in urls)
    # a reader of this capture can tell which layer and which window it is
    assert prov["provider"] == "sentinel2~SWIR~2026-05-01~2026-05-31"
    assert "SWIR" in prov["provider_label"]


def test_tile_url_leaves_zoom_alone_without_an_offset():
    url = tiles.tile_url("https://x/{z}/{x}/{y}.png", 7, 1, 2)
    assert url == "https://x/7/1/2.png"


def test_all_providers_adds_google_js_widget_when_keyed(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {"google_js": "AIza.js"}})
    widget = next(p for p in tiles.all_providers() if p.id == "google-js")
    assert "AIza.js" in widget.url  # the JS loader URL — client-side by design
    assert widget.widget == "google-maps-js"
    assert widget.capturable is False  # nothing to stitch — screenshots only
    assert widget.cacheable is False
    assert widget.meter == "google_js"  # counts map loads, not tiles
    assert widget.eco_max_zoom == 0  # eco would re-bill a load per swap


def test_all_providers_benches_a_key_that_failed_auth(monkeypatch, tmp_path):
    """A basemap whose key was last seen failing (EEA block, revoked key) is
    withheld from the selector until the key changes or a test passes."""
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({
        **config.DEFAULT_SETTINGS,
        "api_keys": {"google": "AIza.x", "mapbox": "pk.y"},
        "provider_status": {"google": {"ok": False, "detail": "EEA policy", "at": "now"}},
    })
    ids = {p.id for p in tiles.all_providers()}
    assert "google-satellite" not in ids  # benched
    assert "mapbox-satellite" in ids  # untouched
    # a passing verdict puts it back
    config.record_provider_status("google", True, "session token created")
    assert "google-satellite" in {p.id for p in tiles.all_providers()}


def test_all_providers_respects_enable_toggles(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({
        **config.DEFAULT_SETTINGS,
        "api_keys": {"mapbox": "pk.test", "google": "AIza.test"},
        "providers_enabled": {"mapbox": False},
    })
    ids = {p.id for p in tiles.all_providers()}
    # mapbox switched off (key kept), google untouched by an absent entry
    assert "mapbox-satellite" not in ids
    assert "google-satellite" in ids


def test_fetch_crop_blocked_at_soft_limit(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "mapbox", "pk.test")
    config.record_usage("mapbox", int(config.FREE_TIER["mapbox"] * config.BLOCK_SHARE))
    with pytest.raises(tiles.TileFetchError, match="free tier"):
        tiles.fetch_crop(48.8584, 2.2945, 15, 512, 512, provider, fetch_tile=_green_tile)


def test_fetch_crop_override_lifts_the_block(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "mapbox", "pk.test")
    config.record_usage("mapbox", config.FREE_TIER["mapbox"])  # 100% used
    settings = config.load_settings()
    settings["usage_overrides"] = {"mapbox": True}
    config.save_settings(settings)

    def fetch(client, url):
        return Image.new("RGB", (512, 512), (10, 120, 10))

    img, prov = tiles.fetch_crop(48.8584, 2.2945, 15, 512, 512, provider, fetch_tile=fetch)
    assert prov["tiles_missing"] == 0


def test_fetch_crop_rejects_non_capturable_provider():
    provider = dataclasses.replace(tiles.BUILTIN_PROVIDERS[0], capturable=False)
    with pytest.raises(tiles.TileFetchError, match="view-only"):
        tiles.fetch_crop(0, 0, 10, 256, 256, provider, fetch_tile=lambda c, u: None)


def _green_tile(client, url):
    return Image.new("RGB", (256, 256), (10, 120, 10))


def _keyed_provider(monkeypatch, tmp_path, name, key):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings({**config.DEFAULT_SETTINGS, "api_keys": {name: key}})
    return next(p for p in tiles.all_providers() if p.id == f"{name}-satellite")


def test_fetch_crop_mapbox_uses_512_tiles_and_meters_served(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "mapbox", "pk.test")
    assert provider.tile_size == 512
    urls = []

    def fetch(client, url):
        urls.append(url)
        return Image.new("RGB", (512, 512), (10, 120, 10))

    img, prov = tiles.fetch_crop(48.8584, 2.2945, 15, 512, 512, provider, fetch_tile=fetch)
    assert all("access_token=pk.test" in u for u in urls)
    # 512px tiles: same m/px, but requested one zoom lower — 4× fewer billed tiles
    assert all("/tiles/512/14/" in u for u in urls)
    assert prov["zoom"] == 15  # provenance keeps the visual zoom
    assert len(urls) <= 4  # a 512px crop needs at most 2×2 512px tiles, not 3×3 256s
    assert prov["attribution"] == "© Mapbox © OpenStreetMap"
    assert prov["attribution_burned"] is False
    assert img.size == (512, 512)  # no footer band for Mapbox
    # exactly the tiles the provider served land in the monthly counter (§6)
    assert config.load_settings()["usage"]["mapbox"][config.month_key()] == len(urls)


def test_fetch_crop_512_grid_covers_the_canvas(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "mapbox", "pk.test")

    def fetch(client, url):
        return Image.new("RGB", (512, 512), (10, 120, 10))

    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 900, 700, provider, marker_style="none", fetch_tile=fetch
    )
    assert prov["tiles_missing"] == 0
    # no background showing through anywhere — the 512 grid must tile seamlessly
    for xy in ((0, 0), (899, 0), (0, 699), (899, 699), (450, 350)):
        assert img.getpixel(xy) == (10, 120, 10)


def test_fetch_crop_missing_tiles_are_not_billed(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "mapbox", "pk.test")
    calls = {"n": 0}

    def fetch(client, url):
        if "/tiles/512/14/" not in url:
            return None  # overzoom parents: nothing there either
        calls["n"] += 1
        return None if calls["n"] == 1 else Image.new("RGB", (512, 512), (10, 120, 10))

    img, prov = tiles.fetch_crop(48.8584, 2.2945, 15, 900, 900, provider, fetch_tile=fetch)
    assert prov["tiles_missing"] == 1
    assert prov["tiles_upscaled"] == 0
    # only tiles the provider actually served count toward the meter
    usage = config.load_settings()["usage"]["mapbox"][config.month_key()]
    assert usage == prov["tiles"] - 1


def test_fetch_crop_overzoom_fills_gaps_from_parent(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "mapbox", "pk.test")
    calls = {"n": 0, "parents": []}

    def fetch(client, url):
        if "/tiles/512/14/" in url:  # the crop's own zoom level
            calls["n"] += 1
            return None if calls["n"] == 1 else Image.new("RGB", (512, 512), (10, 120, 10))
        calls["parents"].append(url)  # one level up: imagery exists
        return Image.new("RGB", (512, 512), (200, 50, 50))

    img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 15, 900, 900, provider, marker_style="none", fetch_tile=fetch
    )
    # the gap was filled from the parent level, once, and recorded as upscaled
    assert prov["tiles_missing"] == 0
    assert prov["tiles_upscaled"] == 1
    assert len(calls["parents"]) == 1
    assert "/tiles/512/13/" in calls["parents"][0]
    # the parent tile the provider served is billed alongside the direct ones
    usage = config.load_settings()["usage"]["mapbox"][config.month_key()]
    assert usage == (prov["tiles"] - 1) + 1


def test_default_fetch_treats_placeholder_tile_as_missing(monkeypatch):
    import hashlib

    body = b"esri-not-yet-available"
    monkeypatch.setattr(
        tiles, "PLACEHOLDER_TILE_SHA256", frozenset({hashlib.sha256(body).hexdigest()})
    )

    class FakeClient:
        def get(self, url):
            return httpx.Response(200, content=body, request=httpx.Request("GET", url))

    assert tiles._default_fetch(FakeClient(), "http://tiles.example/1/2/3") is None
    assert tiles.is_placeholder_tile(b"real imagery") is False


def test_fetch_crop_unmetered_provider_records_nothing(monkeypatch, tmp_path):
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    tiles.fetch_crop(
        48.8584, 2.2945, 15, 512, 512, tiles.BUILTIN_PROVIDERS[0], fetch_tile=_green_tile
    )
    assert config.load_settings()["usage"] == {}


def test_fetch_crop_google_resolves_session_and_burns_attribution(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "google", "AIza.test")
    monkeypatch.setattr(
        tiles.google_tiles,
        "resolve_template",
        lambda url, **kw: url.replace("{session}", "tok-live"),
    )
    monkeypatch.setattr(
        tiles.google_tiles,
        "viewport_copyright",
        lambda *a, **kw: "Map data ©2026 Google, Maxar Technologies",
    )
    urls = []

    def fetch(client, url):
        urls.append(url)
        return Image.new("RGB", (1024, 1024), (10, 120, 10))

    img, prov = tiles.fetch_crop(48.8584, 2.2945, 15, 512, 512, provider, fetch_tile=fetch)
    assert all("session=tok-live" in u and "key=AIza.test" in u for u in urls)
    # 1024px hi-DPI tiles: same m/px, requested two zooms lower — 16× fewer requests
    assert all("/2dtiles/13/" in u for u in urls)
    assert prov["zoom"] == 15  # provenance keeps the visual zoom
    # dynamic viewport copyright recorded, not just "Google"
    assert prov["attribution"] == "Map data ©2026 Google, Maxar Technologies"
    assert prov["attribution_burned"] is True
    # the footer band is appended below the imagery, never covering it
    assert img.size == (512, 512 + tiles.ATTRIBUTION_BAND)
    assert img.getpixel((0, 512 + tiles.ATTRIBUTION_BAND - 1)) == (16, 18, 24)
    assert img.getpixel((0, 511)) == (10, 120, 10)  # imagery intact
    assert config.load_settings()["usage"]["google"][config.month_key()] == prov["tiles"]


def test_fetch_crop_google_remints_session_on_403(monkeypatch, tmp_path):
    provider = _keyed_provider(monkeypatch, tmp_path, "google", "AIza.test")
    tokens = iter(["tok-stale", "tok-fresh"])
    monkeypatch.setattr(
        tiles.google_tiles,
        "resolve_template",
        lambda url, **kw: url.replace("{session}", next(tokens)),
    )
    invalidated = []
    monkeypatch.setattr(tiles.google_tiles, "invalidate", invalidated.append)
    monkeypatch.setattr(tiles.google_tiles, "viewport_copyright", lambda *a, **kw: None)

    def fetch(client, url):
        if "session=tok-stale" in url:
            request = httpx.Request("GET", url)
            raise httpx.HTTPStatusError(
                "expired", request=request, response=httpx.Response(403, request=request)
            )
        assert "session=tok-fresh" in url
        return Image.new("RGB", (1024, 1024), (10, 120, 10))

    img, prov = tiles.fetch_crop(48.8584, 2.2945, 15, 512, 512, provider, fetch_tile=fetch)
    assert invalidated == ["AIza.test"]
    assert prov["tiles_missing"] == 0
    # no viewport copyright reachable — static fallback still carried & burned
    assert prov["attribution"] == "Google"


def test_record_usage_rolls_months(monkeypatch, tmp_path):
    from datetime import datetime, timezone

    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    july = datetime(2026, 7, 20, tzinfo=timezone.utc)
    august = datetime(2026, 8, 2, tzinfo=timezone.utc)
    assert config.record_usage("google", 5, when=july) == 5
    assert config.record_usage("google", 3, when=july) == 8
    assert config.record_usage("google", 2, when=august) == 2  # fresh bucket
    usage = config.load_settings()["usage"]["google"]
    assert usage == {"2026-07": 8, "2026-08": 2}


def test_parse_coords():
    assert geo.parse_coords("50.4501, 30.5234") == (50.4501, 30.5234)
    assert geo.parse_coords("50.4501 30.5234") == (50.4501, 30.5234)
    assert geo.parse_coords("-33.8688, 151.2093") == (-33.8688, 151.2093)
    lat, lon = geo.parse_coords("""48°51'29.6"N 2°17'40.2"E""")
    assert abs(lat - 48.85822) < 1e-4
    assert abs(lon - 2.29450) < 1e-4
    # every displayable format pastes back in: MGRS…
    lat, lon = geo.parse_coords("31U DQ 48250 11951")
    assert abs(lat - 48.85837) < 1e-3 and abs(lon - 2.29448) < 1e-3
    # …and full plus codes (round-trip through the app's own encoder)
    lat, lon = geo.parse_coords(geo.plus_code(48.8584, 2.2945))
    assert abs(lat - 48.8584) < 1e-3 and abs(lon - 2.2945) < 1e-3

    assert geo.parse_coords("hello world") is None
    assert geo.parse_coords("91, 0") is None


def test_plus_code_known_value():
    # Google's OLC reference example: 47.365590, 8.524997 → 8FVC9G8F+6X
    assert geo.plus_code(47.365590, 8.524997) == "8FVC9G8F+6X"


def test_dms_format():
    assert geo.to_dms(48.8584, 2.2945).endswith('E')
    assert "N" in geo.to_dms(48.8584, 2.2945)


class _FakeResp:
    def __init__(self, payload):
        self._payload = payload

    def raise_for_status(self):
        pass

    def json(self):
        return self._payload


def test_esri_capture_date_parses_yyyymmdd():
    payload = {"results": [{"attributes": {"NICE_NAME": "Maxar", "SRC_DATE2": "20210514"}}]}
    out = tiles.esri_capture_date(48.8584, 2.2945, 17, get=lambda *a, **k: _FakeResp(payload))
    assert out == {"date": "2021-05-14", "source": "Maxar"}


def test_esri_capture_date_full_date_beats_year():
    payload = {"results": [{"attributes": {"SRC_DATE": "2019", "SRC_DATE2": "20200103"}}]}
    out = tiles.esri_capture_date(0, 0, 17, get=lambda *a, **k: _FakeResp(payload))
    assert out["date"] == "2020-01-03"


def test_esri_capture_date_empty_results():
    out = tiles.esri_capture_date(0, 0, 17, get=lambda *a, **k: _FakeResp({"results": []}))
    assert out == {"date": None, "source": None}


def test_esri_capture_date_network_failure_returns_none():
    def boom(*a, **k):
        raise OSError("down")

    assert tiles.esri_capture_date(0, 0, 17, get=boom) is None


def test_crop_across_the_antimeridian_is_not_half_blank():
    """Longitude wraps, so the tiles past ±180° are the ones on the other side.

    Clamping them away instead left a blank band down the middle of every
    capture near the date line — the one place on the planet where a crop is
    guaranteed to straddle the edge of the grid.
    """
    provider = tiles.BUILTIN_PROVIDERS[0]
    asked: list[int] = []
    zoom = 6
    max_index = (1 << zoom) - 1

    def fake_fetch(client, url):
        # the x the template was filled with, read back off the URL
        asked.append(int(url.split("/")[-2]))
        return Image.new("RGB", (256, 256), (10, 120, 10))

    img, prov = tiles.fetch_crop(
        0.0, 179.98, zoom, 900, 600, provider, fetch_tile=fake_fetch
    )

    assert prov["tiles_missing"] == 0, "a tile past the antimeridian went unfetched"
    assert asked, "no tile was requested at all"
    assert all(0 <= x <= max_index for x in asked), f"out-of-grid tile index: {sorted(set(asked))}"
    # and the canvas holds imagery edge to edge, not the fill colour
    assert img.getpixel((2, 300)) == (10, 120, 10)
    assert img.getpixel((897, 300)) == (10, 120, 10)


def test_crop_still_leaves_the_poles_empty():
    """Latitude does not wrap: above the top row there is no imagery to read from
    the other side, and inventing some would be a picture of nowhere."""
    provider = tiles.BUILTIN_PROVIDERS[0]

    def fake_fetch(client, url):
        return Image.new("RGB", (256, 256), (10, 120, 10))

    _img, prov = tiles.fetch_crop(
        85.0, 0.0, 3, 700, 700, provider, fetch_tile=fake_fetch
    )
    assert prov["tiles_missing"] > 0


# -- the scale bar and the north arrow -----------------------------------------


def test_scale_span_climbs_the_round_ladder():
    """Every span a bar may state is 1, 2 or 5 × a power of ten, in the unit."""
    for mpp in (0.05, 0.3, 1.19, 9.55, 76.4, 300.0):
        label, pixels = tiles.scale_span(mpp, 300)
        number = float(label.split()[0])
        decade = number / 10 ** math.floor(math.log10(number))
        assert round(decade, 6) in (1.0, 2.0, 5.0), label
        assert pixels <= 300


def test_scale_span_reads_in_the_analysts_own_units():
    metric, _ = tiles.scale_span(1.0, 300)
    imperial, _ = tiles.scale_span(1.0, 300, "imperial")
    assert metric.endswith(" m")
    assert imperial.endswith(" ft")
    # far enough out, each climbs to its own big unit
    assert tiles.scale_span(50.0, 300)[0].endswith(" km")
    assert tiles.scale_span(50.0, 300, "imperial")[0].endswith(" mi")


def test_scale_span_refuses_what_it_cannot_back():
    assert tiles.scale_span(0, 300) is None
    assert tiles.scale_span(-1.0, 300) is None
    assert tiles.scale_span(1.0, 0) is None
    # a bar narrower than its own label is no bar
    assert tiles.scale_span(1.0, 20) is None


def test_burn_scale_north_draws_both_marks_and_says_what_it_drew():
    img = Image.new("RGB", (900, 600), (60, 70, 60))
    before = img.tobytes()
    drawn = tiles.burn_scale_north(img, meters_per_pixel=1.19, bearing=0.0)
    assert drawn == {"scale": "200 m", "north": 0.0}
    assert img.tobytes() != before, "nothing was actually drawn"


def test_burn_scale_north_draws_neither_mark_without_a_fact_behind_it():
    """A capture off a map site that states no rotation gets the bar alone, and
    one with no resolution at all is left exactly as it came in."""
    img = Image.new("RGB", (900, 600), (60, 70, 60))
    assert tiles.burn_scale_north(img, meters_per_pixel=1.19, bearing=None) == {
        "scale": "200 m",
        "north": None,
    }
    bare = Image.new("RGB", (900, 600), (60, 70, 60))
    untouched = bare.tobytes()
    assert tiles.burn_scale_north(bare, meters_per_pixel=None, bearing=None) is None
    assert bare.tobytes() == untouched


def test_fetch_crop_leaves_the_marks_off_unless_they_are_asked_for():
    provider = tiles.BUILTIN_PROVIDERS[0]

    def fake_fetch(client, url):
        return Image.new("RGB", (256, 256), (10, 120, 10))

    plain, prov = tiles.fetch_crop(48.8584, 2.2945, 17, 640, 480, provider, fetch_tile=fake_fetch)
    assert prov["marks"] is None

    marked, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider, scale_north=True, fetch_tile=fake_fetch
    )
    assert prov["marks"]["scale"].endswith(" m")
    assert prov["marks"]["north"] == 0.0
    assert marked.tobytes() != plain.tobytes()


def test_a_turned_crop_records_the_heading_its_needle_points_at():
    provider = tiles.BUILTIN_PROVIDERS[0]

    def fake_fetch(client, url):
        return Image.new("RGB", (256, 256), (10, 120, 10))

    _img, prov = tiles.fetch_crop(
        48.8584, 2.2945, 17, 640, 480, provider,
        bearing=42.0, scale_north=True, fetch_tile=fake_fetch,
    )
    assert prov["marks"]["north"] == 42.0


# -- slow providers, and tiles that come late ---------------------------------


class _Flaky:
    """A client whose tiles fail a few times before arriving."""

    def __init__(self, failures):
        self.failures = list(failures)
        self.asked = []

    def get(self, url, **kwargs):
        self.asked.append(url)
        if self.failures:
            trouble = self.failures.pop(0)
            if isinstance(trouble, Exception):
                raise trouble
            return httpx.Response(trouble, content=b"", request=httpx.Request("GET", url))
        buf = io.BytesIO()
        Image.new("RGB", (16, 16), (10, 120, 10)).save(buf, format="PNG")
        return httpx.Response(
            200, content=buf.getvalue(), request=httpx.Request("GET", url)
        )


def test_a_tile_that_timed_out_is_asked_for_again(monkeypatch):
    """One slow tile used to take a whole capture down with it, which is the
    worst way to lose a scene that is only available for this pass."""
    monkeypatch.setattr(tiles, "RETRY_PAUSE", 0)
    client = _Flaky([httpx.ReadTimeout("too slow"), 503])

    tile = tiles._default_fetch(client, "https://example.test/t.png")

    assert tile is not None
    assert len(client.asked) == 3


def test_a_tile_that_never_comes_still_raises(monkeypatch):
    monkeypatch.setattr(tiles, "RETRY_PAUSE", 0)
    client = _Flaky([httpx.ReadTimeout("too slow")] * tiles.MAX_TILE_TRIES)

    with pytest.raises(httpx.ReadTimeout):
        tiles._default_fetch(client, "https://example.test/t.png")
    assert len(client.asked) == tiles.MAX_TILE_TRIES


def test_a_refused_tile_is_not_asked_for_again(monkeypatch):
    monkeypatch.setattr(tiles, "RETRY_PAUSE", 0)
    client = _Flaky([400] * 5)

    with pytest.raises(httpx.HTTPStatusError):
        tiles._default_fetch(client, "https://example.test/t.png")
    assert len(client.asked) == 1


def test_radar_is_given_longer_than_the_shared_ceiling(monkeypatch, tmp_path):
    """Sentinel-1 is drawn from the GRD per request where the optical layer is
    served already baked, so it is the one that outruns the default."""
    monkeypatch.setenv("AZIMUT_HOME", str(tmp_path))
    config.save_settings(
        {
            **config.DEFAULT_SETTINGS,
            "api_keys": {"sentinelhub": "inst-uuid"},
            "sentinel1_layer": "RADAR",
        }
    )
    radar = tiles.get_provider("sentinel1")
    optical = tiles.get_provider("sentinel2")

    assert radar.timeout == tiles.RADAR_TILE_TIMEOUT > tiles.TILE_TIMEOUT
    assert optical.timeout is None  # the shared ceiling is enough for a baked tile
    # and one pass of it inherits the ceiling the basemap declared
    assert tiles.get_provider("sentinel1~2026-10-06~151800").timeout == tiles.RADAR_TILE_TIMEOUT


# -- what a provider says when it refuses -------------------------------------


# Exactly what Sentinel Hub answered on 2026-10-07, when its elevation service
# was down and every Sentinel-1 render failed with it.
DEM_OUTAGE = b"""<?xml version='1.0' encoding="UTF-8"?>
<ows:ExceptionReport xmlns:ows="http://www.opengis.net/ows/1.1" version="1.0.0" xml:lang="en">
\t<ows:Exception>
\t\t<ows:ExceptionText>java.util.concurrent.ExecutionException: java.util.concurrent.ExecutionException: java.lang.RuntimeException: Could not load necessary digital elevation model for orthorectification! Please try again later or without orthorectification.</ows:ExceptionText>
\t</ows:Exception>
</ows:ExceptionReport>"""


def test_the_provider_s_own_account_of_a_refusal_is_kept():
    """Without it a Copernicus outage is indistinguishable from a bug here,
    and the analyst goes looking at their own connection."""
    assert tiles.upstream_reason(DEM_OUTAGE) == (
        "Could not load necessary digital elevation model for orthorectification! "
        "Please try again later or without orthorectification."
    )


def test_a_refusal_that_explains_nothing_says_nothing():
    assert tiles.upstream_reason(b"") == ""
    assert tiles.upstream_reason(b"<html><body>502 Bad Gateway</body></html>") == ""
    assert tiles.upstream_reason(b"\x89PNG\r\n\x1a\n" + b"\xff" * 64) == ""


def test_a_refusal_never_quotes_back_what_it_was_sent():
    """A message lands in the page, the network log and the screenshot attached
    to a bug report, so the instance id must not travel in one."""
    echoed = (
        "<ows:ExceptionText>java.lang.RuntimeException: Layer not found at "
        "https://services.sentinel-hub.com/ogc/wmts/0f7f2d1e-3c4b-4a5d-8e9f-1a2b3c4d5e6f"
        " for instance 0f7f2d1e-3c4b-4a5d-8e9f-1a2b3c4d5e6f with key pk.eyJhbGciOi"
        "</ows:ExceptionText>"
    ).encode()
    reason = tiles.upstream_reason(echoed)

    assert reason.startswith("Layer not found")
    for secret in ("https://", "0f7f2d1e", "pk.eyJ", "sentinel-hub.com"):
        assert secret not in reason


def test_a_refusal_is_capped_at_a_sentence():
    flood = ("<ows:ExceptionText>" + "no. " * 500 + "</ows:ExceptionText>").encode()
    assert len(tiles.upstream_reason(flood)) == tiles.REASON_MAX


def test_a_credit_wider_than_the_image_goes_on_over_more_lines():
    text = "Esri, Maxar, Earthstar Geographics, and the GIS User Community · Relief © Mapterhorn"
    narrow = tiles.burn_attribution(Image.new("RGB", (400, 100), (10, 120, 10)), text)
    # the band grows a line rather than letting the credit run off the edge
    assert narrow.size == (400, 100 + tiles.ATTRIBUTION_BAND + tiles.ATTRIBUTION_LINE)
    assert narrow.getpixel((0, 99)) == (10, 120, 10)  # imagery intact
    wide = tiles.burn_attribution(Image.new("RGB", (900, 100)), text)
    assert wide.size == (900, 100 + tiles.ATTRIBUTION_BAND)
    # cut between the credits first, so each one reads whole
    font = tiles.ImageFont.load_default()
    assert tiles._attribution_lines(text, font, 400) == [
        "Esri, Maxar, Earthstar Geographics, and the GIS User Community",
        "Relief © Mapterhorn",
    ]