feat(display): compensate for the panel's scan order while scrolling (#634)

A 1:N-scan HUB75 panel lights the two rows either side of its middle at opposite ends of each refresh, so a scroll at one pixel per refresh shows a 1px step across the middle of every panel. While something scrolls at one frame per refresh, DisplayManager now shows the half whose seam row lights first one refresh behind the other (src/scan_order.py), which lines the two up again. Only for layouts whose row order is known; display.scan_order_compensation "off" disables it. Confirmed on hdpi before and after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/scan_order.py

@@ -0,0 +1,130 @@
+"""Compensate for the order an LED panel lights its rows.
+
+A HUB75 panel with 1:N multiplexing lights its rows in pairs: row ``d`` of the
+top half together with row ``d`` of the bottom half, ``d`` running from 0 to
+N-1 across each refresh. So the two rows either side of the middle of a panel
+are lit at opposite ends of every refresh: the last row of one half near the
+end, the first row of the other at the start. When the picture moves, each
+refresh shows it one step further on, and those two neighbouring rows -- lit
+almost a whole refresh apart -- show the text one step apart. On a strip
+scrolling a whole pixel per refresh that is a crisp 1px step across the middle
+of every panel, which the eye and a phone camera both see.
+
+Measured on hdpi (4x128x64 on one chain, rotated 180) on 2026-09-24: switching
+the panel to interlaced scanning made the step vanish, and halving the scroll
+speed halved it, so it is the scan order and not a torn frame. Showing one half
+of the panel a refresh behind the other lines those two rows up again. What is
+left is a uniform lean of about one step per half from top to bottom, which
+reads as nothing at all where the step read as a tear.
+
+Which half lags follows from the geometry. Walking the logical rows top to
+bottom, wherever the next row is lit near the start of a refresh and the one
+above it near the end, the section below must show one more refresh of lag to
+stay continuous with it (and one less where the order jumps the other way).
+Stacked parallel chains are lit simultaneously, so each further half adds one.
+
+Only layouts whose physical row order is known are compensated: plain chains,
+parallel chains, and a 0 or 180 degree rotation. Other pixel mappers
+(U-mapper, 90/270 rotation, ...), special multiplexing and interlaced scan are
+left alone, as is the emulator, which has no scan order to compensate for.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, List, Optional, Sequence, Tuple
+
+from PIL import Image
+
+from src.display_geometry import compose_pixel_mapper_config
+
+#: (first row, last row + 1, refreshes of lag), for bands that lag at all.
+Band = Tuple[int, int, int]
+
+
+def _int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _rotation(hardware: Mapping[str, Any]) -> Optional[int]:
+    """The rotation applied by the pixel mappers, or None if they do anything else."""
+    mappers = [m.strip() for m in compose_pixel_mapper_config(hardware).split(';')
+               if m.strip()]
+    if not mappers:
+        return 0
+    if len(mappers) == 1 and mappers[0].replace(' ', '') in ('Rotate:0', 'Rotate:180'):
+        return int(mappers[0].split(':')[1])
+    return None
+
+
+def scan_lag_bands(hardware: Mapping[str, Any], height: int,
+                   setting: str = "auto") -> Optional[List[Band]]:
+    """Which rows of the logical canvas to show how many refreshes behind.
+
+    Returns None when compensation is off or the layout is not one this
+    understands; see the module docstring.
+    """
+    if str(setting or "auto").lower() == "off":
+        return None
+    rows = _int(hardware.get('rows'), 0)
+    parallel = max(1, _int(hardware.get('parallel'), 1))
+    if rows < 4 or rows % 2:
+        return None
+    if _int(hardware.get('multiplexing'), 0) != 0 or _int(hardware.get('scan_mode'), 0) != 0:
+        return None
+    rotation = _rotation(hardware)
+    if rotation is None:
+        return None
+    physical_height = rows * parallel
+    if physical_height != height:
+        return None   # something remapped the canvas; its row order is unknown
+
+    half = rows // 2
+
+    def phase(y: int) -> int:
+        """When in the refresh logical row y is lit, as a row-pair index."""
+        physical = y if rotation == 0 else physical_height - 1 - y
+        return (physical % rows) % half
+
+    lags = [0]
+    for y in range(1, physical_height):
+        step = phase(y) - phase(y - 1)
+        if step < -half / 2:      # lit near the start after a row lit near the end
+            lags.append(lags[-1] + 1)
+        elif step > half / 2:     # the other way round
+            lags.append(lags[-1] - 1)
+        else:
+            lags.append(lags[-1])
+    low = min(lags)
+    bands: List[Band] = []
+    for y, lag in enumerate(lags):
+        lag -= low
+        if bands and bands[-1][2] == lag and bands[-1][1] == y:
+            bands[-1] = (bands[-1][0], y + 1, lag)
+        else:
+            bands.append((y, y + 1, lag))
+    return [band for band in bands if band[2] > 0] or None
+
+
+def compose(image: Image.Image, history: Sequence[Image.Image],
+            bands: Sequence[Band]) -> Image.Image:
+    """``image`` with each band taken from the frame ``lag`` refreshes back.
+
+    ``history[0]`` is the previous frame. A band whose frame is not available
+    yet (the first frames of a scroll) is left current. Returns ``image`` itself
+    when nothing changes, so the caller pays for a copy only when it must.
+    """
+    out = image
+    for top, bottom, lag in bands:
+        if lag > len(history):
+            continue
+        source = history[lag - 1]
+        if source.size != image.size:
+            continue
+        if out is image:
+            out = image.copy()
+        out.paste(source.crop((0, top, source.width, bottom)), (0, top))
+    return out