IS-Matrix-Forge 1.0.0.dev1__py3-none-any.whl

is_matrix_forge/led_matrix/display/effects/breather.py

@@ -0,0 +1,206 @@
+import threading
+import time
+from is_matrix_forge.common.decorators import freeze_setter
+
+
+class Breather:
+    """
+    Controls a “breathing” (fade in/out) effect on a controller’s brightness.
+
+    Parameters:
+        controller:
+            Any object with a mutable `brightness` attribute (0–100).
+
+        min_brightness (int):
+            Lowest brightness in the cycle. Defaults to 5.
+
+        max_brightness (int):
+            Highest brightness in the cycle. Defaults to 90.
+
+        step (int):
+            Amount to change brightness each tick. Defaults to 5.
+
+        breathe_fps (float):
+            How many brightness updates per second. Defaults to 30.
+
+    Methods:
+
+        start():
+            Launch the breathing loop in a background thread.
+
+        stop():
+            Halt the breathing loop and join the thread.
+    """
+    def __init__(
+            self,
+            controller,
+            min_brightness: int   = 5,
+            max_brightness: int   = 90,
+            step:           int   = 5,
+            breathe_fps:    float = 30.0
+    ):
+        self._controller     = None
+        self._min_brightness = None
+        self._max_brightness = None
+        self._step           = None
+        self._fps            = None
+
+        self.controller      = controller
+
+        self.__initial_brightness = self.controller.brightness
+
+        self.min_brightness  = min_brightness
+        self.max_brightness  = max_brightness
+        self.step            = step
+        self.fps             = breathe_fps
+
+        self._breathing = False
+        self._thread    = None
+
+    @property
+    def breathing(self) -> bool:
+        return self._breathing
+
+    @breathing.setter
+    def breathing(self, new: bool) -> None:
+        if not isinstance(new, bool):
+            raise TypeError(f'"breathing" must be of type `bool`, not {type(new)}')
+
+        if self.breathing and not new:
+            self.stop()
+        elif not self.breathing and new:
+            self.start()
+
+        self._breathing = new
+
+
+    @property
+    def controller(self) -> 'LEDMatrixController':
+        """
+        The controller for the LED matrix device.
+        """
+        return self._controller
+
+    @controller.setter
+    @freeze_setter()
+    def controller(self, new):
+        from is_matrix_forge.led_matrix import LEDMatrixController
+        if not isinstance(new, LEDMatrixController):
+            raise TypeError(f'controller must be LEDMatrixController, not {type(new)}')
+        self._controller = new
+
+    @property
+    def initial_brightness(self) -> int:
+        """
+
+        .. note::
+            This is a read-only property.
+        """
+        return self.__initial_brightness
+
+    @property
+    def min_brightness(self) -> int:
+        """
+        The minimum LED brightness in the cycle.
+        """
+        return self._min_brightness
+
+    @min_brightness.setter
+    def min_brightness(self, new):
+        if not isinstance(new, int):
+            raise TypeError('"min_brightness" must be int')
+        if not 0 <= new <= 100:
+            raise ValueError('"min_brightness" must be between 0 and 100')
+        if self._max_brightness is not None and new > self._max_brightness:
+            raise ValueError('"min_brightness" must be <= max_brightness')
+        self._min_brightness = new
+
+    @property
+    def max_brightness(self) -> int:
+        """
+        The maximum LED brightness in the cycle.
+        """
+        return self._max_brightness
+
+    @max_brightness.setter
+    def max_brightness(self, new):
+        if not isinstance(new, int):
+            raise TypeError('"max_brightness" must be int')
+        if not 0 <= new <= 100:
+            raise ValueError('"max_brightness" must be between 0 and 100')
+        if self._min_brightness is not None and new < self._min_brightness:
+            raise ValueError('"max_brightness" must be >= min_brightness')
+        self._max_brightness = new
+
+    @property
+    def step(self) -> int:
+        """
+        Amount to change brightness each tick.
+        """
+        return self._step
+
+    @step.setter
+    def step(self, new):
+        if not isinstance(new, int):
+            raise TypeError('"step" must be int')
+        if new <= 0 or new > 100:
+            raise ValueError('"step" must be > 0 and <= 100')
+        self._step = new
+
+    @property
+    def fps(self) -> float:
+        """
+        Frames per second for the breathing effect.
+        """
+        return self._fps
+
+    @fps.setter
+    def fps(self, new):
+        if not isinstance(new, (int, float)):
+            raise TypeError('"fps" must be a number')
+        if new <= 0:
+            raise ValueError('"fps" must be > 0')
+        self._fps = float(new)
+
+    def _breath_loop(self):
+        interval = 1.0 / self._fps
+        # start at current brightness, clamped
+        current = max(self._min_brightness,
+                      min(self._controller.brightness, self._max_brightness))
+        going_up = True
+
+        while self._breathing:
+            if going_up:
+                current += self._step
+                if current >= self._max_brightness:
+                    current = self._max_brightness
+                    going_up = False
+            else:
+                current -= self._step
+                if current <= self._min_brightness:
+                    current = self._min_brightness
+                    going_up = True
+
+            self._controller.brightness = current
+            time.sleep(interval)
+
+    def start(self):
+        """
+        Begin the breathing effect in a background daemon thread.
+        No effect if already running.
+        """
+        if not self._breathing:
+            self._breathing = True
+            self._thread = threading.Thread(target=self._breath_loop, daemon=True)
+            self._thread.start()
+
+    def stop(self):
+        """
+        Stop the breathing effect and wait for the thread to finish.
+        """
+        self._breathing = False
+        if self._thread:
+            self._thread.join()
+            self._thread = None
+
+        self.controller.brightness = self.initial_brightness

