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

is_matrix_forge/led_matrix/display/animations/font/map_builder.py

@@ -0,0 +1,123 @@
+# font_map_builder.py
+
+"""
+Author: Taylor
+Project: Inspyre-Toolbox (LED-Matrix Extensions)
+File: font_map_builder.py
+
+Description:
+    Build a mapping from characters to 2D binary grids
+    suitable for driving your TextScroller.
+
+Dependencies:
+    - pillow (PIL)
+
+Classes:
+    FontMapBuilderConfig
+    FontMapBuilder
+
+Example Usage:
+    from font_map_builder import FontMapBuilder, FontMapBuilderConfig
+
+    config = FontMapBuilderConfig(
+        font_path="C:/Windows/Fonts/arial.ttf",
+        font_size=8,
+        canvas_size=(5, 7),  # width x height in pixels
+        characters="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!?,.",
+        threshold=128,
+    )
+    builder  = FontMapBuilder(config)
+    font_map = builder.generate_font_map()
+    # font_map["A"] is now a 7-row x 5-col list of 0/1s
+"""
+
+from dataclasses import dataclass
+from typing import Dict, List, Tuple
+from PIL import Image, ImageDraw, ImageFont
+
+
+@dataclass(frozen=True)
+class FontMapBuilderConfig:
+    """Immutable settings for font‐to‐grid conversion."""
+    font_path: str
+    font_size: int
+    canvas_size: Tuple[int, int]
+    characters: str
+    threshold: int = 128  # pixel brightness cutoff (0–255)
+
+
+class FontMapBuilder:
+    """Generates a font_map mapping each character to a binary grid."""
+
+    def __init__(self, config: FontMapBuilderConfig):
+        """
+        Args:
+            config: All settings needed to render and threshold glyphs.
+        """
+        self.config = config
+        self._font = ImageFont.truetype(config.font_path, config.font_size)
+
+    def generate_font_map(self) -> Dict[str, List[List[int]]]:
+        """
+        Render every character in `config.characters` into a
+        monochrome grid, then threshold to 0/1.
+
+        Returns:
+            A dict mapping each character to its grid (rows of ints).
+        """
+        font_map: Dict[str, List[List[int]]] = {}
+        w, h = self.config.canvas_size
+
+        for char in self.config.characters:
+            if char in self.config.characters:
+                if char == ' ':
+                    grid = [[0] * w for _ in range(h)]
+                else:
+                    img = self._render_char(char, w, h)
+                    grid = self._image_to_grid(img)
+                font_map[char] = grid
+
+        if ' ' not in font_map:
+            font_map[' '] = [[0] * w for _ in range(h)]
+
+        return font_map
+
+    def _render_char(self, ch: str, width: int, height: int) -> Image.Image:
+        """
+        Draw a single character centered in a WxH grayscale image.
+
+        Returns:
+            A Pillow Image in mode 'L'.
+        """
+        img = Image.new("L", (width, height), color=0)
+        draw = ImageDraw.Draw(img)
+
+        try:
+            left, top, right, bottom = draw.textbbox((0, 0), ch, font=self._font)
+            text_w, text_h = right - left, bottom - top
+            x  = (width - text_w) // 2 - left
+            y = (height - text_h) // 2 - top
+        except AttributeError as e:
+            # Maintain compatibility with pre 8.0.0 Pillow
+            text_w, text_h = self._font.getsize(ch)
+            x = (width - text_w) // 2
+            y = (height - text_h) // 2
+
+        draw.text((x, y), ch, fill=255, font=self._font)
+        return img
+
+    def _image_to_grid(self, img: Image.Image) -> List[List[int]]:
+        """
+        Convert a grayscale image to a 2D list of 0/1
+        based on the luminosity threshold.
+
+        Returns:
+            List of rows, each a list of ints (0 or 1).
+        """
+        pixels = img.load()
+        w, h = img.size
+        thresh = self.config.threshold
+        return [
+            [1 if pixels[x, y] >= thresh else 0 for x in range(w)]
+            for y in range(h)
+        ]

is_matrix_forge/led_matrix/display/animations/frame/__init__.py

