IS-Matrix-Forge 1.0.0.dev5__tar.gz → 1.0.0.dev7__tar.gz

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: IS-Matrix-Forge
-Version: 1.0.0.dev5
+Version: 1.0.0.dev7
 Summary: 
 License: MIT
 Keywords: led,matrix,framework,hardware
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: clipboard-support
+Requires-Dist: aliaser (>=1.0.0.dev4,<2.0.0)
 Requires-Dist: chime (>=0.7.0,<0.8.0)
 Requires-Dist: clipboard (>=0.0.4,<0.0.5) ; extra == "clipboard-support"
 Requires-Dist: easy-exit-calls (>=1.0.0.dev1,<2.0.0)
@@ -23,6 +24,7 @@ Requires-Dist: pillow (>=11.2.1,<12.0.0)
 Requires-Dist: pyserial (>=3.5,<4.0)
 Requires-Dist: pysimplegui-4-foss (==4.60.4.1)
 Requires-Dist: pysimpleguiweb (==0.39.0)
+Requires-Dist: requests (>=2.32.4,<3.0.0)
 Project-URL: Homepage, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Project-URL: Repository, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Description-Content-Type: text/markdown

is_matrix_forge-1.0.0.dev7/is_matrix_forge/common/decorators/__init__.py

@@ -0,0 +1,12 @@
+from inspyre_toolbox.syntactic_sweets.classes.decorators import validate_type
+from is_matrix_forge.common.decorators.freeze_setter import freeze_setter
+from is_matrix_forge.led_matrix.errors.misc import ImplicitNameDerivationError
+from aliaser import Aliases
+
+
+__all__ = [
+    'Aliases',
+    'ImplicitNameDerivationError',
+    'freeze_setter',
+    'validate_type',
+]

is_matrix_forge-1.0.0.dev5/is_matrix_forge/common/decorators/__init__.py → is_matrix_forge-1.0.0.dev7/is_matrix_forge/common/decorators/freeze_setter.py

@@ -1,11 +1,6 @@
 import functools
 from typing import Optional, Type, Callable, Any
 