is_matrix_forge/led_matrix/display/effects/scroller/__init__.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from is_matrix_forge.common.decorators import freeze_setter
+
+
+if TYPE_CHECKING:
+    from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
+
+
+class HardwareScroller:
+    """
+    This class just manages the native 'animation' for the LED matrix.
+
+    This simply wraps commands to the LED matrix that can;
+      - Query the current state of the 'animating' flag
+      - Set the 'animating' flag
+    """
+    def __init__(
+            self,
+            controller,
+            do_not_keep_lit: bool = False
+    ):
+        self._controller = None
+        self.__keep_lit  = None
+
+        self.controller = controller
+        self.keep_lit = not do_not_keep_lit
+
+    @property
+    def controller(self):
+        """
+        The controller (therefore the hardware) this scroller is managing.
+
+        Returns:
+            The controller object.
+        """
+        return self._controller
+
+    @controller.setter
+    @freeze_setter(allow_reassignment_to_same_value=True)
+    def controller(self, new: LEDMatrixController):
+        """
+        The controller (therefore the hardware) this scroller is managing.
+
+        Parameters:
+            new (LEDMatrixController):
+                The controller object.
+
+        Returns:
+            None
+
+        Raises:
+            AssertionError:
+                If `new` isn't an instance of :class:`LEDMatrixController`.
+
+        See Also:
+            - :func:`~is_matrix_forge.common.decorators.freeze_setter`
+            - :meth:`controller`
+            - :attr:`controller`
+            - :class:`LEDMatrixController`
+        """
+        from is_matrix_forge.led_matrix import LEDMatrixController
+        assert isinstance(new, LEDMatrixController), f"Expected {LEDMatrixController}, got {type(new)}"
+
+        self._controller = new
+
+    @property
+    def is_scrolling(self) -> bool:
+        """
+        Checks if the LED is currently animating (meaning scrolling).
+
+        .. note::
+            This is a read-only property.
+        """
+        return self.controller.animating
+
+
+    @property
+    def keep_lit(self) -> bool:
+        """
+        Should the LED matrix be kept awake while scrolling?
+        """
+        return self.__keep_lit
+
+    @keep_lit.setter
+    def keep_lit(self, new):
+        if not isinstance(new, bool):
+            raise TypeError('"keep_lit" must be of type "bool"')
+        self.__keep_lit = new
+
+    def start_scrolling(self):
+        pass

