IS-Matrix-Forge 1.0.0.dev27__tar.gz → 1.0.0.dev30__tar.gz

{is_matrix_forge-1.0.0.dev27 → is_matrix_forge-1.0.0.dev30}/LICENSE.md

@@ -1,7 +1,7 @@
 Copyright (c) 2025 Inspyre-Softworks
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software (led-matrix-battery) and associated documentation files (the "Software"), to deal
+of this software (IS-Matrix-Forge) 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

{is_matrix_forge-1.0.0.dev27 → is_matrix_forge-1.0.0.dev30}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: IS-Matrix-Forge
-Version: 1.0.0.dev27
+Version: 1.0.0.dev30
 Summary: 
 License: MIT
+License-File: LICENSE.md
 Keywords: led,matrix,framework,hardware
 Author: Taylor B.
 Author-email: t.blackstone@inspyre.tech
@@ -11,6 +12,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: clipboard-support
 Requires-Dist: aliaser (>=1.0.0.dev4,<2.0.0)
 Requires-Dist: chime (>=0.7.0,<0.8.0)
@@ -22,12 +24,13 @@ Requires-Dist: inspyre-toolbox (>=1.6.0.dev23)
 Requires-Dist: ipywidgets (==8.1.7)
 Requires-Dist: notebook (>=7.4.4,<8.0.0)
 Requires-Dist: opencv-python (>=4.11.0.86,<5.0.0.0)
-Requires-Dist: pillow (>=11.2.1,<12.0.0)
-Requires-Dist: psutil (==6.1.1)
+Requires-Dist: pillow (>=12.0.0,<13.0.0)
+Requires-Dist: platformdirs (>=4.5.0,<5.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)
+Requires-Dist: rich (>=13.9.4,<15)
 Requires-Dist: wmi (>=1.5.1,<2.0.0) ; sys_platform == "win32"
 Project-URL: Homepage, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Project-URL: Repository, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
@@ -41,22 +44,32 @@ Description-Content-Type: text/markdown
 
 **IS Matrix Forge** is a Python framework for creating applications that drive
 9×34 LED matrix displays.  It provides high level helpers for talking to the
-hardware, tools for building animations, and utilities such as progress bars and
-a battery monitor.
-
-## Project Overview
-
-Matrix Forge grew out of the LED Matrix Battery Monitor project.  The goal is to
-make it easy to create rich LED matrix experiences from Python.  In addition to
-monitoring the battery, you can design custom frames, display scrolling text,
-run animations, and integrate the LED matrix with your own applications.
-
-Highlighted features include:
-- Device discovery and control via `pyserial`
-- Drawing grids and patterns with the `Grid` class
-- Built-in and custom animations
-- Progress bars that render on the matrix
-- A battery monitor example using these building blocks
+hardware, tools for building animations, and utilities such as progress bars.
+
+## Features
+
+- **Hardware control** — device discovery and control over serial via
+  `pyserial`, with support for multiple connected matrices
+- **Mixin-based controller** — `LEDMatrixController` composes device access,
+  keep-alive pings, brightness and "breather" management, device
+  identification, and command history with restore support; optional
+  `thread_safe=True` mode guards device operations behind an `RLock`
+- **Display engine** — draw grids and patterns with the `Grid` class, build
+  frame-based `Animation`s (rewind, fast-forward, seek), and scroll text
+  horizontally or vertically with `TextScroller` and bitmap font maps
+- **Firmware games** — launch Snake, Pong, Tetris, and Game of Life
+  (with classic start patterns like glider, blinker, and toad) on the matrix
+- **Audio tools** — notification sounds via
+  `is_matrix_forge.notify.sounds` and an
+  optional `AudioVisualizer` in
+  `is_matrix_forge.led_matrix.display.animations.audio_visualizer` for live
+  input and audio files
+- **Designer tools** — a PySimpleGUI desktop designer, a JSON preset system
+  with verified installs, and an optional Streamlit web-based pixel-grid
+  animation editor
+- **Progress bars** — a `tqdm`-style helper that renders progress on the matrix
+- **CLI** — `led-matrix` console entry point with a threaded
+  `identify-matrices` subcommand that identifies connected devices concurrently
 
 ## Hardware Requirements
 