@@ -0,0 +1,47 @@
+from typing import List
+from .base import Frame
+from serial.tools.list_ports_common import ListPortInfo
+from is_matrix_forge.led_matrix.display.grid.helpers import is_valid_grid
+from is_matrix_forge.led_matrix.display.animations.errors import MalformedGridError
+from is_matrix_forge.led_matrix import render_matrix
+
+
+running = False
+
+
+def hold_pattern(dev, grid: List[List[int]], reapply_interval: float = 55.00) -> None:
+    """
+    Hold the state of the LED matrix indefinitely, only updating the display every `reapply_interval` seconds.
+
+    This is useful for maintaining a static display on the LED matrix without having a constant refresh/computation
+    load.
+
+    Parameters:
+        dev (ListPortInfo):
+            The serial com device/port to use.
+
+        grid (List[List[int]])::
+            The grid to display on the LED matrix.
+
+        reapply_interval (Union[float, int]):
+            The interval in seconds at which to reapply the grid state to the LED matrix. Default is 55 seconds,
+            maximum is 60 (the number of seconds before the matrix turns all the LEDs off unless a new state is
+            applied)
+
+    Returns:
+        None
+    """
+
+    if not isinstance(dev, ListPortInfo):
+        raise TypeError(f"dev must be a ListPortInfo object, not {type(dev)}")
+
+    if not isinstance(grid, list) or not is_valid_grid(grid, 9, 34):
+        raise MalformedGridError(f"grid must be a 9x34 list of 0/1, not {type(grid)}")
+
+    cycles = 0
+    def worker(interval):
+        global running, cycles
+        running = True
+        while running:
+            cycles += 1
+            render_matrix(dev, grid)

is_matrix_forge/led_matrix/display/animations/frame/base.py

