Aircraft, from the menus, on a live board, over a real map

Four things the ADS-B mode was missing, and one it was actively getting wrong. The band plan lists 1090 MHz because that is where ADS-B is, so choosing it from the band plan is the obvious thing to do -- and it records the bursts as clicks in a WAV file and decodes nothing, silently. Both the scanner and the menus now say so, before the sweep starts, and name the mode that does decode it. It is not refused: looking at the raw spectrum is a fair thing to want. Menu 5, Aircraft (ADS-B), is the whole mode without a command line. Every option on one screen with a line saying what it does, ?N for the long version and the flag it corresponds to, l to listen, m to draw a map from any log, s to keep the options. The listening and the drawing moved into bandsaunter/aircraft.py so the menus and the command line run the same code. While it listens the screen is a live board: one line per aircraft in the order first heard, the counter climbing as frames arrive, height coloured low warm to high cold with an arrow for climb or descent, the age of the last report going green to red, and the line removed once nothing has been heard for --hold seconds, everything below moving up. The registers are asked while it runs, so registration, type, operator and route fill themselves in as the answers arrive. --speed-unit knots|mph|kph changes the heading of that board, the speed beside every aircraft on the map and the speeds in the report, and moves the distances with it so that one picture never carries two different miles. The log stays in knots, which is what the aircraft broadcast. And there is a real map under the flight paths: {z}/{x}/{y} tiles fetched once, cached in ~/.cache/bandsaunter/tiles, reprojected from Web Mercator pixel by pixel, inverted and dimmed so the aircraft stay the brightest thing on the picture. The PNGs are decoded here -- zlib and the five row filters from the specification, checked byte for byte against Pillow on real tiles -- so nothing new is depended on. Tiles are cached and never re-fetched, every request says who is asking, and the attribution is drawn onto the picture, because a GIF travels without its readme. conftest now fails any test that reaches for a tile server or a register. It caught four of these on the way in. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
2026-09-04 00:05:32 -07:00 · 2026-09-04 00:05:32 -07:00 · 96fc21ac7d
commit 96fc21ac7d
parent 4239635f74
18 changed files with 3298 additions and 281 deletions
--- a/tests/test_basemap.py
+++ b/tests/test_basemap.py
@ -0,0 +1,459 @@
+"""The ground under the aircraft: reading tiles, and putting them on the map.
+
+Nothing here touches the network.  The tiles are made up in the test and fed
+in through the same door the real ones come through, and the PNGs are built
+here from the specification rather than by the decoder they are testing.
+"""
+import struct
+import zlib
+
+import numpy as np
+import pytest
+
+from bandsaunter import basemap as bm
+from bandsaunter import flightmap as fm
+from test_flightmap import _has_text, two_aircraft
+
+
+# ---------------------------------------------------------------------------
+# Making PNGs the hard way, so the decoder is tested against the format
+# ---------------------------------------------------------------------------
+
+def _chunk(tag: bytes, body: bytes) -> bytes:
+    return (struct.pack(">I", len(body)) + tag + body
+            + struct.pack(">I", zlib.crc32(tag + body) & 0xFFFFFFFF))
+
+
+def _paeth(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    return b if pb <= pc else c
+
+
+def make_png(pixels: np.ndarray, colour: int = 2, filter_type: int = 0,
+             palette: np.ndarray | None = None) -> bytes:
+    """A PNG with every row written using one filter, built from the spec."""
+    pixels = np.asarray(pixels, dtype=np.uint8)
+    height, width = pixels.shape[0], pixels.shape[1]
+    channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}[colour]
+    flat = pixels.reshape(height, width * channels)
+    raw = bytearray()
+    previous = bytearray(width * channels)
+    for row in flat:
+        line = bytearray(int(v) for v in row)
+        out = bytearray(len(line))
+        for i, value in enumerate(line):
+            left_raw = line[i - channels] if i >= channels else 0
+            above = previous[i]
+            upleft = previous[i - channels] if i >= channels else 0
+            if filter_type == 0:
+                out[i] = value
+            elif filter_type == 1:
+                out[i] = (value - left_raw) & 0xFF
+            elif filter_type == 2:
+                out[i] = (value - above) & 0xFF
+            elif filter_type == 3:
+                out[i] = (value - ((left_raw + above) >> 1)) & 0xFF
+            else:
+                out[i] = (value - _paeth(left_raw, above, upleft)) & 0xFF
+        raw.append(filter_type)
+        raw += out
+        previous = line
+    body = (b"\x89PNG\r\n\x1a\n"
+            + _chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8,
+                                          colour, 0, 0, 0)))
+    if palette is not None:
+        body += _chunk(b"PLTE", np.asarray(palette, dtype=np.uint8).tobytes())
+    body += _chunk(b"IDAT", zlib.compress(bytes(raw), 6))
+    return body + _chunk(b"IEND", b"")
+
+
+def a_picture(height=9, width=7, seed=3) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    return rng.integers(0, 256, size=(height, width, 3), dtype=np.uint8)
+
+
+# ---------------------------------------------------------------------------
+# Reading a PNG
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("filter_type", [0, 1, 2, 3, 4])
+def test_every_filter_the_format_defines_is_undone(filter_type):
+    """None, Sub, Up, Average and Paeth: all five, or a tile comes back as
+    coloured noise and nobody notices until the map looks wrong."""
+    want = a_picture()
+    assert np.array_equal(bm.decode_png(make_png(want, 2, filter_type)), want)
+
+
+def test_what_this_program_writes_it_can_read_back():
+    from bandsaunter.images import write_png
+    import tempfile
+    from pathlib import Path
+
+    want = a_picture(height=20, width=13, seed=9)
+    with tempfile.TemporaryDirectory() as tmp:
+        path = write_png(Path(tmp) / "x.png", want)
+        assert np.array_equal(bm.decode_png(path.read_bytes()), want)
+
+
+def test_a_palette_image_is_looked_up():
+    """The tiles most servers send are palette images."""
+    palette = np.array([[0, 0, 0], [255, 0, 0], [0, 128, 255]], dtype=np.uint8)
+    indices = np.array([[0, 1, 2], [2, 1, 0]], dtype=np.uint8)[:, :, None]
+    got = bm.decode_png(make_png(indices, colour=3, palette=palette))
+    assert np.array_equal(got, palette[indices[:, :, 0]])
+
+
+def test_a_grey_image_becomes_grey_pixels():
+    grey = np.array([[0, 64], [128, 255]], dtype=np.uint8)[:, :, None]
+    got = bm.decode_png(make_png(grey, colour=0))
+    assert got.shape == (2, 2, 3)
+    assert np.array_equal(got[:, :, 0], got[:, :, 2])
+    assert got[1, 1, 0] == 255
+
+
+def test_transparency_is_dropped_rather_than_misread():
+    rng = np.random.default_rng(1)
+    rgba = rng.integers(0, 256, size=(4, 4, 4), dtype=np.uint8)
+    got = bm.decode_png(make_png(rgba, colour=6))
+    assert np.array_equal(got, rgba[:, :, :3])
+
+
+@pytest.mark.parametrize("body,why", [
+    (b"not a png at all", "not a PNG"),
+    (b"\x89PNG\r\n\x1a\n", "no image"),
+])
+def test_something_that_is_not_a_tile_is_refused(body, why):
+    with pytest.raises(bm.PNGError):
+        bm.decode_png(body)
+
+
+def test_a_depth_this_cannot_read_says_so_rather_than_guessing():
+    header = (b"\x89PNG\r\n\x1a\n"
+              + _chunk(b"IHDR", struct.pack(">IIBBBBB", 2, 2, 16, 2, 0, 0, 0))
+              + _chunk(b"IEND", b""))
+    with pytest.raises(bm.PNGError):
+        bm.decode_png(header)
+
+
+def test_an_interlaced_tile_is_refused():
+    header = (b"\x89PNG\r\n\x1a\n"
+              + _chunk(b"IHDR", struct.pack(">IIBBBBB", 2, 2, 8, 2, 0, 0, 1))
+              + _chunk(b"IEND", b""))
+    with pytest.raises(bm.PNGError):
+        bm.decode_png(header)
+
+
+# ---------------------------------------------------------------------------
+# Which tiles, and where they go
+# ---------------------------------------------------------------------------
+
+def test_the_middle_of_the_world_is_the_middle_of_the_grid():
+    assert bm.tile_of(0.0, 0.0, 0) == pytest.approx((0.5, 0.5))
+    assert bm.tile_of(0.0, -180.0, 1)[0] == pytest.approx(0.0)
+    assert bm.tile_of(85.05, 0.0, 1)[1] == pytest.approx(0.0, abs=0.001)
+
+
+def test_a_known_place_lands_in_its_known_tile():
+    """Seattle at zoom 10 is tile 164, 357 -- worked out from the standard
+    formula, not from this module."""
+    import math
+
+    lat, lon, z = 47.6062, -122.3321, 10
+    n = 2 ** z
+    x = int((lon + 180.0) / 360.0 * n)
+    y = int((1.0 - math.asinh(math.tan(math.radians(lat))) / math.pi) / 2.0 * n)
+    got = bm.tile_of(lat, lon, z)
+    assert (int(got[0]), int(got[1])) == (x, y)
+
+
+def test_a_small_box_gets_more_detail_than_a_large_one():
+    tight = bm.choose_zoom(47.5, -122.4, 47.7, -122.2)
+    wide = bm.choose_zoom(30.0, -130.0, 50.0, -70.0)
+    assert tight > wide
+    assert tight <= bm.MAX_ZOOM and wide >= bm.MIN_ZOOM
+
+
+def test_the_zoom_is_chosen_to_stay_inside_the_tile_budget():
+    south, west, north, east = 47.0, -122.8, 48.5, -121.0
+    zoom = bm.choose_zoom(south, west, north, east, max_tiles=12)
+    x0, y0 = bm.tile_of(north, west, zoom)
+    x1, y1 = bm.tile_of(south, east, zoom)
+    tiles = (int(x1) - int(x0) + 1) * (int(y1) - int(y0) + 1)
+    assert tiles <= 12
+
+
+# ---------------------------------------------------------------------------
+# Stitching, without a network
+# ---------------------------------------------------------------------------
+
+def solid(value):
+    """A tile of one colour, as PNG bytes."""
+    px = np.zeros((bm.TILE_PIXELS, bm.TILE_PIXELS, 3), dtype=np.uint8) + value
+    return make_png(px)
+
+
+def counting_fetcher(answers=None, fail_on=()):
+    """A stand-in for the tile server that records what it was asked for."""
+    asked = []
+
+    def fetch(z, x, y, **kw):
+        asked.append((z, x, y))
+        if (z, x, y) in fail_on:
+            return None
+        if answers is not None:
+            return answers(z, x, y)
+        return solid((x * 37 + y * 11) % 256)
+
+    fetch.asked = asked
+    return fetch
+
+
+def test_the_tiles_are_stitched_in_the_right_places():
+    fetch = counting_fetcher()
+    raster, ox, oy = bm.mosaic(47.0, -122.8, 48.5, -121.0, 9, fetch=fetch,
+                               pause=0)
+    assert raster is not None
+    assert raster.shape[2] == 3
+    assert raster.shape[0] % bm.TILE_PIXELS == 0
+    assert len(fetch.asked) == (raster.shape[0] // bm.TILE_PIXELS) * \
+        (raster.shape[1] // bm.TILE_PIXELS)
+    # The first tile fetched is the north-west corner, and it is drawn there.
+    z, x, y = fetch.asked[0]
+    assert (ox, oy) == (x * bm.TILE_PIXELS, y * bm.TILE_PIXELS)
+    assert raster[0, 0, 0] == (x * 37 + y * 11) % 256
+
+
+def test_a_tile_that_does_not_arrive_leaves_a_hole_rather_than_an_error():
+    """One tile missing is a hole in the map, not a failed drawing."""
+    seen = counting_fetcher()
+    bm.mosaic(47.0, -122.8, 48.5, -121.0, 9, fetch=seen, pause=0)
+    missing = seen.asked[:1]
+    raster, _, _ = bm.mosaic(47.0, -122.8, 48.5, -121.0, 9,
+                             fetch=counting_fetcher(fail_on=missing), pause=0)
+    assert raster is not None
+    assert not raster[:bm.TILE_PIXELS, :bm.TILE_PIXELS].any()   # the hole
+
+
+def test_nothing_at_all_gives_no_map():
+    def nothing(z, x, y, **kw):
+        return None
+
+    raster, _, _ = bm.mosaic(47.0, -122.8, 48.5, -121.0, 9, fetch=nothing,
+                             pause=0)
+    assert raster is None
+
+
+def test_a_corrupt_tile_is_skipped():
+    def rubbish(z, x, y, **kw):
+        return b"not a png"
+
+    raster, _, _ = bm.mosaic(47.0, -122.8, 48.5, -121.0, 9, fetch=rubbish,
+                             pause=0)
+    assert raster is None
+
+
+# ---------------------------------------------------------------------------
+# On to the picture
+# ---------------------------------------------------------------------------
+
+def gradient_tile(z, x, y, **kw):
+    """A tile that is black at the top and white at the bottom."""
+    column = np.linspace(0, 255, bm.TILE_PIXELS).astype(np.uint8)
+    px = np.repeat(column[:, None], bm.TILE_PIXELS, axis=1)
+    return make_png(np.repeat(px[:, :, None], 3, axis=2))
+
+
+def test_the_ground_comes_back_as_levels_the_map_can_paint():
+    levels = bm.ground_under(47.0, -122.8, 48.5, -121.0, 200, 150,
+                             shades=32, fetch=gradient_tile, pause=0)
+    assert levels is not None
+    assert levels.shape == (150, 200)
+    assert levels.dtype == np.uint8
+    assert levels.max() <= 31
+
+
+def tile_bounds(zoom: int, x: int, y: int):
+    """The corners of one tile, from the inverse of the standard formula.
+
+    Written here rather than taken from the module, so that a test of where
+    the pixels land is not asking the code under test where they land.
+    """
+    import math
+
+    n = 2.0 ** zoom
+
+    def lat_of(row):
+        return math.degrees(math.atan(math.sinh(math.pi * (1 - 2 * row / n))))
+
+    return (lat_of(y + 1), x / n * 360.0 - 180.0,      # south, west
+            lat_of(y), (x + 1) / n * 360.0 - 180.0)    # north, east
+
+
+def test_the_map_is_inverted_so_that_ink_shows_on_a_dark_picture():
+    """A printed map is dark ink on white paper; this picture is the other
+    way round, so the dark parts of a tile are the bright parts here."""
+    south, west, north, east = tile_bounds(9, 81, 178)
+    levels = bm.ground_under(south, west, north, east, 64, 64, shades=32,
+                             fetch=gradient_tile, zoom=9, pause=0)
+    # The tile is black at the top and white at the bottom, so the picture
+    # has to be bright at the top and dark at the bottom.
+    assert levels[0].mean() > levels[-1].mean()
+    assert levels[0].mean() > 25 and levels[-1].mean() < 6
+
+
+def test_north_is_at_the_top():
+    def half_and_half(z, x, y, **kw):
+        px = np.zeros((bm.TILE_PIXELS, bm.TILE_PIXELS, 3), dtype=np.uint8)
+        px[:bm.TILE_PIXELS // 2] = 255            # white in the north
+        return make_png(px)
+
+    south, west, north, east = tile_bounds(9, 81, 178)
+    levels = bm.ground_under(south, west, north, east, 40, 40, shades=32,
+                             fetch=half_and_half, zoom=9, pause=0)
+    assert levels[0].mean() < levels[-1].mean()   # white inverts to dark
+
+
+def test_east_is_to_the_right():
+    def half_and_half(z, x, y, **kw):
+        px = np.zeros((bm.TILE_PIXELS, bm.TILE_PIXELS, 3), dtype=np.uint8)
+        px[:, :bm.TILE_PIXELS // 2] = 255         # white in the west
+        return make_png(px)
+
+    south, west, north, east = tile_bounds(9, 81, 178)
+    levels = bm.ground_under(south, west, north, east, 40, 40, shades=32,
+                             fetch=half_and_half, zoom=9, pause=0)
+    assert levels[:, 0].mean() < levels[:, -1].mean()
+
+
+def test_one_tile_covers_its_own_box_exactly():
+    """The reprojection has to put the tile where the tile says it is."""
+    def corner_marks(z, x, y, **kw):
+        px = np.zeros((bm.TILE_PIXELS, bm.TILE_PIXELS, 3), dtype=np.uint8)
+        px[:8, :8] = 255                          # a mark in the north-west
+        return make_png(px)
+
+    south, west, north, east = tile_bounds(9, 81, 178)
+    levels = bm.ground_under(south, west, north, east, 128, 128, shades=32,
+                             fetch=corner_marks, zoom=9, pause=0)
+    dark = levels < levels.max() / 2              # the white corner, inverted
+    assert dark[:4, :4].all()
+    assert not dark[64:, 64:].any()
+
+
+def test_no_tiles_means_no_ground_rather_than_an_exception():
+    def nothing(z, x, y, **kw):
+        return None
+
+    assert bm.ground_under(47.0, -122.8, 48.5, -121.0, 50, 50,
+                           fetch=nothing, pause=0) is None
+
+
+def test_a_box_that_makes_no_sense_is_refused_quietly():
+    assert bm.ground_under(48.0, -122.0, 47.0, -123.0, 50, 50,
+                           fetch=gradient_tile, pause=0) is None
+
+
+# ---------------------------------------------------------------------------
+# Fetching once, and saying who it came from
+# ---------------------------------------------------------------------------
+
+def test_a_tile_is_fetched_once_and_then_read_from_the_disk(tmp_path,
+                                                            monkeypatch):
+    calls = []
+
+    class _Answer:
+        def __init__(self, body):
+            self.body = body
+
+        def read(self, *a):
+            return self.body
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc):
+            return False
+
+    def fake_urlopen(request, timeout=None):
+        calls.append(request.full_url)
+        assert "bandsaunter" in request.headers.get("User-agent", ""), \
+            "a tile server is told who is asking"
+        return _Answer(solid(120))
+
+    monkeypatch.setattr(bm.urllib.request, "urlopen", fake_urlopen)
+    first = bm.fetch_tile(9, 81, 178, cache=tmp_path)
+    second = bm.fetch_tile(9, 81, 178, cache=tmp_path)
+    assert first == second
+    assert len(calls) == 1, "the second one came off the disk"
+    assert (tmp_path / "9" / "81" / "178.png").is_file()
+
+
+def test_a_tile_server_that_is_not_there_is_not_an_error(tmp_path, monkeypatch):
+    def refuse(request, timeout=None):
+        raise OSError("no route to host")
+
+    monkeypatch.setattr(bm.urllib.request, "urlopen", refuse)
+    assert bm.fetch_tile(9, 81, 178, cache=tmp_path) is None
+
+
+def test_the_tile_server_can_be_pointed_somewhere_else(tmp_path, monkeypatch):
+    seen = []
+
+    def fake_urlopen(request, timeout=None):
+        seen.append(request.full_url)
+        raise OSError("stop here")
+
+    monkeypatch.setattr(bm.urllib.request, "urlopen", fake_urlopen)
+    bm.fetch_tile(4, 2, 3, url="https://example.invalid/{z}/{x}/{y}.png",
+                  cache=tmp_path)
+    assert seen == ["https://example.invalid/4/2/3.png"]
+
+
+# ---------------------------------------------------------------------------
+# And under the aircraft
+# ---------------------------------------------------------------------------
+
+def test_the_map_goes_under_the_picture_and_is_credited(tmp_path):
+    out = fm.animate(two_aircraft(), tmp_path / "on-the-map.png", width=400,
+                     ground=True, fetch=gradient_tile)
+    assert out is not None and out.ground
+    assert "on the map" in out.summary()
+    from bandsaunter.images import PNG_SIGNATURE
+    assert out.path.read_bytes()[:8] == PNG_SIGNATURE
+
+
+def test_the_ground_is_drawn_in_its_own_shades():
+    view = fm.fit(two_aircraft(), width=400)
+    levels, credit = fm.ground_for(view, fetch=gradient_tile)
+    assert levels is not None and credit
+    base = fm.background(view, ground=levels, attribution=credit)
+    body = base[view.top:view.top + view.height,
+                view.left:view.left + view.width]
+    ground = (body >= fm.GROUND) & (body < fm.GROUND + fm.GROUND_SHADES)
+    assert ground.mean() > 0.9          # nearly all of the body is map
+
+
+def test_without_it_the_picture_is_the_plain_grid_it_always_was():
+    view = fm.fit(two_aircraft(), width=400)
+    base = fm.background(view)
+    assert not ((base >= fm.GROUND) & (base < fm.GROUND + fm.GROUND_SHADES)).any()
+
+
+def test_no_network_falls_back_to_the_plain_grid(monkeypatch):
+    def nothing(z, x, y, **kw):
+        return None
+
+    view = fm.fit(two_aircraft(), width=400)
+    levels, credit = fm.ground_for(view, fetch=nothing)
+    assert levels is None and credit == ""
+
+
+def test_the_credit_is_written_on_the_picture_itself():
+    """A GIF travels without the readme that would otherwise carry it."""
+    view = fm.fit(two_aircraft(), width=520)
+    levels, credit = fm.ground_for(view, fetch=gradient_tile)
+    base = fm.background(view, ground=levels, attribution=credit)
+    assert _has_text(base, "OPENSTREETMAP")