@@ -77,10 +90,23 @@ This project requires Python 3.12 or newer and the following dependencies:
 - inspyre-toolbox (>=1.6.0) - Utility functions
 - pillow (>=11.2.1,<12.0.0) - Image processing
 - opencv-python (>=4.11.0.86,<5.0.0.0) - Image processing
-- pysimplegui-4-foss (>=4.60.4.1,<5.0.0.0) - GUI components
-- tk (>=0.1.0,<0.2.0) - GUI toolkit
-- easy-exit-calls (>=1.0.0.dev1,<2.0.0) - Exit handling
-- psutil - For battery status monitoring
+
+### Optional Tool Dependencies
+
+The Streamlit editor and audio visualizer are included in the source tree but
+their third-party dependencies are not installed by `poetry install` or
+`pip install .`. Install only the dependencies for the tools you intend to use:
+
+```shell
+# Streamlit pixel-grid editor
+pip install streamlit
+
+# Audio visualizer (live input and audio-file playback)
+pip install sounddevice soundfile
+```
+
+When using Poetry, run these commands after `poetry shell` so the packages are
+installed in the project's virtual environment.
 
 ## Installation Instructions
 
@@ -136,6 +162,31 @@ ctrl = LEDMatrixController(DEVICES[0])
 ctrl.scroll_text("Hello World!", loop=False)
 ```
 
+### Navigate an Animation
+
+```python
+from is_matrix_forge.led_matrix.display.animations.animation import Animation
+from is_matrix_forge.led_matrix.display.animations.frame.base import Frame
+
+animation = Animation(
+    frame_data=[
+        Frame(grid=[[1]], duration=0.1, width=1, height=1),
+        Frame(grid=[[0]], duration=0.1, width=1, height=1),
+        Frame(grid=[[1]], duration=0.1, width=1, height=1),
+    ]
+)
+
+animation.fast_forward()   # jump all the way to the last frame
+animation.rewind()         # jump all the way back to the first frame
+animation.fast_forward(2)  # move ahead two frames from the current cursor
+animation.rewind(1)        # move back one frame from the current cursor
+animation.seek(0)          # jump to an absolute frame index
+```
+
+`Animation.rewind()` and `Animation.fast_forward()` use relative step counts.
+Passing `0` or omitting the argument jumps to the beginning/end respectively.
+Use `Animation.seek(index)` when you want to jump to an absolute frame index.
+
 ## Controller Architecture
 
 - Composition is implemented via multiple mixins that all use cooperative
@@ -166,16 +217,6 @@ for _ in tqdm(range(100)):
     time.sleep(0.05)
 ```
 
-### Battery Monitor Example
-
-```python
-from is_matrix_forge.monitor import run_power_monitor
-from is_matrix_forge.led_matrix.helpers.device import DEVICES
-
-device = DEVICES[0]
-run_power_monitor(device)
-```
-
 ## Troubleshooting
 
 ### LED Matrix Not Detected
@@ -191,12 +232,6 @@ run_power_monitor(device)
 2. Check that the WAV files for notifications exist in the expected locations.
 3. Verify that the chime library is properly installed.
 
-### Battery Status Not Updating
-
-1. Make sure psutil is properly installed.
-2. Check that your system supports battery status monitoring through psutil.
-3. Try increasing the battery_check_interval to reduce CPU usage.
-
 ### Animation Issues
 
 1. Verify that the LED matrix is functioning correctly.

{is_matrix_forge-1.0.0.dev27 → is_matrix_forge-1.0.0.dev30}/README.md

@@ -6,22 +6,32 @@
 
 **IS Matrix Forge** is a Python framework for creating applications that drive
 9×34 LED matrix displays.  It provides high level helpers for talking to the
