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

is_matrix_forge/led_matrix/display/media.py

@@ -0,0 +1,199 @@
+"""
+Media display module for LED Matrix.
+
+This module provides functions for displaying images and videos on the LED matrix.
+It includes functions for rendering images, playing videos, and capturing from a camera.
+"""
+
+import serial
+import time
+import cv2
+from PIL import Image
+
+from ..constants import WIDTH, HEIGHT
+from ..hardware import send_serial
+from ..commands.map import CommandVals
+from ..commands import send_command
+from . import send_col, commit_cols
+from is_matrix_forge.led_matrix.helpers.status_handler import get_status, set_status
+
+
+def image(dev, image_file):
+    """Display a black/white image
+    Send everything in a single command"""
+    # Initialize a byte array to hold the binary representation of the image
+    # 39 bytes = 312 bits, which is enough for 9x34 = 306 pixels
+    vals = [0x00 for _ in range(39)]
+
+    # Open and convert the image to RGB format
+    im = Image.open(image_file).convert("RGB")
+    width, height = im.size
+
+    # Verify image dimensions match the LED matrix size
+    assert width == 9
+    assert height == 34
+
+    # Get all pixel values as a flat list
+    pixel_values = list(im.getdata())
+
+    # Process each pixel
+    for i, pixel in enumerate(pixel_values):
+        # Calculate average brightness of RGB components
+        brightness = sum(pixel) / 3
+
+        # If brightness is above half of max (127.5), consider it "on"
+        # This creates a binary black/white effect
+        if brightness > 0xFF / 2:
+            # Calculate which byte in vals array this pixel belongs to (i/8)
+            # Then set the appropriate bit within that byte (i%8)
+            # This packs 8 pixels into each byte of the vals array
+            vals[int(i / 8)] |= 1 << i % 8
+
+    # Send the packed binary data to the device
+    send_command(dev, CommandVals.Draw, vals)
+
+
+def pixel_to_brightness(pixel):
+    """Calculate pixel brightness from an RGB triple"""
+    assert len(pixel) == 3
+    brightness = sum(pixel) / len(pixel)
+
+    # Poor man's scaling to make the greyscale pop better.
+    # Should find a good function.
+    if brightness > 200:
+        brightness = brightness
+    elif brightness > 150:
+        brightness = brightness * 0.8
+    elif brightness > 100:
+        brightness = brightness * 0.5
+    elif brightness > 50:
+        brightness = brightness
+    else:
+        brightness = brightness * 2
+
+    return int(brightness)
+
+
+def image_greyscale(dev, image_file):
+    """Display an image in greyscale
+    Sends each 1x34 column and then commits => 10 commands
+    """
+    with serial.Serial(dev.device, 115200) as s:
+        from PIL import Image
+
+        im = Image.open(image_file).convert("RGB")
+        width, height = im.size
+        assert width == 9
+        assert height == 34
+        pixel_values = list(im.getdata())
+        for x in range(0, WIDTH):
+            vals = [0 for _ in range(HEIGHT)]
+
+            for y in range(HEIGHT):
+                vals[y] = pixel_to_brightness(pixel_values[x + y * WIDTH])
+
+            send_col(dev, s, x, vals)
+        commit_cols(dev, s)
+
+
+def camera(dev):
+    """Play a live view from the webcam, for fun"""
+    set_status('camera')
+    with serial.Serial(dev.device, 115200) as s:
+        import cv2
+
+        capture = cv2.VideoCapture(1)
+        ret, frame = capture.read()
+
+        scale_y = HEIGHT / frame.shape[0]
+
+        # Scale the video to 34 pixels height
+        dim = (HEIGHT, int(round(frame.shape[1] * scale_y)))
+        # Find the starting position to crop the width to be centered
+        # For very narrow videos, make sure to stay in bounds
+        start_x = max(0, int(round(dim[1] / 2 - WIDTH / 2)))
+        end_x = min(dim[1], start_x + WIDTH)
+
+        # Pre-process the video into resized, cropped, grayscale frames
+        while get_status() == 'camera':
+            ret, frame = capture.read()
+            if not ret:
+                print("Failed to capture video frames")
+                break
+
+            gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+
+            resized = cv2.resize(gray, (dim[1], dim[0]))
+            cropped = resized[0:HEIGHT, start_x:end_x]
+
+            for x in range(0, cropped.shape[1]):
+                vals = [0 for _ in range(HEIGHT)]
+
+                for y in range(0, HEIGHT):
+                    vals[y] = cropped[y, x]
+
+                send_col(dev, s, x, vals)
+            commit_cols(dev, s)
+
+
+def video(dev, video_file):
+    """Resize and play back a video"""
+    set_status('video')
+    with serial.Serial(dev.device, 115200) as s:
+        import cv2
+
+        capture = cv2.VideoCapture(video_file)
+        ret, frame = capture.read()
+
+        scale_y = HEIGHT / frame.shape[0]
+
+        # Scale the video to 34 pixels height
+        dim = (HEIGHT, int(round(frame.shape[1] * scale_y)))
+        # Find the starting position to crop the width to be centered
+        # For very narrow videos, make sure to stay in bounds
+        start_x = max(0, int(round(dim[1] / 2 - WIDTH / 2)))
+        end_x = min(dim[1], start_x + WIDTH)
+
+        processed = []
+
+        # Pre-process the video into resized, cropped, grayscale frames
+        while get_status() == 'video':
+            ret, frame = capture.read()
+            if not ret:
+                print("Failed to read video frames")
+                break
+
+            gray = cv2.cvtColor(frame, cv2.COLOR_RGB2GRAY)
+
+            resized = cv2.resize(gray, (dim[1], dim[0]))
+            cropped = resized[0:HEIGHT, start_x:end_x]
+
+            processed.append(cropped)
+
+        # Determine frame delay based on the video's FPS.  Fall back to 30 FPS
+        # if the FPS value cannot be obtained.
+        fps = capture.get(cv2.CAP_PROP_FPS)
+        try:
+            fps = float(fps)
+            if fps <= 0 or fps != fps:
+                raise ValueError
+        except Exception:
+            fps = 30.0
+        frame_delay = 1.0 / fps
+
+        # Write it out to the module one frame at a time while respecting the
+        # original frame rate.
+        for frame in processed:
+            start = time.time()
+            for x in range(0, cropped.shape[1]):
+                vals = [0 for _ in range(HEIGHT)]
+
+                for y in range(0, HEIGHT):
+                    vals[y] = frame[y, x]
+
+                send_col(dev, s, x, vals)
+            commit_cols(dev, s)
+
+            elapsed = time.time() - start
+            if frame_delay > elapsed:
+                time.sleep(frame_delay - elapsed)