is_matrix_forge/led_matrix/display/effects/scroller/base.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Generic, TypeVar
+from is_matrix_forge.common.decorators import freeze_setter
+
+if TYPE_CHECKING:
+    from is_matrix_forge.led_matrix import LEDMatrixController
+
+# Make our base class generic so you can subclass it for other scrollers, too
+C = TypeVar('C', bound='LEDMatrixController')
+
+class Scroller(ABC, Generic[C]):
+    """
+    Base functionality for scrolling-like animations on an LEDMatrixController.
+
+    Subclasses only need to implement start_scrolling (and stop_scrolling, if desired).
+    """
+
+    def __init__(
+        self,
+        controller: C,
+        *,
+        keep_lit: bool = True
+    ):
+        self._controller: C | None = None
+        self._keep_lit: bool | None = None
+
+        # these setters enforce type checks/freeze behavior
+        self.controller = controller
+        self.keep_lit = keep_lit
+
+    @property
+    def controller(self) -> C:
+        """The LEDMatrixController instance used for scrolling."""
+        return self._controller  # type: ignore
+
+    @controller.setter
+    @freeze_setter(allow_reassignment_to_same_value=True)
+    def controller(self, new: C) -> None:
+        from is_matrix_forge.led_matrix.controller import LEDMatrixController
+        assert isinstance(new, LEDMatrixController), (
+            f"Expected LEDMatrixController, got {type(new).__name__}"
+        )
+        self._controller = new
+
+    @property
+    def is_scrolling(self) -> bool:
+        """
+        Whether a scroll animation is currently in progress.
+        """
+        return bool(self.controller.animating)
+
+    @property
+    def keep_lit(self) -> bool:
+        """
+        If True, keep the LED matrix powered while scrolling.
+        """
+        return self._keep_lit  # type: ignore
+
+    @keep_lit.setter
+    def keep_lit(self, new: bool) -> None:
+        if not isinstance(new, bool):
+            raise TypeError('"keep_lit" must be a bool')
+        self._keep_lit = new
+
+    @abstractmethod
+    def start_scrolling(self) -> None:
+        """
+        Begin the scroll animation. Must be implemented by subclasses.
+        """
+
+    def stop_scrolling(self) -> None:
+        """
+        Stop the scroll animation. Optional override by subclasses.
+        """
+        self.controller.animating = False

is_matrix_forge/led_matrix/display/effects/scroller/helpers.py

@@ -0,0 +1,62 @@
+from easy_exit_calls import ExitCallHandler
+from is_matrix_forge.common.decorators import freeze_setter, validate_type
+
+
+ECH = ExitCallHandler()
+DEFAULT_TIME_BETWEEN_JIGGLES = 50
+MAX_TIME_BETWEEN_JIGGLES     = 59  # Matrix goes to sleep after 60 seconds of command inactivity, so we need to jiggle
+                                   # at least once every minute
+
+
+class MatrixJiggler:
+    def __init__(
+            self,
+            controller    = None,
+            power_monitor = None,
+            interval: int = None,
+            do_not_clear_on_stop: bool = False,
+
+    ):
+        if controller and power_monitor:
+            raise ValueError("Cannot specify both `controller` and `power_monitor`")
+
+        self.controller         = controller
+        self.power_monitor      = power_monitor
+        self.clear_on_stop      = not do_not_clear_on_stop
+        self._controller        = None
+        self.__interval         = None
+        self.__last_jiggle_time = None
+        self._power_monitor     = None
+
+    @property
+    def controller(self):
+        return self._controller
+
+    @property
+    def interval(self) -> float:
+        return self.__interval
+
+    @interval.setter
+    @validate_type([float, int], float)
+    def interval(self, new):
+        self.__interval = new
+
+    @property
+    def power_monitor(self):
+        return self._power_monitor
+
+    @power_monitor.setter
+    @freeze_setter()
+    def power_monitor(self, new):
+        from is_matrix_forge.monitor.monitor import PowerMonitor
+
+        if not isinstance(new, PowerMonitor):
+            raise TypeError(f"Expected {PowerMonitor}, got {type(new)}")
+
+        self._controller = new.controller
+
+        self._power_monitor = new
+
+    def cleanup(self):
+        if self.clear_on_stop:
+            self.controller.clear()