-hardware, tools for building animations, and utilities such as progress bars and
-a battery monitor.
-
-## Project Overview
-
-Matrix Forge grew out of the LED Matrix Battery Monitor project.  The goal is to
-make it easy to create rich LED matrix experiences from Python.  In addition to
-monitoring the battery, you can design custom frames, display scrolling text,
-run animations, and integrate the LED matrix with your own applications.
-
-Highlighted features include:
-- Device discovery and control via `pyserial`
-- Drawing grids and patterns with the `Grid` class
-- Built-in and custom animations
-- Progress bars that render on the matrix
-- A battery monitor example using these building blocks
+hardware, tools for building animations, and utilities such as progress bars.
+
+## Features
+
+- **Hardware control** — device discovery and control over serial via
+  `pyserial`, with support for multiple connected matrices
+- **Mixin-based controller** — `LEDMatrixController` composes device access,
+  keep-alive pings, brightness and "breather" management, device
+  identification, and command history with restore support; optional
+  `thread_safe=True` mode guards device operations behind an `RLock`
+- **Display engine** — draw grids and patterns with the `Grid` class, build
+  frame-based `Animation`s (rewind, fast-forward, seek), and scroll text
+  horizontally or vertically with `TextScroller` and bitmap font maps
+- **Firmware games** — launch Snake, Pong, Tetris, and Game of Life
+  (with classic start patterns like glider, blinker, and toad) on the matrix
+- **Audio tools** — notification sounds via
+  `is_matrix_forge.notify.sounds` and an
+  optional `AudioVisualizer` in
+  `is_matrix_forge.led_matrix.display.animations.audio_visualizer` for live
+  input and audio files
+- **Designer tools** — a PySimpleGUI desktop designer, a JSON preset system
+  with verified installs, and an optional Streamlit web-based pixel-grid
+  animation editor
+- **Progress bars** — a `tqdm`-style helper that renders progress on the matrix
+- **CLI** — `led-matrix` console entry point with a threaded
+  `identify-matrices` subcommand that identifies connected devices concurrently
 
 ## Hardware Requirements
 
@@ -42,10 +52,23 @@ This project requires Python 3.12 or newer and the following dependencies:
 - inspyre-toolbox (>=1.6.0) - Utility functions
 - pillow (>=11.2.1,<12.0.0) - Image processing
 - opencv-python (>=4.11.0.86,<5.0.0.0) - Image processing
-- pysimplegui-4-foss (>=4.60.4.1,<5.0.0.0) - GUI components
-- tk (>=0.1.0,<0.2.0) - GUI toolkit
-- easy-exit-calls (>=1.0.0.dev1,<2.0.0) - Exit handling
-- psutil - For battery status monitoring
+
+### Optional Tool Dependencies
+
+The Streamlit editor and audio visualizer are included in the source tree but
+their third-party dependencies are not installed by `poetry install` or
+`pip install .`. Install only the dependencies for the tools you intend to use:
+
+```shell
+# Streamlit pixel-grid editor
+pip install streamlit
+
+# Audio visualizer (live input and audio-file playback)
+pip install sounddevice soundfile
+```
+
+When using Poetry, run these commands after `poetry shell` so the packages are
+installed in the project's virtual environment.
 
 ## Installation Instructions
 