@@ -0,0 +1,245 @@
+# is_matrix_forge.led_matrix.display.animations.frame.base
+# Standard library imports
+
+from time import sleep
+
+from typing import List, Any, Union
+from is_matrix_forge.led_matrix.display.grid.helpers import is_valid_grid
+
+from is_matrix_forge.led_matrix import render_matrix
+from is_matrix_forge.led_matrix.display.grid.grid import Grid
+from is_matrix_forge.led_matrix.display.grid.helpers import generate_blank_grid
+
+
+class Frame:
+    """
+    Represents a single animation frame with a duration.
+    """
+    DEFAULT_DURATION = 0.33
+
+    def __init__(self, grid: Union[List[List[int]], Grid], duration: float = 1.0):
+        self.__grid = None
+        self.__number_of_plays = 0
+        self.__duration = duration
+
+        # Accept Grid instances by extracting their underlying data
+        if grid is None:
+            grid = generate_blank_grid()
+        elif isinstance(grid, Grid):
+            # Grid stores column-major lists in _grid
+            grid = getattr(grid, '_grid', list(grid))
+
+        # Determine dimensions from column-major layout
+        self.__width = len(grid)
+        self.__height = len(grid[0])
+        # Validate and store grid data
+        self.grid = grid
+
+        if duration is not None:
+            self.duration = duration
+
+    @property
+    def duration(self) -> float:
+        """
+        The time the program should wait after displaying this frame before moving to the next.
+
+        Returns:
+            float: Frame duration in seconds.
+        """
+        return self.__duration or self.DEFAULT_DURATION
+
+    @duration.setter
+    def duration(self, new: Union[float, int, str]):
+        """
+        Set the duration of the frame in seconds.
+
+        Parameters:
+            new (Union[float, int, str]):
+                The duration of the frame in seconds, or fraction thereof, or a string.
+        """
+        try:
+            dur = float(new)
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Invalid duration: {new}") from e
+        if dur < 0:
+            raise ValueError(f"Duration must be positive, not {dur}")
+        self.__duration = dur
+
+    @property
+    def grid(self) -> List[List[int]]:
+        return self.__grid
+
+    @grid.setter
+    def grid(self, value: Any) -> None:
+        # If user passed a Grid, unwrap to list-of-columns
+        #if isinstance(value, Grid):
+        #    value = getattr(value, '_grid', list(value))
+        # if not is_valid_grid(value, self.__width, self.__height):
+        #    raise ValueError(f"Grid must be {self.__width}x{self.__height} list of 0/1")
+        self.__grid = value
+
+    @property
+    def number_of_plays(self) -> int:
+        return self.__number_of_plays
+
+    @number_of_plays.setter
+    def number_of_plays(self, new: int) -> None:
+        if not isinstance(new, int) or new < 0:
+            raise ValueError("Number of plays must be a non-negative integer")
+        self.__number_of_plays = new
+
+    def __repr__(self) -> str:
+        return f"Frame(grid={self.grid}, duration={self.duration})"
+
+    @staticmethod
+    def from_dict(data: dict) -> 'Frame':
+        """
+        Create a `Frame` object directly from a properly formatted dictionary.
+
+        Parameters:
+            data (dict): A dictionary containing 'grid' and optional 'duration'.
+        Returns:
+            Frame: A new `Frame` object.
+        """
+        try:
+            return Frame(
+                grid=data['grid'],
+                duration=data.get('duration', Frame.DEFAULT_DURATION)
+            )
+        except KeyError as e:
+            raise e from e
+
+    def play(self, device) -> None:
+        """
+        Play the frame on the LED matrix device.
+        """
+        device.draw_grid(self.grid)
+        sleep(self.duration)
+        self.__number_of_plays += 1
+
+
+
+# class Frame:
+#     """
+#     Represents a single animation frame with a duration.
+#     """
+#     DEFAULT_DURATION = 0.33
+#
+#     def __init__(self, grid: List[List[int]], duration: float = 1.0):
+#         self.__grid = None
+#         self.__number_of_plays = 0
+#         self.__duration = duration
+#
+#         if grid is None:
+#             grid = generate_blank_grid()
+#
+#         self.__width  = len(grid)
+#         self.__height = len(grid[0])
+#         self.grid = grid
+#
+#         if duration is not None:
+#             self.duration = duration
+#
+#     @property
+#     def duration(self) -> float:
+#         """
+#         The time the program should wait after displaying this frame before moving to the next.
+#
+#         Parameters:
+#
+#         """
+#
+#         return self.__duration or self.DEFAULT_DURATION
+#
+#     @duration.setter
+#     def duration(self, new: Union[float, int, str]):
+#         """
+#         Set the duration of the frame in seconds.
+#
+#         Parameters:
+#             new (Union[float, int, str]):
+#                 The duration of the frame in seconds, or fractions thereof, or a string representing a fraction of a
+#                 second/full-second.
+#         """
+#         try:
+#             dur = float(new)
+#         except (TypeError, ValueError) as e:
+#             raise ValueError(f"Invalid duration: {new}") from e
+#         if dur < 0:
+#             raise ValueError(f"Duration must be positive, not {dur}")
+#         self.__duration = dur
+#
+#     @property
+#     def grid(self) -> List[List[int]]:
+#         return self.__grid
+#
+#     @grid.setter
+#     def grid(self, value: Any) -> None:
+#         if not is_valid_grid(value, self.__width, self.__height):
+#             raise ValueError(f"Grid must be {self.__width}x{self.__height} list of 0/1")
+#         self.__grid = value
+#
+#     @property
+#     def number_of_plays(self):
+#         return self.__number_of_plays
+#
+#     @number_of_plays.setter
+#     def number_of_plays(self, new: int) -> None:
+#         if not isinstance(new, int) or new < 0:
+#             raise ValueError("Number of plays must be a non-negative integer")
+#         self.__number_of_plays = new
+#
+#     def __repr__(self) -> str:
+#         return f"Frame(grid={self.grid}, duration={self.duration})"
+#
+#     # width/height context for validation inherited from usage
+#     @property
+#     def width(self) -> int:
+#         return self.__width
+#
+#     @property
+#     def height(self) -> int:
+#         return self.__height
+#
+#     @staticmethod
+#     def from_dict(data: dict) -> 'Frame':
+#         """
+#         Create a `Frame` object directly from a properly formatted dictionary.
+#
+#         The dictionary must contain the following keys:
+#             - `grid`:
+#                 A list of lists representing the grid of the frame.
+#
+#             - `duration`:
+#                 The duration of the frame in seconds.
+#
+#         Parameters:
+#             data (dict):
+#                 A dictionary containing the data for the frame.
+#
+#         Returns:
+#             Frame:
+#                 A new `Frame` object.
+#         """
+#         try:
+#             return Frame(
+#                 grid=data['grid'],
+#                 duration=data['duration']
+#             )
+#         except KeyError as e:
+#             key = e.args[0]
+#             if key == 'duration':
+#                 return Frame(
+#                     grid=data['grid'],
+#                     duration=Frame.DEFAULT_DURATION
+#                 )
+#             else:
+#                 raise e from e
+#
+#     def play(self, device) -> None:
+#         """
+#         Play the frame on the LED matrix.
+#         """
+#         render_matrix(device, self.grid)
+#         sleep(self.duration)
+#         self.__number_of_plays += 1