is_matrix_forge/led_matrix/display/grid/__init__.py

@@ -0,0 +1,9 @@
+"""
+Grid module for LED Matrix display.
+
+This module provides the Grid class for representing and manipulating
+the LED matrix display grid. It includes functionality for creating,
+loading, and modifying grid patterns.
+"""
+from is_matrix_forge.led_matrix.display.grid.helpers import generate_blank_grid
+from is_matrix_forge.led_matrix.display.grid.grid import Grid

is_matrix_forge/led_matrix/display/grid/grid.py

@@ -0,0 +1,208 @@
+# is_matrix_forge.led_matrix.display.grid.grid
+"""
+Grid module for LED Matrix display.
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/display/grid/grid.py
+
+Description:
+    This module provides the Grid class which represents a 2D grid of pixels
+    for the LED matrix display. It handles grid creation, manipulation, and
+    loading from files.
+"""
+
+import itertools
+from pathlib import Path
+from typing import List, Optional, Union, ClassVar, Type, Any, Dict  # Added Any, Dict
+from ...constants import WIDTH as __WIDTH, HEIGHT as __HEIGHT, PRESETS_DIR
+from .helpers import is_valid_grid, generate_blank_grid
+from is_matrix_forge.common.helpers import coerce_to_int
+
+MATRIX_HEIGHT = __HEIGHT
+"""int: Height of the LED matrix grid in pixels.
+This constant defines the default height for new Grid instances and for loading operations.
+"""
+
+MATRIX_WIDTH = __WIDTH
+"""int: Width of the LED matrix grid in pixels.
+This constant defines the default width for new Grid instances and for loading operations.
+"""
+
+
+class Grid:
+    """
+    Represents a 2D column-major grid for the LED display (grid[x][y], 9×34).
+    Provides methods for grid creation, manipulation, and loading from files.
+
+    The Grid class allows for the management of pixel data in a column-major format,
+    supporting operations such as shifting, drawing, and loading from specifications or files.
+    """
+
+    def __init__(
+        self,
+        width: int = MATRIX_WIDTH,
+        height: int = MATRIX_HEIGHT,
+        fill_value: int = 0,
+        init_grid: List[List[int]] = None
+    ) -> None:
+        """
+        Initialize a Grid. If `init_grid` is provided, it must be column-major
+        with shape (width × height). Otherwise, create a blank grid.
+        """
+        if init_grid is not None:
+            if not is_valid_grid(init_grid, width, height):
+                raise ValueError(f"init_grid must be {width}×{height} column-major 0/1 list")
+            self._grid = [col[:] for col in init_grid]
+        else:
+            if fill_value not in (0, 1):
+                raise ValueError("fill_value must be 0 or 1")
+            self._grid = generate_blank_grid(width=width, height=height, fill_value=fill_value)
+
+        self._width = width
+        self._height = height
+        self._fill_value = fill_value
+
+    @property
+    def grid(self) -> List[List[int]]:
+        """Defensive copy of the column-major grid data."""
+        return [col[:] for col in self._grid]
+
+    @grid.setter
+    def grid(self, value: List[List[int]]) -> None:
+        """Replace the internal grid; must be column-major and correct shape."""
+        if not is_valid_grid(value, self._width, self._height):
+            raise ValueError(f"grid must be {self._width}×{self._height} column-major 0/1 list")
+        self._grid = [col[:] for col in value]
+
+    @property
+    def width(self) -> int:
+        """Number of columns."""
+        return self._width
+
+    @property
+    def height(self) -> int:
+        """Number of rows."""
+        return self._height
+
+    @property
+    def fill_value(self) -> int:
+        """Default pixel fill (0 or 1)."""
+        return self._fill_value
+
+    @fill_value.setter
+    def fill_value(self, v: int) -> None:
+        """Set default pixel fill; must be 0 or 1."""
+        if not isinstance(v, int) or v not in (0, 1):
+            raise ValueError("fill_value must be 0 or 1")
+        self._fill_value = v
+
+    @property
+    def cols(self) -> int:
+        """Alias for width."""
+        return self._width
+
+    @property
+    def rows(self) -> int:
+        """Alias for height."""
+        return self._height
+
+    @classmethod
+    def load_blank_grid(
+        cls,
+        width:      int = MATRIX_WIDTH,
+        height:     int = MATRIX_HEIGHT,
+        fill_value: int = 0
+    ) -> List[List[int]]:
+        """Return a new blank column-major grid."""
+        return generate_blank_grid(width=width, height=height, fill_value=fill_value)
+
+    @classmethod
+    def from_spec(
+        cls,
+        spec: List[List[int]]
+    ) -> 'Grid':
+        """Instantiate directly from a column-major spec list."""
+        return cls(init_grid=spec)
+
+    @classmethod
+    def from_file(
+        cls,
+        filename: Union[str, Path],
+        frame_number: int = 0,
+        height: int = MATRIX_HEIGHT,
+        width: int = MATRIX_WIDTH
+    ) -> 'Grid':
+        """
+        Load a column-major grid from file (single grid or frames of grids).
+        """
+        from ...helpers import load_from_file
+        raw = load_from_file(str(filename))
+        # Single-grid JSON: list of lists
+        if isinstance(raw, list) and raw and isinstance(raw[0], list):
+            grid_data = raw
+        # Frame-list JSON: list of dicts
+        elif isinstance(raw, list) and all(isinstance(f, dict) for f in raw):
+            frame = raw[frame_number]
+            grid_data = frame.get('grid')
+            if not isinstance(grid_data, list):
+                raise ValueError(f"Frame {frame_number} missing 'grid' list")
+        else:
+            raise ValueError("Unsupported file structure for grid data.")
+
+        if not is_valid_grid(grid_data, width, height):
+            raise ValueError(f"Loaded grid is not {width}×{height} column-major 0/1 list")
+
+        return cls(width=width, height=height, init_grid=grid_data)
+
+    def draw(self, device: Any) -> None:
+        """Draw this grid via device.draw_grid(grid)."""
+        if not hasattr(device, 'draw_grid') or not callable(device.draw_grid):
+            raise AttributeError("device.draw_grid(grid) not available")
+        device.draw_grid(self)
+
+    def get_pixel_value(self, x: int, y: int) -> int:
+        """Return the value at column x, row y."""
+        if x < 0 or x >= self._width or y < 0 or y >= self._height:
+            raise IndexError(f"({x},{y}) out of bounds {self._width}×{self._height}")
+        return self._grid[x][y]
+
+    def get_shifted(
+        self,
+        dx: int = 0,
+        dy: int = 0,
+        wrap: bool = False
+    ) -> 'Grid':
+        """
+        Return a new Grid shifted by (dx, dy):
+          - dx > 0 moves right, dx < 0 moves left
+          - dy > 0 moves down, dy < 0 moves up
+        If wrap=True, shifts wrap around edges; otherwise, out-of-bounds fill with fill_value.
+        """
+        new = generate_blank_grid(self._width, self._height, self._fill_value)
+
+        for c, r in itertools.product(range(self._width), range(self._height)):
+            src_c = (c + dx) % self._width if wrap else c + dx
+            src_r = (r + dy) % self._height if wrap else r + dy
+
+            if 0 <= src_c < self._width and 0 <= src_r < self._height:
+                new[c][r] = self._grid[src_c][src_r]
+
+        return Grid(width=self._width, height=self._height, fill_value=self._fill_value, init_grid=new)
+
+    def __getitem__(self, index: int) -> list[int]:
+        """Allow column-major indexing: grid[col] → list of pixel values down that column."""
+        return self._grid[index]
+
+    def __len__(self) -> int:
+        """Number of columns (i.e. grid width)."""
+        return len(self._grid)
+
+    def __iter__(self):
+        """Iterate over columns."""
+        return iter(self._grid)