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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: IS-Matrix-Forge
-Version: 1.0.0.dev2
+Version: 1.0.0.dev5
 Summary: 
 License: MIT
 Keywords: led,matrix,framework,hardware
@@ -15,27 +15,42 @@ Provides-Extra: clipboard-support
 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)
+Requires-Dist: imapclient (==3.0.1)
 Requires-Dist: inspy-logger (>=3.2.3,<4.0.0)
 Requires-Dist: inspyre-toolbox (>=1.6.0.dev23)
 Requires-Dist: opencv-python (>=4.11.0.86,<5.0.0.0)
 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)
+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
 
-# LED Matrix Battery Monitor
+[![PyPI version](https://img.shields.io/pypi/v/IS-Matrix-Forge)](https://pypi.org/project/IS-Matrix-Forge)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/IS-Matrix-Forge)
 
-A Python application that displays your computer's battery status on an LED matrix display. The application monitors battery level and power state, providing visual feedback on an LED matrix and audio notifications when power is plugged or unplugged.
 
-## Project Description and Purpose
+# IS Matrix Forge
 
-The LED Matrix Battery Monitor is designed to provide a visual representation of your computer's battery status on an external LED matrix display. It serves as a convenient way to monitor battery levels without having to check your computer's status bar, especially useful for setups where the status bar might not be visible or when you want a more noticeable indicator.
+**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.
 
-Key features:
-- Real-time battery level display on an LED matrix
-- Visual animations when power is plugged in
-- Audio notifications when power state changes (plugged/unplugged)
-- Configurable checking intervals
-- Support for multiple LED matrices
+## 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 Requirements
 
@@ -67,8 +82,8 @@ This project requires Python 3.12 or newer and the following dependencies:
 
 1. Clone the repository:
    ```
-   git clone https://github.com/Inspyre-Softworks/led-matrix-battery.git
-   cd led-matrix-battery
+   git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
+   cd IS-Matrix-Forge
    ```
 
 2. Install dependencies using Poetry:
@@ -85,8 +100,8 @@ This project requires Python 3.12 or newer and the following dependencies:
 
 1. Clone the repository:
    ```
-   git clone https://github.com/Inspyre-Softworks/led-matrix-battery.git
-   cd led-matrix-battery
+   git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
+   cd IS-Matrix-Forge
    ```
 
 2. Install the package:
@@ -96,60 +111,43 @@ This project requires Python 3.12 or newer and the following dependencies:
 
 ## Usage Examples
 
-### Basic Usage
-
-To start monitoring your battery with default settings:
+### Identify Connected Devices
 
 ```python
-from is_matrix_forge.monitor import run_power_monitor
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
 
-# Get the first available LED matrix device
-device = DEVICES[0]
-
-# Start monitoring with default settings
-run_power_monitor(device)
+for dev in DEVICES:
+    print(dev)
 ```
 
-### Custom Configuration
-
-To customize the monitoring behavior:
+### Display Text on the Matrix
 
 ```python
-from is_matrix_forge.monitor import run_power_monitor
+from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
-from pathlib import Path
 
-# Get the first available LED matrix device
-device = DEVICES[0]
-
-# Custom sound files
-plugged_sound = Path("path/to/custom_plugged_sound.wav")
-unplugged_sound = Path("path/to/custom_unplugged_sound.wav")
-
-# Start monitoring with custom settings
-run_power_monitor(
-    device,
-    battery_check_interval=10,  # Check every 10 seconds
-    plugged_alert=plugged_sound,
-    unplugged_alert=unplugged_sound
-)
+ctrl = LEDMatrixController(DEVICES[0])
+ctrl.scroll_text("Hello World!", loop=False)
 ```
 
-### Running in a Thread
+### Progress Bars
+
+```python
+import time
+from is_matrix_forge.progress import tqdm
+
+for _ in tqdm(range(100)):
+    time.sleep(0.05)
+```
 
-To run the monitor in a background thread:
+### Battery Monitor Example
 
 ```python
-from is_matrix_forge.monitor import run_power_monitor_threaded
+from is_matrix_forge.monitor import run_power_monitor
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
 
-# Get the first available LED matrix device
 device = DEVICES[0]
-
-# Start monitoring in a background thread
-monitor = run_power_monitor_threaded(device)
-# ``monitor`` is a :class:`threading.Thread` instance
+run_power_monitor(device)
 ```
 
 ## Troubleshooting
@@ -181,8 +179,10 @@ monitor = run_power_monitor_threaded(device)
 
 ## Contributing
 
-Contributions to the LED Matrix Battery Monitor are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! If you have ideas or improvements for Matrix Forge,
+feel free to open an issue or submit a pull request.
 
 ## License
 
 This project is licensed under the MIT License - see the LICENSE.md file for details.
+

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/README.md

@@ -1,17 +1,27 @@
-# LED Matrix Battery Monitor
+[![PyPI version](https://img.shields.io/pypi/v/IS-Matrix-Forge)](https://pypi.org/project/IS-Matrix-Forge)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/IS-Matrix-Forge)
 
-A Python application that displays your computer's battery status on an LED matrix display. The application monitors battery level and power state, providing visual feedback on an LED matrix and audio notifications when power is plugged or unplugged.
 
-## Project Description and Purpose
+# IS Matrix Forge
 
-The LED Matrix Battery Monitor is designed to provide a visual representation of your computer's battery status on an external LED matrix display. It serves as a convenient way to monitor battery levels without having to check your computer's status bar, especially useful for setups where the status bar might not be visible or when you want a more noticeable indicator.
+**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.
 
-Key features:
-- Real-time battery level display on an LED matrix
-- Visual animations when power is plugged in
-- Audio notifications when power state changes (plugged/unplugged)
-- Configurable checking intervals
-- Support for multiple LED matrices
+## 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 Requirements
 
@@ -43,8 +53,8 @@ This project requires Python 3.12 or newer and the following dependencies:
 
 1. Clone the repository:
    ```
-   git clone https://github.com/Inspyre-Softworks/led-matrix-battery.git
-   cd led-matrix-battery
+   git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
+   cd IS-Matrix-Forge
    ```
 
 2. Install dependencies using Poetry:
@@ -61,8 +71,8 @@ This project requires Python 3.12 or newer and the following dependencies:
 
 1. Clone the repository:
    ```
-   git clone https://github.com/Inspyre-Softworks/led-matrix-battery.git
-   cd led-matrix-battery
+   git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
+   cd IS-Matrix-Forge
    ```
 
 2. Install the package:
@@ -72,60 +82,43 @@ This project requires Python 3.12 or newer and the following dependencies:
 
 ## Usage Examples
 
-### Basic Usage
-
-To start monitoring your battery with default settings:
+### Identify Connected Devices
 
 ```python
-from is_matrix_forge.monitor import run_power_monitor
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
 
-# Get the first available LED matrix device
-device = DEVICES[0]
-
-# Start monitoring with default settings
-run_power_monitor(device)
+for dev in DEVICES:
+    print(dev)
 ```
 
-### Custom Configuration
-
-To customize the monitoring behavior:
+### Display Text on the Matrix
 
 ```python
-from is_matrix_forge.monitor import run_power_monitor
+from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
-from pathlib import Path
 
-# Get the first available LED matrix device
-device = DEVICES[0]
-
-# Custom sound files
-plugged_sound = Path("path/to/custom_plugged_sound.wav")
-unplugged_sound = Path("path/to/custom_unplugged_sound.wav")
-
-# Start monitoring with custom settings
-run_power_monitor(
-    device,
-    battery_check_interval=10,  # Check every 10 seconds
-    plugged_alert=plugged_sound,
-    unplugged_alert=unplugged_sound
-)
+ctrl = LEDMatrixController(DEVICES[0])
+ctrl.scroll_text("Hello World!", loop=False)
 ```
 
-### Running in a Thread
+### Progress Bars
 
-To run the monitor in a background thread:
+```python
+import time
+from is_matrix_forge.progress import tqdm
+
+for _ in tqdm(range(100)):
+    time.sleep(0.05)
+```
+
+### Battery Monitor Example
 
 ```python
-from is_matrix_forge.monitor import run_power_monitor_threaded
+from is_matrix_forge.monitor import run_power_monitor
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
 
-# Get the first available LED matrix device
 device = DEVICES[0]
-
-# Start monitoring in a background thread
-monitor = run_power_monitor_threaded(device)
-# ``monitor`` is a :class:`threading.Thread` instance
+run_power_monitor(device)
 ```
 
 ## Troubleshooting
@@ -157,8 +150,9 @@ monitor = run_power_monitor_threaded(device)
 
 ## Contributing
 
-Contributions to the LED Matrix Battery Monitor are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! If you have ideas or improvements for Matrix Forge,
+feel free to open an issue or submit a pull request.
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE.md file for details.
+This project is licensed under the MIT License - see the LICENSE.md file for details.

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/__init__.py

@@ -3,6 +3,6 @@ Author: Taylor B. tayjaybabee@gmail.com
 Date: 2025-04-15 09:15:25
 LastEditors: Taylor B. tayjaybabee@gmail.com
 LastEditTime: 2025-04-15 09:24:40
-FilePath: is_matrix_forge/__init__.py
+FilePath: is_matrix_forge/grid.py
 Description: 这是默认设置,可以在设置》工具》File Description中进行配置
 """

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/assets/__init__.py

@@ -3,6 +3,6 @@ Author: Taylor B. tayjaybabee@gmail.com
 Date: 2025-04-15 09:15:37
 LastEditors: Taylor B. tayjaybabee@gmail.com
 LastEditTime: 2025-04-15 09:24:40
-FilePath: is_matrix_forge/assets/__init__.py
+FilePath: is_matrix_forge/assets/grid.py
 Description: 这是默认设置,可以在设置》工具》File Description中进行配置
 """

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/common/helpers/__init__.py

@@ -3,6 +3,10 @@ from pathlib import Path
 from typing import Optional
 import requests
 from inspyre_toolbox.path_man import provision_path
+from is_matrix_forge.log_engine import ROOT_LOGGER
+
+
+MOD_LOGGER = ROOT_LOGGER.get_child(__name__)
 
 
 def download_presets():
@@ -24,9 +28,13 @@ def calculate_checksum(file_path):
         str:
             The SHA-256 checksum of the file.
     """
+    log = MOD_LOGGER.get_child('calculate_checksum')
+
     if not isinstance(file_path, Path):
         file_path = provision_path(file_path)
 
+    log.debug(f'Calculating checksum for file: {file_path}')
+
     sha256 = hashlib.sha256()
 
     with open(file_path, 'rb') as f:
@@ -78,6 +86,30 @@ def percentage_to_value(percent, max_value=255):
     return int(round(percent * max_value / 100))
 
 
+def value_to_percentage(value, max_value=255):
+    """
+    Convert a value to its percentage representation relative to `max_value`.
+
+    Parameters:
+        value (int or float):
+            The value to convert.
+
+        max_value (int, optional):
+            The maximum possible value. Defaults to 255.
+
+    Returns:
+        float:
+            The percentage value between 0 and 100.
+    """
+    if not isinstance(value, (int, float)):
+        raise TypeError(f'value must be of type int or float, not {type(value)}')
+
+    if value < 0 or value > max_value:
+        raise ValueError(f'value must be between 0 and {max_value}, not {value}')
+
+    return (value / max_value) * 100
+
+
 def verify_checksum(remote_checksum, local_file_path):
     """
     Verify the checksum of a local file against a remote checksum.

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/designer_gui/__init__.py

@@ -3,6 +3,6 @@ Author: Taylor B. tayjaybabee@gmail.com
 Date: 2025-04-30 16:01:10
 LastEditors: Taylor B. tayjaybabee@gmail.com
 LastEditTime: 2025-04-30 16:01:49
-FilePath: is_matrix_forge/designer_gui/__init__.py
+FilePath: is_matrix_forge/designer_gui/grid.py
 Description: 这是默认设置,可以在设置》工具》File Description中进行配置
 """

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/designer_gui/main_window/__init__.py

@@ -4,12 +4,15 @@ import PySimpleGUI as sg
 import copy
 import os
 
-from ...led_matrix.helpers.device import DEVICES
+from is_matrix_forge.led_matrix.helpers.device import DEVICES
 from is_matrix_forge.led_matrix.display.animations.frame.base import Frame
 from is_matrix_forge.led_matrix.display.grid.helpers import is_valid_grid
 from is_matrix_forge.led_matrix.display.animations.frame.helpers import is_valid_frames
-from .layout import PixelGridLayout
-from is_matrix_forge.led_matrix import render_matrix
+from is_matrix_forge.designer_gui.main_window.layout import PixelGridLayout
+from is_matrix_forge.led_matrix.display.helpers import render_matrix
+
+
+sg.theme('DarkTeal2')
 
 
 def _normalize(key: Any) -> str:
@@ -139,6 +142,7 @@ class PixelGrid:
     def _toggle_pixel(self, key: Tuple[int, int]) -> None:
         col, row = key
         new = 1 - self.grid[col][row]
+        print(f'Pixel {col},{row} toggled from {self.grid[col][row]} to {new}')
         self.grid = [[new if (c==col and r==row) else self.grid[c][r]
                       for r in range(self.height)]
                      for c in range(self.width)]
@@ -250,3 +254,7 @@ class PixelGrid:
 
     def _validate(self, grid: Any) -> bool:
         return is_valid_grid(grid, self.width, self.height)
+
+
+if __name__ == '__main__':
+    PixelGrid().run()

is_matrix_forge-1.0.0.dev2/is_matrix_forge/designer_gui/main_window/layout.py → is_matrix_forge-1.0.0.dev5/is_matrix_forge/designer_gui/main_window/layout/__init__.py

@@ -1,5 +1,6 @@
 import PySimpleGUI as sg
 from typing import List, Tuple, Any
+from is_matrix_forge.designer_gui.main_window.layout.button_grid.column import build_grid_frame
 
 
 class PixelGridLayout:
@@ -93,12 +94,7 @@ class PixelGridLayout:
         self.__button_list = value
 
     def build(self) -> List[List[Any]]:
-        grid = [
-            [sg.Button(' ', size=self.button_size, key=(col, row), pad=self.pad)
-             for col in range(self.width)]
-            for row in range(self.height)
-        ]
-        grid_column = sg.Column(grid)
+        grid_column = build_grid_frame(self.width, self.height, button_size=self.button_size, pad=self.pad)
 
         controls = [[sg.Button(btn)] for btn in self.button_list]
         control_column = sg.Column(controls, vertical_alignment='top')

is_matrix_forge-1.0.0.dev5/is_matrix_forge/designer_gui/main_window/layout/button_grid/column.py

@@ -0,0 +1,17 @@
+import PySimpleGUI as sg
+
+
+def build_grid_frame(num_cols=9, num_rows=34, button_size=(2,1), pad=(1,1)):
+    """Return a layout of 9 vertical columns (of 34 buttons each), side by side."""
+    return [
+        [
+            sg.Column(
+                [
+                    [sg.Button(' ', key=(col, row), size=button_size, pad=pad)]
+                    for row in range(num_rows)
+                ],
+                pad=(0,0)
+            )
+            for col in range(num_cols)
+        ]
+    ]

is_matrix_forge-1.0.0.dev5/is_matrix_forge/designer_gui/main_window/layout/button_grid/grid.py

@@ -0,0 +1,15 @@
+import PySimpleGUI as sg
+
+
+def build_button_grid(num_cols, num_rows, button_size=(1, 1), pad=(1, 1)):
+    """
+    Returns a list of `num_cols` lists, each containing `num_rows` buttons.
+    So: 9 columns of 34 rows each.
+    """
+    return [
+        [sg.Button(' ', key=(col, row), size=button_size, pad=pad)]
+         for row in range(num_rows)
+    ],
+        for col in range(num_cols)
+    ]
+

is_matrix_forge-1.0.0.dev5/is_matrix_forge/designer_gui/main_window/streamlit_app.py

@@ -0,0 +1,93 @@
+import streamlit as st
+import json
+import copy
+
+class Frame:
+    def __init__(self, grid, duration=1.0):
+        self.grid = grid
+        self.duration = duration
+
+class PixelGridWeb:
+    def __init__(self, width=9, height=34):
+        self.width = width
+        self.height = height
+        if "frames" not in st.session_state:
+            st.session_state.frames = [Frame(self._new_grid())]
+        if "current_frame" not in st.session_state:
+            st.session_state.current_frame = 0
+
+    def _new_grid(self):
+        return [[0 for _ in range(self.height)] for _ in range(self.width)]
+
+    @property
+    def frames(self):
+        return st.session_state.frames
+
+    @frames.setter
+    def frames(self, value):
+        st.session_state.frames = value
+
+    @property
+    def current_frame(self):
+        return st.session_state.current_frame
+
+    @current_frame.setter
+    def current_frame(self, value):
+        st.session_state.current_frame = value
+
+    @property
+    def grid(self):
+        return self.frames[self.current_frame].grid
+
+    def draw(self):
+        st.title("PixelGrid Animator")
+        st.write(f"Frame {self.current_frame+1}/{len(self.frames)}")
+        # Render grid
+        grid = self.grid
+        for row in range(self.height):
+            cols = st.columns(self.width)
+            for col in range(self.width):
+                key = f"pix_{col}_{row}_{self.current_frame}"
+                is_on = grid[col][row]
+                label = "🟩" if is_on else "⬛"
+                if cols[col].button(label, key=key, use_container_width=True):
+                    grid[col][row] ^= 1  # Toggle
+
+        # Frame controls
+        c1, c2, c3, c4 = st.columns(4)
+        if c1.button("Prev", disabled=self.current_frame == 0):
+            self.current_frame -= 1
+        if c2.button("Next", disabled=self.current_frame == len(self.frames)-1):
+            self.current_frame += 1
+        if c3.button("Add Frame"):
+            self.frames.append(Frame(copy.deepcopy(self.grid)))
+            self.current_frame = len(self.frames) - 1
+        if c4.button("Delete Frame", disabled=len(self.frames) == 1):
+            self.frames.pop(self.current_frame)
+            self.current_frame = max(0, self.current_frame-1)
+        # Export/import
+        st.markdown("---")
+        exp1, exp2, exp3 = st.columns(3)
+        if exp1.button("Export JSON"):
+            st.download_button(
+                "Download JSON",
+                data=json.dumps([f.grid for f in self.frames]),
+                file_name="frames.json",
+                mime="application/json"
+            )
+        uploaded = exp2.file_uploader("Load JSON", type="json")
+        if uploaded:
+            data = json.load(uploaded)
+            if isinstance(data, list) and all(isinstance(frame, list) for frame in data):
+                self.frames = [Frame(copy.deepcopy(g)) for g in data]
+                self.current_frame = 0
+        # Placeholder for "Send to Matrix"
+        if exp3.button("Send to Matrix"):
+            st.info("This would send to your matrix (not implemented here)!")
+
+def main():
+    pg = PixelGridWeb()
+    pg.draw()
+
+if __name__ == "__main__":
+    main()

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/dev_tools/__init__.py

@@ -3,6 +3,6 @@ Author: Taylor B. tayjaybabee@gmail.com
 Date: 2025-05-05 15:02:58
 LastEditors: Taylor B. tayjaybabee@gmail.com
 LastEditTime: 2025-05-05 15:24:08
-FilePath: is_matrix_forge/dev_tools/__init__.py
+FilePath: is_matrix_forge/dev_tools/grid.py
 Description: 这是默认设置,可以在设置》工具》File Description中进行配置
 """

{is_matrix_forge-1.0.0.dev2 → is_matrix_forge-1.0.0.dev5}/is_matrix_forge/inputmodule/ledmatrix.py

@@ -40,22 +40,6 @@ PWM_FREQUENCIES = [
 ]
 
 
-def get_pwm_freq(dev):
-    """Adjust the brightness scaling of the entire screen."""
-    res = send_command(dev, CommandVals.PwmFreq, with_response=True)
-    freq = int(res[0])
-    if freq == 0:
-        return 29000
-    elif freq == 1:
-        return 3600
-    elif freq == 2:
-        return 1800
-    elif freq == 3:
-        return 900
-    else:
-        return None
-
-
 def percentage(dev, p):
     """Fill a percentage of the screen. Bottom to top"""
     send_command(dev, CommandVals.Pattern, [PatternVals.Percentage, p])

is_matrix_forge-1.0.0.dev5/is_matrix_forge/led_matrix/Scripts/__init__.py

@@ -0,0 +1,4 @@
+"""
+Fake `grid.py` to make the Scripts directory a sub-package.
+"""
+