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/display_manager.py

@@ -36,6 +36,7 @@ from pathlib import Path
 from PIL import Image, ImageDraw, ImageFont
 from src.common.bdf_font import draw_bdf_text, load_bdf_face
 from src.common.font_layout import crisp_size, load_truetype, resolve_asset_path
+from src import scan_order
 from src.display_geometry import (
     DEFAULT_CHAIN_LENGTH, DEFAULT_COLS, DEFAULT_PARALLEL, DEFAULT_ROWS,
     compose_pixel_mapper_config, physical_size, resolve_double_sided,
@@ -44,7 +45,7 @@ from src.matrix_support import MatrixSettingsRefused, library_refusals, refusal_
 from src.pi5_matrix_support import is_raspberry_pi_5
 import threading
 import time
-from collections import OrderedDict
+from collections import OrderedDict, deque
 from typing import Dict, Any, List, Optional, Tuple
 import math
 import zlib
@@ -253,6 +254,7 @@ class DisplayManager:
         
         self._setup_matrix()
         logger.info("Matrix setup completed in %.3f seconds", time.time() - start_time)
+        self._setup_scan_order_compensation()
         
         font_time = time.time()
         self._load_fonts()
@@ -808,7 +810,7 @@ class DisplayManager:
                 if self._double_sided is not None:
                     self.offscreen_canvas.SetImage(self._composite_double_sided())
                 else:
-                    self.offscreen_canvas.SetImage(self.image)
+                    self.offscreen_canvas.SetImage(self._scan_compensated(self.image))
                 blit_done = time.perf_counter()
 
                 # Swap buffers immediately. framerate_fraction holds the frame
@@ -830,6 +832,48 @@ class DisplayManager:
         except Exception as e:
             logger.error(f"Error updating display: {e}")
 
+    def _setup_scan_order_compensation(self) -> None:
+        """Work out which rows to show a refresh behind while scrolling.
+
+        See src/scan_order.py. Only on real hardware: the emulator has no scan
+        order, so there the lag would add the very step it removes elsewhere.
+        """
+        self._scan_lag_bands = None
+        self._scan_history = deque(maxlen=1)
+        if (self.matrix is None or self._double_sided is not None
+                or os.environ.get('EMULATOR', 'false') == 'true'):
+            return
+        display = self.config.get('display') or {}
+        bands = scan_order.scan_lag_bands(
+            display.get('hardware') or {}, self.height,
+            display.get('scan_order_compensation', 'auto'))
+        if not bands:
+            return
+        self._scan_lag_bands = bands
+        self._scan_history = deque(maxlen=max(lag for _, _, lag in bands))
+        logger.info(
+            "Scan-order compensation on: while scrolling, %s",
+            ", ".join(f"rows {top}-{bottom - 1} show {lag} refresh(es) behind"
+                      for top, bottom, lag in bands))
+
+    def _scan_compensated(self, image: Image.Image) -> Image.Image:
+        """The frame to present, with lagging rows taken from earlier frames.
+
+        Only mid-scroll at one frame per refresh: that is when consecutive
+        frames are consecutive refreshes. At a longer hold, or on a static
+        screen, the history is dropped and the frame goes out as it is.
+        """
+        bands = getattr(self, '_scan_lag_bands', None)
+        if not bands:
+            return image
+        if self._frame_hold != 1 or not self.is_currently_scrolling():
+            self._scan_history.clear()
+            return image
+        presented = scan_order.compose(image, self._scan_history, bands)
+        # A copy: plugins draw into the same image object frame after frame.
+        self._scan_history.appendleft(image.copy())
+        return presented
+
     def clear(self):
         """Clear the display completely."""
         try:

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