From eed7f6b38ec2a30363aa0f9e666117c82750c0ba Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sat, 8 Aug 2026 01:19:04 -0400 Subject: [PATCH] Map: keep the screen and one screen of history, drop the rest The map's decoded-tile dict was never evicted from, so it grew for the life of the screen with every tile the view had ever touched. Measured on the Lyra, a decoded tile is ~0.9 MB resident (62 bytes a point) against a device with ~100 MB in total and, in practice, under 20 MB free -- so a long enough pan was an out-of-memory kill waiting to happen. It predates the caching work, but making tiles cheap to load makes it easier to reach. The budget is relative to the view rather than a fixed number, so it scales itself: twice what the current viewport needs, floored at 8. That lands around 8-12 tiles on the PicoCalc's 53x26 and grows on a desktop terminal, without either one needing to know about the other. Two details worth keeping. Tiles on screen are moved to the end of the order before the trim runs, so eviction starts at the far end and can never take something being drawn. And only entries holding geometry are counted or dropped: a None is the memory of having *asked* -- the tile was absent, or the source never answered -- which costs a dict slot rather than a megabyte, and dropping it would buy nothing back while costing a re-request on the next repaint. Getting this wrong is now cheap, which is what makes a tight budget the right call: an evicted tile comes back from the decoded cache in ~25-50 ms having already been parsed once, so the cache is trading a little memory for instant back-panning, not for correctness. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/ui/map_screen.py | 46 ++++++++++++++++++++++-- tests/test_map.py | 75 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 118 insertions(+), 3 deletions(-) diff --git a/meshterm/ui/map_screen.py b/meshterm/ui/map_screen.py index f05a897..c66b383 100644 --- a/meshterm/ui/map_screen.py +++ b/meshterm/ui/map_screen.py @@ -24,6 +24,7 @@ from __future__ import annotations import asyncio import math +from collections import OrderedDict from typing import TYPE_CHECKING, Callable, Optional from ..core.geo import DEFAULT_VIEW_FRACTION, EARTH_RADIUS_KM, Viewport, clamp_lat @@ -49,6 +50,18 @@ _PAN_DIRS: dict[str, tuple[int, int]] = { #: How far past the tile source's max zoom the display may go (lower tiles are magnified). _OVERZOOM = 2 +#: How many screens' worth of decoded tiles to keep resident, as a multiple of what the +#: current view needs. A decoded tile costs ~0.9 MB on the PicoCalc (62 bytes a point, +#: measured) against a device that has ~100 MB in total, so a map panned far enough would +#: otherwise fill memory with ground the user has left behind. Keeping the screen plus one +#: screen of history costs almost nothing to get wrong: an evicted tile comes back from +#: the decoded cache in ~25-50 ms, having already been parsed once. +_TILE_CACHE_SCREENS = 2 + +#: Floor on that budget, so a zoomed-out view needing one or two tiles still keeps enough +#: history for a pan away and back to be instant. +_MIN_TILE_CACHE = 8 + #: The zoom an Enter-to-frame homes in at when the matches set no extent of their own — a #: single node (or several at one spot) has nothing to frame, so Enter zooms to this #: street-level closeness rather than the fit's neutral default. Capped at the tile @@ -138,7 +151,8 @@ class MapScreen(Screen): # cleaned even before the first pan. self._needs_scrub = True # Decoded tiles keyed by (z, x, y); a stored ``None`` means "fetched, empty/absent". - self._tiles: dict[tuple[int, int, int], Optional[list[Layer]]] = {} + # Decoded tiles, least-recently-shown first — see :meth:`_trim_tiles`. + self._tiles: OrderedDict[tuple[int, int, int], Optional[list[Layer]]] = OrderedDict() self._pending: set[tuple[int, int, int]] = set() # --- rendering ----------------------------------------------------------- @@ -251,9 +265,14 @@ class MapScreen(Screen): def _ensure_tiles(self, vp: Viewport) -> None: """Schedule background fetches for any visible tiles not yet loaded or pending.""" + wanted = vp.tiles(self._max_tile_zoom) + for t in wanted: + if t in self._tiles: + self._tiles.move_to_end(t) # on screen now, so last in line to be dropped + self._trim_tiles(len(wanted)) if not self._source.available: # offline (resolved at open time) — nodes only return - for t in vp.tiles(self._max_tile_zoom): + for t in wanted: if t in self._tiles or t in self._pending: continue self._pending.add(t) @@ -262,6 +281,29 @@ class MapScreen(Screen): except RuntimeError: # pragma: no cover - no running loop (non-interactive) self._pending.discard(t) + def _trim_tiles(self, in_view: int) -> None: + """Release the least recently shown tiles once the view's budget is exceeded. + + Only tiles holding geometry are counted or dropped. An entry whose value is + ``None`` is the memory of having *asked* — the tile was absent, or the source + never answered — and it costs a dict slot rather than a megabyte, so it stays; + dropping it would only buy a pointless re-request on the next repaint. + + Args: + in_view: How many tiles the current viewport needs, which sets the budget. + """ + budget = max(_MIN_TILE_CACHE, in_view * _TILE_CACHE_SCREENS) + loaded = sum(1 for layers in self._tiles.values() if layers) + if loaded <= budget: + return + # Oldest first; everything on screen was just moved to the end, so it is safe. + for key in list(self._tiles): + if loaded <= budget: + break + if self._tiles[key]: + del self._tiles[key] + loaded -= 1 + async def _load(self, t: tuple[int, int, int]) -> None: """Fetch+decode one tile off the event loop, then repaint.""" try: diff --git a/tests/test_map.py b/tests/test_map.py index 8bc32b5..cf77d5b 100644 --- a/tests/test_map.py +++ b/tests/test_map.py @@ -22,7 +22,7 @@ from meshterm.core.models import ( Observation, utcnow, ) -from meshterm.core.mvt import GEOM_LINE, GEOM_POLYGON, decode_tile +from meshterm.core.mvt import GEOM_LINE, GEOM_POLYGON, Layer, decode_tile from meshterm.tools.map import MapTool from meshterm.ui.mapcanvas import MapCanvas, parse_hex @@ -790,6 +790,79 @@ class _StubSource: return None +def _loaded_tile() -> list[Layer]: + """A stand-in for a decoded tile: truthy, which is all the budget cares about.""" + return [Layer(name="water", extent=4096)] + + +def _map_screen_with_tiles(count: int) -> "MapScreen": + """A rendered map screen carrying ``count`` tiles' worth of pan history.""" + 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)], _StubSource(), 14) + screen.render_body(80) + for i in range(count): + screen._tiles[(14, 9000 + i, 9000 + i)] = _loaded_tile() + return screen + + +def _budget(screen) -> int: # noqa: ANN001 - the screen's own arithmetic, mirrored + from meshterm.ui.map_screen import _MIN_TILE_CACHE, _TILE_CACHE_SCREENS + + in_view = len(screen._viewport.tiles(14)) + return max(_MIN_TILE_CACHE, in_view * _TILE_CACHE_SCREENS) + + +def test_map_tile_cache_stays_bounded_while_panning() -> None: + """Panning far doesn't accumulate decoded tiles without limit. + + One decoded tile is ~0.9 MB on the PicoCalc, which has ~100 MB in total, so an + unbounded cache turns a long pan into an out-of-memory kill. + """ + screen = _map_screen_with_tiles(200) + for _ in range(12): + screen.handle("right") + screen.render_body(80) + + held = sum(1 for layers in screen._tiles.values() if layers) + assert held <= _budget(screen), f"{held} decoded tiles held, over budget" + + +def test_map_tile_cache_never_drops_what_is_on_screen() -> None: + """Whatever the view needs survives the trim — eviction starts at the far end.""" + 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)], _StubSource(), 14) + screen.render_body(80) + visible = list(screen._viewport.tiles(14)) + for t in visible: + screen._tiles[t] = _loaded_tile() + for i in range(200): # a long pan's worth of history arriving after them + screen._tiles[(14, 9000 + i, 9000 + i)] = _loaded_tile() + + screen.render_body(80) + + for t in visible: + assert screen._tiles.get(t), f"{t} is on screen and must not have been evicted" + + +def test_map_tile_cache_keeps_the_absent_tile_markers() -> None: + """A ``None`` is the memory of having asked; it costs a slot, so it is never evicted. + + Dropping one would buy nothing back and cost a re-request on the very next repaint. + """ + screen = _map_screen_with_tiles(200) + for i in range(30): + screen._tiles[(14, 100 + i, 100)] = None + + screen.render_body(80) + + absent = [k for k, v in screen._tiles.items() if v is None] + assert len(absent) == 30, "absent-tile markers were evicted along with the geometry" + + class _CapturingSession(_StubSession): """Drives :func:`open_map` headless: captures the pushed screen, renders it once, then replays a canned key sequence — so a test can assert on where the map opened and what