scrollkit 0.8.3__py3-none-any.whl

scrollkit/display/boards.py

@@ -0,0 +1,186 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Board registry: how ScrollKit builds a panel on each supported board.
+
+ScrollKit runs the *same* app on more than one HUB75 driver board. The boards
+differ in exactly three places — how the RGB matrix is constructed on
+CircuitPython, the default panel geometry, and the calibrated performance profile
+(that last one lives in ``simulator/core/hardware_profile.py``). This module owns
+the first two and the board-detection logic.
+
+This module is imported **on the device** (by ``display/unified.py``), so it must
+stay CircuitPython-safe: no ``dataclasses``, no runtime ``typing``, no
+``os.environ`` (use ``os.getenv``). All hardware imports (``rgbmatrix``,
+``adafruit_matrixportal``, ``board`` …) are **function-local** inside the
+``make_matrix`` builders, which only run on the real board — so the module
+imports cleanly on the desktop and in unit tests with no hardware present.
+
+To add a board, see ``docs/guide/hardware.md`` (the "Adding new hardware" guide).
+"""
+
+import os
+import sys
+
+# Canonical board ids (the keys used everywhere: settings, baselines, profiles).
+MATRIXPORTAL_S3 = "adafruit_matrixportal_s3"
+INTERSTATE75_W = "pimoroni_interstate75_w"
+
+DEFAULT_BOARD_ID = MATRIXPORTAL_S3
+
+
+# --- per-board matrix constructors (run ONLY on CircuitPython hardware) --------
+#
+# Each returns the triple UnifiedDisplay stores: (hardware, display, matrix).
+# Imports are function-local on purpose — see the module docstring.
+
+__all__ = ['BoardSpec', 'BOARDS', 'resolve_board', 'detect_board_id', 'DEFAULT_BOARD_ID', 'MATRIXPORTAL_S3', 'INTERSTATE75_W']
+
+def _make_matrix_s3(spec, width, height, bit_depth):
+    """Adafruit MatrixPortal S3: the adafruit_matrixportal wrapper (unchanged)."""
+    from adafruit_matrixportal.matrix import Matrix
+    m = Matrix(width=width, height=height, bit_depth=bit_depth)
+    return m, m.display, m
+
+
+def _make_matrix_interstate75(spec, width, height, bit_depth):
+    """Pimoroni Interstate 75 / 75 W: direct rgbmatrix + framebufferio.
+
+    Prefers the board's own RGBMatrix convenience aliases
+    (``board.MTX_COMMON`` / ``board.MTX_ADDRESS``) so no GPIO numbers are
+    hard-coded; falls back to the explicit Interstate 75 pin names if a given
+    build doesn't expose them.
+    """
+    import board
+    import rgbmatrix
+    import framebufferio
+
+    common = getattr(board, "MTX_COMMON", None)      # rgb_pins, clock/latch/oe
+    address = getattr(board, "MTX_ADDRESS", None)    # tuple of address pins
+    if common is not None and address is not None:
+        matrix = rgbmatrix.RGBMatrix(
+            width=width, height=height, bit_depth=bit_depth,
+            addr_pins=address[:spec.addr_pin_count], **common)
+    else:
+        matrix = rgbmatrix.RGBMatrix(
+            width=width, height=height, bit_depth=bit_depth,
+            rgb_pins=[board.R0, board.G0, board.B0,
+                      board.R1, board.G1, board.B1],
+            addr_pins=[board.ROW_A, board.ROW_B, board.ROW_C,
+                       board.ROW_D, board.ROW_E][:spec.addr_pin_count],
+            clock_pin=board.CLK, latch_pin=board.LAT,
+            output_enable_pin=board.OE)
+    display = framebufferio.FramebufferDisplay(matrix, auto_refresh=False)
+    return matrix, display, matrix
+
+
+class BoardSpec:
+    """Static description of a supported board.
+
+    Args:
+        board_id: canonical id (the registry key).
+        name: human-readable board name.
+        default_width / default_height: panel geometry used when the app does
+            not pass explicit dimensions.
+        pitch: physical LED pitch in mm (cosmetic; used by the simulator render).
+        addr_pin_count: HUB75 address lines (4 for 64-row panels, 5 for 64-tall).
+        matrix_builder: callable ``(spec, width, height, bit_depth)`` returning
+            ``(hardware, display, matrix)`` — runs only on CircuitPython.
+    """
+
+    def __init__(self, board_id, name, default_width, default_height, pitch,
+                 addr_pin_count, matrix_builder):
+        self.board_id = board_id
+        self.name = name
+        self.default_width = default_width
+        self.default_height = default_height
+        self.pitch = pitch
+        self.addr_pin_count = addr_pin_count
+        self._matrix_builder = matrix_builder
+
+    def make_matrix(self, width, height, bit_depth):
+        """Construct the RGB matrix on hardware (CircuitPython only)."""
+        return self._matrix_builder(self, width, height, bit_depth)
+
+
+BOARDS = {
+    MATRIXPORTAL_S3: BoardSpec(
+        MATRIXPORTAL_S3, "Adafruit MatrixPortal S3 (ESP32-S3)",
+        default_width=64, default_height=32, pitch=3.0, addr_pin_count=4,
+        matrix_builder=_make_matrix_s3),
+    INTERSTATE75_W: BoardSpec(
+        INTERSTATE75_W, "Pimoroni Interstate 75 W (RP2350)",
+        default_width=64, default_height=32, pitch=3.0, addr_pin_count=4,
+        matrix_builder=_make_matrix_interstate75),
+}
+
+
+# Map the on-device ``board.board_id`` (or ``os.uname().machine``) strings to a
+# canonical id. The exact RP2350 "W" id should be confirmed on the real board;
+# the substring fallback in _map_ondevice_id() catches naming variants.
+_ONDEVICE_ID_MAP = {
+    "adafruit_matrixportal_s3": MATRIXPORTAL_S3,
+    "pimoroni_interstate75": INTERSTATE75_W,
+    "pimoroni_interstate75_w": INTERSTATE75_W,
+    "pimoroni_interstate75_rp2350": INTERSTATE75_W,
+    "pimoroni_interstate75_w_rp2350": INTERSTATE75_W,
+}
+
+
+def _read_ondevice_id():
+    """The raw board id string on CircuitPython; ``None`` on desktop."""
+    if not (hasattr(sys, "implementation")
+            and sys.implementation.name == "circuitpython"):
+        return None
+    try:
+        import board
+        bid = getattr(board, "board_id", None)
+        if bid:
+            return bid
+    except Exception:
+        pass
+    try:
+        return os.uname().machine
+    except Exception:
+        return None
+
+
+def _map_ondevice_id(raw):
+    """Resolve a raw on-device id (or any id string) to a canonical board id."""
+    if not raw:
+        return DEFAULT_BOARD_ID
+    key = str(raw).strip().lower()
+    if key in BOARDS:
+        return key
+    if key in _ONDEVICE_ID_MAP:
+        return _ONDEVICE_ID_MAP[key]
+    if "interstate75" in key or "interstate 75" in key:
+        return INTERSTATE75_W
+    if "matrixportal" in key:
+        return MATRIXPORTAL_S3
+    return DEFAULT_BOARD_ID
+
+
+def detect_board_id():
+    """Best-effort canonical board id for the board we're running on.
+
+    On CircuitPython this reads ``board.board_id``; on the desktop there is no
+    board, so it returns the default (MatrixPortal S3).
+    """
+    return _map_ondevice_id(_read_ondevice_id())
+
+
+def resolve_board(board=None):
+    """Return the :class:`BoardSpec` to use.
+
+    Precedence: an explicit ``board`` argument, then the ``SCROLLKIT_HW_BOARD``
+    environment variable, then auto-detection, then the default board. Accepts a
+    canonical id or a raw on-device id; unknown ids fall back to the default.
+    """
+    chosen = board
+    if not chosen:
+        try:
+            chosen = os.getenv("SCROLLKIT_HW_BOARD")
+        except Exception:
+            chosen = None
+    if not chosen:
+        chosen = detect_board_id()
+    return BOARDS.get(_map_ondevice_id(chosen), BOARDS[DEFAULT_BOARD_ID])

scrollkit/display/colors.py

@@ -0,0 +1,176 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Continuous 24-bit colour generators (device-safe, pure-integer math).
+
+These expose the **full** colour space as functions an app or effect samples at any
+resolution — deliberately NOT a catalogue of named palettes. The point is to escape
+fixed mini-palettes (the old 6-colour rainbow ramp, the 16 named colours): generate
+exactly the gradient/spectrum you want, at the resolution that suits the panel.
+
+CircuitPython-safe: integer arithmetic, no ``colorsys``, no typing at runtime. Build a
+ramp ONCE (at effect construction or import) and reuse it — none of these belong in a
+per-frame loop. Every function takes/returns packed ``0xRRGGBB`` ints.
+
+    spectrum(24)                  # 24 smooth hues around the wheel
+    gradient(0x102840, 0x00CCFF, 16)   # 16 steps, deep blue -> cyan
+    multi_gradient((0x330000, 0xFF4400, 0xFFF0A0), 32)  # fire ramp, 32 steps
+    hsv(210, 0.8, 1.0)            # any hue/sat/value -> one colour
+"""
+
+
+__all__ = ['wheel', 'spectrum', 'lerp', 'gradient', 'multi_gradient', 'scale', 'depth_palette', 'hsv']
+
+def _clamp8(v):
+    if v < 0:
+        return 0
+    if v > 255:
+        return 255
+    return v
+
+
+def wheel(pos):
+    """Full-saturation, full-value hue for ``pos`` 0..255 -> ``0xRRGGBB``.
+
+    A continuous colour wheel (red -> green -> blue -> red), cheap integer math so it
+    is safe to call on CircuitPython. Wraps, so ``pos`` may be any int.
+    """
+    pos = pos & 0xFF
+    if pos < 85:
+        return ((255 - pos * 3) << 16) | ((pos * 3) << 8)
+    if pos < 170:
+        pos -= 85
+        return ((255 - pos * 3) << 8) | (pos * 3)
+    pos -= 170
+    return ((pos * 3) << 16) | (255 - pos * 3)
+
+
+def spectrum(n):
+    """``n`` evenly spaced full-saturation hues across the wheel (cyclic-friendly).
+
+    Endpoints don't duplicate (positions are ``i*256//n``), so the ramp tiles/rotates
+    without a visible seam — ideal for a rotating rainbow.
+    """
+    if n <= 0:
+        return ()
+    return tuple(wheel(i * 256 // n) for i in range(n))
+
+
+def lerp(a, b, t):
+    """Blend ``0xRRGGBB`` ``a`` -> ``b`` by ``t`` in 0.0..1.0."""
+    if t <= 0:
+        return a
+    if t >= 1:
+        return b
+    ar = (a >> 16) & 0xFF
+    ag = (a >> 8) & 0xFF
+    ab = a & 0xFF
+    br = (b >> 16) & 0xFF
+    bg = (b >> 8) & 0xFF
+    bb = b & 0xFF
+    r = ar + int((br - ar) * t)
+    g = ag + int((bg - ag) * t)
+    bl = ab + int((bb - ab) * t)
+    return (_clamp8(r) << 16) | (_clamp8(g) << 8) | _clamp8(bl)
+
+
+def gradient(a, b, n):
+    """``n`` colours interpolated from ``a`` to ``b`` (both inclusive)."""
+    if n <= 0:
+        return ()
+    if n == 1:
+        return (a,)
+    return tuple(lerp(a, b, i / (n - 1)) for i in range(n))
+
+
+def multi_gradient(stops, n):
+    """``n`` colours interpolated across a sequence of ``stops`` (>= 1 colour)."""
+    stops = tuple(stops)
+    if not stops or n <= 0:
+        return ()
+    if len(stops) == 1:
+        return tuple(stops[0] for _ in range(n))
+    if n == 1:
+        return (stops[0],)
+    segs = len(stops) - 1
+    out = []
+    for i in range(n):
+        pos = i * segs / (n - 1)        # 0 .. segs
+        si = int(pos)
+        if si >= segs:
+            si = segs - 1
+            t = 1.0
+        else:
+            t = pos - si
+        out.append(lerp(stops[si], stops[si + 1], t))
+    return tuple(out)
+
+
+def scale(color, factor):
+    """Scale a ``0xRRGGBB`` colour's brightness by ``factor`` (0.0-1.0). Integer-only.
+
+    Effects call this once at construction to derive shades from a base colour, so
+    there is no per-frame cost.
+    """
+    if factor <= 0.0:
+        return 0
+    f = 256 if factor >= 1.0 else int(factor * 256)
+    r = (((color >> 16) & 0xFF) * f) >> 8
+    g = (((color >> 8) & 0xFF) * f) >> 8
+    b = ((color & 0xFF) * f) >> 8
+    return (r << 16) | (g << 8) | b
+
+
+def depth_palette(color, strength=0.4, steps=2):
+    """Two (or more) close shades of ``color`` for subtle "lit from above" depth.
+
+    Returns a ramp from ``color`` (the highlight) down to a darker shade
+    ``scale(color, 1 - strength)`` (the shadow). Feed it straight to a gradient
+    text fill::
+
+        ScrollingText("NEXT TRAIN", palette=depth_palette(0x66CCFF))
+
+    This is a colour *transform*, NOT a named palette — it keeps the
+    "expose the full space via generators" philosophy: you pass any base colour
+    and a subtlety knob, and get a tasteful close ramp instead of hand-picking
+    two near-identical hex values.
+
+    Args:
+        color:    Base ``0xRRGGBB`` highlight colour.
+        strength: 0.0..1.0 depth amount; the shadow is ``color`` darkened by this
+                  fraction. ~0.4 is a tasteful default; below ~0.15 the two shades
+                  can collapse to one step on the 4-bit panel.
+        steps:    Length of the returned ramp. 2 returns just ``(highlight,
+                  shadow)`` (the renderer expands it to ``palette_steps``); >2
+                  returns an already-interpolated ramp.
+    """
+    shadow = scale(color, max(0.0, 1.0 - strength))
+    if steps <= 2:
+        return (color, shadow)
+    return gradient(color, shadow, steps)
+
+
+def hsv(h, s=1.0, v=1.0):
+    """HSV -> ``0xRRGGBB``. ``h`` in degrees (0..360, wraps), ``s``/``v`` in 0.0..1.0.
+
+    The general-purpose generator when you want a specific hue at a chosen saturation
+    and value rather than a point on the full-bright :func:`wheel`.
+    """
+    h = h % 360
+    c = v * s
+    x = c * (1 - abs((h / 60.0) % 2 - 1))
+    m = v - c
+    if h < 60:
+        rp, gp, bp = c, x, 0.0
+    elif h < 120:
+        rp, gp, bp = x, c, 0.0
+    elif h < 180:
+        rp, gp, bp = 0.0, c, x
+    elif h < 240:
+        rp, gp, bp = 0.0, x, c
+    elif h < 300:
+        rp, gp, bp = x, 0.0, c
+    else:
+        rp, gp, bp = c, 0.0, x
+    r = _clamp8(int((rp + m) * 255))
+    g = _clamp8(int((gp + m) * 255))
+    b = _clamp8(int((bp + m) * 255))
+    return (r << 16) | (g << 8) | b