is_matrix_forge/led_matrix/display/patterns/__init__.py

@@ -0,0 +1,59 @@
+"""
+Pattern display module for LED Matrix.
+
+This module provides functions for displaying various patterns on the LED matrix.
+It includes functions for displaying checkerboards, gradients, and other visual patterns.
+"""
+
+import time
+
+from .built_in.stencils import every_nth_row, every_nth_col
+from ..helpers import render_matrix
+from is_matrix_forge.led_matrix.display.patterns.built_in.stencils import every_nth_row, every_nth_col
+from is_matrix_forge.led_matrix.display.helpers.columns import send_col
+
+
+def breathing(dev):
+    """Animate breathing brightness.
+    Keeps currently displayed grid"""
+    set_status('breathing')
+    # Bright ranges appear similar, so we have to go through those faster
+    while get_status() == 'breathing':
+        # Go quickly from 250 to 50
+        for i in range(10):
+            time.sleep(0.03)
+            brightness(dev, 250 - i * 20)
+
+        # Go slowly from 50 to 0
+        for i in range(10):
+            time.sleep(0.06)
+            brightness(dev, 50 - i * 5)
+
+        # Go slowly from 0 to 50
+        for i in range(10):
+            time.sleep(0.06)
+            brightness(dev, i * 5)
+
+        # Go quickly from 50 to 250
+        for i in range(10):
+            time.sleep(0.03)
+            brightness(dev, 50 + i * 20)
+
+
+def eq(dev, vals):
+    """Display 9 values in equalizer diagram starting from the middle, going up and down"""
+    matrix = [[0 for _ in range(34)] for _ in range(9)]
+
+    for col, val in enumerate(vals[:9]):
+        row = int(34 / 2)
+        above = int(val / 2)
+        below = val - above
+
+        for i in range(above):
+            matrix[col][row + i] = 0xFF
+        for i in range(below):
+            matrix[col][row - 1 - i] = 0xFF
+
+    render_matrix(dev, matrix)
+
+

is_matrix_forge/led_matrix/display/patterns/built_in/__init__.py

