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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-08-08 01:19:04 -04:00
1 parent 504ee37b9a
commit eed7f6b38e
2 files changed
+118 -3

No files matched your search

+44 -2
View File
@@ -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:
+74 -1
View File
@@ -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