-import functools
-from typing import Optional, Type, Callable, Any
-from inspyre_toolbox.syntactic_sweets.classes.decorators import validate_type
-from is_matrix_forge.led_matrix.errors.misc import ImplicitNameDerivationError
-
 
 def freeze_setter(
     attr_name: Optional[str] = None,
@@ -94,6 +89,8 @@ def freeze_setter(
         - `ImplicitNameDerivationError`: Raised for configuration issues with underscore-prefixed setters.
         - `AttributeError`: Default exception for reassigning a frozen attribute.
     """
+    from is_matrix_forge.led_matrix.errors.misc import ImplicitNameDerivationError
+
     def decorator(setter: Callable) -> Callable:
         setter_name = setter.__name__
 
@@ -143,10 +140,3 @@ def freeze_setter(
         return wrapper
 
     return decorator
-
-
-__all__ = [
-    'ImplicitNameDerivationError',
-    'freeze_setter',
-    'validate_type',
-]

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/is_matrix_forge/led_matrix/controller/controller.py

@@ -26,20 +26,20 @@ from inspyre_toolbox.syntactic_sweets.classes.decorators.aliases import add_alia
 from serial.tools.list_ports_common import ListPortInfo
 
 from is_matrix_forge.common.helpers import coerce_to_int
+from aliaser.metaclass import AliasMeta
 from is_matrix_forge.led_matrix.constants import SLOT_MAP
 from is_matrix_forge.led_matrix.display.text import show_string as _show_string_raw
 from is_matrix_forge.led_matrix.controller import MultitonMeta
 from is_matrix_forge.led_matrix.controller.helpers.threading import synchronized
 from is_matrix_forge.led_matrix.commands.map import CommandVals
-from is_matrix_forge.led_matrix.hardware import send_serial, send_command
+from is_matrix_forge.led_matrix.hardware import send_command
 from is_matrix_forge.led_matrix.display.effects.breather import Breather
 from is_matrix_forge.led_matrix.display.text import show_string
 
 COMMANDS = CommandVals
 
 
-@add_aliases
-class LEDMatrixController(metaclass=MultitonMeta):
+class LEDMatrixController(metaclass=AliasMeta):
     """
     Controller class for LED Matrix devices.
 
@@ -115,6 +115,8 @@ class LEDMatrixController(metaclass=MultitonMeta):
         self.__show_grid_on_init      = None
         self._thread_safe             = None
         self._cmd_lock                = None
+        self._keep_alive              = False
+        self._KEEP_ALIVE_INTERVAL    = 50
 
         self.hold_all = hold_all or False
 
@@ -129,6 +131,7 @@ class LEDMatrixController(metaclass=MultitonMeta):
             self.__init_clear = not skip_init_clear
 
         if init_grid is not None:
+            from is_matrix_forge.led_matrix.display.grid import Grid
             if not isinstance(init_grid, Grid):
                 raise TypeError(f'init_grid must be of type `Grid`, not {type(init_grid)}')
 
@@ -145,13 +148,75 @@ class LEDMatrixController(metaclass=MultitonMeta):
 
         self.__post_init__()
 
+    # ---------------------------------------------------------------------
+    # Keep‑alive internal worker
+    # ---------------------------------------------------------------------
+
+    @synchronized
+    def __keep_alive_worker(self):
+        """Loop until signalled, polling :pyattr:`animating` every 50 s."""
+        # Lazily create the stop event (should already exist, but be safe)
+        stop_evt = self._keep_alive_stop_evt or threading.Event()
+        self._keep_alive_stop_evt = stop_evt
+
+        while not stop_evt.is_set():
+            try:
+                _ = self.animating  # A simple query is enough to keep FW awake
+            except Exception:  # pragma: no cover – we don't crash the thread
+                pass
+
+            # Wait with timeout so the thread can exit early when stop_evt is set
+            stop_evt.wait(self._KEEP_ALIVE_INTERVAL)
+
+    # ---------------------------------------------------------------------
+    # Property controlling the keep‑alive thread
+    # ---------------------------------------------------------------------
+
+    @property
+    def keep_alive(self) -> bool:
+        """Whether the background keep‑alive thread is active."""
+        return self._keep_alive
+
+    @keep_alive.setter
+    def keep_alive(self, enable: bool):
+        if not isinstance(enable, bool):
+            raise TypeError('keep_alive must be a boolean.')
+
+        # No change ➜ nothing to do
+        if enable == self._keep_alive:
+            return
+
+        if enable:
+            # Start background thread
+            self._keep_alive_stop_evt = threading.Event()
+            self._keep_alive_thread = threading.Thread(
+                target=self.__keep_alive_worker,
+                name=f"{self.__class__.__name__}-KeepAlive-{self.device.name}",
+                daemon=True,
+            )
+            self._keep_alive_thread.start()
+            self._keep_alive = True
+        else:
+            # Signal thread to exit and wait (briefly) for it
+            if self._keep_alive_stop_evt is not None:
+                self._keep_alive_stop_evt.set()
+            if (
+                    self._keep_alive_thread is not None
+                    and self._keep_alive_thread.is_alive()
+            ):
+                self._keep_alive_thread.join(timeout=self._KEEP_ALIVE_INTERVAL + 1)
+            self._keep_alive_thread = None
+            self._keep_alive_stop_evt = None
+            self._keep_alive = False
+        self.__post_init__()
+
     def __post_init__(self):
         from is_matrix_forge.led_matrix.display.effects.breather import Breather
 
         self.__breather = Breather(self)
 
         if self.clear_on_init:
-            self.clear()
+            self.clear_matrix()
 
         if self.set_brightness_on_init:
             self.set_brightness(self.__default_brightness)
@@ -184,7 +249,6 @@ class LEDMatrixController(metaclass=MultitonMeta):
             bool: True if the device is animating, False otherwise.
         """
         return bool(send_command(self.device, COMMANDS.Animate, with_response=True)[0])
-        # return animate(self.device)
 
     @property
     def breather(self) -> Breather:
@@ -320,8 +384,12 @@ class LEDMatrixController(metaclass=MultitonMeta):
         return self.location['abbrev']
 
     @property
+    @alias('serial_port', 'port_name')
     def name(self) -> str:
-        return self.__name if self.__name is not None else self.device.name
+        if self.__name is None:
+            self.__name = self.device.name
+
+        return self.__name
 
     def play_animation(self, animation):
         from is_matrix_forge.led_matrix.display.animations.animation import Animation
@@ -344,9 +412,6 @@ class LEDMatrixController(metaclass=MultitonMeta):
             text_animation.loop = True
         return self.play_animation(text_animation)
 
-    def show_text(self, text: str):
-        self.draw_text(text)
-
     @property
     def set_brightness_on_init(self):
         """
@@ -404,6 +469,7 @@ class LEDMatrixController(metaclass=MultitonMeta):
         # The animate function also sets the status to 'animate' when enabled
         animate(self.device, enable)
 
+    @alias('clear')
     @synchronized
     def clear_matrix(self) -> None:
         """
@@ -419,12 +485,7 @@ class LEDMatrixController(metaclass=MultitonMeta):
         grid = Grid(init_grid=data)
         self.draw_grid(grid)
 
-    def clear(self):
-        self.clear_matrix()
-
-    def draw(self, grid: 'Grid' = None) -> None:
-        return self.draw_grid(grid)
-
+    @alias('draw')
     @synchronized
     def draw_grid(self, grid: 'Grid' = None) -> None:
         """
@@ -442,8 +503,8 @@ class LEDMatrixController(metaclass=MultitonMeta):
             grid = Grid(init_grid=grid)
         render_matrix(self.device, grid.grid)
 
+    @alias('pattern', 'show_pattern')
     @synchronized
-    @method_alias('pattern')
     def draw_pattern(self, pattern: str) -> None:
         """
         Draw a pattern on the LED matrix.
@@ -459,6 +520,7 @@ class LEDMatrixController(metaclass=MultitonMeta):
         pattern_pen = BuiltInPatterns(self)
         pattern_pen.render(pattern)
 
+    @alias('display_percentage', 'show_percentage')
     @synchronized
     def draw_percentage(self, percentage: int, clear_first: bool = False):
         from is_matrix_forge.led_matrix.hardware import percentage as _show_percentage_raw
@@ -476,12 +538,6 @@ class LEDMatrixController(metaclass=MultitonMeta):
 
         _show_percentage_raw(self.device, percentage)
 
-    def draw_string(self, text: str):
-        self.show_text(text)
-
-    def draw_text(self, text: str):
-        self.show_text(text)
-
     @synchronized
     def display_location(self):
         """
@@ -613,15 +669,8 @@ class LEDMatrixController(metaclass=MultitonMeta):
         if not __from_setter:
             self.__brightness = brightness
 
-    def show_string(self, text: str) -> None:
-        """
-        Alias for LEDMatrixController.show_text.
-
-        See Also:
-            LEDMatrixController.show_text
-        """
-        self.show_text(text)
 
+    @method_alias('draw_text', 'show_string', 'draw_string')
     @synchronized
     def show_text(self, text: str) -> None:
         """

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/is_matrix_forge/led_matrix/display/animations/__init__.py

@@ -2,6 +2,7 @@ from time import sleep
 
 from is_matrix_forge.led_matrix.hardware import brightness
 from is_matrix_forge.led_matrix.display.text import show_string
+from .audio_visualizer import AudioVisualizer
 
 
 def clear(dev):
@@ -26,3 +27,11 @@ def goodbye_animation(dev):
     checkerboard_cycle(dev)
     sleep(.5)
     show_string(dev, 'Bye')
+
+
+__all__ = [
+    'AudioVisualizer',
+    'clear',
+    'checkerboard_cycle',
+    'goodbye_animation',
+]

is_matrix_forge-1.0.0.dev7/is_matrix_forge/led_matrix/display/animations/audio_visualizer.py

@@ -0,0 +1,124 @@
+"""Real-time audio visualizer for the LED matrix.
+
+This module provides a small utility that streams audio data and renders simple
+bar style visualizations on one or more LED matrix controllers.  By default it
+uses the system microphone for input, however an audio file may also be used as
+the source allowing "regular" audio to be visualized.  ``sounddevice`` and
+``soundfile`` are optional dependencies and the visualiser gracefully degrades
+if they are unavailable.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import Iterable, List, Optional, Union
+
+import numpy as np
+
+try:  # ``sounddevice`` is an optional dependency
+    import sounddevice as sd
+except Exception:  # pragma: no cover - optional dependency missing
+    sd = None  # type: ignore
+
+try:  # ``soundfile`` is also optional
+    import soundfile as sf
+except Exception:  # pragma: no cover - optional dependency missing
+    sf = None  # type: ignore
+
+from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
+from is_matrix_forge.led_matrix.display.animations.frame.base import Frame
+
+
+class AudioVisualizer:
+    """Stream audio data and render a simple bar visualisation."""
+
+    def __init__(
+        self,
+        controllers: Iterable[LEDMatrixController],
+        sample_rate: int = 44_100,
+        chunk_size: int = 1_024,
+        audio_source: Union[str, Path, None] = None,
+        loop_file: bool = True,
+    ) -> None:
+        self.controllers: List[LEDMatrixController] = list(controllers)
+        self.sample_rate = sample_rate
+        self.chunk_size = chunk_size
+        self._stream: Optional[sd.InputStream] = None  # type: ignore[var-annotated]
+        self._thread: Optional[threading.Thread] = None
+        self._running = False
+        self._audio_source: Optional[Path] = Path(audio_source) if audio_source else None
+        self._loop_file = loop_file
+
+    # ------------------------------------------------------------------ utils --
+    def _process_chunk(self, data: np.ndarray) -> None:  # pragma: no cover - real time
+        """Render a frame based on ``data`` samples."""
+        amplitude = float(np.linalg.norm(data) / len(data))
+        bar_height = min(int(amplitude * 34), 34)
+
+        grid = [[0 for _ in range(34)] for _ in range(9)]
+        for x in range(9):
+            for y in range(bar_height):
+                grid[x][33 - y] = 1
+
+        frame = Frame(grid=grid, duration=0.01)
+
+        for ctrl in self.controllers:
+            ctrl.draw_grid(frame.grid)
+
+    def _audio_callback(self, indata, frames, time, status) -> None:  # pragma: no cover - real time
+        if not self._running:
+            return
+        self._process_chunk(indata[:, 0])
+
+    def _file_loop(self) -> None:  # pragma: no cover - requires soundfile
+        assert sf is not None and self._audio_source is not None
+        while self._running:
+            with sf.SoundFile(self._audio_source) as f:
+                while self._running:
+                    data = f.read(self.chunk_size, dtype='float32')
+                    if len(data) == 0:
+                        break
+                    self._process_chunk(data)
+            if not self._loop_file:
+                break
+
+    # ------------------------------------------------------------------- API --
+    def start(self) -> None:
+        if sd is None:  # pragma: no cover - environment without sounddevice
+            raise RuntimeError("sounddevice is required for AudioVisualizer")
+
+        if self._running:
+            return
+
+        self._running = True
+        if self._audio_source is not None:
+            if sf is None:
+                raise RuntimeError("soundfile is required for file playback")
+            self._thread = threading.Thread(target=self._file_loop, daemon=True)
+            self._thread.start()
+        else:
+            self._stream = sd.InputStream(
+                channels=1,
+                samplerate=self.sample_rate,
+                blocksize=self.chunk_size,
+                callback=self._audio_callback,
+            )
+            self._stream.start()
+
+    def stop(self) -> None:
+        if not self._running:
+            return
+
+        self._running = False
+        if self._stream is not None:
+            self._stream.stop()
+            self._stream.close()
+            self._stream = None
+        if self._thread is not None:
+            self._thread.join(timeout=1)
+            self._thread = None
+
+
+__all__ = ["AudioVisualizer"]
+

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/is_matrix_forge/led_matrix/display/effects/breather.py

@@ -1,6 +1,6 @@
 import threading
 import time
-from is_matrix_forge.common.decorators import freeze_setter
+from is_matrix_forge.common.decorators.freeze_setter import freeze_setter
 from is_matrix_forge.log_engine import ROOT_LOGGER, Loggable
 
 

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/is_matrix_forge/led_matrix/display/grid/grid.py

@@ -22,6 +22,7 @@ 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 ...helpers import load_from_file as _helpers_load_from_file
 from is_matrix_forge.common.helpers import coerce_to_int
 
 MATRIX_HEIGHT = __HEIGHT
@@ -35,6 +36,24 @@ This constant defines the default width for new Grid instances and for loading o
 """
 
 
+def load_from_file(
+    path: Union[str, Path],
+    expected_width: Optional[int] | None = None,
+    expected_height: Optional[int] | None = None,
+    fallback_duration: Optional[Union[int, float]] = None,
+) -> Any:
+    """Wrapper around :func:`is_matrix_forge.led_matrix.helpers.load_from_file`.
+
+    Exists primarily for unit tests which monkeypatch this function directly.
+    """
+    return _helpers_load_from_file(
+        path,
+        expected_width,
+        expected_height,
+        fallback_duration,
+    )
+
+
 class Grid:
     """
     Represents a 2D column-major grid for the LED display (grid[x][y], 9×34).
@@ -127,8 +146,18 @@ class Grid:
         cls,
         spec: List[List[int]]
     ) -> 'Grid':
-        """Instantiate directly from a column-major spec list."""
-        return cls(init_grid=spec)
+        """Instantiate directly from a column-major spec list.
+
+        The dimensions of the grid are inferred from ``spec`` so tests can
+        provide arbitrary sized grids.
+        """
+        width = len(spec)
+        height = len(spec[0]) if spec else 0
+        if not is_valid_grid(spec, width, height):
+            raise ValueError(
+                f"init_grid must be {width}×{height} column-major 0/1 list"
+            )
+        return cls(width=width, height=height, init_grid=spec)
 
     @classmethod
     def from_file(
@@ -141,10 +170,16 @@ class 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):
+        if (
+            isinstance(raw, list)
+            and raw
+            and isinstance(raw[0], list)
+            and is_valid_grid(raw[0], width, height)
+        ):
+            grid_data = raw[0]
+        elif 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):
@@ -187,11 +222,11 @@ class Grid:
         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