@@ -0,0 +1,91 @@
+import difflib
+from typing import Any
+
+from .constants import PATTERN_MAP
+
+
+class BuiltInPatterns:
+    """
+    Interface for rendering built-in LED matrix patterns on a device.
+
+    Parameters
+    ----------
+    dev : Any
+        The device instance to send commands to.
+    """
+
+    def __init__(self, dev: Any):
+        from serial.tools.list_ports_common import ListPortInfo
+        from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
+
+        if dev is None:
+            from is_matrix_forge.led_matrix.controller.helpers import get_controllers
+
+        if not isinstance(dev, ListPortInfo) and not isinstance(dev, LEDMatrixController):
+            raise TypeError(f'dev must be of type `ListPortInfo` or `LEDMatrixController`, not {type(dev)}')
+        elif isinstance(dev, LEDMatrixController):
+            dev = dev.device
+
+        self.dev = dev
+
+    def render(self, pattern_name: str) -> None:
+        """
+        Render the specified pattern on the device.
+
+        Parameters
+        ----------
+        pattern_name : str
+            The name of the pattern to render.
+        """
+        normalized = self._normalize(pattern_name)
+        action = PATTERN_MAP.get(normalized)
+
+        if action:
+            action(self.dev)
+        else:
+            print(f"❌ Invalid pattern: '{pattern_name}'")
+            suggestions = self.suggest(pattern_name)
+            if suggestions:
+                print("💡 Did you mean:")
+                for s in suggestions:
+                    print(f"  - {s}")
+            else:
+                print("ℹ️ Available patterns:")
+                for key in self.list():
+                    print(f"  - {key}")
+
+    def suggest(self, pattern_name: str, n: int = 3) -> list[str]:
+        """
+        Suggest similar pattern names.
+
+        Parameters
+        ----------
+        pattern_name : str
+            The name to suggest alternatives for.
+
+        n : int, optional
+            Maximum number of suggestions to return.
+
+        Returns
+        -------
+        list[str]
+            List of suggested pattern names.
+        """
+        return difflib.get_close_matches(pattern_name, self.list(), n=n)
+
+    @staticmethod
+    def list() -> list[str]:
+        """
+        List all available pattern names.
+
+        Returns
+        -------
+        list[str]
+            Names of all patterns available.
+        """
+        return list(PATTERN_MAP.keys())
+
+    @staticmethod
+    def _normalize(name: str) -> str:
+        return name.strip()
+

is_matrix_forge/led_matrix/display/patterns/built_in/commands.py

@@ -0,0 +1,3 @@
+from is_matrix_forge.led_matrix.hardware import PatternVals
+from is_matrix_forge.led_matrix.commands.map import CommandVals
+from is_matrix_forge.led_matrix.commands import send_command

is_matrix_forge/led_matrix/display/patterns/built_in/constants.py

@@ -0,0 +1,29 @@
+from .commands import PatternVals
+from is_matrix_forge.led_matrix.commands.map import CommandVals
+from is_matrix_forge.led_matrix.commands import send_command
+from .stencils import all_brightnesses, every_nth_row, every_nth_col, checkerboard
+
+
+PATTERN_MAP = {
+    "All LEDs on": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.FullBrightness]),
+    "Gradient (0-13% Brightness)": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.Gradient]),
+    "Double Gradient (0-7-0% Brightness)": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.DoubleGradient]),
+    "\"LOTUS\" sideways": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.DisplayLotus]),
+    "Zigzag": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.ZigZag]),
+    "\"PANIC\"": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.DisplayPanic]),
+    "\"LOTUS\" Top Down": lambda dev: send_command(dev, CommandVals.Pattern, [PatternVals.DisplayLotus2]),
+    "All brightness levels (1 LED each)": lambda dev: all_brightnesses(dev),
+    "Every Second Row": lambda dev: every_nth_row(dev, 2),
+    "Every Third Row": lambda dev: every_nth_row(dev, 3),
+    "Every Fourth Row": lambda dev: every_nth_row(dev, 4),
+    "Every Fifth Row": lambda dev: every_nth_row(dev, 5),
+    "Every Sixth Row": lambda dev: every_nth_row(dev, 6),
+    "Every Second Col": lambda dev: every_nth_col(dev, 2),
+    "Every Third Col": lambda dev: every_nth_col(dev, 3),
+    "Every Fourth Col": lambda dev: every_nth_col(dev, 4),
+    "Every Fifth Col": lambda dev: every_nth_col(dev, 5),
+    "Checkerboard": lambda dev: checkerboard(dev, 1),
+    "Double Checkerboard": lambda dev: checkerboard(dev, 2),
+    "Triple Checkerboard": lambda dev: checkerboard(dev, 3),
+    "Quad Checkerboard": lambda dev: checkerboard(dev, 4),
+}

is_matrix_forge/led_matrix/display/patterns/built_in/stencils.py

