scrollkit 0.8.3__py3-none-any.whl

scrollkit/effects/particles.py

@@ -0,0 +1,355 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Particle effects for SLDK.
+
+Simple particle systems optimized for ESP32 memory constraints.
+"""
+
+from __future__ import annotations
+
+try:
+    from typing import Any, List, Optional
+except ImportError:  # CircuitPython has no 'typing' module
+    pass
+
+from ..display.colors import multi_gradient
+
+# Default ember fire ramp: a smooth 24-step gradient (deep red -> orange -> yellow ->
+# near-white), built ONCE. Far richer than a handful of fixed primaries; pass your own
+# ``colors`` to recolour the fire (e.g. a blue/green flame).
+_FIRE_RAMP = multi_gradient((0x330000, 0xCC1100, 0xFF4400, 0xFF8800, 0xFFCC22, 0xFFF0A0), 24)
+
+try:
+    import time
+    get_time = time.monotonic
+except (ImportError, AttributeError):
+    import time
+    get_time = time.time
+
+try:
+    import random
+except ImportError:
+    # Simple random for CircuitPython if needed
+    class SimpleRandom:
+        def __init__(self):
+            self.seed = int(get_time() * 1000) % 65536
+        
+        def randint(self, a, b):
+            self.seed = (self.seed * 1103515245 + 12345) & 0x7fffffff
+            return a + (self.seed % (b - a + 1))
+        
+        def random(self):
+            return self.randint(0, 1000) / 1000.0
+    
+    random = SimpleRandom()
+
+
+__all__ = ['ParticleEngine', 'Particle', 'Sparkle', 'RainDrop', 'Ember', 'Snow']
+
+class ParticleEngine:
+    """Lightweight particle engine for ESP32."""
+    
+    def __init__(self, max_particles: int = 8) -> None:
+        """Initialize particle engine.
+        
+        Args:
+            max_particles: Maximum number of particles (keep low for ESP32)
+        """
+        self.max_particles: int = max_particles
+        self.particles: list = []
+        self.last_spawn_time: float = 0
+    
+    def add_particle(self, particle: Any) -> bool:
+        """Add particle to system.
+        
+        Args:
+            particle: Particle instance
+        """
+        if len(self.particles) < self.max_particles:
+            particle.spawn_time = get_time()
+            self.particles.append(particle)
+            return True
+        return False
+    
+    async def update(self, display: Any) -> None:
+        """Update all particles.
+        
+        Args:
+            display: Display interface
+        """
+        current_time = get_time()
+        
+        # Update particles (backwards to allow removal)
+        for i in range(len(self.particles) - 1, -1, -1):
+            particle = self.particles[i]
+            elapsed = current_time - particle.spawn_time
+            
+            # Remove dead particles
+            if particle.is_dead(elapsed):
+                self.particles.pop(i)
+                continue
+            
+            # Update and render particle
+            particle.update(elapsed)
+            await particle.render(display)
+    
+    def clear_particles(self) -> None:
+        """Remove all particles."""
+        self.particles.clear()
+    
+    def get_particle_count(self) -> int:
+        """Get current particle count."""
+        return len(self.particles)
+
+
+class Particle:
+    """Base particle class."""
+    
+    def __init__(self, x: int, y: int, lifetime: float = 2.0) -> None:
+        """Initialize particle.
+        
+        Args:
+            x: Starting X position
+            y: Starting Y position
+            lifetime: Particle lifetime in seconds
+        """
+        self.start_x: int = x
+        self.start_y: int = y
+        self.x: float = float(x)
+        self.y: float = float(y)
+        self.lifetime: float = lifetime
+        self.spawn_time: float = 0
+    
+    def update(self, elapsed_time: float) -> None:
+        """Update particle physics.
+        
+        Args:
+            elapsed_time: Time since spawn
+        """
+        pass  # Override in subclasses
+    
+    async def render(self, display: Any) -> None:
+        """Render particle to display.
+        
+        Args:
+            display: Display interface
+        """
+        pass  # Override in subclasses
+    
+    def is_dead(self, elapsed_time: float) -> bool:
+        """Check if particle should be removed.
+        
+        Args:
+            elapsed_time: Time since spawn
+            
+        Returns:
+            bool: True if particle is dead
+        """
+        return elapsed_time > self.lifetime
+    
+    def get_life_ratio(self, elapsed_time: float) -> float:
+        """Get life ratio (0.0 = just born, 1.0 = about to die).
+        
+        Args:
+            elapsed_time: Time since spawn
+            
+        Returns:
+            float: Life ratio
+        """
+        return min(elapsed_time / self.lifetime, 1.0)
+
+
+class Sparkle(Particle):
+    """Simple sparkle particle."""
+    
+    def __init__(self, x: int, y: int, color: int = 0xFFFFFF, lifetime: float = 1.0) -> None:
+        """Initialize sparkle.
+        
+        Args:
+            x: X position
+            y: Y position
+            color: Sparkle color
+            lifetime: How long sparkle lasts
+        """
+        super().__init__(x, y, lifetime)
+        self.color: int = color
+        self.peak_time: float = lifetime * 0.2  # Peak brightness at 20% of lifetime
+    
+    async def render(self, display: Any) -> None:
+        """Render sparkle with fading."""
+        # Check bounds
+        x = int(self.x)
+        y = int(self.y)
+        
+        if not (0 <= x < display.width and 0 <= y < display.height):
+            return
+        
+        # Calculate brightness based on age
+        life_ratio = self.get_life_ratio(get_time() - self.spawn_time)
+        
+        if life_ratio < 0.2:
+            # Growing phase
+            brightness = life_ratio / 0.2
+        else:
+            # Fading phase
+            brightness = 1.0 - ((life_ratio - 0.2) / 0.8)
+        
+        brightness = max(0.0, min(1.0, brightness))
+        
+        # Apply brightness to color
+        r = int(((self.color >> 16) & 0xFF) * brightness)
+        g = int(((self.color >> 8) & 0xFF) * brightness)
+        b = int((self.color & 0xFF) * brightness)
+        
+        final_color = (r << 16) | (g << 8) | b
+        await display.set_pixel(x, y, final_color)
+
+
+class RainDrop(Particle):
+    """Rain drop particle that falls down."""
+    
+    def __init__(self, x: int, y: int, speed: float = 10.0, color: int = 0x0080FF, lifetime: float = 3.0) -> None:
+        """Initialize rain drop.
+        
+        Args:
+            x: Starting X position
+            y: Starting Y position
+            speed: Fall speed (pixels per second)
+            color: Drop color
+            lifetime: Maximum lifetime
+        """
+        super().__init__(x, y, lifetime)
+        self.speed: float = speed
+        self.color: int = color
+    
+    def update(self, elapsed_time: float) -> None:
+        """Update rain drop physics."""
+        # Move down
+        self.y = self.start_y + (self.speed * elapsed_time)
+    
+    async def render(self, display: Any) -> None:
+        """Render rain drop."""
+        # Learn the real panel height for is_dead() (no display arg there).
+        self._bottom = display.height
+        x = int(self.x)
+        y = int(self.y)
+
+        # Check if still on screen
+        if not (0 <= x < display.width and 0 <= y < display.height):
+            return
+
+        await display.set_pixel(x, y, self.color)
+
+    def is_dead(self, elapsed_time: float) -> bool:
+        """Rain drop dies when it falls off the bottom of the panel."""
+        bottom = getattr(self, "_bottom", 32)   # real height learned in render()
+        return (self.y >= bottom) or super().is_dead(elapsed_time)
+
+
+class Ember(Particle):
+    """Fire ember that rises and fades."""
+    
+    def __init__(self, x: int, y: int, speed: float = 5.0, drift: float = 2.0,
+                 lifetime: float = 2.0, colors=None) -> None:
+        """Initialize ember.
+
+        Args:
+            x: Starting X position
+            y: Starting Y position
+            speed: Rise speed
+            drift: Horizontal drift amount
+            lifetime: Ember lifetime
+            colors: Optional colour ramp (sequence of 0xRRGGBB, coolest first) the
+                ember walks as it ages. Defaults to a smooth 24-step fire gradient;
+                pass e.g. ``colors.gradient(0x001133, 0x66CCFF, 24)`` for a blue flame.
+        """
+        super().__init__(x, y, lifetime)
+        self.speed = speed
+        self.drift = drift
+        self.drift_direction = 1 if random.random() > 0.5 else -1
+
+        # Smooth fire ramp (deep red -> orange -> yellow -> near-white) by default.
+        self.colors = list(colors) if colors is not None else _FIRE_RAMP
+    
+    def update(self, elapsed_time: float) -> None:
+        """Update ember physics."""
+        # Move up
+        self.y = self.start_y - (self.speed * elapsed_time)
+        
+        # Drift sideways
+        drift_amount = self.drift * elapsed_time * self.drift_direction
+        self.x = self.start_x + drift_amount
+    
+    async def render(self, display: Any) -> None:
+        """Render ember with color transition."""
+        x = int(self.x)
+        y = int(self.y)
+        
+        if not (0 <= x < display.width and 0 <= y < display.height):
+            return
+        
+        # Color changes over lifetime
+        life_ratio = self.get_life_ratio(get_time() - self.spawn_time)
+        color_index = int(life_ratio * (len(self.colors) - 1))
+        color_index = min(color_index, len(self.colors) - 1)
+        
+        # Fade brightness over time
+        brightness = 1.0 - life_ratio
+        color = self.colors[color_index]
+        
+        r = int(((color >> 16) & 0xFF) * brightness)
+        g = int(((color >> 8) & 0xFF) * brightness)
+        b = int((color & 0xFF) * brightness)
+        
+        final_color = (r << 16) | (g << 8) | b
+        await display.set_pixel(x, y, final_color)
+    
+    def is_dead(self, elapsed_time: float) -> bool:
+        """Ember dies when it rises off screen or expires."""
+        return (self.y < 0) or super().is_dead(elapsed_time)
+
+
+class Snow(Particle):
+    """Snow flake that falls gently."""
+    
+    def __init__(self, x: int, y: int, speed: float = 3.0, sway: float = 1.0, lifetime: float = 5.0) -> None:
+        """Initialize snow flake.
+        
+        Args:
+            x: Starting X position
+            y: Starting Y position
+            speed: Fall speed
+            sway: Side-to-side sway amount
+            lifetime: Snow lifetime
+        """
+        super().__init__(x, y, lifetime)
+        self.speed = speed
+        self.sway = sway
+        self.sway_phase: float = random.random() * 6.28  # Random phase for sway
+    
+    def update(self, elapsed_time: float) -> None:
+        """Update snow physics."""
+        # Fall down
+        self.y = self.start_y + (self.speed * elapsed_time)
+        
+        # Sway side to side
+        import math
+        sway_offset = self.sway * math.sin(elapsed_time * 2 + self.sway_phase)
+        self.x = self.start_x + sway_offset
+    
+    async def render(self, display: Any) -> None:
+        """Render snow flake."""
+        # Learn the real panel height for is_dead() (no display arg there).
+        self._bottom = display.height
+        x = int(self.x)
+        y = int(self.y)
+
+        if not (0 <= x < display.width and 0 <= y < display.height):
+            return
+
+        # White snow flake
+        await display.set_pixel(x, y, 0xFFFFFF)
+
+    def is_dead(self, elapsed_time: float) -> bool:
+        """Snow dies when it falls off the bottom of the panel."""
+        bottom = getattr(self, "_bottom", 32)   # real height learned in render()
+        return (self.y >= bottom) or super().is_dead(elapsed_time)

scrollkit/effects/reveal_splash.py

@@ -0,0 +1,132 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Reveal-splash animation — all LEDs on, wink off non-text pixels to reveal art.
+
+Drop-in library version of the ThemeParkWaits reveal animation.  The caller
+supplies the list of pixels that should remain on (the "text" or "logo"); the
+rest wink off in random order until the image is revealed, then hold briefly.
+
+Pixel-exact via displayio Bitmap so Label y-origin issues don't apply.  Uses
+``display.gfx`` (the same graphics context OverlayMask uses) rather than a bare
+``import displayio`` — this guarantees the simulator's displayio is used on
+desktop and the hardware one on CircuitPython.
+
+Typical usage::
+
+    from scrollkit.effects.reveal_splash import show_reveal_splash, pixels_from_text
+
+    # Build a pixel list from text using the built-in 5x7 font.
+    px = pixels_from_text("SCROLL", x=14, y=8)
+    px += pixels_from_text("KIT", x=23, y=20)
+    await show_reveal_splash(display, px)
+
+    # Or supply your own pixel-art coordinates.
+    await show_reveal_splash(display, my_logo_pixels, color=0x00FF88)
+"""
+
+import asyncio
+import random
+
+
+__all__ = ['show_reveal_splash', 'pixels_from_text']
+
+def _simple_shuffle(lst):
+    """In-place Fisher-Yates shuffle — random.shuffle is not on CircuitPython."""
+    for i in range(len(lst) - 1, 0, -1):
+        j = random.randint(0, i)
+        lst[i], lst[j] = lst[j], lst[i]
+
+
+def pixels_from_text(text, x=0, y=0):
+    """Return ``[(col, row), ...]`` for ``text`` rendered in the built-in 5×7 font.
+
+    The coordinates are absolute display pixels: each glyph starts at ``x`` and
+    advances 6 px (5 wide + 1 gap) per character; glyphs are 7 rows tall
+    starting at ``y``.  Pixels that fall outside the font table (unknown chars)
+    are silently skipped.
+
+    Args:
+        text: String to render (case-insensitive; unknown chars are skipped).
+        x:    Left edge of the first character in display pixels.
+        y:    Top edge of the text in display pixels.
+
+    Returns:
+        List of ``(x, y)`` integer tuples for every lit pixel.
+
+    Example — "SCROLL" centred on the top half of a 64×32 display::
+
+        px = pixels_from_text("SCROLL", x=14, y=8)
+    """
+    from ..display.bitmap_text import FONT_5x7 as _FONT_5x7  # lazy — keep device RAM low
+    pixels = []
+    cx = x
+    for ch in text:
+        rows = _FONT_5x7.get(ch.upper())
+        if rows is not None:
+            for ry, row in enumerate(rows):
+                for rx, cell in enumerate(row):
+                    if cell != " ":
+                        pixels.append((cx + rx, y + ry))
+        cx += 6  # CELL_W = glyph(5) + gap(1)
+    return pixels
+
+
+async def show_reveal_splash(
+    display,
+    pixels,
+    color=0xFFFF00,
+    off_per_frame=14,
+    hold_seconds=2.0,
+):
+    """Play a reveal animation on ``display``.
+
+    All LEDs start on (``color``), then non-``pixels`` LEDs wink off in
+    random order ``off_per_frame`` at a time until only the ``pixels`` remain.
+    The image then holds for ``hold_seconds`` before the overlay is removed.
+
+    Args:
+        display:       A ScrollKit ``UnifiedDisplay`` (must be initialised).
+        pixels:        Iterable of ``(x, y)`` tuples — pixels that stay on.
+                       Everything else will be turned off during the reveal.
+        color:         24-bit RGB fill color (default: yellow 0xFFFF00).
+        off_per_frame: Pixels turned off per animation step (speed knob).
+                       14 is calibrated for the 64×32 MatrixPortal S3 at ~20 fps.
+        hold_seconds:  Seconds to hold the revealed image before finishing.
+    """
+    gfx = display.gfx
+    w, h = display.width, display.height
+
+    bitmap = gfx.Bitmap(w, h, 2)
+    palette = gfx.Palette(2)
+    palette[0] = 0x000000
+    palette[1] = color
+    tilegrid = gfx.TileGrid(bitmap, pixel_shader=palette)
+    display.add_layer(tilegrid)
+
+    target_set = set(pixels)
+
+    # Fill all pixels on in one C bulk call (never a per-pixel Python loop).
+    try:
+        bitmap.fill(1)
+    except (AttributeError, TypeError):
+        for x in range(w):
+            for y in range(h):
+                bitmap[x, y] = 1
+
+    # Non-target pixels to wink off, in random order.
+    to_off = [(x, y) for x in range(w) for y in range(h)
+              if (x, y) not in target_set]
+    _simple_shuffle(to_off)
+
+    await display.show()
+
+    while to_off:
+        batch = min(off_per_frame, len(to_off))
+        for _ in range(batch):
+            px = to_off.pop()
+            bitmap[px[0], px[1]] = 0
+        await display.show()
+        await asyncio.sleep(0.02)
+
+    await display.show()
+    await asyncio.sleep(hold_seconds)
+    display.remove_layer(tilegrid)