@@ -80,7 +103,7 @@ This project requires Python 3.12 or newer and the following dependencies:
    pip install .
    ```
 
-## Usage Examples
+## Usage Examples
 
 ### Identify Connected Devices
 
@@ -98,28 +121,53 @@ from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
 
 ctrl = LEDMatrixController(DEVICES[0])
-ctrl.scroll_text("Hello World!", loop=False)
-```
-
-## Controller Architecture
-
-- Composition is implemented via multiple mixins that all use cooperative
-  initialization with `super()`.
-- MRO ordering ensures safe access patterns during `__init__`:
-  - `DeviceBase` initializes early so mixins can use `self.device`.
-  - `BrightnessManager` precedes `BreatherManager` because the breather inspects
-    brightness at init time.
-  - `BreatherManager` precedes `IdentifyManager` because `IdentifyManager` may
-    call `@synchronized` methods in `__init__` that rely on a breather pause context.
-  - `Loggable` is placed last so the cooperative chain can pass `logger=` safely.
-- Thread safety: pass `thread_safe=True` to enable an internal `RLock` used by
-  the `@synchronized` decorator for device operations.
-- Logging: integrates with InspyLogger when available and falls back to a simple
-  logger; the controller passes `parent_log_device` through the cooperative chain
-  and the fallback stub supports it.
-
-MRO diagram (left → right, init order)
-`DeviceBase → KeepAliveManager → AnimationManager → DrawingManager → BrightnessManager → BreatherManager → IdentifyManager → Loggable`
+ctrl.scroll_text("Hello World!", loop=False)
+```
+
+### Navigate an Animation
+
+```python
+from is_matrix_forge.led_matrix.display.animations.animation import Animation
+from is_matrix_forge.led_matrix.display.animations.frame.base import Frame
+
+animation = Animation(
+    frame_data=[
+        Frame(grid=[[1]], duration=0.1, width=1, height=1),
+        Frame(grid=[[0]], duration=0.1, width=1, height=1),
+        Frame(grid=[[1]], duration=0.1, width=1, height=1),
+    ]
+)
+
+animation.fast_forward()   # jump all the way to the last frame
+animation.rewind()         # jump all the way back to the first frame
+animation.fast_forward(2)  # move ahead two frames from the current cursor
+animation.rewind(1)        # move back one frame from the current cursor
+animation.seek(0)          # jump to an absolute frame index
+```
+
+`Animation.rewind()` and `Animation.fast_forward()` use relative step counts.
+Passing `0` or omitting the argument jumps to the beginning/end respectively.
+Use `Animation.seek(index)` when you want to jump to an absolute frame index.
+
+## Controller Architecture
+
+- Composition is implemented via multiple mixins that all use cooperative
+  initialization with `super()`.
+- MRO ordering ensures safe access patterns during `__init__`:
+  - `DeviceBase` initializes early so mixins can use `self.device`.
+  - `BrightnessManager` precedes `BreatherManager` because the breather inspects
+    brightness at init time.
+  - `BreatherManager` precedes `IdentifyManager` because `IdentifyManager` may
+    call `@synchronized` methods in `__init__` that rely on a breather pause context.
+  - `Loggable` is placed last so the cooperative chain can pass `logger=` safely.
+- Thread safety: pass `thread_safe=True` to enable an internal `RLock` used by
+  the `@synchronized` decorator for device operations.
+- Logging: integrates with InspyLogger when available and falls back to a simple
+  logger; the controller passes `parent_log_device` through the cooperative chain
+  and the fallback stub supports it.
+
+MRO diagram (left → right, init order)
+`DeviceBase → KeepAliveManager → AnimationManager → DrawingManager → BrightnessManager → BreatherManager → IdentifyManager → Loggable`
 
 ### Progress Bars
 
@@ -131,16 +179,6 @@ for _ in tqdm(range(100)):
     time.sleep(0.05)
 ```
 
-### Battery Monitor Example
-
-```python
-from is_matrix_forge.monitor import run_power_monitor
-from is_matrix_forge.led_matrix.helpers.device import DEVICES
-
-device = DEVICES[0]
-run_power_monitor(device)
-```
-
 ## Troubleshooting
 
 ### LED Matrix Not Detected
@@ -156,35 +194,29 @@ run_power_monitor(device)
 2. Check that the WAV files for notifications exist in the expected locations.
 3. Verify that the chime library is properly installed.
 
-### Battery Status Not Updating
-
-1. Make sure psutil is properly installed.
-2. Check that your system supports battery status monitoring through psutil.
-3. Try increasing the battery_check_interval to reduce CPU usage.
-
 ### Animation Issues
 
 1. Verify that the LED matrix is functioning correctly.
 2. Check that the matrix dimensions match the expected 9x34 size.
 3. Try clearing the matrix and restarting the application.
 