@@ -0,0 +1,70 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    ${DIR_PATH}/${FILE_NAME}
+ 
+
+Description:
+    $DESCRIPTION
+
+"""
+import serial
+
+from is_matrix_forge.led_matrix.constants import WIDTH, HEIGHT
+from is_matrix_forge.led_matrix.display.helpers.columns import send_col, commit_cols
+
+
+def all_brightnesses(dev):
+    """Increase the brightness with each pixel.
+    Only 0-255 available, so it can't fill all 306 LEDs"""
+    with serial.Serial(dev.device, 115200) as s:
+        for x in range(0, WIDTH):
+            vals = [0 for _ in range(HEIGHT)]
+
+            for y in range(HEIGHT):
+                brightness = x + WIDTH * y
+                if brightness > 255:
+                    vals[y] = 0
+                else:
+                    vals[y] = brightness
+
+            send_col(dev, s, x, vals)
+        commit_cols(dev, s)
+
+
+
+def every_nth_row(dev, n):
+    with serial.Serial(dev.device, 115200) as s:
+        for x in range(0, WIDTH):
+            vals = [(0xFF if y % n == 0 else 0) for y in range(HEIGHT)]
+
+            send_col(dev, s, x, vals)
+        commit_cols(dev, s)
+
+
+def every_nth_col(dev, n):
+    with serial.Serial(dev.device, 115200) as s:
+        for x in range(0, WIDTH):
+            vals = [(0xFF if x % n == 0 else 0) for _ in range(HEIGHT)]
+
+            send_col(dev, s, x, vals)
+        commit_cols(dev, s)
+
+
+def checkerboard(dev, n):
+    with serial.Serial(dev.device, 115200) as s:
+        for x in range(0, WIDTH):
+            vals = (([0xFF] * n) + ([0x00] * n)) * int(HEIGHT / 2)
+            if x % (n * 2) < n:
+                # Rotate once
+                vals = vals[n:] + vals[:n]
+
+            send_col(dev, s, x, vals)
+        commit_cols(dev, s)

is_matrix_forge/led_matrix/display/patterns/utils.py

@@ -0,0 +1,2 @@
+import serial
+from is_matrix_forge.led_matrix.constants import HEIGHT, WIDTH

is_matrix_forge/led_matrix/display/text/__init__.py

@@ -0,0 +1,66 @@
+from .scroller import TextScroller
+"""
+Text and symbol rendering module for LED Matrix.
+
+This module provides functions for displaying text and symbols on the LED matrix.
+It includes functions for rendering strings, fonts, and special symbols.
+"""
+
+from is_matrix_forge.led_matrix import fonts as font
+from is_matrix_forge.led_matrix.commands import send_command
+from ...commands.map import CommandVals
+
+
+def show_string(dev, s):
+    """Render a string with up to five letters"""
+    show_font(dev, [font.convert_font(letter) for letter in str(s)[:5]])
+
+
+def show_font(dev, font_items):
+    """Render up to five 5x6 pixel font items"""
+    # Initialize a byte array with all pixels off
+    vals = [0x00 for _ in range(39)]
+
+    # Process each font item (character/symbol)
+    for digit_i, digit_pixels in enumerate(font_items):
+        # Calculate vertical offset for this character
+        # Each character is placed 7 pixels apart vertically
+        offset = digit_i * 7
+
+        # Process each pixel in the 5x6 character grid
+        for pixel_x in range(5):
+            for pixel_y in range(6):
+                # Convert 2D coordinates to 1D index in the font data
+                # Font data is stored as a 1D array in row-major order
+                pixel_value = digit_pixels[pixel_x + pixel_y * 5]
+
+                # Calculate the position in the LED matrix
+                # Characters start at x=2 (to center them) and are stacked vertically
+                # with the calculated offset
+                i = (2 + pixel_x) + (9 * (pixel_y + offset))
+
+                # If this pixel should be on
+                if pixel_value:
+                    # Calculate which byte and bit to set
+                    byte_index = int(i / 8)
+                    bit_position = i % 8
+
+                    # Set the bit in the appropriate byte
+                    vals[byte_index] = vals[byte_index] | (1 << bit_position)
+
+    # Send the command to display the characters
+    send_command(dev, CommandVals.Draw, vals)
+
+
+def show_symbols(dev, symbols):
+    """Render a list of up to five symbols
+    Can use letters/numbers or symbol names, like 'sun', ':)'"""
+    font_items = []
+    for symbol in symbols:
+        s = font.convert_symbol(symbol)
+        if not s:
+            s = font.convert_font(symbol)
+        font_items.append(s)
+
+    show_font(dev, font_items)
+

