scrollkit 0.8.4__tar.gz → 0.9.0__tar.gz

{scrollkit-0.8.4/src/scrollkit.egg-info → scrollkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrollkit
-Version: 0.8.4
+Version: 0.9.0
 Summary: LED Matrix Display Framework for CircuitPython and Desktop
 Author-email: Michael Czeiszperger <michael@czei.org>
 License: MIT
@@ -57,17 +57,28 @@ Most LED-matrix libraries get you a scrolling "Hello, World" and stop. I built S
 
 ## Installation
 
+For a stable desktop install, use the version published on PyPI. A Git tag such
+as `v0.8.4` is a released PyPI build; `master` is the development branch and can
+contain unreleased work. Pin an exact version in a project that needs reproducible
+builds.
+
 ```bash
-# Desktop development with simulator
+# Stable desktop install with simulator support
 pip install "scrollkit[simulator]"
+# Or pin a tested release: pip install "scrollkit[simulator]==X.Y.Z"
 
-# To modify ScrollKit itself (or run the demos): clone and install editable
+# To contribute, test unreleased work, or run the bundled demos: clone master
+# and install it editable.
 git clone https://github.com/czei/scrollkit.git
 cd scrollkit && pip install -e ".[simulator]"
 
-# CircuitPython — copy scrollkit/ to your device's lib/ alongside your source
+# CircuitPython — deploy a tested copy (or matching .mpy build) of scrollkit/
+# inside your app payload; a device should not track Git master directly.
 ```
 
+The `release-*` branches and the optional `live` OTA branch are deployment
+channels for application payloads, not alternate `pip` installation channels.
+
 ## Quick Start
 
 ```python
@@ -228,7 +239,6 @@ if is_dev_mode():
 | Platform | Backend | Status |
 |---|---|---|
 | Adafruit MatrixPortal S3 | CircuitPython + displayio | ✅ Calibrated from device |
-| Pimoroni Interstate 75 W (RP2350) | CircuitPython + rgbmatrix | ✅ Supported (perf profile uncalibrated) |
 | Desktop (macOS/Linux/Windows) | SLDK Simulator | ✅ |
 | Custom CircuitPython boards | displayio / rgbmatrix | 🔌 Extensible (see [Adding New Hardware](https://scrollkit.dev/guide/hardware/)) |
 

{scrollkit-0.8.4 → scrollkit-0.9.0}/README.md

@@ -13,17 +13,28 @@ Most LED-matrix libraries get you a scrolling "Hello, World" and stop. I built S
 
 ## Installation
 
+For a stable desktop install, use the version published on PyPI. A Git tag such
+as `v0.8.4` is a released PyPI build; `master` is the development branch and can
+contain unreleased work. Pin an exact version in a project that needs reproducible
+builds.
+
 ```bash
-# Desktop development with simulator
+# Stable desktop install with simulator support
 pip install "scrollkit[simulator]"
+# Or pin a tested release: pip install "scrollkit[simulator]==X.Y.Z"
 
-# To modify ScrollKit itself (or run the demos): clone and install editable
+# To contribute, test unreleased work, or run the bundled demos: clone master
+# and install it editable.
 git clone https://github.com/czei/scrollkit.git
 cd scrollkit && pip install -e ".[simulator]"
 
-# CircuitPython — copy scrollkit/ to your device's lib/ alongside your source
+# CircuitPython — deploy a tested copy (or matching .mpy build) of scrollkit/
+# inside your app payload; a device should not track Git master directly.
 ```
 
+The `release-*` branches and the optional `live` OTA branch are deployment
+channels for application payloads, not alternate `pip` installation channels.
+
 ## Quick Start
 
 ```python
@@ -184,7 +195,6 @@ if is_dev_mode():
 | Platform | Backend | Status |
 |---|---|---|
 | Adafruit MatrixPortal S3 | CircuitPython + displayio | ✅ Calibrated from device |
-| Pimoroni Interstate 75 W (RP2350) | CircuitPython + rgbmatrix | ✅ Supported (perf profile uncalibrated) |
 | Desktop (macOS/Linux/Windows) | SLDK Simulator | ✅ |
 | Custom CircuitPython boards | displayio / rgbmatrix | 🔌 Extensible (see [Adding New Hardware](https://scrollkit.dev/guide/hardware/)) |
 
@@ -208,4 +218,4 @@ of his code — but the idea came from his project, and it deserves the shout-ou
 
 ## License
 
-MIT
+MIT

{scrollkit-0.8.4 → scrollkit-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scrollkit"
-version = "0.8.4"
+version = "0.9.0"
 description = "LED Matrix Display Framework for CircuitPython and Desktop"
 readme = "README.md"
 requires-python = ">=3.8"

{scrollkit-0.8.4 → scrollkit-0.9.0}/src/scrollkit/__init__.py

@@ -13,4 +13,4 @@ need from submodules, e.g.::
     from scrollkit.display.unified import UnifiedDisplay
 """
 
-__version__ = "0.8.4"
+__version__ = "0.9.0"

{scrollkit-0.8.4 → scrollkit-0.9.0}/src/scrollkit/dev/capabilities.py

@@ -146,6 +146,17 @@ def _effects():
         out.append({"name": "SwarmReveal", "doc": _first_line(SwarmReveal)})
     except ImportError:
         pass
+    try:
+        from ..effects.palette_partition import PalettePartition
+        out.append({"name": "PalettePartition",
+                    "doc": _first_line(PalettePartition)})
+    except ImportError:
+        pass
+    try:
+        from ..effects.swirl_in import SwirlIn
+        out.append({"name": "SwirlIn", "doc": _first_line(SwirlIn)})
+    except ImportError:
+        pass
     return out
 
 
@@ -228,6 +239,26 @@ def _palette_effects():
     return out
 
 
+def _palette_treatments():
+    """``[{name, doc, partition, feasibility}]`` for the partition dwell
+    treatments (see :mod:`scrollkit.effects.palette_treatments`).
+
+    Frame-driven classes animating a :class:`PalettePartition` purely with
+    palette writes; ``partition`` names the recommended partition builder.
+    Enumerated via the module's explicit ``TREATMENT_CLASSES`` catalog.
+    """
+    out = []
+    try:
+        from ..effects.palette_treatments import TREATMENT_CLASSES
+    except ImportError:
+        return out
+    for cls in TREATMENT_CLASSES:
+        out.append({"name": cls.__name__, "doc": _first_line(cls),
+                    "partition": cls.PARTITION,
+                    "feasibility": getattr(cls, "FEASIBILITY", None)})
+    return out
+
+
 def _named_colors():
     """name -> 0xRRGGBB int, from the tooling color table (deduped)."""
     from ..utils.color_utils import NAMED_COLORS
@@ -322,6 +353,7 @@ def capabilities():
     for key, fn in (("content_types", _content_types), ("priorities", _priorities),
                     ("effects", _effects), ("transitions", _transitions),
                     ("scrolling", _scrolling), ("palette_effects", _palette_effects),
+                    ("palette_treatments", _palette_treatments),
                     ("image_animators", _image_animators),
                     ("text_fills", _text_fills), ("color_utilities", _color_utilities),
                     ("named_colors", _named_colors),

{scrollkit-0.8.4 → scrollkit-0.9.0}/src/scrollkit/display/_graphics.py

@@ -120,6 +120,32 @@ class GraphicsMixin:
                 lg.pop(i)
                 return
 
+    def clear_layers(self):
+        """Strip EVERY persistent layer — the takeover blank.
+
+        ``clear()`` deliberately leaves ``_layer_group`` alone (per-frame label
+        reset must not disturb long-lived effect layers), so a full-screen
+        takeover message needs this instead: without it, an interrupted ride
+        screen's bitmap layers stay composited and the takeover text paints ON
+        TOP of them (the "Updating — DO NOT UNPLUG over the ride list" bug,
+        2026-07-12). Content objects whose layers vanish are unaffected later:
+        ``remove_layer`` is idempotent.
+
+        The bounded painter's canvas lives in ``_layer_group`` too, so its refs
+        are reset here — ``_ensure_paint`` rebuilds a composited canvas on the
+        next ``set_pixel``/``fill_rect`` (stale refs would silently draw into a
+        bitmap no longer in the displayio tree).
+        """
+        lg = getattr(self, "_layer_group", None)
+        if lg is None:
+            return
+        while len(lg):
+            lg.pop()
+        self._paint_bitmap = None
+        self._paint_palette = None
+        self._paint_tile = None
+        self._paint_colors = {}
+
     # --- bounded painters -----------------------------------------------------
     def _ensure_paint(self):
         if self._paint_bitmap is not None:

{scrollkit-0.8.4 → scrollkit-0.9.0}/src/scrollkit/effects/__init__.py

@@ -22,6 +22,14 @@ into RAM. Import each submodule directly instead:
   screen — start/step/detach, not the ``Transition`` contract) —
   ``from scrollkit.effects.image_animators import TwinkleAnimator, MotionAnimator,
   ComboAnimator``
+- **Palette partitions** (indexed layers animated purely by palette writes) —
+  ``from scrollkit.effects.palette_partition import PalettePartition,
+  map_diagonal, map_radial, map_route``
+- **Palette treatments** (dwell animations on a partition — the gallery) —
+  ``from scrollkit.effects.palette_treatments import VelvetSweep, HaloPulse,
+  TREATMENT_CLASSES, treatments_for``
+- **Swirl entrance** (sprites spiral in onto their targets) —
+  ``from scrollkit.effects.swirl_in import SwirlIn``
 - **Text-rendering helpers** —
   ``from scrollkit.effects.text_render import pixels_from_font_text, font_text_width``
 

{scrollkit-0.8.4 → scrollkit-0.9.0}/src/scrollkit/effects/image_animators.py

@@ -579,7 +579,9 @@ class RegionRotateAnimator(IntroAnimator):
                 ci = bitmap[x, y]
                 if ci != 0 and not self._in_excl(x, y):    # body pixels stay put
                     src[(x, y)] = ci
-                    r = math.hypot(x - self._px, y - self._py)
+                    dx = x - self._px
+                    dy = y - self._py
+                    r = math.sqrt(dx * dx + dy * dy)   # math.hypot is absent on CircuitPython
                     if r > maxr:
                         maxr = r
         if not src or len(src) > 320:
@@ -598,16 +600,18 @@ class RegionRotateAnimator(IntroAnimator):
         self._hidden = False
 
     def _stamp(self, ang):
-        bmp = self.bitmap
-        for x, y in self._stamped:               # erase only what we last drew
-            bmp[x, y] = 0
         # forward is dest = R(ang)*(p-pivot)+pivot, so the pre-image of a dest pixel is
         # src = R(-ang)*(dest-pivot)+pivot.  R(-ang) = [[cos, sin], [-sin, cos]].
+        # Compute the whole new pose FIRST (no bitmap writes), then apply it as a
+        # DIFF against the previous pose. The device panel refreshes continuously
+        # from the bitmap, so the old erase-everything-then-slowly-redraw left a
+        # visible "head blinks out" window on every restamp (the desktop simulator
+        # only presents between steps, which is why it never showed there).
         ca = math.cos(ang)
         sa = math.sin(ang)
         px, py = self._px, self._py
         src = self._src
-        stamped = []
+        new = {}
         excl = self._excl
         for Y in range(self._sy0, self._sy1 + 1):
             dY = Y - py
@@ -619,9 +623,15 @@ class RegionRotateAnimator(IntroAnimator):
                 sy = int(round(py - dX * sa + dY * ca))
                 ci = src.get((sx, sy))
                 if ci:
-                    bmp[X, Y] = ci
-                    stamped.append((X, Y))
-        self._stamped = stamped
+                    new[(X, Y)] = ci
+        bmp = self.bitmap
+        for xy in self._stamped:                 # erase only pixels LEAVING the pose
+            if xy not in new:
+                bmp[xy[0], xy[1]] = 0
+        for xy, ci in new.items():               # write only pixels that changed
+            if bmp[xy[0], xy[1]] != ci:
+                bmp[xy[0], xy[1]] = ci
+        self._stamped = list(new)
         self._last_ang = ang
         self._hidden = False
 
@@ -1074,14 +1084,36 @@ class CelWalkAnimator(IntroAnimator):
     HOLD_FRAMES = 104            # a full off-screen-to-off-screen crossing plus several strides
 
     def __init__(self, sheet_suffix="_walk", period=6, bob=0, path="traverse_lr",
-                 tile_w=None, tile_h=None):
+                 tile_w=None, tile_h=None, head_box=None, head_pivot=None,
+                 head_amp_deg=0, head_period=None, head_steps=5):
+        """Create an authored cel walk, optionally with a procedurally nodding head.
+
+        ``head_box`` is an inclusive ``(x0, y0, x1, y1)`` box in each cel and
+        ``head_pivot`` is the fixed neck joint.  When both are supplied with a
+        non-zero ``head_amp_deg``, the head pixels are split from every authored
+        cel and a small set of rotated head poses is baked at :meth:`start`.
+        The walk still costs only tile-index and position writes per displayed
+        frame; the one-time bake avoids rotating pixels on the MatrixPortal.
+
+        The box must include only the head/neck and the transparent space its arc
+        crosses.  The default ``head_period`` is one complete authored gait cycle
+        (``period * number_of_cels``), and ``head_steps`` is the number of baked
+        angles across ``-head_amp_deg`` through ``+head_amp_deg``.
+        """
         self._suffix = sheet_suffix
         self._period = max(1, period)     # display frames per pose (the gait clock)
         self._bob = bob
         self._path = path
         self._tw = tile_w
         self._th = tile_h
+        self._head_box = tuple(head_box) if head_box is not None else None
+        self._head_pivot = tuple(head_pivot) if head_pivot is not None else None
+        self._head_amp = head_amp_deg * 0.017453292519943295
+        self._head_period = head_period
+        steps = max(3, head_steps)
+        self._head_steps = steps if steps & 1 else steps + 1
         self._tile = None
+        self._head_tile = None
         self._odb = None
 
     def _sheet_path(self):
@@ -1108,17 +1140,98 @@ class CelWalkAnimator(IntroAnimator):
         n = sheet.width // tw
         if n < 1:
             raise ValueError("cel_walk: sheet narrower than one tile")
-        gtile = display.gfx.TileGrid(sheet, pixel_shader=pal, tile_width=tw, tile_height=th)
+        head_enabled = self._head_box is not None or self._head_pivot is not None
+        if head_enabled:
+            if self._head_box is None or self._head_pivot is None or not self._head_amp:
+                raise ValueError("cel_walk: head rotation needs box, pivot, and non-zero amplitude")
+            sheet, head_sheet = self._bake_head_poses(display.gfx, self._sheet_path(),
+                                                       n, tw, th, len(pal))
+            gtile = display.gfx.TileGrid(sheet, pixel_shader=pal,
+                                         tile_width=tw, tile_height=th)
+            head_tile = display.gfx.TileGrid(head_sheet, pixel_shader=pal,
+                                              tile_width=tw, tile_height=th)
+        else:
+            gtile = display.gfx.TileGrid(sheet, pixel_shader=pal, tile_width=tw, tile_height=th)
+            head_tile = None
         # Commit: blank the static base sprite, then composite the walking strip above it.
         self._odb = odb
         self._tile = gtile
+        self._head_tile = head_tile
         self._n = n
         self._apply(0)
         bitmap.fill(0)
         display.add_layer(self._tile)
+        if self._head_tile is not None:
+            display.add_layer(self._head_tile)
+
+    def _bake_head_poses(self, gfx, sheet_path, n, tw, th, ncolors):
+        """Return a headless cel sheet plus a sheet of pre-rotated head poses.
+
+        A sheet read from ``OnDiskBitmap`` cannot be inspected or changed on
+        CircuitPython.  Decode it once only when this opt-in feature is used;
+        the base sheet retains the authored body/leg poses while the sparse head
+        sheet supplies ``n * head_steps`` rotated alternatives.
+        """
+        x0, y0, x1, y1 = self._head_box
+        px, py = self._head_pivot
+        if x0 < 0 or y0 < 0 or x1 < x0 or y1 < y0 or x1 >= tw or y1 >= th:
+            raise ValueError("cel_walk: head box outside a cel")
+        if not (0 <= px < tw and 0 <= py < th):
+            raise ValueError("cel_walk: head pivot outside a cel")
+
+        base = read_indexed_bmp(gfx, sheet_path)
+        head_sheet = gfx.Bitmap(tw * n * self._head_steps, th, ncolors)
+        max_radius = 1.0
+        head_pixels = []
+        for pose in range(n):
+            pixels = {}
+            offset = pose * tw
+            for y in range(y0, y1 + 1):
+                for x in range(x0, x1 + 1):
+                    ci = base[offset + x, y]
+                    if ci:
+                        pixels[(x, y)] = ci
+                        base[offset + x, y] = 0
+                        dx, dy = x - px, y - py
+                        radius = math.sqrt(dx * dx + dy * dy)
+                        if radius > max_radius:
+                            max_radius = radius
+            if not pixels:
+                raise ValueError("cel_walk: head box has no pixels in pose %d" % pose)
+            head_pixels.append(pixels)
+
+        margin = int(max_radius * abs(math.sin(self._head_amp))) + 1
+        sx0, sx1 = max(0, x0 - margin), min(tw - 1, x1 + margin)
+        sy0, sy1 = max(0, y0 - margin), min(th - 1, y1 + margin)
+        for pose, pixels in enumerate(head_pixels):
+            for step in range(self._head_steps):
+                # Equally-spaced angles include the upright rest pose because
+                # head_steps is always odd.
+                angle = self._head_amp * ((2.0 * step / (self._head_steps - 1)) - 1.0)
+                ca, sa = math.cos(angle), math.sin(angle)
+                cell_offset = (pose * self._head_steps + step) * tw
+                # Inverse-map the bounded destination rectangle so the rotated
+                # head stays solid instead of developing forward-map holes.
+                for Y in range(sy0, sy1 + 1):
+                    dy = Y - py
+                    for X in range(sx0, sx1 + 1):
+                        dx = X - px
+                        sx = int(round(px + dx * ca + dy * sa))
+                        sy = int(round(py - dx * sa + dy * ca))
+                        ci = pixels.get((sx, sy))
+                        if ci:
+                            head_sheet[cell_offset + X, Y] = ci
+        return base, head_sheet
 
     def _apply(self, frame):
         self._tile[0, 0] = (frame // self._period) % self._n     # gait clock -> which pose
+        head_tile = self._head_tile
+        if head_tile is not None:
+            cycle = self._head_period or (self._period * self._n)
+            amount = (math.sin(6.2832 * frame / float(max(1, cycle))) + 1.0) * 0.5
+            head_step = int(round(amount * (self._head_steps - 1)))
+            pose = (frame // self._period) % self._n
+            head_tile[0, 0] = pose * self._head_steps + head_step
         span = self.HOLD_FRAMES - 1 if self.HOLD_FRAMES > 1 else 1
         t = frame / span
         if t > 1.0:
@@ -1126,13 +1239,23 @@ class CelWalkAnimator(IntroAnimator):
         x0, x1 = ((self._off, -self._off) if self._path == "traverse_rl"
                   else (-self._off, self._off))
         self._tile.x = int(round(x0 + (x1 - x0) * t))
+        if head_tile is not None:
+            head_tile.x = self._tile.x
         if self._bob:
             self._tile.y = int(round(self._bob * math.sin(frame * 0.3)))
+        if head_tile is not None:
+            head_tile.y = self._tile.y
 
     def step(self, frame):
         self._apply(frame)
 
     def detach(self):
+        head = getattr(self, "_head_tile", None)
+        if head is not None and getattr(self, "display", None) is not None:
+            try:
+                self.display.remove_layer(head)
+            except Exception:
+                pass
         t = getattr(self, "_tile", None)
         if t is not None and getattr(self, "display", None) is not None:
             try:
@@ -1143,6 +1266,7 @@ class CelWalkAnimator(IntroAnimator):
         # (CircuitPython has a small open-file limit). No base-restore — the sprite walked off,
         # the base is blank, the fade shows empty sky (matches MotionAnimator traverse).
         self._tile = None
+        self._head_tile = None
         self._odb = None