From 8b5c27909bf335c313fdc31ec07979a24a2f5833 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 18 Aug 2026 23:19:35 -0400 Subject: [PATCH] Map: draw a rough frame first, so a moved view is never black for long MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A coarse pan step is 30% of the view, so four keypresses leave nothing of the last frame under the screen — there is no ground to reproject, and the map went black. It then stayed black for a whole raster, which is most of a second on the PicoCalc, and often for two: the raster in flight was being drawn for a view the user had already left, and the one they were actually looking at could not start until it finished. So the raster is two passes now. The first draws the ground fills, the watercourses and the through-roads (tertiary and up, derived from the road styles so the two sets cannot drift) — no buildings, no back streets, no text at all. It is a quarter of the work: 249 ms against 962 at zoom 13 on the device, 120 against 529 at zoom 16. The second draws the finished frame over it. The gap between them is where a moving view gets off. Checking _wanted there cuts the abandonable unit of work from a whole raster to the rough one, so a pan being held is answered with real ground about four times as often and the finished frame is drawn for where the user actually stopped. Measured on the device, four quick pan steps from a settled map to the first ground back on screen: zoom 13: 1984 ms -> 617 ms zoom 15: 970 ms -> 348 ms The rough pass is skipped where a frame for this view is already on screen and merely waiting on a tile: there a coarser picture would take away detail the reader can already see. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/ui/map_render.py | 57 +++++++++++++++++-- meshterm/ui/map_screen.py | 117 ++++++++++++++++++++++++++++++-------- tests/test_map.py | 117 +++++++++++++++++++++++++++++++++++++- 3 files changed, 262 insertions(+), 29 deletions(-) diff --git a/meshterm/ui/map_render.py b/meshterm/ui/map_render.py index d417cb7..f33bc73 100644 --- a/meshterm/ui/map_render.py +++ b/meshterm/ui/map_render.py @@ -158,6 +158,18 @@ DRAWN_LAYERS: frozenset[str] = frozenset( #: memos, where ``None`` is a real answer meaning "a class we deliberately don't draw". _UNRESOLVED = object() +#: Lowest road priority a **coarse** pass draws — see :func:`render_ground`. Tertiary and +#: up: the through-roads whose pattern says *where you are*, against the residential mesh +#: that says only *town*. Derived from :data:`_ROAD_STYLE` rather than listed again, so a +#: reclassified road can't end up in one pass and not the other. +_COARSE_ROAD_PRIORITY = 23 + +#: The road classes a coarse pass keeps. At the PicoCalc's zoom 13 that is 2 522 features +#: of 5 416 — under half the lines for nearly all of the legibility. +_COARSE_ROADS: frozenset[str] = frozenset( + cls for cls, (_, prio) in _ROAD_STYLE.items() if prio >= _COARSE_ROAD_PRIORITY +) + @dataclass(slots=True) class _Label: @@ -181,11 +193,17 @@ class _Label: @dataclass(slots=True) class _Frame: - """Working state while composing one frame.""" + """Working state while composing one frame. + + Attributes: + coarse: Whether this is the quick first pass — ground and through-roads only, + no buildings, no back streets, no text (see :func:`render_ground`). + """ canvas: MapCanvas viewport: Viewport labels: list[_Label] = field(default_factory=list) + coarse: bool = False # -- the stale ground --------------------------------------------------------- @@ -349,14 +367,37 @@ def render_ground( *, max_labels: int = 80, find: str = "", + coarse: bool = False, ) -> tuple[list[str], Ghost]: """Render a frame and keep its ground, for the next moved view to stand on. The same work as :func:`render_map`, plus the :class:`Ghost` the frame leaves behind — which is why the interactive map calls this one for the real (background) raster and :func:`render_map` for the immediate paints in between. + + ``coarse`` draws the **first pass**: the ground fills, the watercourses, the admin + boundaries and the through-roads (:data:`_COARSE_ROADS`) — no buildings, no back + streets, no text at all. It is the same picture at a lower resolution of detail, and + it is a quarter of the work: on the PicoCalc, 249 ms against 962 at zoom 13, 120 ms + against 529 at zoom 16. The map draws one of these before the full frame so a view + that has run past its last ground has *something* true on it within a blink, and so + that a pan being held has a unit of work small enough to abandon (see + :meth:`meshterm.ui.map_screen.MapScreen._draw_ground`). + + Args: + viewport: The view to render. + tiles: Decoded layers keyed by ``(z, x, y)``. + markers: Mesh nodes to overlay. + max_labels: Cap on basemap labels placed. + find: A live node-name filter (see :func:`render_map`). + coarse: Draw the quick first pass rather than the finished frame. + + Returns: + The ANSI lines, and the ground they leave behind. """ - canvas = _compose(viewport, tiles, markers, max_labels=max_labels, find=find) + canvas = _compose( + viewport, tiles, markers, max_labels=max_labels, find=find, coarse=coarse + ) return canvas.to_ansi_lines(), Ghost(canvas.raster(), viewport) @@ -368,10 +409,11 @@ def _compose( max_labels: int = 80, find: str = "", ghost: Optional[Ghost] = None, + coarse: bool = False, ) -> MapCanvas: """Draw one frame onto a fresh canvas — see :func:`render_map` for the arguments.""" canvas = MapCanvas(viewport.dot_w // 2, viewport.dot_h // 4) - frame = _Frame(canvas=canvas, viewport=viewport) + frame = _Frame(canvas=canvas, viewport=viewport, coarse=coarse) if ghost is not None: _paste_ghost(canvas, viewport, ghost) @@ -452,7 +494,7 @@ def _draw_tile(frame: _Frame, layers: list[Layer], z: int, x: int, y: int) -> No # Buildings, as a stippled texture under the streets. building = by_name.get("building") - if building is not None and frame.viewport.zoom >= _BUILDING_MIN_ZOOM: + if building is not None and frame.viewport.zoom >= _BUILDING_MIN_ZOOM and not frame.coarse: rgb = mark_rgb(_BUILDING_FILL[0]) # One tile-local unit is a fixed number of dots, so the visible slab of the tile # is a rectangle in tile coordinates: work out its bounds once and reject each @@ -503,7 +545,7 @@ def _draw_tile(frame: _Frame, layers: list[Layer], z: int, x: int, y: int) -> No for ring in feat.rings: if len(ring) >= 2: vp.draw_line(project(ring, waterway.extent), rgb, prio) - if feat.name: + if feat.name and not frame.coarse: _add_line_label(frame, feat.rings, waterway.extent, z, x, y, feat.name, _WATER_LABEL) # Roads / rail. @@ -521,6 +563,8 @@ def _draw_tile(frame: _Frame, layers: list[Layer], z: int, x: int, y: int) -> No ) style = road_styles[cls] = (mark_rgb(named[0]), named[1]) rgb, prio = style + if frame.coarse and prio < _COARSE_ROAD_PRIORITY: + continue # the back streets are the bulk of the lines and the last to matter for ring in feat.rings: if len(ring) >= 2: vp.draw_line(project(ring, transportation.extent), rgb, prio) @@ -540,6 +584,9 @@ def _draw_tile(frame: _Frame, layers: list[Layer], z: int, x: int, y: int) -> No if len(ring) >= 2: vp.draw_line(project(ring, boundary.extent), boundary_rgb, 14) + if frame.coarse: + return # everything past here is text, and text is what the second pass is for + # Street-name labels (only kick in at high zoom via the label's min_zoom gate). tname = by_name.get("transportation_name") if tname is not None: diff --git a/meshterm/ui/map_screen.py b/meshterm/ui/map_screen.py index 1f5fab3..b6ea08f 100644 --- a/meshterm/ui/map_screen.py +++ b/meshterm/ui/map_screen.py @@ -219,6 +219,8 @@ class MapScreen(Screen): # path and the paint serves whatever is ready. self._frame: Optional[list[str]] = None self._frame_key: Optional[tuple] = None + # Whether that frame is only the coarse first pass, and so still owes its detail. + self._frame_coarse = False # That frame's ground, kept so a view that has moved on can stand on it until its # own is drawn (see :meth:`_ground`). self._ghost: Optional[Ghost] = None @@ -329,7 +331,8 @@ class MapScreen(Screen): immediately, with the best picture available *right now*, and a background task draws the real one and asks for a repaint when it lands: - * **Nothing has changed** — the finished raster is exactly this view: serve it. + * **Nothing has changed** — the raster is exactly this view: serve it (and if it + is only the coarse first pass, ask for the finishing one behind it). * **Only the tiles changed** (a fetch landed, the view did not move) — the previous raster is still correctly aligned, just missing some streets. Keep showing it rather than blanking a good picture to redraw the same ground. @@ -340,21 +343,38 @@ class MapScreen(Screen): keys exactly, and the streets slide with the view — dimmed, and short of the edge you are panning onto — instead of the map blanking to black between every keypress and flashing back when the frame lands (JP, 2026-08-09). + + The last of those is where the map used to go black *and stay black*: four coarse + pan steps are 120% of the screen, so nothing drawn is under the view any more and + there is no ground to reproject. What fixes that is not this method but the one it + schedules — see :meth:`_draw_ground`, which now lands a rough picture in a quarter + of the time rather than nothing at all for a whole raster. """ key = self._ground_key(vp) if self._frame_key == key and self._frame is not None: + if self._frame_coarse: + self._schedule_ground(key, vp) # the first pass is on screen; finish it return list(self._frame) self._schedule_ground(key, vp) - if self._frame is not None and self._frame_key is not None: - # Everything but the tiles (key[1]) has to match: a frame drawn for a different - # marker set is not "the same picture missing streets", it is a picture missing - # a node — the picker's crosshair, say. - if self._frame_key[0] == key[0] and self._frame_key[2:] == key[2:]: - return list(self._frame) # same view, only tiles differ — still aligned + if self._aligned(key) and self._frame is not None: + return list(self._frame) # same view, only tiles differ — still aligned # The view moved (or nothing has ever been drawn): markers over the last ground. return render_map(vp, {}, self._markers, find=self._filter, ghost=self._ghost) + def _aligned(self, key: tuple) -> bool: + """Whether the drawn frame is this view's picture, merely short of some detail. + + Everything but the tiles (``key[1]``) has to match: a frame drawn for a different + marker set is not "the same picture missing streets", it is a picture missing a + node — the picker's crosshair, say. A frame that *is* aligned stays on screen + while the newer one draws, and tells :meth:`_draw_ground` not to bother with a + first pass, since a coarser picture of ground already drawn is a step backwards. + """ + if self._frame is None or self._frame_key is None: + return False + return self._frame_key[0] == key[0] and self._frame_key[2:] == key[2:] + def _schedule_ground(self, key: tuple, vp: Viewport) -> None: """Note that ``key`` wants drawing, and start on it if nothing else is in flight. @@ -373,7 +393,7 @@ class MapScreen(Screen): :meth:`LocationPickScreen.render_body`). Reading it at draw time would find it gone, and the finished basemap would land over the crosshair and erase it. """ - if key == self._drawing or key == self._frame_key: + if key == self._drawing or (key == self._frame_key and not self._frame_coarse): return self._wanted = (key, vp, list(self._markers), self._filter) if self._drawing is None: @@ -391,41 +411,92 @@ class MapScreen(Screen): # responsive *to*, so draw it here and now rather than never. self._drawing = None self._frame, self._ghost = render_ground(vp, tiles, markers, find=find) - self._frame_key = key + self._frame_key, self._frame_coarse = key, False return self._drawing = key - asyncio.ensure_future(self._draw_ground(key, vp, tiles, markers, find)) + preview = not self._aligned(key) + asyncio.ensure_future(self._draw_ground(key, vp, tiles, markers, find, preview)) async def _draw_ground( - self, key: tuple, vp: Viewport, tiles: dict, markers: list[MapMarker], find: str + self, + key: tuple, + vp: Viewport, + tiles: dict, + markers: list[MapMarker], + find: str, + preview: bool, ) -> None: - """Rasterize one view off the event loop, then repaint and take the next request. + """Rasterize one view off the event loop, coarse then finished, repainting at each. The work is pure Python, so a thread does not truly run it in parallel — but the interpreter still switches between threads every few milliseconds, which is the whole point: keystrokes keep being serviced throughout instead of waiting for the frame (measured worst-case delay ~50 ms, against the ~1 s of a blocking draw). + **Two passes, because a whole frame is too big a thing to wait for or to throw + away.** A coarse pass (ground, water, through-roads; see + :func:`~meshterm.ui.map_render.render_ground`) is a quarter of the work — 249 ms + against 962 at zoom 13 on the PicoCalc — and it lands first, so a view that has + run past every scrap of drawn ground shows something true within a blink instead + of sitting black. Then the finished pass replaces it in place. + + The gap between the passes is also where a moving view gets off. A coarse pan step + is 30% of the screen, so four keypresses leave *nothing* of the last frame under + the view and the stand-in has no ground to reproject — and each of those presses + used to have to wait out a full raster being drawn for a view already three steps + stale. Checking :attr:`_wanted` between the passes cuts the unit of abandonable + work to the coarse one, so a pan being held is answered with real ground roughly + four times as often, and the finished frame is drawn for where the user actually + stopped. + Everything the frame is a function of arrives as an argument (see :meth:`_schedule_ground`) — the screen's own state may have moved on by the time the thread runs, and the frame is filed under the key of the scene it was asked for, so it must *be* that scene. + + Args: + key: What the finished frame will be filed under. + vp: The view to draw. + tiles: The decoded tiles it draws from. + markers: The nodes to overlay, snapshotted at request time. + find: The live find filter, likewise. + preview: Whether to draw the coarse pass first. Skipped when an aligned frame + is already on screen (see :meth:`_aligned`): there a coarse picture would + *remove* detail the reader can already see. """ - try: - drawn = await asyncio.to_thread( - render_ground, vp, tiles, markers, find=find - ) - except Exception: # noqa: BLE001 - a frame we couldn't draw is one we draw again - drawn = None + if preview and await self._pass(key, vp, tiles, markers, find, coarse=True): + if self._wanted is not None: + self._drawing = None # the view has moved on; draw where it is now + self._start_ground() + return + await self._pass(key, vp, tiles, markers, find, coarse=False) self._drawing = None - if drawn is not None: - lines, self._ghost = drawn - self._frame, self._frame_key = lines, key - self._needs_scrub = True - self._session.invalidate() if self._wanted is not None: self._start_ground() + async def _pass( + self, + key: tuple, + vp: Viewport, + tiles: dict, + markers: list[MapMarker], + find: str, + *, + coarse: bool, + ) -> bool: + """Draw one pass off the loop and publish it; report whether it landed.""" + try: + drawn = await asyncio.to_thread( + render_ground, vp, tiles, markers, find=find, coarse=coarse + ) + except Exception: # noqa: BLE001 - a frame we couldn't draw is one we draw again + return False + lines, self._ghost = drawn + self._frame, self._frame_key, self._frame_coarse = lines, key, coarse + self._needs_scrub = True + self._session.invalidate() + return True + def _initial_viewport(self, dot_w: int, dot_h: int) -> Viewport: """Restore the saved view (clamped to sane bounds) or frame the nodes' dense core. diff --git a/tests/test_map.py b/tests/test_map.py index cfeef35..9d2e2a4 100644 --- a/tests/test_map.py +++ b/tests/test_map.py @@ -1812,6 +1812,120 @@ def test_map_fetches_before_the_source_has_resolved(monkeypatch) -> None: # noq asyncio.run(drive()) +# --- the coarse first pass ----------------------------------------------------------- + + +def test_coarse_ground_keeps_the_shape_and_drops_the_detail() -> None: + """The quick pass draws water, parks and through-roads — no buildings, no text.""" + from meshterm.ui.map_render import MapMarker, render_ground + + vp = Viewport(45.5019, -73.5674, 15, 160, 96) + tiles = {(14, 4843, 5861): decode_tile(_FIXTURE.read_bytes())} + markers = [MapMarker("Yagi", 45.5019, -73.5674)] + + coarse, _ = render_ground(vp, tiles, markers, coarse=True) + full, _ = render_ground(vp, tiles, markers) + + def ink(lines): + return sum(1 for ch in _plain(lines) if ch.strip()) + + assert ink(coarse), "the coarse pass drew nothing at all" + assert ink(coarse) < ink(full), "the coarse pass drew as much as the full one" + # Our own marker label is overlaid on every paint; the basemap's text is not. + assert "Yagi" in _plain(coarse) + assert not (_street_names(full) & _street_names(coarse)), "text came with the quick pass" + + +def _street_names(lines: list[str]) -> set: + """Words in a frame that are basemap text rather than a node marker's label.""" + return {w for w in re.findall(r"[A-Za-zÀ-ÿ]{4,}", _plain(lines))} - {"Yagi"} + + +def test_map_draws_a_coarse_frame_before_the_finished_one(monkeypatch) -> None: # noqa: ANN001 + """A view with no ground under it must not sit black for a whole raster. + + A coarse pan step is 30% of the screen, so four keypresses leave nothing of the last + frame to reproject — and a full raster is most of a second on the PicoCalc (JP, + 2026-08-18). + """ + from meshterm.ui import map_screen as ms + + passes: list = [] + monkeypatch.setattr( + ms, "render_ground", + lambda vp, tiles, m, **k: (passes.append(k.get("coarse", False)) or (["x"], None)), + ) + screen = _map_over(_StubSource()) + + async def drive() -> None: + screen.render_body(80) # builds the viewport, and asks for its own first draw + while screen._drawing is not None: + await asyncio.sleep(0) + passes.clear() + await screen._draw_ground(("k",), screen._viewport, {}, [], "", True) + + asyncio.run(drive()) + assert passes == [True, False], "the coarse pass did not come first, or at all" + assert screen._frame_coarse is False, "the frame was left owing its detail" + + +def test_map_abandons_the_finished_pass_for_a_view_that_moved(monkeypatch) -> None: # noqa: ANN001 + """Between the passes is where a held key gets off: don't finish a stale frame.""" + from meshterm.ui import map_screen as ms + + screen = _map_over(_StubSource()) + passes: list = [] + + def render(vp, tiles, m, **k): + coarse = k.get("coarse", False) + passes.append(coarse) + if coarse and len(passes) == 1: + # The user pans on while the coarse pass is being drawn. + screen._wanted = (("newer",), screen._viewport, [], "") + return ["x"], None + + monkeypatch.setattr(ms, "render_ground", render) + + async def drive() -> None: + screen.render_body(80) + while screen._drawing is not None: + await asyncio.sleep(0) + passes.clear() + screen._drawing = ("k",) + await screen._draw_ground(("k",), screen._viewport, {}, [], "", True) + + asyncio.run(drive()) + assert False not in passes, "a finished pass was drawn for a view already left behind" + assert screen._frame_coarse is True + + +def test_map_skips_the_coarse_pass_over_a_picture_already_drawn(monkeypatch) -> None: # noqa: ANN001 + """A tile landing must refine the frame, never coarsen it.""" + from meshterm.ui import map_screen as ms + + screen = _map_over(_StubSource()) + coarse_asked: list = [] + monkeypatch.setattr( + ms, "render_ground", + lambda vp, tiles, m, **k: (coarse_asked.append(k.get("coarse", False)) + or (["x"], None)), + ) + + async def drive() -> None: + screen.render_body(80) + while screen._drawing is not None: + await asyncio.sleep(0) + coarse_asked.clear() + # A tile lands: same view, more detail. The frame on screen is still aligned. + screen._tiles[screen._viewport.tiles(14)[0]] = _loaded_tile() + screen.render_body(80) + while screen._drawing is not None: + await asyncio.sleep(0) + + asyncio.run(drive()) + assert coarse_asked == [False], "a drawn frame was replaced by a coarser one" + + # --- the ground raster runs off the paint path --------------------------------------- @@ -1917,7 +2031,8 @@ async def test_map_pans_on_the_ground_its_last_raster_left(monkeypatch) -> None: screen.render_body(80) await screen._draw_ground( - screen._ground_key(screen._viewport), screen._viewport, {}, screen._markers, "" + screen._ground_key(screen._viewport), screen._viewport, {}, screen._markers, "", + False, ) assert screen._ghost is not None, "the finished raster left no ground behind" assert screen._ghost.viewport == screen._viewport