is_matrix_forge/led_matrix/display/animations/frame/helpers.py

@@ -0,0 +1,67 @@
+from typing import Any, List, Union
+from pathlib import Path
+
+from inspyre_toolbox.path_man import provision_path
+
+from is_matrix_forge.led_matrix.display.grid.helpers import is_valid_grid
+
+
+def check_path(path: Union[str, Path], skip_exists_check: bool = False) -> Path:
+    path = provision_path(path)
+
+    if not skip_exists_check and not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    return path
+
+
+def load_frames_from_file(path: Union[str, Path]) -> List['Frame']:
+    from is_matrix_forge.led_matrix.display.animations.frame.base import Frame
+    from is_matrix_forge.led_matrix.helpers import get_json_from_file
+
+    path = provision_path(path)
+
+
+
+def is_valid_frames(raw: Any, width: int, height: int) -> bool:
+    """
+    Check if a list of frames is valid.
+
+    A list of frames is valid if it is a list of lists of 0s and 1s, and the length of each list is equal to the width
+    and height.
+
+
+    Parameters:
+        raw (Any):
+            The list of frames to check.
+
+        width (int):
+            The expected width (in pixels) of the frames.
+
+        height (int):
+            The expected height (in pixels) of the frames.
+
+    Returns:
+        bool:
+            - True if the list of frames is valid.
+            - False otherwise.
+    """
+    return (
+            isinstance(raw, list)
+            and len(raw) > 0
+            and all(is_valid_grid(frame, width, height) for frame in raw)
+    )
+
+
+def migrate_frame(matrix_spec: List[List[int]], duration: Union[int, str]) -> dict:
+    """
+    Creates a frame entry from a matrix spec.
+
+    Note:
+         A 'matrix spec' is a list of lists each containing 0s and 1s representing the pixels of a frame. 1 indicates a
+         pixel is on; 0 indicates it is off.
+    """
+    return {
+        'grid':     matrix_spec,
+        'duration': duration
+    }

is_matrix_forge/led_matrix/display/animations/keep_awake.py

@@ -0,0 +1 @@
+from threading import Thread

is_matrix_forge/led_matrix/display/animations/text_scroller.py

