Metadata-Version: 2.4
Name: IS-Matrix-Forge
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
Requires-Python: >=3.12,<4.0
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)
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: 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 (>=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
Description-Content-Type: text/markdown

[![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)


# IS Matrix Forge

**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.

## 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

- LED Matrix display with dimensions 9x34 (compatible with the project's specifications)
- Serial connection to the computer (USB)
- The LED matrix should have the following hardware identifiers:
  - VID: 0x32AC
  - PID: 0x20
  - Serial Number Prefix: FRAK

## Software Dependencies

This project requires Python 3.12 or newer and the following dependencies:

- chime (>=0.7.0,<0.8.0) - For audio notifications
- pyserial (>=3.5,<4.0) - For serial communication with the LED matrix
- inspy-logger (>=3.2.3,<4.0.0) - For logging
- 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

### 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

### Using Poetry (Recommended)

1. Clone the repository:
   ```
   git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
   cd IS-Matrix-Forge
   ```

2. Install dependencies using Poetry:
   ```
   poetry install
   ```

3. Activate the virtual environment:
   ```
   poetry shell
   ```

### Using pip

1. Clone the repository:
   ```
   git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
   cd IS-Matrix-Forge
   ```

2. Install the package:
   ```
   pip install .
   ```

## Usage Examples

### Identify Connected Devices

```python
from is_matrix_forge.led_matrix.helpers.device import DEVICES

for dev in DEVICES:
    print(dev)
```

### Display Text on the Matrix

```python
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)
```

### 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

```python
import time
from is_matrix_forge.progress import tqdm

for _ in tqdm(range(100)):
    time.sleep(0.05)
```

## Troubleshooting

### LED Matrix Not Detected

1. Check that the LED matrix is properly connected to your computer.
2. Verify that the LED matrix has the correct hardware identifiers (VID, PID, SN_PREFIX).
3. Make sure you have the necessary permissions to access the serial port.
4. Try running the application with administrator/root privileges.

### Audio Notifications Not Working

1. Ensure your system's audio is working correctly.
2. Check that the WAV files for notifications exist in the expected locations.
3. Verify that the chime library is properly installed.

### 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.

## License

This project is licensed under the MIT License - see the LICENSE.md file for details.