is_matrix_forge/led_matrix/display/text/scroller.py

@@ -0,0 +1,136 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    ${DIR_PATH}/${FILE_NAME}
+ 
+
+Description:
+    $DESCRIPTION
+
+"""
+from typing import List
+
+
+
+class TextScroller:
+    """
+    Generate Frame objects for scrolling text bottom-to-top on an LED matrix.
+
+    Frames are returned as a list of "columns", each column is a list of bits down the rows.
+    """
+
+    def __init__(
+        self,
+        font,
+        rows: int = 34,
+        cols: int = 9,
+        delay: float = 0.1,
+        letter_width: int = 5,
+        letter_height: int = 6,
+        spacing: int = 1,
+        col_offset: int = 2,
+    ):
+        """
+        Initialize a TextScroller.
+
+        Parameters:
+            font:
+                A font object with convert_font(char) -> glyph callable.
+            rows:
+                Number of rows in the matrix.
+            cols:
+                Number of columns in the matrix.
+            delay:
+                Duration for each generated Frame.
+            letter_width:
+                Width of each character in pixels.
+            letter_height:
+                Height of each character in pixels.
+            spacing:
+                Vertical spacing between characters.
+            col_offset:
+                Horizontal offset for character placement.
+        """
+        self.font = font
+        self.rows = rows
+        self.cols = cols
+        self.delay = delay
+        self.letter_width = letter_width
+        self.letter_height = letter_height
+        self.spacing = spacing
+        self.col_offset = col_offset
+
+    def scroll(self, text: str, skip_end_space: bool = False) -> List['Frame']:
+        """
+        Build and return a list of Frame objects representing the text scroll.
+
+        Parameters:
+            text:
+                The text string to scroll.
+            skip_end_space:
+                If True, omit trailing blank frames after text.
+
+        Returns:
+            A list of Frame instances, each covering the full matrix as columns×rows.
+        """
+        from is_matrix_forge.led_matrix.display.animations.frame import Frame
+
+        grid = self._build_big_grid(text)
+        total_height = len(grid)
+        end_limit = total_height if skip_end_space else total_height + self.rows
+        frames: List[Frame] = []
+
+        for top in range(-self.rows, end_limit):
+            # extract a rows×cols slice (list of rows)
+            slice_rows = [
+                grid[r] if 0 <= r < total_height else [0] * self.cols
+                for r in range(top, top + self.rows)
+            ]
+            # reorient to columns×rows
+            cols_grid = self._orient_frame(slice_rows)
+            frames.append(Frame(cols_grid, duration=self.delay))
+
+        return frames
+
+    def _build_big_grid(self, text: str) -> List[List[int]]:
+        """
+        Build a concatenated vertical grid of all glyphs in text as list of rows.
+
+        Returns:
+            A 2D list of bits [total_height][cols].
+        """
+        font_items = [self.font.convert_font(c) for c in text]
+        total_height = len(font_items) * (self.letter_height + self.spacing) - self.spacing
+        grid = [[0] * self.cols for _ in range(total_height)]
+
+        for idx, glyph in enumerate(font_items):
+            base = idx * (self.letter_height + self.spacing)
+            for x in range(self.letter_width):
+                for y in range(self.letter_height):
+                    if glyph[x + y * self.letter_width]:
+                        grid[base + y][self.col_offset + x] = 1
+
+        return grid
+
+    def _orient_frame(self, rows_grid: List[List[int]]) -> List[List[int]]:
+        """
+        Transpose a rows×cols grid into cols×rows orientation.
+
+        Parameters:
+            rows_grid:
+                A list of self.rows lists, each length self.cols.
+
+        Returns:
+            A list of self.cols lists, each length self.rows.
+        """
+        return [
+            [rows_grid[r][c] for r in range(self.rows)]
+            for c in range(self.cols)
+        ]

is_matrix_forge/led_matrix/errors/__init__.py

@@ -0,0 +1,4 @@
+from .matrix import *
+from .grid import *
+
+

is_matrix_forge/led_matrix/errors/base.py

@@ -0,0 +1,14 @@
+from inspyre_toolbox.exceptional import CustomRootException
+
+
+class LEDMatrixControllerError(CustomRootException):
+    """
+    Base class for all LED matrix controller errors.
+
+    Class Attributes:
+        default_message (str): Read-Only. The default message for the error.
+    """
+    default_message = 'An error occurred with the LED matrix controller library!'
+
+
+__all__ = ['LEDMatrixControllerError']