-## Contributing
-
-Contributions are welcome! If you have ideas or improvements for Matrix Forge,
-feel free to open an issue or submit a pull request.
-
-- See docs/contributing-mixins.md for guidance on authoring new controller mixins
-  using cooperative initialization and the `@synchronized` decorator.
-  A minimal reference mixin is available at
-  `is_matrix_forge/led_matrix/controller/components/example_template.py`.
-
-Quick checklist for a new controller mixin
-- Create `is_matrix_forge/led_matrix/controller/components/<name>.py` with `ClassNameManager`.
-- In `__init__(...)`, accept keyword-only args and call `super().__init__(**kwargs)`.
-- Avoid IO-heavy work in `__init__`; use `@synchronized` for device methods.
-- If calling synchronized methods in `__init__`, ensure MRO places you after `BreatherManager`.
-- If adding to the main controller, place after `DeviceBase` and before `IdentifyManager`; consider dependencies.
-- Provide docstrings, type hints, and a small usage example or test.
+## Contributing
+
+Contributions are welcome! If you have ideas or improvements for Matrix Forge,
+feel free to open an issue or submit a pull request.
+
+- See docs/contributing-mixins.md for guidance on authoring new controller mixins
+  using cooperative initialization and the `@synchronized` decorator.
+  A minimal reference mixin is available at
+  `is_matrix_forge/led_matrix/controller/components/example_template.py`.
+
+Quick checklist for a new controller mixin
+- Create `is_matrix_forge/led_matrix/controller/components/<name>.py` with `ClassNameManager`.
+- In `__init__(...)`, accept keyword-only args and call `super().__init__(**kwargs)`.
+- Avoid IO-heavy work in `__init__`; use `@synchronized` for device methods.
+- If calling synchronized methods in `__init__`, ensure MRO places you after `BreatherManager`.
+- If adding to the main controller, place after `DeviceBase` and before `IdentifyManager`; consider dependencies.
+- Provide docstrings, type hints, and a small usage example or test.
 
 ## License
 

is_matrix_forge-1.0.0.dev30/is_matrix_forge/__init__.py

@@ -0,0 +1,19 @@
+"""Top-level package for IS Matrix Forge.
+
+Keep package imports lightweight so submodules can be imported in isolation
+without eagerly initializing the full controller stack.
+"""
+
+from __future__ import annotations
+
+__all__ = ["get_controllers"]
+
+
+def __getattr__(name: str):
+    if name == "get_controllers":
+        from is_matrix_forge.led_matrix.controller import get_controllers
+
+        globals()["get_controllers"] = get_controllers
+        return get_controllers
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{is_matrix_forge-1.0.0.dev27 → is_matrix_forge-1.0.0.dev30}/is_matrix_forge/assets/font_map/base.py

@@ -20,8 +20,8 @@ from dataclasses import dataclass
 from typing import Any, Dict, Iterable, Optional, Tuple, Callable
 
 from inspyre_toolbox.syntactic_sweets.classes import validate_type
-from .models.glyph import Glyph
-from .helpers import load_builtin_char_map, get_ignore_case, has_key_ignore_case
+from is_matrix_forge.assets.font_map.models.glyph import Glyph
+from is_matrix_forge.assets.font_map.helpers import load_builtin_char_map, get_ignore_case, has_key_ignore_case
 
 
 @dataclass(init=False, slots=True)

is_matrix_forge-1.0.0.dev30/is_matrix_forge/common/dirs.py

@@ -0,0 +1,27 @@
+"""
+Directory configuration for the IS-Matrix-Forge application.
+
+This module provides platform-specific directory paths for storing application
+data, configuration files, and other resources using the platformdirs library.
+
+``PRESETS_DIR`` is derived from :class:`~is_matrix_forge.common.preset_config.PresetConfig`
+so that any user-configured preset location is always honoured.
+"""
+
+from platformdirs import PlatformDirs
+
+from is_matrix_forge.common.preset_config import get_preset_config
+
+
+APP_DIRS = PlatformDirs('IS-Matrix-Forge', appauthor='Inspyre Softworks')
+APP_DIR  = APP_DIRS.user_data_path
+
+# Read the user-configured preset directory; falls back to APP_DIR/presets.
+PRESETS_DIR = get_preset_config().presets_dir
+
+
+__all__ = [
+    'APP_DIRS',
+    'APP_DIR',
+    'PRESETS_DIR',
+]

{is_matrix_forge-1.0.0.dev27 → is_matrix_forge-1.0.0.dev30}/is_matrix_forge/common/helpers/github_api.py

@@ -5,7 +5,7 @@ Author:
     Inspyre Softworks
 
 Project:
-    led-matrix-battery
+    IS-Matrix-Forge
 
 File: 
     is_matrix_forge/common/helpers/github_api.py