+            dest_c = (c + dx) % self._width if wrap else c + dx
+            dest_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]
+            if 0 <= dest_c < self._width and 0 <= dest_r < self._height:
+                new[dest_c][dest_r] = self._grid[c][r]
 
         return Grid(width=self._width, height=self._height, fill_value=self._fill_value, init_grid=new)
 

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/is_matrix_forge/led_matrix/helpers/device.py

@@ -7,6 +7,7 @@ including functions to convert between different device location formats.
 from serial import Serial, SerialException
 from serial.tools import list_ports
 from is_matrix_forge.log_engine import ROOT_LOGGER
+from is_matrix_forge.led_matrix.constants import VID as EXPECTED_VID, PID as EXPECTED_PID
 
 
 MOD_LOGGER = ROOT_LOGGER.get_child('led_matrix.helpers.device')

{is_matrix_forge-1.0.0.dev5 → is_matrix_forge-1.0.0.dev7}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "IS-Matrix-Forge"
-version = "1.0.0-dev.5"
+version = "1.0.0-dev.7"
 description = ""
 authors = ["Taylor B. <t.blackstone@inspyre.tech>"]
 readme = "README.md"
@@ -31,6 +31,8 @@ clipboard = { version = "^0.0.4", optional = true }
 pysimplegui-4-foss = "==4.60.4.1"
 pysimpleguiweb = "==0.39.0"
 imapclient = "==3.0.1"
+requests = "^2.32.4"
+aliaser = "^1.0.0.dev4"
 
 [tool.poetry.extras]
 clipboard_support = ["clipboard"]
@@ -44,7 +46,8 @@ ipyboost = { version = "1.0.0.a3", source = "testpypi" }
 [tool.poetry.scripts]
 python-path = "Scripts.python_path:main"
 led-matrix-identify = "is_matrix_forge.led_matrix.Scripts.identify_matrices:main"
-install-presets = "Scripts.install_presets:main"
+install-presets = "is_matrix_forge.led_matrix.Scripts.install_presets.main:main"
+pixel-grid = "is_matrix_forge.designer_gui.main_window:main"
 
 [[tool.poetry.include]]
 path = "presets/**"