Map: draw a rough frame first, so a moved view is never black for long

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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-08-18 23:19:35 -04:00
1 parent d12873694e
commit 8b5c27909b
3 files changed
+262 -29

No files matched your search

+52 -5
View File
@@ -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:
+94 -23
View File
@@ -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.
+116 -1
View File
@@ -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