From 98e8e5f260051961b5b4a6fbce746ca6295d0e31 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 18 Aug 2026 23:56:08 -0400 Subject: [PATCH] Map: fetch the ground the next move will want, while nobody is waiting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A tile is 1.4 s off the PicoCalc's Wi-Fi on a good day and a few hundred milliseconds to decode the first time, so ground fetched only once it is looked at arrives after it was wanted. It does not have to: whatever the reader presses next, the ground it reveals comes from the ring of tiles around the ones on screen, or from one of the two neighbouring zooms — the only moves whose tiles are a different set entirely. That is a plan, not a prediction, and what the reader just did orders it. A run of pans in one direction is a heading, and the side of the ring it points at is fetched first; once the run is long enough to be a heading rather than a nudge, the corners flanking it come too, because a diagonal is two keys and readers steer. Then the step out and the step in. Then the rest of the ring, which with no heading at all is the whole of the plan, nearest neighbours before corners. A zoom or a jump home clears the heading: that is looking around, not travelling on. Working in tiles rather than in pan steps matters at the zooms where one keypress uncovers no new tile at all — the plan asks for the ground a move reaches, not the ground one press lands on. The pacing is the load-bearing part, because speculation must never be the thing in the way. One fetch at a time; never while a visible tile is in flight or a raster is running or queued; and not until a second of quiet has passed since the last of that cleared — measured from when the screen went quiet, not from when the view stopped moving, since a frame that took a second to draw has not been looked at for a second. Without that wait a raster landing between two keypresses of a pan reads as a pause, and the tile decode it starts lands in front of the next frame: measured at ~110 ms on the device, which is exactly what this must not cost. What a prefetch leaves behind is a tile in the source's cache, on disk and in its small resident memo. The screen keeps only what it draws. Measured on the device, panning on after a pause, onto ground never fetched (zoom 12, three runs): without: 0/1 tiles ready, view complete after 2297-2324 ms with: 1/1 tiles ready, view complete after 81-112 ms and the pan-after-idle path is unchanged: 621 ms to ground without, 535 with. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/ui/map_screen.py | 208 ++++++++++++++++++++++++++++++++++++++ tests/test_map.py | 158 +++++++++++++++++++++++++++++ 2 files changed, 366 insertions(+) diff --git a/meshterm/ui/map_screen.py b/meshterm/ui/map_screen.py index b6ea08f..19958c3 100644 --- a/meshterm/ui/map_screen.py +++ b/meshterm/ui/map_screen.py @@ -88,6 +88,25 @@ _TILE_CACHE_SCREENS = 2 #: history for a pan away and back to be instant. _MIN_TILE_CACHE = 8 +#: How far ahead of a sustained pan to fetch, in pan steps. Two steps is 60% of the view: +#: enough that ground arrives before it is looked at without reaching for tiles a change of +#: mind would waste. Momentum earns the second step (see :meth:`MapScreen._prefetch_plan`). +_PREFETCH_LEAD = 2 + +#: How many pans in one direction it takes to read as a heading rather than a nudge. +_PREFETCH_MOMENTUM = 2 + +#: How long the view must have held still before the prefetcher starts guessing. A raster +#: finishing between two keypresses of a pan is not a pause — starting a fetch there puts +#: a tile decode in the way of the next frame, which measured ~110 ms on the device. Long +#: enough to tell a pause from a gap, short enough to still be reading time. +_PREFETCH_SETTLE = 1.0 + +#: How many tiles the prefetcher will ask for around one view before it is satisfied. A +#: bound rather than a target: the plan usually runs dry first, and this stops a view at a +#: tile-grid corner from walking the whole neighbourhood. +_PREFETCH_MAX = 12 + #: How long a tile the source gave no answer about is left alone before it is asked for #: again. Long enough that a genuinely offline map isn't retrying every visible tile on a #: loop, short enough that a Wi-Fi blip costs a few seconds of missing streets rather than @@ -213,6 +232,15 @@ class MapScreen(Screen): # Tiles the source gave no answer about, and when each may be asked for again — # a cooldown, not a verdict (see :meth:`_load`). self._unanswered: dict[tuple[int, int, int], float] = {} + # Anticipation (see :meth:`_prefetch_plan`): which way the view has been moving and + # for how many steps, the tiles already speculated on, and the one fetch in flight. + self._heading: Optional[str] = None + self._momentum = 0 + # When the view last stopped changing, and which view that was (monotonic). + self._settled_at = 0.0 + self._settled_view: Optional[Viewport] = None + self._speculated: OrderedDict[tuple[int, int, int], None] = OrderedDict() + self._speculating = False # The last finished ground frame and what it was drawn for — see :meth:`render_body`. # Rasterizing a downtown view is ~0.5-1 s of pure Python (tens of thousands of # vector features), far too slow to sit on a keystroke, so it happens off the paint @@ -593,6 +621,7 @@ class MapScreen(Screen): continue self._pending.add(t) asyncio.ensure_future(self._load(t)) + self._ensure_prefetch(vp) def _expire_cooldowns(self) -> None: """Forget the silences that have served their time, so a long pan can't hoard them.""" @@ -601,6 +630,163 @@ class MapScreen(Screen): now = monotonic() self._unanswered = {t: at for t, at in self._unanswered.items() if at > now} + # --- anticipation --------------------------------------------------------- + + def _ensure_prefetch(self, vp: Viewport) -> None: + """Fetch one tile the next move is likely to need — but only in the quiet. + + A tile is 1.4 s off the PicoCalc's Wi-Fi and a few hundred milliseconds to decode + the first time, so ground that is fetched only once it is looked at arrives after + it was wanted. Fetching it a move early costs nothing the user can feel *provided + it is never the thing in the way*, and that is the whole of the pacing rule here: + the prefetcher runs only when the view it is guessing from is finished *and has + been for a moment* — every visible tile in, no raster running, nothing queued, and + :data:`_PREFETCH_SETTLE` of that since. Those are the seconds the user spends + reading the screen, which are also the seconds before they move; the wait is what + keeps a raster landing between two keypresses of a pan from being mistaken for a + pause, and it is measured from when the screen went quiet rather than from when + the view stopped moving, because a frame that took a second to draw has not been + looked at for a second. + + One fetch at a time, and the finished one asks for the next itself + (:meth:`_prefetch`) rather than waiting for a repaint: chaining through the paint + would cost a 40-80 ms interim frame per tile on the device, to show a picture that + has not changed. + """ + # Still owing the reader something: a tile in flight, a raster running or queued. + busy = bool(self._pending) or self._drawing is not None or self._wanted is not None + if busy or self._settled_view is not vp: + self._settled_view, self._settled_at = vp, monotonic() + if busy or self._speculating or not _loop_running(): + return + if monotonic() - self._settled_at < _PREFETCH_SETTLE: + return # a raster landing between two keypresses of a pan is a gap, not a pause + tile = self._next_speculation(vp) + if tile is None: + return + self._speculating = True + self._remember_speculation(tile) + asyncio.ensure_future(self._prefetch(tile, vp)) + + def _next_speculation(self, vp: Viewport) -> Optional[tuple[int, int, int]]: + """The first tile in :meth:`_prefetch_plan` we have neither got nor guessed at.""" + for tile in self._prefetch_plan(vp): + if tile in self._tiles or tile in self._pending or tile in self._speculated: + continue + return tile + return None + + def _prefetch_plan(self, vp: Viewport) -> list[tuple[int, int, int]]: + """The tiles the next few moves would want, in the order they'd be wanted. + + What the user does next is not a mystery to be modelled. Whatever they press, the + ground it reveals comes from the **ring of tiles around the ones on screen** — + that is what a pan uncovers, in whichever direction — or from one of the two + neighbouring zooms, which are the only moves whose tiles are a different set + entirely. So the plan is that ring and those two views, ordered by what the reader + just did: + + * **Ahead first.** A pan is rarely alone; the view is being carried somewhere. The + side of the ring the heading points at is fetched before any other, and once the + run reads as a heading rather than a nudge + (:data:`_PREFETCH_MOMENTUM`) the corners flanking it come too, because a + diagonal is two keys and readers steer. + * **Then out, then in.** Zooming out is how you find where you are, and it is the + move that shares nothing with the screen: a step out is four times the ground at + a tile zoom never visited. A step in is cheap to ask for and often free to + answer — at or above the source's max zoom it is the same tiles, magnified. + * **Then the rest of the ring**, for a reader who hasn't moved yet or is about to + change their mind. With no heading at all this is the whole of it, nearest + neighbours before corners, which is the right hedge when there is nothing to read. + + Working in tiles rather than in pan steps matters at the zooms where a single step + uncovers no new tile at all: the plan asks for the ground a move *reaches*, not + the ground one keypress lands on. + + Deliberately not here: the nodes a find could jump to. Those are a keystroke away + all over the map, so speculating on them is speculating on everything — and the + jump reframes the view anyway, arriving here as a new view with its own plan. + """ + visible = vp.tiles(self._max_tile_zoom) + if not visible: + return [] + tz = visible[0][0] + span = 2**tz + xs = [x for _, x, _ in visible] + ys = [y for _, _, y in visible] + x0, x1, y0, y1 = min(xs), max(xs), min(ys), max(ys) + seen = set(visible) + + ahead: list[tuple[int, int, int]] = [] + flank: list[tuple[int, int, int]] = [] + hx, hy = _PAN_DIRS.get(self._heading or "", (0, 0)) + corners = self._momentum >= _PREFETCH_MOMENTUM + for ty in range(y0 - 1, y1 + 2): + if not 0 <= ty < span: + continue + for tx in range(x0 - 1, x1 + 2): + tile = (tz, tx % span, ty) # wrap x around the antimeridian, as tiles() does + if tile in seen: + continue + seen.add(tile) + # Which way this tile lies from the block on screen: -1, 0 or +1 per axis. + off_x = -1 if tx < x0 else (1 if tx > x1 else 0) + off_y = -1 if ty < y0 else (1 if ty > y1 else 0) + towards = off_x * hx + off_y * hy + if towards > 0 and (corners or not (off_x and off_y)): + ahead.append(tile) + else: + # No heading: straight neighbours before corners. With one: everything + # that isn't ahead is equally a change of mind, so distance decides. + flank.append(tile) + flank.sort(key=lambda t: abs(t[1] - (x0 + x1) // 2) + abs(t[2] - (y0 + y1) // 2)) + + zooms: list[tuple[int, int, int]] = [] + for view in (vp.zoomed(-1), vp.zoomed(1, max_zoom=self._max_tile_zoom + _OVERZOOM)): + for tile in view.tiles(self._max_tile_zoom): + if tile not in seen: + seen.add(tile) + zooms.append(tile) + # With a heading to follow: ahead, then the zooms, then the change of mind. With + # none: every way a pan could go *first*, because the arrows are how this screen + # is driven and a zoom guessed at ahead of them is a tile the pan then waits for. + plan = ahead + zooms + flank if ahead else flank + zooms + return plan[:_PREFETCH_MAX] + + def _remember_speculation(self, tile: tuple[int, int, int]) -> None: + """Note that we've already guessed at ``tile``, keeping the record bounded. + + Guessed-at, not *held*: what a prefetch leaves behind is a decoded tile in the + source's own cache (on disk, and in its small resident memo), which is the whole + point — the screen keeps only what it is drawing. This is just the note that stops + the plan from asking twice, and it is allowed to forget, since forgetting costs at + worst a cache hit. + """ + self._speculated[tile] = None + self._speculated.move_to_end(tile) + while len(self._speculated) > _PREFETCH_MAX * 4: + self._speculated.popitem(last=False) + + async def _prefetch(self, tile: tuple[int, int, int], vp: Viewport) -> None: + """Warm one tile into the source's cache, then take the next guess. + + The result is thrown away on purpose. A prefetched tile is not this screen's to + hold — :attr:`_tiles` is the view's working set and has a budget sized to it — and + it does not need to be: the fetch has written the tile and its decoded form to + disk and left it in the source's resident memo, so the paint that finally wants it + gets it in tens of milliseconds instead of a second and a half. + + No repaint either way: nothing on screen changed, and the whole point of doing + this early was to not spend the user's time. + """ + try: + await asyncio.to_thread(self._source.load_tile, *tile) + except Exception: # noqa: BLE001 - a guess that didn't pay off is not an error + pass + self._speculating = False + if self._viewport is vp: # still the same view, so the same plan: keep going + self._ensure_prefetch(vp) + def _trim_tiles(self, in_view: int) -> None: """Release the least recently shown tiles once the view's budget is exceeded. @@ -700,21 +886,27 @@ class MapScreen(Screen): # so a raw PgUp with Shift held can only *be* a shifted arrow: fine-pan. self._pan(vp, "up", fine=True) else: + self._reorient() self._viewport = vp.zoomed(1, max_zoom=self._max_tile_zoom + _OVERZOOM) elif action == "pagedown": if modifier_watch.shift_down(): self._pan(vp, "down", fine=True) # Shift+↓ arrives as PgDn — see above else: + self._reorient() self._viewport = vp.zoomed(-1) elif action in ("home", "ctrl_home"): + self._reorient() self._reset_view(vp) elif action == "locate": + self._reorient() self._locate(vp) elif action == "locate_zoom": + self._reorient() self._locate(vp, zoom_in=True) elif action in ("clear_find", "enter"): self._filter = "" elif action in ("frame", "ctrl_enter") and self._filter: + self._reorient() self._frame_matches(vp) elif action == "text" and self.find_enabled: if not data.isspace() or self._filter: # never begin the filter with a space @@ -783,6 +975,16 @@ class MapScreen(Screen): fraction=1.0, ) + def _reorient(self) -> None: + """Forget which way the view was being carried — this move is not a continuation. + + A zoom or a jump home is the reader looking *around* rather than travelling, and + the ground it lands on says nothing about which way they will go from there. The + prefetcher reads the cleared heading as "no reading available" and hedges the four + directions evenly instead of buying ground ahead of a pan that has ended. + """ + self._heading, self._momentum = None, 0 + def _pan(self, vp: Viewport, direction: str, *, fine: bool) -> None: """Pan by one coarse step, or — when ``fine`` — a single character cell. @@ -790,6 +992,12 @@ class MapScreen(Screen): dots expressed as a fraction of the current view. """ dx, dy = _PAN_DIRS[direction] + # Which way the view is being carried, and for how long — what the prefetcher + # reads to tell a heading from a nudge (see :meth:`_prefetch_plan`). A fine step + # is a correction, not a direction, so it holds the heading without extending it. + if not fine: + self._momentum = self._momentum + 1 if direction == self._heading else 1 + self._heading = direction if fine: self._viewport = vp.panned(dx * 2 / vp.dot_w, dy * 4 / vp.dot_h) else: diff --git a/tests/test_map.py b/tests/test_map.py index 9d2e2a4..7d57f19 100644 --- a/tests/test_map.py +++ b/tests/test_map.py @@ -27,6 +27,7 @@ from meshterm.core.models import ( ) from meshterm.core.mvt import GEOM_LINE, GEOM_POLYGON, Layer, decode_tile from meshterm.tools.map import MapTool +from meshterm.ui.map_screen import _PAN_DIRS, _PAN_STEP from meshterm.ui.map_screen import _TILE_RETRY_SECONDS as _TILE_RETRY from meshterm.ui.mapcanvas import MapCanvas, parse_hex @@ -1812,6 +1813,163 @@ def test_map_fetches_before_the_source_has_resolved(monkeypatch) -> None: # noq asyncio.run(drive()) +# --- anticipating the next move ------------------------------------------------------ + + +class _CountingSource(_StubSource): + """A source that answers instantly and remembers everything it was asked for.""" + + available = True + + def __init__(self) -> None: + self.asked: list[tuple[int, int, int]] = [] + + def load_tile(self, z: int, x: int, y: int): + self.asked.append((z, x, y)) + return _loaded_tile() + + +def _settled_map(source, zoom: int = 13): + """A map screen with its own view drawn and every visible tile in hand.""" + from meshterm.ui.map_render import MapMarker + from meshterm.ui.map_screen import MapScreen + + screen = MapScreen( + _StubSession(80, 24), [MapMarker("A", 45.5, -73.6)], source, 14, + saved_view=(45.5, -73.6, zoom), + ) + return screen + + +async def _quiet(screen, source) -> list: + """Paint until the prefetcher runs dry, and report what it went and got. + + Real sleeps, not ``sleep(0)``: both the raster and every tile load go through + ``asyncio.to_thread``, and a thread does not finish on a bare loop turn. + """ + for _ in range(200): + screen.render_body(80) + screen._settled_at = 0.0 # the settle wait has its own test; don't sleep it out + await asyncio.sleep(0.005) + if (not screen._pending and not screen._speculating and screen._drawing is None + and screen._next_speculation(screen._viewport) is None): + break + visible = set(screen._viewport.tiles(14)) + return [t for t in source.asked if t not in visible] + + +def test_map_fetches_ahead_of_the_way_it_is_being_panned() -> None: + """Two steps one way is a heading, and ground is bought in front of it.""" + source = _CountingSource() + screen = _settled_map(source) + + async def drive() -> list: + await _quiet(screen, source) + source.asked.clear() + screen._speculated.clear() + for _ in range(2): # two steps east: a heading, not a nudge + screen.handle("right") + return await _quiet(screen, source) + + ahead = asyncio.run(drive()) + vp = screen._viewport + east = set(vp.panned(_PAN_STEP, 0).tiles(14)) - set(vp.tiles(14)) + west = set(vp.panned(-_PAN_STEP, 0).tiles(14)) - set(vp.tiles(14)) + assert east, "the fixture leaves no tile to the east to fetch" + assert east <= set(ahead), "the ground ahead of the pan was not fetched" + if west & set(ahead): # a hedge is allowed, but it comes after the heading + assert ahead.index(next(iter(east))) < ahead.index(next(iter(west & set(ahead)))) + + +def test_map_fetches_the_step_out_it_has_no_tiles_for() -> None: + """Zooming out is the one move whose tiles were never on screen.""" + source = _CountingSource() + screen = _settled_map(source) + + async def drive() -> list: + return await _quiet(screen, source) + + ahead = asyncio.run(drive()) + out = set(screen._viewport.zoomed(-1).tiles(14)) + assert out <= set(ahead), "the view one step out was not anticipated" + + +def test_map_does_not_fetch_ahead_while_the_view_is_still_arriving() -> None: + """Speculation must never be the thing in the way of the view being looked at.""" + source = _CountingSource() + screen = _settled_map(source) + + async def drive() -> None: + screen.render_body(80) # visible tiles now pending, nothing drawn + assert screen._pending, "the fixture settled too early to test this" + screen._ensure_prefetch(screen._viewport) + assert not screen._speculating, "fetched ahead while the visible tiles were in flight" + + screen._pending.clear() + screen._drawing = ("busy",) + screen._ensure_prefetch(screen._viewport) + assert not screen._speculating, "fetched ahead while the ground was being drawn" + + asyncio.run(drive()) + + +def test_map_waits_for_the_view_to_settle_before_it_guesses() -> None: + """A raster landing between two keypresses of a pan is a gap, not a pause. + + Starting a fetch there puts a tile decode in front of the next frame — measured at + ~110 ms on the device, which is exactly what the prefetcher must never cost. + """ + source = _CountingSource() + screen = _settled_map(source) + + async def drive() -> None: + screen.render_body(80) # builds the viewport + screen._pending.clear() # ...and here it is, arrived and drawn this instant + screen._drawing = screen._wanted = None + + screen._ensure_prefetch(screen._viewport) # stamps the view as newly arrived + assert not screen._speculating, "guessed while the view was still moving" + + screen._settled_at = 0.0 # ...and now it has been still for a while + screen._ensure_prefetch(screen._viewport) + assert screen._speculating, "never got round to guessing at all" + + asyncio.run(drive()) + + +def test_map_forgets_its_heading_when_the_reader_reframes() -> None: + """A zoom or a jump home is looking around, not travelling on.""" + screen = _settled_map(_CountingSource()) + screen.render_body(80) + screen.handle("right") + screen.handle("right") # two coarse steps east + assert screen._heading == "right" and screen._momentum == 2 + + screen.handle("pagedown") # a zoom out + assert screen._heading is None and screen._momentum == 0 + plan = screen._prefetch_plan(screen._viewport) + vp = screen._viewport + for direction, (dx, dy) in _PAN_DIRS.items(): + stepped = set(vp.panned(dx * _PAN_STEP, dy * _PAN_STEP).tiles(14)) + assert stepped - set(vp.tiles(14)) <= set(plan) or not ( + stepped - set(vp.tiles(14)) + ), f"{direction} was not hedged once the heading was gone" + + +def test_map_keeps_no_speculated_tile_of_its_own() -> None: + """A prefetch warms the source's cache; the screen holds only what it draws.""" + source = _CountingSource() + screen = _settled_map(source) + + async def drive() -> None: + await _quiet(screen, source) + + asyncio.run(drive()) + visible = set(screen._viewport.tiles(14)) + assert set(screen._tiles) <= visible, "speculated tiles landed in the view's working set" + assert screen._speculated, "nothing was speculated at all" + + # --- the coarse first pass -----------------------------------------------------------