@@ -0,0 +1,104 @@
+from dataclasses import dataclass
+from typing import Dict, List
+
+from is_matrix_forge.led_matrix.display.grid.grid import MATRIX_WIDTH, MATRIX_HEIGHT
+from is_matrix_forge.led_matrix.display.grid import Grid
+from is_matrix_forge.led_matrix.display.animations.animation import Animation, Frame
+
+
+@dataclass(frozen=True)
+class TextScrollerConfig:
+    """Immutable configuration for the text scroller."""
+    text: str
+    font_map: Dict[str, List[List[int]]]
+    spacing: int = 1
+    frame_duration: float = 0.05
+    wrap: bool = False  # unused for vertical mode
+    direction: str = "horizontal"  # one of: "horizontal", "vertical_up", "vertical_down"
+
+
+class TextScroller:
+    """Generates scrolling‐text Animations in horizontal or vertical directions."""
+
+    VALID_DIRS = {"horizontal", "vertical_up", "vertical_down"}
+
+    def __init__(self, config: TextScrollerConfig):
+        self.config = config
+        if config.direction not in self.VALID_DIRS:
+            raise ValueError(f"Unsupported scroll direction: {config.direction}")
+        # ensure font fits display height
+        sample = next(iter(config.font_map.values()))
+        if len(sample) > MATRIX_HEIGHT:
+            raise ValueError(f"Font height {len(sample)} > display height {MATRIX_HEIGHT}")
+
+    def generate_animation(self) -> Animation:
+        """Build and return your scrolling‐text Animation.
+
+        Raises:
+            ValueError: if `text` contains a character not in `font_map`.
+        """
+        # build list of glyphs from text
+        glyphs: List[List[List[int]]] = []  # each glyph: rows of cols
+        for ch in self.config.text:
+            glyph = self.config.font_map.get(ch)
+            if glyph is None:
+                raise ValueError(f"Character '{ch}' not found in font_map")
+            glyphs.append(glyph)
+
+        glyph_h = len(glyphs[0])
+        glyph_ws = [len(g[0]) for g in glyphs]
+
+        frames: List[Frame] = []
+
+        if self.config.direction == "horizontal":
+            # existing horizontal behavior unchanged
+            total_w = sum(glyph_ws) + self.config.spacing * (len(glyph_ws) - 1)
+            canvas = [[0] * total_w for _ in range(MATRIX_HEIGHT)]
+            x = 0
+            # render glyphs horizontally
+            for g, w in zip(glyphs, glyph_ws):
+                vpad = (MATRIX_HEIGHT - glyph_h) // 2
+                for r in range(glyph_h):
+                    canvas[vpad + r][x : x + w] = g[r]
+                x += w + self.config.spacing
+
+            offsets = range(0, total_w) if self.config.wrap else range(-MATRIX_WIDTH, total_w)
+            for off in offsets:
+                window = [
+                    [canvas[r][off + c] if 0 <= off + c < total_w else 0 for c in range(MATRIX_WIDTH)]
+                    for r in range(MATRIX_HEIGHT)
+                ]
+                cols = [[window[r][c] for r in range(MATRIX_HEIGHT)] for c in range(MATRIX_WIDTH)]
+                frames.append(Frame(grid=Grid(init_grid=cols)))
+
+        else:
+            # vertical mode: scroll each glyph in turn, center-justified
+            direction = self.config.direction
+            for glyph, w in zip(glyphs, glyph_ws):
+                # horizontal center offset
+                x0 = (MATRIX_WIDTH - w) // 2
+                # choose offset range
+                if direction == "vertical_up":
+                    offsets = range(MATRIX_HEIGHT, -glyph_h - 1, -1)
+                else:  # vertical_down
+                    offsets = range(-glyph_h, MATRIX_HEIGHT + 1)
+                # scroll this glyph
+                for off in offsets:
+                    window = [[0] * MATRIX_WIDTH for _ in range(MATRIX_HEIGHT)]
+                    for r in range(glyph_h):
+                        for c in range(w):
+                            if glyph[r][c]:
+                                y = off + r
+                                if 0 <= y < MATRIX_HEIGHT:
+                                    window[y][x0 + c] = 1
+                    cols = [[window[r][c] for r in range(MATRIX_HEIGHT)] for c in range(MATRIX_WIDTH)]
+                    frames.append(Frame(grid=Grid(init_grid=cols)))
+                # blank-gap frames between letters
+                for _ in range(self.config.spacing):
+                    blank = [[0] * MATRIX_WIDTH for _ in range(MATRIX_HEIGHT)]
+                    cols = [[blank[r][c] for r in range(MATRIX_HEIGHT)] for c in range(MATRIX_WIDTH)]
+                    frames.append(Frame(grid=Grid(init_grid=cols)))
+
+        anim = Animation(frame_data=frames)
+        anim.set_all_frame_durations(self.config.frame_duration)
+        return anim

is_matrix_forge/led_matrix/display/effects/__init__.py

@@ -0,0 +1,17 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/led_matrix/display/effects/__init__.py
+ 
+
+Description:
+    
+
+"""