cm-pixel 0.1.0__py3-none-any.whl

cm_pixel-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: cm-pixel
+Version: 0.1.0
+Summary: Open-source driver for the Cooler Master MasterLiquid Atmos II Pixel LED hexagonal screen
+Author-email: Feiko Wielsma <feiko.w@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/FeikoWielsma/cm-pixel
+Project-URL: Source, https://github.com/FeikoWielsma/cm-pixel
+Project-URL: Issues, https://github.com/FeikoWielsma/cm-pixel/issues
+Keywords: cooler-master,atmos,pixel,led,hid,aio
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hidapi>=0.14
+Requires-Dist: numpy>=1.21
+Requires-Dist: Pillow>=9
+Dynamic: license-file
+
+# cm-pixel
+
+Open-source driver + toolkit for the **Cooler Master MasterLiquid Atmos II Pixel LED**
+hexagonal pixel screen — a clean, lightweight alternative to the official MasterCTRL app
+for controlling the LEDs over USB. **Screen only** (pump/fans are PWM and untouched).
+
+The USB protocol was reverse-engineered from scratch; see [`PROTOCOL.md`](PROTOCOL.md).
+
+## Hardware
+- Cooler Master "Atmos V2 - Pixel", USB `2516:021C`, plain HID (no special driver).
+- 32×32 addressing grid, **556 real LEDs** arranged in a hexagon, RGB888.
+
+## Install
+
+This project uses [uv](https://docs.astral.sh/uv/). From a clone:
+```bash
+uv sync                 # creates .venv and installs everything (incl. uv.lock)
+uv run cm-pixel list    # run the CLI
+```
+Or add it to your own uv project:
+```bash
+uv add cm-pixel
+```
+(Plain pip also works: `pip install cm-pixel`.)
+
+> Close the official MasterCTRL software first — only one program can drive the screen.
+> On Linux you may need a udev rule for HID write access.
+
+## CLI
+```bash
+cm-pixel color 255 0 0           # solid red
+cm-pixel image photo.png         # show an image (auto-fit to the hexagon)
+cm-pixel gif spinner.gif         # play a GIF
+cm-pixel text "HI"               # static centered text
+cm-pixel scroll "HELLO WORLD"    # scrolling marquee
+cm-pixel anim plasma             # procedural animation
+cm-pixel anim fire --speed 1.5
+cm-pixel list                    # list animations
+```
+Common flags: `--fps`, `--duration`, `--mask` (blank pixels outside the hexagon), `--keep`,
+`--brightness 0-100`, `--rotate 0|90|180|270`. Brightness and rotation are applied in software
+(the device has no command for them); 180° is exact, 90/270 clip slightly at the hexagon vertices.
+
+Animations: `plasma rainbow swirl ripple breathe sparkle fire starfield`.
+
+## Library
+```python
+from cmpixel import PixelDisplay, Canvas
+from cmpixel.font import draw_text
+
+with PixelDisplay() as d:
+    c = Canvas().fill((0, 0, 20))
+    c.set_pixel(16, 16, (255, 255, 255))
+    draw_text(c, "GO", color=(0, 255, 0))
+    d.send_canvas(c)
+```
+
+```python
+# play a built-in animation
+from cmpixel import PixelDisplay
+from cmpixel.animations import plasma
+from cmpixel.media import play
+
+with PixelDisplay() as d:
+    play(d, plasma(speed=1.0), fps=30, duration=10)
+```
+
+## How it works (short version)
+A frame is 28 HID output reports of 64 bytes: `80 DD <pkt:u16> + 60 data`, concatenated to
+556×RGB in serpentine LED order. Streaming a frame displays it immediately — no handshake.
+Full details and the LED layout map are in [`PROTOCOL.md`](PROTOCOL.md) and `cmpixel/layout.json`.
+
+## Status
+v0.1 — drawing, text, GIF, procedural animations, software brightness & rotation.
+
+## Disclaimer
+Unofficial, not affiliated with Cooler Master. Use at your own risk; touches only the
+screen framebuffer (no firmware/DFU).

cm_pixel-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+cm_pixel-0.1.0.dist-info/licenses/LICENSE,sha256=QWs4fDn9m68TwZkHsL1hhO4urfdzqfdVnJCZlvgeNb0,1062
+cmpixel/__init__.py,sha256=z9ISz71omFdOr3Fdrc4WDGfKtX4vzVWYp87fmtpOFn8,376
+cmpixel/animations.py,sha256=ma96nIqR-Mieb--tMAhaOdLJ9gFsbRFQZBLkOEWydZA,11019
+cmpixel/canvas.py,sha256=maZCqOvYOvJ2Pht6G7CZ50xhc9EfTwzUKFX-a8Fjsiw,2701
+cmpixel/cli.py,sha256=YxVo1HJ-U2v-uOk62bJYDjDSlnU477QNMIv7B3EUfXc,4036
+cmpixel/device.py,sha256=hgm5bqeTQdiZOdX_jW_YA8l79O-NnosekpLUlX2q6zs,4338
+cmpixel/font.py,sha256=IRAVTZR9lI0UbwmT_X-rkSL96jhuS2w-IeUet8TNh4Y,4799
+cmpixel/layout.json,sha256=HeMw46UeLjlsWjFfAxAGorx7nv9P9IynuEvYD8jkHjQ,4076
+cmpixel/media.py,sha256=o5wSsHVZoQNCzPyGl-WzOmUwQuRCjX0luTSX28-iEuw,1921
+cmpixel/rubik.py,sha256=WgSfMgA83pnzEoHya4f1vkplmFsS-nYW4HEBadSrJMM,6312
+cm_pixel-0.1.0.dist-info/METADATA,sha256=XJgFoPiC_k4KsM2_hjImlPGwLSdSkcAB0UZiJbM4b8E,3624
+cm_pixel-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cm_pixel-0.1.0.dist-info/entry_points.txt,sha256=yPP9C0lOZAY7FUmi17FG0rYYk8k9uGBl_r3-5WsHDys,46
+cm_pixel-0.1.0.dist-info/top_level.txt,sha256=h3O7TuQBhaU7nx9Itox-NWXRBOQXTxKUyO9AXp1LqCU,8
+cm_pixel-0.1.0.dist-info/RECORD,,

cm_pixel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cm_pixel-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cm-pixel = cmpixel.cli:main

cm_pixel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Feiko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cm_pixel-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmpixel

cmpixel/__init__.py

@@ -0,0 +1,11 @@
+"""cmpixel — open-source driver for the Cooler Master Atmos V2 'Pixel' screen."""
+from .device import PixelDisplay, VID, PID, GRID_W, GRID_H, NLED
+from .canvas import Canvas, MASK
+from . import animations, font, media
+
+__version__ = "0.1.0"
+__all__ = [
+    "PixelDisplay", "Canvas", "MASK",
+    "VID", "PID", "GRID_W", "GRID_H", "NLED",
+    "animations", "font", "media",
+]

cmpixel/animations.py

@@ -0,0 +1,337 @@
+"""Procedural animations. Each is a generator yielding (32,32,3) uint8 frames.
+
+All take a `speed` multiplier; most accept extra knobs. They run forever.
+Frames are full-grid; the hexagon mask is applied by the player/device anyway.
+"""
+import numpy as np
+
+from .canvas import GRID_W, GRID_H, MASK
+from .rubik import rubik
+
+_Y, _X = np.mgrid[0:GRID_H, 0:GRID_W].astype(np.float32)
+_CX, _CY = (GRID_W - 1) / 2.0, (GRID_H - 1) / 2.0
+_DX, _DY = _X - _CX, _Y - _CY
+_R = np.sqrt(_DX**2 + _DY**2)
+_ANG = np.arctan2(_DY, _DX)
+
+
+def hsv_to_rgb(h, s, v):
+    """h,s,v in [0,1] arrays -> (H,W,3) uint8."""
+    h = (h % 1.0) * 6.0
+    i = np.floor(h).astype(int)
+    f = h - i
+    p = v * (1 - s)
+    q = v * (1 - f * s)
+    t = v * (1 - (1 - f) * s)
+    i = i % 6
+    r = np.choose(i, [v, q, p, p, t, v])
+    g = np.choose(i, [t, v, v, q, p, p])
+    b = np.choose(i, [p, p, t, v, v, q])
+    return (np.stack([r, g, b], axis=-1).clip(0, 1) * 255).astype(np.uint8)
+
+
+def plasma(speed=1.0):
+    t = 0.0
+    while True:
+        v = (np.sin(_X / 4.0 + t)
+             + np.sin(_Y / 3.0 - t)
+             + np.sin((_X + _Y) / 4.0 + t)
+             + np.sin(_R / 3.0 - t))
+        h = (v + 4) / 8.0
+        yield hsv_to_rgb(h, np.ones_like(h), np.ones_like(h))
+        t += 0.15 * speed
+
+
+def rainbow(speed=1.0, vertical=False):
+    t = 0.0
+    base = _Y if vertical else _X
+    while True:
+        h = base / GRID_W + t
+        yield hsv_to_rgb(h, np.ones_like(h), np.ones_like(h))
+        t += 0.02 * speed
+
+
+def swirl(speed=1.0):
+    t = 0.0
+    while True:
+        h = (_ANG / (2 * np.pi)) + _R / 16.0 + t
+        yield hsv_to_rgb(h, np.ones_like(h), np.ones_like(h))
+        t += 0.05 * speed
+
+
+def ripple(speed=1.0, color=None):
+    t = 0.0
+    while True:
+        wave = (np.sin(_R - t) + 1) / 2.0
+        if color is None:
+            out = hsv_to_rgb((_R / 16.0 - t / 6.0), np.ones_like(wave), wave)
+        else:
+            out = (np.array(color, np.float32) * wave[..., None]).astype(np.uint8)
+        yield out
+        t += 0.3 * speed
+
+
+def breathe(color=(0, 120, 255), speed=1.0):
+    t = 0.0
+    col = np.array(color, np.float32)
+    while True:
+        v = (np.sin(t) + 1) / 2.0
+        frame = np.empty((GRID_H, GRID_W, 3), np.uint8)
+        frame[:] = (col * v).astype(np.uint8)
+        yield frame
+        t += 0.08 * speed
+
+
+def sparkle(color=(255, 255, 255), speed=1.0, fade=0.85, rate=6):
+    buf = np.zeros((GRID_H, GRID_W, 3), np.float32)
+    leds = np.argwhere(MASK)
+    while True:
+        buf *= fade
+        for _ in range(int(rate * speed)):
+            y, x = leds[np.random.randint(len(leds))]
+            buf[y, x] = color
+        yield buf.clip(0, 255).astype(np.uint8)
+
+
+def fire(speed=1.0):
+    heat = np.zeros((GRID_H + 2, GRID_W), np.float32)
+    # fire palette: black -> red -> orange -> yellow -> white
+    stops = np.array([[0, 0, 0], [80, 0, 0], [220, 50, 0],
+                      [255, 160, 0], [255, 255, 120]], np.float32)
+    xp = np.linspace(0, 1, len(stops))
+    grad = np.stack([np.interp(np.linspace(0, 1, 256), xp, stops[:, c]) for c in range(3)], axis=-1)
+    while True:
+        heat[-1] = np.random.rand(GRID_W) * 255  # spark row at bottom
+        # cool + rise
+        nh = (heat[1:] * 0.5 + heat[:-1] * 0.0)
+        rolled = (np.roll(heat, -1, axis=0) * 0.42 + heat * 0.30
+                  + np.roll(heat, (-1, 1), (0, 1)) * 0.14
+                  + np.roll(heat, (-1, -1), (0, 1)) * 0.14)
+        heat[:] = rolled.clip(0, 255)
+        idx = heat[:GRID_H].astype(int).clip(0, 255)
+        yield grad[idx].astype(np.uint8)
+        if speed != 1.0:
+            pass
+
+
+def starfield(speed=1.0, density=0.04):
+    stars = []  # (x, y, z)
+    while True:
+        if np.random.rand() < density * 8:
+            stars.append([np.random.uniform(-_CX, _CX), np.random.uniform(-_CY, _CY), 16.0])
+        frame = np.zeros((GRID_H, GRID_W, 3), np.uint8)
+        alive = []
+        for s in stars:
+            s[2] -= 0.4 * speed
+            if s[2] <= 1:
+                continue
+            px = int(_CX + s[0] * 8 / s[2])
+            py = int(_CY + s[1] * 8 / s[2])
+            if 0 <= px < GRID_W and 0 <= py < GRID_H:
+                b = int(255 * (1 - s[2] / 16))
+                frame[py, px] = (b, b, b)
+                alive.append(s)
+        stars[:] = alive[-200:]
+        yield frame
+
+
+def _solid(hue, sat, val):
+    """hsv_to_rgb for scalar h,s,v -> (3,) float array."""
+    return hsv_to_rgb(np.array([[hue]]), np.array([[sat]]), np.array([[val]]))[0, 0].astype(float)
+
+
+def tunnel(speed=1.0):
+    """Hypnotic radial tunnel rushing inward."""
+    t = 0.0
+    v = 1.0 / (_R + 0.6)
+    u = _ANG / (2 * np.pi)
+    vig = 1 - np.clip(_R / (GRID_W * 0.6), 0, 1)
+    while True:
+        stripes = 0.5 + 0.5 * np.sin(v * 18 - t * 4)
+        hue = (v * 1.5 + u + t * 0.05) % 1.0
+        val = stripes * (0.3 + 0.7 * vig)
+        yield hsv_to_rgb(hue, np.ones_like(hue), val)
+        t += 0.05 * speed
+
+
+def metaballs(speed=1.0, n=4):
+    """Smooth gooey blobs drifting and merging."""
+    t = 0.0
+    ph = np.random.rand(n, 2) * 2 * np.pi
+    while True:
+        field = np.zeros((GRID_H, GRID_W), np.float32)
+        for i in range(n):
+            cx = GRID_W / 2 + GRID_W * 0.34 * np.sin(t * 0.6 + ph[i, 0])
+            cy = GRID_H / 2 + GRID_H * 0.34 * np.cos(t * 0.5 + ph[i, 1])
+            field += 30.0 / ((_X - cx) ** 2 + (_Y - cy) ** 2 + 8)
+        hue = (field * 0.3 + t * 0.05) % 1.0
+        val = np.clip(field * 0.9, 0, 1)
+        yield hsv_to_rgb(hue, np.ones_like(hue), val)
+        t += 0.05 * speed
+
+
+def matrix(speed=1.0, fade=0.78):
+    """Falling green 'digital rain' columns."""
+    buf = np.zeros((GRID_H, GRID_W, 3), np.float32)
+    heads = np.zeros(GRID_W)
+    spd = 0.3 + np.random.rand(GRID_W) * 0.7
+    active = np.random.rand(GRID_W) < 0.4
+    while True:
+        buf *= fade
+        for x in range(GRID_W):
+            if not active[x]:
+                if np.random.rand() < 0.03:
+                    active[x] = True
+                    heads[x] = 0
+                continue
+            y = int(heads[x])
+            if 0 <= y < GRID_H:
+                buf[y, x] = (170, 255, 170)
+            heads[x] += spd[x] * speed
+            if heads[x] > GRID_H + 4:
+                active[x] = False
+        yield buf.clip(0, 255).astype(np.uint8)
+
+
+def fireworks(speed=1.0, gravity=0.05):
+    """Launch bursts that explode and fall."""
+    parts = []
+    buf = np.zeros((GRID_H, GRID_W, 3), np.float32)
+    while True:
+        buf *= 0.82
+        if np.random.rand() < 0.06 * speed or not parts:
+            cx, cy = np.random.uniform(8, 24), np.random.uniform(6, 18)
+            col = _solid(np.random.rand(), 1.0, 1.0)
+            n = np.random.randint(18, 30)
+            for k in range(n):
+                a = 2 * np.pi * k / n
+                sp = np.random.uniform(0.4, 1.2)
+                parts.append([cx, cy, np.cos(a) * sp, np.sin(a) * sp, 1.0, col])
+        alive = []
+        for p in parts:
+            p[0] += p[2] * speed
+            p[1] += p[3] * speed
+            p[3] += gravity * speed
+            p[4] -= 0.02 * speed
+            if p[4] <= 0:
+                continue
+            xi, yi = int(round(p[0])), int(round(p[1]))
+            if 0 <= xi < GRID_W and 0 <= yi < GRID_H:
+                buf[yi, xi] = np.array(p[5]) * p[4]
+            alive.append(p)
+        parts[:] = alive
+        yield buf.clip(0, 255).astype(np.uint8)
+
+
+def aurora(speed=1.0):
+    """Northern-lights curtains, green through purple."""
+    t = 0.0
+    while True:
+        center = GRID_H * 0.5 + 6 * np.sin(_X * 0.3 + t) + 3 * np.sin(_X * 0.7 - t * 1.3)
+        val = np.clip(np.exp(-((_Y - center) ** 2) / 18.0), 0, 1)
+        hue = (0.33 + 0.18 * np.sin(_X * 0.2 + t * 0.5) + _Y * 0.012) % 1.0
+        yield hsv_to_rgb(hue, np.full_like(hue, 0.85), val)
+        t += 0.06 * speed
+
+
+def comet(speed=1.0):
+    """A color-cycling comet orbiting with a fading tail."""
+    buf = np.zeros((GRID_H, GRID_W, 3), np.float32)
+    t = 0.0
+    while True:
+        buf *= 0.80
+        r = GRID_W * 0.32
+        x = GRID_W / 2 + r * np.cos(t)
+        y = GRID_H / 2 + r * np.sin(t)
+        xi, yi = int(round(x)), int(round(y))
+        if 0 <= xi < GRID_W and 0 <= yi < GRID_H:
+            buf[yi, xi] = _solid((t * 0.1) % 1, 1.0, 1.0)
+        yield buf.clip(0, 255).astype(np.uint8)
+        t += 0.15 * speed
+
+
+def pinwheel(speed=1.0, arms=5):
+    """Rotating rainbow pinwheel."""
+    t = 0.0
+    while True:
+        val = 0.5 + 0.5 * np.sin(_ANG * arms + _R * 0.5 - t * 3)
+        hue = (_ANG / (2 * np.pi) + t * 0.1) % 1.0
+        yield hsv_to_rgb(hue, np.ones_like(hue), val ** 1.5)
+        t += 0.05 * speed
+
+
+def bounce(speed=1.0):
+    """A bouncing ball with a motion trail."""
+    buf = np.zeros((GRID_H, GRID_W, 3), np.float32)
+    pos = np.array([16.0, 16.0])
+    vel = np.array([0.7, 0.5])
+    lo, hi = 4, 27
+    t = 0.0
+    while True:
+        buf *= 0.75
+        pos += vel * speed
+        for k in range(2):
+            if pos[k] < lo:
+                pos[k], vel[k] = lo, -vel[k]
+            if pos[k] > hi:
+                pos[k], vel[k] = hi, -vel[k]
+        buf[int(round(pos[1])), int(round(pos[0]))] = _solid((t * 0.02) % 1, 1.0, 1.0)
+        yield buf.clip(0, 255).astype(np.uint8)
+        t += speed
+
+
+def interference(speed=1.0):
+    """Two moving wave sources rippling and interfering."""
+    t = 0.0
+    while True:
+        c1x, c1y = GRID_W / 2 + 10 * np.sin(t * 0.7), GRID_H / 2 + 10 * np.cos(t * 0.5)
+        c2x, c2y = GRID_W / 2 + 10 * np.sin(t * 0.4 + 2), GRID_H / 2 + 10 * np.cos(t * 0.6 + 1)
+        d1 = np.sqrt((_X - c1x) ** 2 + (_Y - c1y) ** 2)
+        d2 = np.sqrt((_X - c2x) ** 2 + (_Y - c2y) ** 2)
+        val = (np.sin(d1 - t * 3) + np.sin(d2 - t * 3)) / 2
+        hue = (val * 0.5 + 0.5 + t * 0.03) % 1.0
+        yield hsv_to_rgb(hue, np.ones_like(hue), val * 0.5 + 0.5)
+        t += 0.05 * speed
+
+
+def twinkle(speed=1.0, n=45):
+    """Colorful stars fading in and out."""
+    leds = np.argwhere(MASK)
+    stars = []
+    while True:
+        if len(stars) < n and np.random.rand() < 0.6:
+            y, x = leds[np.random.randint(len(leds))]
+            stars.append([int(x), int(y), np.random.rand(), 0.0, 0.03 + np.random.rand() * 0.06])
+        frame = np.zeros((GRID_H, GRID_W, 3), np.uint8)
+        alive = []
+        for s in stars:
+            s[3] += s[4] * speed
+            if s[3] >= np.pi:
+                continue
+            frame[s[1], s[0]] = _solid(s[2], 0.6, np.sin(s[3]))
+            alive.append(s)
+        stars[:] = alive
+        yield frame
+
+
+ANIMATIONS = {
+    "plasma": plasma,
+    "rainbow": rainbow,
+    "swirl": swirl,
+    "ripple": ripple,
+    "breathe": breathe,
+    "sparkle": sparkle,
+    "fire": fire,
+    "starfield": starfield,
+    "tunnel": tunnel,
+    "metaballs": metaballs,
+    "matrix": matrix,
+    "fireworks": fireworks,
+    "aurora": aurora,
+    "comet": comet,
+    "pinwheel": pinwheel,
+    "bounce": bounce,
+    "interference": interference,
+    "twinkle": twinkle,
+    "rubik": rubik,
+}

cmpixel/canvas.py

@@ -0,0 +1,86 @@
+"""32x32 RGB canvas with the hexagon LED mask baked in."""
+import json
+import os
+
+import numpy as np
+
+GRID_W = GRID_H = 32
+
+_LAYOUT = json.load(open(os.path.join(os.path.dirname(__file__), "layout.json")))
+# boolean mask: True where a real LED exists
+MASK = np.array(_LAYOUT, dtype=bool).reshape(GRID_H, GRID_W)
+# (y, x) coords of every lit LED, handy for procedural effects
+LED_YX = np.argwhere(MASK)
+
+
+class Canvas:
+    """A (32, 32, 3) uint8 framebuffer. Pixels outside the hexagon are ignored
+    by the device, but `apply_mask()` can zero them for clean previews."""
+
+    def __init__(self, fill=(0, 0, 0)):
+        self.buf = np.zeros((GRID_H, GRID_W, 3), dtype=np.uint8)
+        if any(fill):
+            self.buf[:] = fill
+
+    # --- basics ---
+    def clear(self):
+        self.buf[:] = 0
+        return self
+
+    def fill(self, rgb):
+        self.buf[:] = rgb
+        return self
+
+    def set_pixel(self, x, y, rgb):
+        if 0 <= x < GRID_W and 0 <= y < GRID_H:
+            self.buf[y, x] = rgb
+        return self
+
+    def get_pixel(self, x, y):
+        return tuple(int(c) for c in self.buf[y, x])
+
+    # --- bulk ---
+    @classmethod
+    def from_array(cls, arr):
+        c = cls()
+        a = np.asarray(arr, dtype=np.uint8)
+        c.buf[:] = a[:GRID_H, :GRID_W, :3]
+        return c
+
+    @classmethod
+    def from_image(cls, img, fit="cover"):
+        """img: PIL.Image -> 32x32 Canvas. fit='cover' crops, 'stretch' distorts."""
+        from PIL import Image
+        img = img.convert("RGB")
+        if fit == "cover":
+            w, h = img.size
+            s = max(GRID_W / w, GRID_H / h)
+            img = img.resize((max(1, round(w * s)), max(1, round(h * s))), Image.LANCZOS)
+            w, h = img.size
+            left, top = (w - GRID_W) // 2, (h - GRID_H) // 2
+            img = img.crop((left, top, left + GRID_W, top + GRID_H))
+        else:
+            img = img.resize((GRID_W, GRID_H), Image.LANCZOS)
+        return cls.from_array(np.asarray(img))
+
+    def paste(self, arr, x=0, y=0):
+        """Blit a (h, w, 3) array at (x, y), clipped to the grid."""
+        a = np.asarray(arr, dtype=np.uint8)
+        h, w = a.shape[:2]
+        x0, y0 = max(0, x), max(0, y)
+        x1, y1 = min(GRID_W, x + w), min(GRID_H, y + h)
+        if x1 <= x0 or y1 <= y0:
+            return self
+        self.buf[y0:y1, x0:x1] = a[y0 - y:y1 - y, x0 - x:x1 - x, :3]
+        return self
+
+    def apply_mask(self):
+        self.buf[~MASK] = 0
+        return self
+
+    def to_image(self, scale=12):
+        from PIL import Image
+        im = Image.fromarray(self.buf, "RGB")
+        if scale != 1:
+            im = im.resize((GRID_W * scale, GRID_H * scale), Image.NEAREST)
+        return im

cmpixel/cli.py

@@ -0,0 +1,106 @@
+"""Command-line interface:  cm-pixel <command> ...
+
+Examples:
+  cm-pixel color 255 0 0
+  cm-pixel image photo.png
+  cm-pixel gif spinner.gif
+  cm-pixel text "HI" --color 0 255 0
+  cm-pixel scroll "HELLO WORLD"
+  cm-pixel anim plasma
+  cm-pixel list
+"""
+import argparse
+import itertools
+import sys
+
+from . import PixelDisplay
+from .canvas import Canvas
+from .animations import ANIMATIONS
+from .font import draw_text, scroll_text
+from . import media
+
+
+def _common(p):
+    p.add_argument("--fps", type=float, default=None, help="frames per second")
+    p.add_argument("--duration", type=float, default=None, help="seconds to run, then stop")
+    p.add_argument("--mask", action="store_true", help="zero pixels outside the hexagon")
+    p.add_argument("--keep", action="store_true", help="don't clear the screen on exit")
+    p.add_argument("--brightness", type=int, default=100, help="0-100 (host-side scale)")
+    p.add_argument("--rotate", type=int, choices=[0, 90, 180, 270], default=0, help="rotate degrees")
+
+
+def build_parser():
+    ap = argparse.ArgumentParser(prog="cm-pixel", description="Drive the Atmos V2 Pixel screen.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("list", help="list available animations")
+
+    sp = sub.add_parser("color", help="fill a solid color")
+    sp.add_argument("r", type=int); sp.add_argument("g", type=int); sp.add_argument("b", type=int)
+    _common(sp)
+
+    sp = sub.add_parser("image", help="show an image file")
+    sp.add_argument("path"); sp.add_argument("--fit", choices=["cover", "stretch"], default="cover")
+    _common(sp)
+
+    sp = sub.add_parser("gif", help="play a GIF")
+    sp.add_argument("path"); sp.add_argument("--fit", choices=["cover", "stretch"], default="cover")
+    _common(sp)
+
+    sp = sub.add_parser("text", help="show static text (centered)")
+    sp.add_argument("message"); sp.add_argument("--color", nargs=3, type=int, default=[255, 255, 255])
+    _common(sp)
+
+    sp = sub.add_parser("scroll", help="scroll text right-to-left")
+    sp.add_argument("message"); sp.add_argument("--color", nargs=3, type=int, default=[255, 255, 255])
+    _common(sp)
+
+    sp = sub.add_parser("anim", help="run a procedural animation")
+    sp.add_argument("name", choices=list(ANIMATIONS))
+    sp.add_argument("--speed", type=float, default=1.0)
+    _common(sp)
+
+    return ap
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    if args.cmd == "list":
+        print("animations:", ", ".join(ANIMATIONS))
+        return 0
+
+    with PixelDisplay(brightness=getattr(args, "brightness", 100),
+                      rotation=getattr(args, "rotate", 0)) as d:
+        clear = not getattr(args, "keep", False)
+        mask = getattr(args, "mask", False)
+        dur = getattr(args, "duration", None)
+
+        if args.cmd == "color":
+            c = Canvas().fill((args.r, args.g, args.b))
+            media.play(d, itertools.repeat(c), fps=args.fps or 5, duration=dur, mask=mask, clear_on_exit=clear)
+
+        elif args.cmd == "image":
+            c = media.load_image(args.path, fit=args.fit)
+            media.play(d, itertools.repeat(c), fps=args.fps or 5, duration=dur, mask=mask, clear_on_exit=clear)
+
+        elif args.cmd == "gif":
+            media.play(d, media.iter_gif(args.path, fit=args.fit), fps=args.fps, duration=dur, mask=mask, clear_on_exit=clear)
+
+        elif args.cmd == "text":
+            c = draw_text(Canvas(), args.message, color=tuple(args.color))
+            media.play(d, itertools.repeat(c), fps=args.fps or 5, duration=dur, mask=mask, clear_on_exit=clear)
+
+        elif args.cmd == "scroll":
+            gen = scroll_text(args.message, color=tuple(args.color))
+            media.play(d, gen, fps=args.fps or 15, duration=dur, mask=mask, clear_on_exit=clear)
+
+        elif args.cmd == "anim":
+            gen = ANIMATIONS[args.name](speed=args.speed)
+            media.play(d, gen, fps=args.fps or 30, duration=dur, mask=mask, clear_on_exit=clear)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cmpixel/device.py

@@ -0,0 +1,129 @@
+"""Driver for the Cooler Master Atmos V2 'Pixel' hexagonal LED screen.
+
+Protocol fully documented in PROTOCOL.md. Screen is a 32x32 grid with 556 real
+LEDs in a hexagon; frames are streamed over HID interface 1 as 28 x 64-byte reports.
+"""
+import json
+import os
+import time
+
+import hid
+
+VID = 0x2516
+PID = 0x021C
+FRAME_USAGE_PAGE = 0xFF01   # interface 1 = frame channel
+GRID_W = GRID_H = 32
+NLED = 556
+PACKETS = 28
+PAYLOAD = 60                # data bytes per report
+MAGIC = (0x80, 0xDD)
+
+_LAYOUT = json.load(open(os.path.join(os.path.dirname(__file__), "layout.json")))
+
+
+class PixelDisplay:
+    """Connect to the screen and push 32x32 RGB frames."""
+
+    def __init__(self, layout=_LAYOUT, brightness=100, rotation=0):
+        self.layout = layout
+        self.dev = None
+        self.brightness = brightness   # 0..100, host-side scale (device has no brightness cmd)
+        self.rotation = rotation        # 0/90/180/270, host-side rotate
+        # precompute: led_index(0-based) -> grid cell (for fast image->stream)
+        self.cell_of_led = [0] * NLED
+        for cell, lamp in enumerate(layout):
+            if lamp:
+                self.cell_of_led[lamp - 1] = cell
+
+    # ---- connection ----
+    def open(self):
+        path = None
+        for d in hid.enumerate(VID, PID):
+            if d["usage_page"] == FRAME_USAGE_PAGE:
+                path = d["path"]
+                break
+        if path is None:
+            raise RuntimeError(
+                "Frame interface (usage_page 0xff01) not found. "
+                "Is the cooler connected and the CM software closed?"
+            )
+        self.dev = hid.device()
+        self.dev.open_path(path)
+        return self
+
+    def close(self):
+        if self.dev:
+            self.dev.close()
+            self.dev = None
+
+    def __enter__(self):
+        return self.open()
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ---- frame building ----
+    def _stream_from_grid(self, pixels):
+        """pixels: list of 1024 (r,g,b). Returns 1668-byte LED stream in index order."""
+        buf = bytearray(NLED * 3)
+        for led, cell in enumerate(self.cell_of_led):
+            r, g, b = pixels[cell]
+            o = led * 3
+            buf[o], buf[o + 1], buf[o + 2] = r & 0xFF, g & 0xFF, b & 0xFF
+        return bytes(buf)
+
+    def send_stream(self, led_stream):
+        """led_stream: 1668 bytes (556*RGB) in LED index order -> write 28 reports."""
+        if self.dev is None:
+            raise RuntimeError("not open")
+        data = bytes(led_stream).ljust(PACKETS * PAYLOAD, b"\x00")  # pad to 1680
+        for i in range(PACKETS):
+            chunk = data[i * PAYLOAD:(i + 1) * PAYLOAD]
+            report = bytes([0x00, MAGIC[0], MAGIC[1], (i >> 8) & 0xFF, i & 0xFF]) + chunk
+            self.dev.write(report)
+
+    def send_grid(self, pixels):
+        """pixels: list of 1024 (r,g,b) tuples (row-major, 32 wide)."""
+        self.send_stream(self._stream_from_grid(pixels))
+
+    def send_array(self, arr):
+        """arr: numpy (32, 32, 3) uint8 (row-major). Applies rotation+brightness."""
+        import numpy as np
+        a = np.asarray(arr, dtype=np.uint8)
+        if self.rotation % 360:
+            a = np.rot90(a, k=(self.rotation // 90) % 4)
+        if self.brightness != 100:
+            a = (a.astype(np.uint16) * max(0, min(100, self.brightness)) // 100).astype(np.uint8)
+        stream = a.reshape(-1, 3)[self.cell_of_led]   # (556, 3) in LED index order
+        self.send_stream(stream.tobytes())
+
+    def send_canvas(self, canvas):
+        """canvas: cmpixel.canvas.Canvas"""
+        self.send_array(canvas.buf)
+
+    def send_image(self, img):
+        """img: PIL Image; resized to 32x32 RGB and pushed."""
+        from PIL import Image
+        img = img.convert("RGB").resize((GRID_W, GRID_H), Image.NEAREST)
+        self.send_grid(list(img.getdata()))
+
+    def fill(self, rgb):
+        self.send_grid([tuple(rgb)] * (GRID_W * GRID_H))
+
+
+def main():
+    import sys
+    color = (0, 80, 0)
+    with PixelDisplay() as d:
+        print("connected. filling green; Ctrl+C to stop.")
+        try:
+            while True:
+                d.fill(color)
+                time.sleep(0.1)   # keep streaming ~10fps
+        except KeyboardInterrupt:
+            d.fill((0, 0, 0))
+            print("\ncleared.")
+
+
+if __name__ == "__main__":
+    main()

cmpixel/font.py

@@ -0,0 +1,132 @@
+"""Tiny 5-pixel-tall variable-width bitmap font + text rendering helpers.
+
+Glyphs are written as ASCII art ('#' = on) so they're trivial to read/extend.
+Lowercase falls back to uppercase; unknown chars render as a blank box.
+"""
+import numpy as np
+
+from .canvas import Canvas, GRID_W, GRID_H
+
+FONT_H = 5
+
+_GLYPHS = {
+    " ": ["..", "..", "..", "..", ".."],
+    "0": ["###", "#.#", "#.#", "#.#", "###"],
+    "1": [".#.", "##.", ".#.", ".#.", "###"],
+    "2": ["###", "..#", "###", "#..", "###"],
+    "3": ["###", "..#", ".##", "..#", "###"],
+    "4": ["#.#", "#.#", "###", "..#", "..#"],
+    "5": ["###", "#..", "###", "..#", "###"],
+    "6": ["###", "#..", "###", "#.#", "###"],
+    "7": ["###", "..#", "..#", ".#.", ".#."],
+    "8": ["###", "#.#", "###", "#.#", "###"],
+    "9": ["###", "#.#", "###", "..#", "###"],
+    "A": [".#.", "#.#", "###", "#.#", "#.#"],
+    "B": ["##.", "#.#", "##.", "#.#", "##."],
+    "C": [".##", "#..", "#..", "#..", ".##"],
+    "D": ["##.", "#.#", "#.#", "#.#", "##."],
+    "E": ["###", "#..", "##.", "#..", "###"],
+    "F": ["###", "#..", "##.", "#..", "#.."],
+    "G": [".##", "#..", "#.#", "#.#", ".##"],
+    "H": ["#.#", "#.#", "###", "#.#", "#.#"],
+    "I": ["###", ".#.", ".#.", ".#.", "###"],
+    "J": ["..#", "..#", "..#", "#.#", "##."],
+    "K": ["#..#", "#.#.", "##..", "#.#.", "#..#"],
+    "L": ["#..", "#..", "#..", "#..", "###"],
+    "M": ["#...#", "##.##", "#.#.#", "#...#", "#...#"],
+    "N": ["#..#", "##.#", "#.##", "#..#", "#..#"],
+    "O": [".#.", "#.#", "#.#", "#.#", ".#."],
+    "P": ["##.", "#.#", "##.", "#..", "#.."],
+    "Q": [".#.", "#.#", "#.#", "#.#", ".##"],
+    "R": ["##.", "#.#", "##.", "#.#", "#.#"],
+    "S": [".##", "#..", ".#.", "..#", "##."],
+    "T": ["###", ".#.", ".#.", ".#.", ".#."],
+    "U": ["#.#", "#.#", "#.#", "#.#", "###"],
+    "V": ["#.#", "#.#", "#.#", "#.#", ".#."],
+    "W": ["#...#", "#...#", "#.#.#", "##.##", "#...#"],
+    "X": ["#.#", "#.#", ".#.", "#.#", "#.#"],
+    "Y": ["#.#", "#.#", ".#.", ".#.", ".#."],
+    "Z": ["###", "..#", ".#.", "#..", "###"],
+    ".": [".", ".", ".", ".", "#"],
+    ",": [".", ".", ".", "#", "#"],
+    ":": [".", "#", ".", "#", "."],
+    ";": [".", "#", ".", "#", "#"],
+    "-": ["...", "...", "###", "...", "..."],
+    "_": ["...", "...", "...", "...", "###"],
+    "+": ["...", ".#.", "###", ".#.", "..."],
+    "=": ["...", "###", "...", "###", "..."],
+    "/": ["..#", "..#", ".#.", "#..", "#.."],
+    "\\": ["#..", "#..", ".#.", "..#", "..#"],
+    "!": ["#", "#", "#", ".", "#"],
+    "?": ["###", "..#", ".##", "...", ".#."],
+    "'": ["#", "#", ".", ".", "."],
+    "\"": ["#.#", "#.#", "...", "...", "..."],
+    "(": [".#", "#.", "#.", "#.", ".#"],
+    ")": ["#.", ".#", ".#", ".#", "#."],
+    "*": ["#.#", ".#.", "###", ".#.", "#.#"],
+    "%": ["#.#", "..#", ".#.", "#..", "#.#"],
+    "#": [".#.#.", "#####", ".#.#.", "#####", ".#.#."],
+    "<": ["..#", ".#.", "#..", ".#.", "..#"],
+    ">": ["#..", ".#.", "..#", ".#.", "#.."],
+    "°": ["###", "#.#", "###", "...", "..."],
+    "@": ["###", "#.#", "#.#", "#..", "###"],
+}
+_UNKNOWN = ["###", "#.#", "#.#", "#.#", "###"]
+
+
+def _glyph(ch):
+    return _GLYPHS.get(ch) or _GLYPHS.get(ch.upper()) or _UNKNOWN
+
+
+def text_width(s, spacing=1):
+    if not s:
+        return 0
+    return sum(len(_glyph(c)[0]) for c in s) + spacing * (len(s) - 1)
+
+
+def render_text(s, color=(255, 255, 255), bg=(0, 0, 0), spacing=1):
+    """Return an (5, width, 3) uint8 array of rendered text."""
+    w = max(1, text_width(s, spacing))
+    out = np.zeros((FONT_H, w, 3), dtype=np.uint8)
+    out[:] = bg
+    x = 0
+    for c in s:
+        g = _glyph(c)
+        gw = len(g[0])
+        for row in range(FONT_H):
+            for col in range(gw):
+                if g[row][col] == "#":
+                    out[row, x + col] = color
+        x += gw + spacing
+    return out
+
+
+def draw_text(canvas, s, x=0, y=None, color=(255, 255, 255), spacing=1):
+    """Draw text onto a Canvas. y defaults to vertically centered."""
+    img = render_text(s, color=color, spacing=spacing)
+    if y is None:
+        y = (GRID_H - FONT_H) // 2
+    # paste only the 'on' pixels (transparent bg)
+    h, w = img.shape[:2]
+    for ry in range(h):
+        for rx in range(w):
+            if img[ry, rx].any():
+                canvas.set_pixel(x + rx, y + ry, tuple(int(v) for v in img[ry, rx]))
+    return canvas
+
+
+def scroll_text(s, color=(255, 255, 255), y=None, gap=GRID_W, spacing=1):
+    """Yield Canvas frames scrolling `s` right-to-left. Loops forever."""
+    img = render_text(s, color=color, spacing=spacing)
+    h, w = img.shape[:2]
+    if y is None:
+        y = (GRID_H - FONT_H) // 2
+    total = w + gap
+    pos = GRID_W
+    while True:
+        c = Canvas()
+        c.paste(img, x=pos, y=y)
+        yield c
+        pos -= 1
+        if pos < -w:
+            pos = gap

cmpixel/layout.json

@@ -0,0 +1 @@
+[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10, 9, 8, 7, 6, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 34, 33, 32, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 72, 71, 70, 69, 68, 67, 66, 65, 64, 63, 62, 61, 60, 59, 58, 57, 56, 55, 54, 53, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 0, 0, 0, 0, 0, 0, 0, 122, 121, 120, 119, 118, 117, 116, 115, 114, 113, 112, 111, 110, 109, 108, 107, 106, 105, 104, 103, 102, 101, 100, 99, 98, 97, 0, 0, 0, 0, 0, 0, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 0, 0, 0, 0, 0, 0, 174, 173, 172, 171, 170, 169, 168, 167, 166, 165, 164, 163, 162, 161, 160, 159, 158, 157, 156, 155, 154, 153, 152, 151, 150, 149, 0, 0, 0, 0, 0, 0, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 0, 0, 0, 0, 0, 0, 226, 225, 224, 223, 222, 221, 220, 219, 218, 217, 216, 215, 214, 213, 212, 211, 210, 209, 208, 207, 206, 205, 204, 203, 202, 201, 0, 0, 0, 0, 0, 0, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 0, 0, 0, 0, 0, 0, 278, 277, 276, 275, 274, 273, 272, 271, 270, 269, 268, 267, 266, 265, 264, 263, 262, 261, 260, 259, 258, 257, 256, 255, 254, 253, 0, 0, 0, 0, 0, 0, 279, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 297, 298, 299, 300, 301, 302, 303, 304, 0, 0, 0, 0, 0, 0, 330, 329, 328, 327, 326, 325, 324, 323, 322, 321, 320, 319, 318, 317, 316, 315, 314, 313, 312, 311, 310, 309, 308, 307, 306, 305, 0, 0, 0, 0, 0, 0, 331, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356, 0, 0, 0, 0, 0, 0, 382, 381, 380, 379, 378, 377, 376, 375, 374, 373, 372, 371, 370, 369, 368, 367, 366, 365, 364, 363, 362, 361, 360, 359, 358, 357, 0, 0, 0, 0, 0, 0, 383, 384, 385, 386, 387, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 402, 403, 404, 405, 406, 407, 408, 0, 0, 0, 0, 0, 0, 434, 433, 432, 431, 430, 429, 428, 427, 426, 425, 424, 423, 422, 421, 420, 419, 418, 417, 416, 415, 414, 413, 412, 411, 410, 409, 0, 0, 0, 0, 0, 0, 435, 436, 437, 438, 439, 440, 441, 442, 443, 444, 445, 446, 447, 448, 449, 450, 451, 452, 453, 454, 455, 456, 457, 458, 459, 460, 0, 0, 0, 0, 0, 0, 0, 484, 483, 482, 481, 480, 479, 478, 477, 476, 475, 474, 473, 472, 471, 470, 469, 468, 467, 466, 465, 464, 463, 462, 461, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 485, 486, 487, 488, 489, 490, 491, 492, 493, 494, 495, 496, 497, 498, 499, 500, 501, 502, 503, 504, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 522, 521, 520, 519, 518, 517, 516, 515, 514, 513, 512, 511, 510, 509, 508, 507, 506, 505, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 523, 524, 525, 526, 527, 528, 529, 530, 531, 532, 533, 534, 535, 536, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 546, 545, 544, 543, 542, 541, 540, 539, 538, 537, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 547, 548, 549, 550, 551, 552, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 556, 555, 554, 553, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

cmpixel/media.py

@@ -0,0 +1,61 @@
+"""Image / GIF loading and the frame playback loop."""
+import time
+
+import numpy as np
+
+from .canvas import Canvas, MASK
+
+
+def _to_array(frame):
+    """Accept a Canvas or an ndarray, return (32,32,3) uint8."""
+    if isinstance(frame, Canvas):
+        return frame.buf
+    return np.asarray(frame, dtype=np.uint8)
+
+
+def load_image(path, fit="cover"):
+    from PIL import Image
+    return Canvas.from_image(Image.open(path), fit=fit)
+
+
+def iter_gif(path, fit="cover"):
+    """Yield (32,32,3) frames of a GIF forever, honoring per-frame timing.
+    Yields (array, duration_seconds)."""
+    from PIL import Image, ImageSequence
+    im = Image.open(path)
+    frames = []
+    for fr in ImageSequence.Iterator(im):
+        dur = fr.info.get("duration", 100) / 1000.0
+        frames.append((Canvas.from_image(fr.convert("RGB"), fit=fit).buf.copy(), max(0.02, dur)))
+    while True:
+        for f in frames:
+            yield f
+
+
+def play(device, frames, fps=None, duration=None, mask=False, clear_on_exit=True):
+    """Drive the device from an iterable of frames (Canvas or ndarray).
+
+    frames may yield either `arr` or `(arr, frame_duration)` tuples (GIF).
+    fps overrides per-frame timing. duration = seconds to run (None = forever).
+    """
+    period = (1.0 / fps) if fps else None
+    t_end = (time.monotonic() + duration) if duration else None
+    try:
+        for fr in frames:
+            if isinstance(fr, tuple):
+                arr, dur = fr
+            else:
+                arr, dur = fr, period or 0.066
+            arr = _to_array(arr)
+            if mask:
+                arr = arr.copy()
+                arr[~MASK] = 0
+            device.send_array(arr)
+            time.sleep(period if period is not None else dur)
+            if t_end and time.monotonic() >= t_end:
+                break
+    except KeyboardInterrupt:
+        pass
+    finally:
+        if clear_on_exit:
+            device.fill((0, 0, 0))

cmpixel/rubik.py

@@ -0,0 +1,177 @@
+"""Self-solving isometric Rubik's cube — its hexagonal silhouette fits the panel.
+
+A minimal 3x3 cube model with real layer turns, rendered with an isometric
+projection + painter's algorithm. It scrambles, then solves itself, forever.
+"""
+import numpy as np
+
+from .canvas import GRID_W, GRID_H
+
+# sticker color by the cubie face's outward normal (x, y, z)
+_COLORS = {
+    (1, 0, 0): (0, 210, 40),     # +x green
+    (-1, 0, 0): (0, 90, 255),    # -x blue
+    (0, 1, 0): (245, 245, 245),  # +y white (top)
+    (0, -1, 0): (255, 210, 0),   # -y yellow
+    (0, 0, 1): (235, 0, 0),      # +z red
+    (0, 0, -1): (255, 95, 0),    # -z orange
+}
+_LIGHT = np.array([0.35, 1.0, 0.55])
+_LIGHT /= np.linalg.norm(_LIGHT)
+
+
+def _rot(axis, deg):
+    r = np.radians(deg)
+    c, s = np.cos(r), np.sin(r)
+    if axis == 0:
+        return np.array([[1, 0, 0], [0, c, -s], [0, s, c]])
+    if axis == 1:
+        return np.array([[c, 0, s], [0, 1, 0], [-s, 0, c]])
+    return np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]])
+
+
+# isometric view: corner-on so we see three faces (silhouette = hexagon)
+_VIEW = _rot(0, 35.264) @ _rot(1, 45)
+_SCALE = 5.6
+_CX, _CY = (GRID_W - 1) / 2.0, (GRID_H - 1) / 2.0
+
+
+class _Cube:
+    def __init__(self):
+        self.cubies = []  # each: [pos(int3), [[normal(int3), color], ...]]
+        for x in (-1, 0, 1):
+            for y in (-1, 0, 1):
+                for z in (-1, 0, 1):
+                    if x == y == z == 0:
+                        continue
+                    pos = np.array([x, y, z])
+                    st = []
+                    for ax, n in ((0, x), (1, y), (2, z)):
+                        if n:
+                            nrm = np.zeros(3, int)
+                            nrm[ax] = n
+                            st.append([nrm, _COLORS[tuple(nrm)]])
+                    self.cubies.append([pos, st])
+
+    def turn(self, axis, layer, direction):
+        R = np.rint(_rot(axis, 90 * direction)).astype(int)
+        for cub in self.cubies:
+            if cub[0][axis] == layer:
+                cub[0] = R @ cub[0]
+                for s in cub[1]:
+                    s[0] = R @ s[0]
+
+
+def _basis(normal):
+    """two in-plane unit axes for a face normal."""
+    ax = int(np.argmax(np.abs(normal)))
+    u = np.zeros(3); u[(ax + 1) % 3] = 1
+    v = np.zeros(3); v[(ax + 2) % 3] = 1
+    return u, v
+
+
+def _inside(poly, px, py):
+    sign = 0
+    n = len(poly)
+    for i in range(n):
+        ax, ay = poly[i]
+        bx, by = poly[(i + 1) % n]
+        cross = (bx - ax) * (py - ay) - (by - ay) * (px - ax)
+        if cross != 0:
+            s = 1 if cross > 0 else -1
+            if sign == 0:
+                sign = s
+            elif s != sign:
+                return False
+    return True
+
+
+def _fill(buf, pts, color):
+    xs = [p[0] for p in pts]; ys = [p[1] for p in pts]
+    x0 = max(0, int(np.floor(min(xs)))); x1 = min(GRID_W - 1, int(np.ceil(max(xs))))
+    y0 = max(0, int(np.floor(min(ys)))); y1 = min(GRID_H - 1, int(np.ceil(max(ys))))
+    for yy in range(y0, y1 + 1):
+        for xx in range(x0, x1 + 1):
+            if _inside(pts, xx + 0.5, yy + 0.5):
+                buf[yy, xx] = color
+
+
+def _render(cube, moving_axis=None, moving_layer=None, anim_R=None):
+    buf = np.zeros((GRID_H, GRID_W, 3), np.uint8)
+    quads = []
+    for pos, stickers in cube.cubies:
+        in_layer = moving_axis is not None and pos[moving_axis] == moving_layer
+        for normal, color in stickers:
+            n = normal.astype(float)
+            center = pos.astype(float) + 0.5 * n
+            u, v = _basis(normal)
+            corners = [center + u * 0.5 + v * 0.5, center + u * 0.5 - v * 0.5,
+                       center - u * 0.5 - v * 0.5, center - u * 0.5 + v * 0.5]
+            face_corners = [center + u * 0.42 + v * 0.42, center + u * 0.42 - v * 0.42,
+                            center - u * 0.42 - v * 0.42, center - u * 0.42 + v * 0.42]
+            if in_layer and anim_R is not None:
+                n = anim_R @ n
+                corners = [anim_R @ c for c in corners]
+                face_corners = [anim_R @ c for c in face_corners]
+            nv = _VIEW @ n
+            if nv[2] <= 0.02:           # back-face cull
+                continue
+            shade = 0.45 + 0.55 * max(0.0, float(np.dot(n / np.linalg.norm(n), _LIGHT)))
+            depth = 0.0
+            black_pts, col_pts = [], []
+            for c in corners:
+                cv = _VIEW @ c
+                depth += cv[2]
+                black_pts.append((_CX + cv[0] * _SCALE, _CY - cv[1] * _SCALE))
+            for c in face_corners:
+                cv = _VIEW @ c
+                col_pts.append((_CX + cv[0] * _SCALE, _CY - cv[1] * _SCALE))
+            col = tuple(int(c * shade) for c in color)
+            quads.append((depth, black_pts, col_pts, col))
+    quads.sort(key=lambda q: q[0])     # far first
+    for _, black_pts, col_pts, col in quads:
+        _fill(buf, black_pts, (8, 8, 8))   # black cube frame
+        _fill(buf, col_pts, col)           # colored sticker
+    return buf
+
+
+_AXES = (0, 1, 2)
+
+
+def _scramble(n):
+    moves, last = [], None
+    for _ in range(n):
+        while True:
+            ax = _AXES[np.random.randint(3)]
+            layer = (-1, 1)[np.random.randint(2)]
+            if (ax, layer) != last:
+                break
+        moves.append((ax, layer, (-1, 1)[np.random.randint(2)]))
+        last = (ax, layer)
+    return moves
+
+
+def rubik(speed=1.0, scramble_len=16):
+    """Self-solving isometric Rubik's cube."""
+    cube = _Cube()
+    queue = []          # list of (move, frames_per_move)
+    pause = 0
+    while True:
+        if pause > 0:
+            pause -= 1
+            yield _render(cube)
+            continue
+        if not queue:
+            scr = _scramble(scramble_len)
+            sol = [(a, l, -d) for (a, l, d) in reversed(scr)]
+            queue = [(m, 3) for m in scr] + [(m, 9) for m in sol]
+        move, fpm = queue.pop(0)
+        ax, layer, direction = move
+        steps = max(1, int(round(fpm / max(0.25, speed))))
+        for f in range(1, steps + 1):
+            theta = 90 * direction * f / steps
+            yield _render(cube, ax, layer, _rot(ax, theta))
+        cube.turn(ax, layer, direction)
+        if not queue:                 # just finished solving
+            pause = int(18 / max(0.25, speed))
+            yield _render(cube)