scrollkit 0.8.3__py3-none-any.whl

scrollkit/simulator/displayio/bitmap.py

@@ -0,0 +1,158 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython displayio.Bitmap equivalent."""
+
+import numpy as np
+
+
+class Bitmap:
+    """Bitmap for pixel data storage.
+    
+    Stores pixel data as palette indices. Each pixel is an index
+    into a Palette object that defines the actual colors.
+    Compatible with CircuitPython's displayio.Bitmap API.
+    """
+    
+    def __init__(self, width, height, value_count):
+        """Initialize bitmap with specified dimensions.
+        
+        Args:
+            width: Bitmap width in pixels
+            height: Bitmap height in pixels
+            value_count: Number of different values each pixel can have
+        """
+        self.width = width
+        self.height = height
+        self.value_count = value_count
+        
+        # Determine data type based on value count
+        if value_count <= 2:
+            self._bits_per_value = 1
+            dtype = np.uint8
+        elif value_count <= 4:
+            self._bits_per_value = 2
+            dtype = np.uint8
+        elif value_count <= 16:
+            self._bits_per_value = 4
+            dtype = np.uint8
+        elif value_count <= 256:
+            self._bits_per_value = 8
+            dtype = np.uint8
+        else:
+            self._bits_per_value = 16
+            dtype = np.uint16
+            
+        # Create buffer to store pixel values
+        self._buffer = np.zeros((height, width), dtype=dtype)
+        
+    def __setitem__(self, index, value):
+        """Set pixel value.
+        
+        Args:
+            index: (x, y) tuple or flat index
+            value: Palette index value
+        """
+        if isinstance(index, tuple):
+            x, y = index
+            if not (0 <= x < self.width and 0 <= y < self.height):
+                raise IndexError(f"Pixel index ({x}, {y}) out of bounds")
+        else:
+            # Convert flat index to x, y
+            y = index // self.width
+            x = index % self.width
+            if not (0 <= index < self.width * self.height):
+                raise IndexError(f"Pixel index {index} out of bounds")
+                
+        if not 0 <= value < self.value_count:
+            raise ValueError(f"Pixel value {value} out of range")
+            
+        self._buffer[y, x] = value
+        
+    def __getitem__(self, index):
+        """Get pixel value.
+        
+        Args:
+            index: (x, y) tuple or flat index
+            
+        Returns:
+            Palette index value
+        """
+        if isinstance(index, tuple):
+            x, y = index
+            if not (0 <= x < self.width and 0 <= y < self.height):
+                raise IndexError(f"Pixel index ({x}, {y}) out of bounds")
+        else:
+            # Convert flat index to x, y
+            y = index // self.width
+            x = index % self.width
+            if not (0 <= index < self.width * self.height):
+                raise IndexError(f"Pixel index {index} out of bounds")
+                
+        return int(self._buffer[y, x])
+        
+    def fill(self, value):
+        """Fill entire bitmap with a single value.
+        
+        Args:
+            value: Palette index value to fill with
+        """
+        if not 0 <= value < self.value_count:
+            raise ValueError(f"Pixel value {value} out of range")
+            
+        self._buffer.fill(value)
+        
+    def blit(self, x, y, source_bitmap, *, x1=0, y1=0, x2=None, y2=None, skip_index=None):
+        """Copy pixels from another bitmap.
+        
+        Args:
+            x: Destination X coordinate
+            y: Destination Y coordinate
+            source_bitmap: Source Bitmap to copy from
+            x1: Source left edge (default 0)
+            y1: Source top edge (default 0)
+            x2: Source right edge (default source width)
+            y2: Source bottom edge (default source height)
+            skip_index: Palette index to treat as transparent
+        """
+        # Set default source bounds
+        if x2 is None:
+            x2 = source_bitmap.width
+        if y2 is None:
+            y2 = source_bitmap.height
+            
+        # Calculate copy region
+        src_width = x2 - x1
+        src_height = y2 - y1
+        
+        # Clip to destination bounds
+        copy_width = min(src_width, self.width - x)
+        copy_height = min(src_height, self.height - y)
+        
+        if copy_width <= 0 or copy_height <= 0:
+            return
+            
+        # Clip source region
+        if x < 0:
+            x1 -= x
+            copy_width += x
+            x = 0
+        if y < 0:
+            y1 -= y
+            copy_height += y
+            y = 0
+            
+        # Copy pixel data
+        src_data = source_bitmap._buffer[y1:y1 + copy_height, x1:x1 + copy_width]
+        
+        if skip_index is not None:
+            # Copy only non-transparent pixels
+            mask = src_data != skip_index
+            dst_slice = self._buffer[y:y + copy_height, x:x + copy_width]
+            dst_slice[mask] = src_data[mask]
+        else:
+            # Copy all pixels
+            self._buffer[y:y + copy_height, x:x + copy_width] = src_data
+            
+    @property
+    def bits_per_value(self):
+        """Get the number of bits per pixel value."""
+        return self._bits_per_value

scrollkit/simulator/displayio/display.py

@@ -0,0 +1,195 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython displayio.Display equivalent."""
+
+from ..core.led_matrix import LEDMatrix
+from ..core.color_utils import rgb565_to_rgb888
+
+
+class Display:
+    """Display manages the screen output.
+    
+    This class provides the main interface for showing groups and
+    managing display properties like brightness and rotation.
+    Compatible with CircuitPython's displayio.Display API.
+    """
+    
+    def __init__(self, display_bus, *, width, height, rotation=0,
+                 color_depth=16, auto_refresh=True, backlight_pin=None,
+                 brightness=1.0, auto_brightness=False, backlight_on_high=True,
+                 native_frames_per_second=60):
+        """Initialize Display.
+        
+        Args:
+            display_bus: Display bus interface (e.g., FourWire)
+            width: Display width in pixels
+            height: Display height in pixels
+            rotation: Display rotation in degrees (0, 90, 180, 270)
+            color_depth: Color depth in bits (default 16)
+            auto_refresh: Whether to automatically refresh display
+            backlight_pin: Pin for backlight control (ignored in simulator)
+            brightness: Initial brightness (0.0 to 1.0)
+            auto_brightness: Whether to automatically adjust brightness
+            backlight_on_high: Whether backlight is on when pin is high
+            native_frames_per_second: Native refresh rate
+        """
+        self.display_bus = display_bus
+        self.width = width
+        self.height = height
+        self.rotation = rotation
+        self.color_depth = color_depth
+        self.auto_refresh = auto_refresh
+        self._brightness = brightness
+        self.auto_brightness = auto_brightness
+        self.native_frames_per_second = native_frames_per_second
+        
+        # Current root group
+        self.root_group = None
+        
+        # Create LED matrix for rendering
+        self._matrix = LEDMatrix(width, height)
+        self._matrix.set_brightness(brightness)
+        
+    @property
+    def brightness(self):
+        """Get display brightness."""
+        return self._brightness
+        
+    @brightness.setter
+    def brightness(self, value):
+        """Set display brightness.
+        
+        Args:
+            value: Brightness from 0.0 to 1.0
+        """
+        self._brightness = max(0.0, min(1.0, value))
+        self._matrix.set_brightness(self._brightness)
+        
+    def show(self, group_or_tilegrid):
+        """Show a Group or TileGrid on the display.
+        
+        Args:
+            group_or_tilegrid: Group or TileGrid to display
+        """
+        self.root_group = group_or_tilegrid
+        if self.auto_refresh:
+            self.refresh()
+            
+    def refresh(self, *, target_frames_per_second=None, minimum_frames_per_second=1):
+        """Manually refresh the display.
+        
+        Args:
+            target_frames_per_second: Target refresh rate
+            minimum_frames_per_second: Minimum acceptable refresh rate
+        """
+        if self.root_group is None:
+            return
+            
+        # Clear the matrix
+        self._matrix.clear()
+        
+        # Render the root group
+        self._render_group(self.root_group, 0, 0, 1)
+        
+        # Update the display
+        self._matrix.render()
+        
+    def _render_group(self, group, offset_x, offset_y, scale):
+        """Recursively render a group and its contents.
+        
+        Args:
+            group: Group to render
+            offset_x: X offset from parent
+            offset_y: Y offset from parent
+            scale: Cumulative scale factor
+        """
+        if hasattr(group, 'hidden') and group.hidden:
+            return
+            
+        # Calculate group position
+        group_x = offset_x + (group.x if hasattr(group, 'x') else 0) * scale
+        group_y = offset_y + (group.y if hasattr(group, 'y') else 0) * scale
+        group_scale = scale * (group.scale if hasattr(group, 'scale') else 1)
+        
+        # Check if this is a Group with items
+        if hasattr(group, '_items'):
+            # Render all items in the group
+            for item in group._items:
+                self._render_group(item, group_x, group_y, group_scale)
+        # Check if this is a TileGrid
+        elif hasattr(group, 'bitmap') and hasattr(group, 'pixel_shader'):
+            self._render_tilegrid(group, group_x, group_y, group_scale)
+        # Check if this is a Label (from adafruit_display_text)
+        elif hasattr(group, '_bitmap') and hasattr(group, 'color'):
+            self._render_label(group, group_x, group_y, group_scale)
+            
+    def _render_tilegrid(self, tilegrid, x, y, scale):
+        """Render a TileGrid to the display.
+        
+        Args:
+            tilegrid: TileGrid to render
+            x: X position
+            y: Y position
+            scale: Scale factor
+        """
+        if tilegrid.hidden:
+            return
+            
+        # Get bitmap and palette
+        bitmap = tilegrid.bitmap
+        palette = tilegrid.pixel_shader
+        
+        # Render each tile
+        for tile_y in range(tilegrid.height):
+            for tile_x in range(tilegrid.width):
+                tile_index = tilegrid[tile_x, tile_y]
+                
+                # Calculate tile source position
+                src_tile_x = (tile_index % tilegrid._tiles_per_row) * tilegrid.tile_width
+                src_tile_y = (tile_index // tilegrid._tiles_per_row) * tilegrid.tile_height
+                
+                # Calculate destination position
+                dst_x = x + tile_x * tilegrid.tile_width * scale
+                dst_y = y + tile_y * tilegrid.tile_height * scale
+                
+                # Render tile pixels
+                for py in range(tilegrid.tile_height):
+                    for px in range(tilegrid.tile_width):
+                        # Get pixel from bitmap
+                        pixel_value = bitmap[src_tile_x + px, src_tile_y + py]
+                        
+                        # Skip transparent pixels
+                        if palette.is_transparent(pixel_value):
+                            continue
+                            
+                        # Get color from palette
+                        color = palette.get_rgb888(pixel_value)
+                        
+                        # Apply scaling
+                        for sy in range(scale):
+                            for sx in range(scale):
+                                pixel_x = int(dst_x + px * scale + sx)
+                                pixel_y = int(dst_y + py * scale + sy)
+                                
+                                # Set pixel if within bounds
+                                if 0 <= pixel_x < self.width and 0 <= pixel_y < self.height:
+                                    self._matrix.set_pixel(pixel_x, pixel_y, color)
+                                    
+    def _render_label(self, label, x, y, scale):
+        """Render a Label to the display.
+        
+        Args:
+            label: Label to render
+            x: X position
+            y: Y position
+            scale: Scale factor
+        """
+        # Labels are Groups that contain a TileGrid, so render them as groups
+        self._render_group(label, x, y, scale)
+        
+    def get_matrix(self):
+        """Get the underlying LED matrix.
+        
+        Returns:
+            LEDMatrix instance
+        """
+        return self._matrix

scrollkit/simulator/displayio/fourwire.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython displayio.FourWire equivalent."""
+
+
+class FourWire:
+    """FourWire interface for display communication.
+    
+    This is a stub implementation for API compatibility.
+    The simulator doesn't need actual SPI communication.
+    """
+    
+    def __init__(self, spi_bus, *, command=None, chip_select=None, reset=None, 
+                 baudrate=24000000, polarity=0, phase=0):
+        """Initialize FourWire interface.
+        
+        Args:
+            spi_bus: SPI bus object (ignored in simulator)
+            command: Command pin (ignored in simulator)
+            chip_select: Chip select pin (ignored in simulator)
+            reset: Reset pin (ignored in simulator)
+            baudrate: SPI baudrate (ignored in simulator)
+            polarity: SPI polarity (ignored in simulator)
+            phase: SPI phase (ignored in simulator)
+        """
+        self.spi_bus = spi_bus
+        self.command = command
+        self.chip_select = chip_select
+        self.reset = reset
+        self.baudrate = baudrate
+        self.polarity = polarity
+        self.phase = phase
+        self._locked = False
+        
+    def reset(self):
+        """Reset the display (no-op in simulator)."""
+        pass
+        
+    def send(self, command, data):
+        """Send command and data (no-op in simulator).
+        
+        Args:
+            command: Command byte
+            data: Data bytes
+        """
+        pass
+        
+    def __enter__(self):
+        """Context manager entry."""
+        self._locked = True
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self._locked = False

scrollkit/simulator/displayio/group.py

@@ -0,0 +1,125 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython displayio.Group equivalent."""
+
+
+class Group:
+    """Group organizes display elements into a tree structure.
+    
+    Groups can contain other groups, creating a display hierarchy.
+    Elements in a group can be positioned, scaled, and hidden.
+    Compatible with CircuitPython's displayio.Group API.
+    """
+    
+    def __init__(self, *, scale=1, x=0, y=0):
+        """Initialize Group.
+        
+        Args:
+            scale: Integer scale factor (default 1) 
+            x: X position of group (default 0)
+            y: Y position of group (default 0)
+        """
+        self.scale = scale
+        self.x = x
+        self.y = y
+        self.hidden = False
+        self._items = []
+        
+    def append(self, item):
+        """Add an item to the group.
+        
+        Args:
+            item: Display object (Group, TileGrid, etc.) to add
+        """
+        if item in self._items:
+            raise ValueError("Item already in group")
+        self._items.append(item)
+        
+    def insert(self, index, item):
+        """Insert an item at a specific position.
+        
+        Args:
+            index: Position to insert at
+            item: Display object to insert
+        """
+        if item in self._items:
+            raise ValueError("Item already in group")
+        self._items.insert(index, item)
+        
+    def remove(self, item):
+        """Remove an item from the group.
+        
+        Args:
+            item: Display object to remove
+        """
+        self._items.remove(item)
+        
+    def pop(self, index=-1):
+        """Remove and return an item.
+        
+        Args:
+            index: Index of item to remove (default -1 for last item)
+            
+        Returns:
+            Removed display object
+        """
+        return self._items.pop(index)
+        
+    def index(self, item):
+        """Find the index of an item.
+        
+        Args:
+            item: Display object to find
+            
+        Returns:
+            Index of item in group
+        """
+        return self._items.index(item)
+        
+    def __len__(self):
+        """Get number of items in group."""
+        return len(self._items)
+        
+    def __getitem__(self, index):
+        """Get item at index.
+        
+        Args:
+            index: Index of item to get
+            
+        Returns:
+            Display object at index
+        """
+        return self._items[index]
+        
+    def __setitem__(self, index, item):
+        """Replace item at index.
+        
+        Args:
+            index: Index to replace at
+            item: New display object
+        """
+        # Remove old item if it exists elsewhere in group
+        if item in self._items:
+            self._items.remove(item)
+        self._items[index] = item
+        
+    def __iter__(self):
+        """Iterate over items in group."""
+        return iter(self._items)
+        
+    def sort(self, key=None):
+        """Sort items in group.
+        
+        Args:
+            key: Optional key function for sorting
+        """
+        self._items.sort(key=key)
+        
+    @property
+    def auto_write(self):
+        """Get auto_write setting (always True for compatibility)."""
+        return True
+        
+    @auto_write.setter
+    def auto_write(self, value):
+        """Set auto_write (no-op for compatibility)."""
+        pass  # No-op for API compatibility

scrollkit/simulator/displayio/ondiskbitmap.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython displayio.OnDiskBitmap equivalent."""
+
+from PIL import Image
+import numpy as np
+from .bitmap import Bitmap
+from .palette import Palette
+
+
+class OnDiskBitmap:
+    """Load bitmap images from disk.
+    
+    Supports loading BMP and other image formats from disk.
+    Creates a bitmap and palette from the loaded image.
+    Compatible with CircuitPython's displayio.OnDiskBitmap API.
+    """
+    
+    def __init__(self, file_path):
+        """Initialize OnDiskBitmap from file.
+        
+        Args:
+            file_path: Path to image file
+        """
+        self.file_path = file_path
+        self._load_image()
+        
+    def _load_image(self):
+        """Load image from disk and create bitmap/palette."""
+        # Load image using PIL
+        img = Image.open(self.file_path)
+        
+        # Convert to RGB if needed
+        if img.mode != 'RGB':
+            if img.mode == 'P':
+                # Palette mode - extract palette
+                img = img.convert('RGB')
+            elif img.mode == 'RGBA':
+                # Convert RGBA to RGB with white background
+                background = Image.new('RGB', img.size, (255, 255, 255))
+                background.paste(img, mask=img.split()[3])
+                img = background
+            else:
+                img = img.convert('RGB')
+                
+        # Get image dimensions
+        self.width = img.width
+        self.height = img.height
+        
+        # Convert to numpy array
+        img_array = np.array(img)
+        
+        # Create palette with unique colors (up to 256)
+        unique_colors = {}
+        color_index = 0
+        
+        # Create bitmap
+        self.bitmap = Bitmap(self.width, self.height, 256)
+        
+        # Process pixels and build palette
+        for y in range(self.height):
+            for x in range(self.width):
+                color = tuple(img_array[y, x])
+                
+                if color not in unique_colors:
+                    if color_index < 256:
+                        unique_colors[color] = color_index
+                        color_index += 1
+                    else:
+                        # Find closest existing color
+                        closest_idx = self._find_closest_color(color, unique_colors)
+                        unique_colors[color] = closest_idx
+                        
+                self.bitmap[x, y] = unique_colors[color]
+                
+        # Create palette. Hand Palette the plain-int RGB888 tuple and let
+        # Palette.__setitem__ do the single, correct RGB565 conversion. (Passing
+        # rgb888_to_rgb565() the raw numpy uint8 channels overflowed the dtype —
+        # (r & 0xF8) << 8 wrapped to 0 — zeroing red/green so every image went
+        # blue; it also double-converted, since __setitem__ re-converts ints.)
+        self.palette = Palette(len(unique_colors))
+        for color, idx in unique_colors.items():
+            self.palette[idx] = (int(color[0]), int(color[1]), int(color[2]))
+            
+    def _find_closest_color(self, target_color, color_dict):
+        """Find closest color in palette.
+        
+        Args:
+            target_color: Target RGB color tuple
+            color_dict: Dictionary of existing colors
+            
+        Returns:
+            Index of closest color
+        """
+        min_distance = float('inf')
+        closest_idx = 0
+        
+        for color, idx in color_dict.items():
+            # Calculate color distance (simple RGB distance)
+            distance = sum((a - b) ** 2 for a, b in zip(target_color, color))
+            if distance < min_distance:
+                min_distance = distance
+                closest_idx = idx
+                
+        return closest_idx
+        
+    @property
+    def pixel_shader(self):
+        """Get the palette (alias for CircuitPython compatibility)."""
+        return self.palette