RGBMatrixEmulator 0.16.0__py3-none-any.whl

RGBMatrixEmulator/__init__.py

@@ -0,0 +1,5 @@
+from RGBMatrixEmulator.graphics import *
+from RGBMatrixEmulator.emulation.matrix import RGBMatrix
+from RGBMatrixEmulator.emulation.options import RGBMatrixOptions
+
+from RGBMatrixEmulator.version import __version__

RGBMatrixEmulator/adapters/__init__.py

@@ -0,0 +1,42 @@
+ADAPTERS = {
+    "browser": {
+        "path": "RGBMatrixEmulator.adapters.browser_adapter.adapter",
+        "class": "BrowserAdapter",
+        "fallback": True,
+    },
+    "pygame": {
+        "path": "RGBMatrixEmulator.adapters.pygame_adapter",
+        "class": "PygameAdapter",
+        "fallback": True,
+    },
+    "sixel": {
+        "path": "RGBMatrixEmulator.adapters.sixel_adapter",
+        "class": "SixelAdapter",
+        "fallback": True,
+    },
+    "terminal": {
+        "path": "RGBMatrixEmulator.adapters.terminal_adapter",
+        "class": "TerminalAdapter",
+        "fallback": True,
+    },
+    "tkinter": {
+        "path": "RGBMatrixEmulator.adapters.tkinter_adapter",
+        "class": "TkinterAdapter",
+        "fallback": True,
+    },
+    "turtle": {
+        "path": "RGBMatrixEmulator.adapters.turtle_adapter",
+        "class": "TurtleAdapter",
+        "fallback": True,
+    },
+    "raw": {
+        "path": "RGBMatrixEmulator.adapters.raw_adapter",
+        "class": "RawAdapter",
+        "fallback": False,
+    },
+    "pi5": {
+        "path": "RGBMatrixEmulator.adapters.pi5_adapter",
+        "class": "Pi5Adapter",
+        "fallback": False,
+    },
+}

RGBMatrixEmulator/adapters/base.py

@@ -0,0 +1,229 @@
+import numpy as np
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+from RGBMatrixEmulator import version
+from RGBMatrixEmulator.logger import Logger
+from RGBMatrixEmulator.internal.pixel_style import PixelStyle
+
+
+class BaseAdapter:
+    SUPPORTED_PIXEL_STYLES = [PixelStyle.DEFAULT]
+    INSTANCE = None
+
+    DEFAULT_MASK_FN = "_draw_square_mask"
+    MASK_FNS = {
+        PixelStyle.SQUARE: "_draw_square_mask",
+        PixelStyle.CIRCLE: "_draw_circle_mask",
+        PixelStyle.REAL: "_draw_real_mask",
+    }
+
+    DEBUG_TEXT_TEMPLATE = (
+        "RGBME v{} - {}x{} Matrix | {}x{} Chain | {}px per LED ({}) | {}"
+    )
+
+    ICON_FORMATS = ["PNG", "ICO", "JPEG"]
+    ICON_MAX_SIZE = (512, 512)
+
+    def __init__(self, width, height, options):
+        self.width = width
+        self.height = height
+        self.options = options
+        self.__black = Image.new("RGB", self.options.window_size(), "black")
+        self.__mask = self.__draw_mask()
+        self.loaded = False
+
+        self.emulator_title = self.options.emulator_title or str(self)
+
+        self.default_icon_path = (Path(__file__).parent / ".." / "icon.png").resolve()
+        self._set_icon_path()
+
+    @classmethod
+    def get_instance(cls, *args, **kwargs):
+        if cls.INSTANCE is None:
+            instance = cls(*args, **kwargs)
+            cls.INSTANCE = instance
+
+        return cls.INSTANCE
+
+    # This method is required for the pygame adapter but nothing else, so just skip it if not defined.
+    def check_for_quit_event(self):
+        pass
+
+    #############################################################
+    # These methods must be implemented by BaseAdapter subclasses
+    #############################################################
+    def load_emulator_window(self):
+        """
+        Initialize the external dependency as a graphics display.
+
+        This method is fired when the emulated canvas is initialized.
+        """
+        raise NotImplementedError
+
+    def draw_to_screen(self, _pixels):
+        """
+        Accepts a 2D array of pixels of size height x width.
+
+        Implements drawing each pixel to the screen via the external dependency loaded in load_emulator_window.
+        """
+        raise NotImplementedError
+
+    #############################################################
+    # These methods implement pixel masks (styles)
+    #############################################################
+    def _get_masked_image(self, pixels):
+        image = Image.fromarray(np.array(pixels, dtype=np.uint8), "RGB")
+        image = image.resize(self.options.window_size(), Image.NEAREST)
+
+        return Image.composite(image, self.__black, self.__mask)
+
+    def __mask_fn(self, pixel_style):
+        if pixel_style not in self.MASK_FNS:
+            Logger.warning(
+                f"Pixel style '{pixel_style.config_name}' mask function not found, defaulting to {self.DEFAULT_MASK_FN}..."
+            )
+
+        return getattr(self, self.MASK_FNS.get(pixel_style, self.DEFAULT_MASK_FN))
+
+    def __draw_mask(self):
+        mask = Image.new("L", self.options.window_size())
+
+        draw_fn = self.__mask_fn(self.options.pixel_style)
+        draw_fn(mask)
+
+        return mask
+
+    def _draw_circle_mask(self, mask):
+        pixel_size = self.options.pixel_size
+        width, height = self.options.window_size()
+
+        drawer = ImageDraw.Draw(mask)
+
+        for y in range(0, height, pixel_size):
+            for x in range(0, width, pixel_size):
+                drawer.ellipse(
+                    (x, y, x + pixel_size - 1, y + pixel_size - 1),
+                    fill=255,
+                    outline=255,
+                )
+
+    def _draw_square_mask(self, mask):
+        pixel_size = self.options.pixel_size
+        width, height = self.options.window_size()
+
+        drawer = ImageDraw.Draw(mask)
+
+        for y in range(0, height, pixel_size):
+            for x in range(0, width, pixel_size):
+                drawer.rectangle(
+                    (x, y, x + pixel_size, y + pixel_size),
+                    fill=255,
+                    outline=255,
+                )
+
+    def _draw_real_mask(self, mask):
+        pixel_size = self.options.pixel_size
+        width, height = self.options.window_size()
+        pixel_glow = self.options.pixel_glow
+
+        if pixel_glow == 0:
+            # Short circuit to a faster draw routine
+            return self._draw_circle_mask(mask)
+
+        # Create two gradients.
+        # The first is the LED with a gradient amount of 1 to antialias the result.
+        # The second is the actual glow given the setting.
+        gradient = self._gradient_add(
+            self._generate_gradient(pixel_size, 1),
+            self._generate_gradient(pixel_size, pixel_glow),
+        )
+
+        pixel = Image.fromarray(gradient.astype(np.uint8))
+
+        # Paste the pixel into the mask at each point.
+        for y in range(0, height, pixel_size):
+            for x in range(0, width, pixel_size):
+                mask.paste(pixel, (x, y), pixel)
+
+    def _generate_gradient(self, sz, amt):
+        """
+        Generates a radial gradient of size sz with glow amt.
+
+        The resulting array is normalized between [0, 255].
+        """
+        # Calculate our own radial gradient to use in the mask.
+        # PIL.Image.radial_gradient() produces subpar results (LEDs look blocky)
+        x = np.linspace(0, sz, sz)
+        y = np.linspace(0, sz, sz)
+
+        # Discrete points (x, y) between 0 and pixel_size
+        X, Y = np.meshgrid(x, y)
+
+        # Distance of point to center
+        center = sz / 2
+        D = np.sqrt((X - center) ** 2 + (Y - center) ** 2)
+
+        # LED radius
+        L = (sz - amt) / 2
+        G = amt
+
+        # Calculate the radial gradient glow, clip it between 0 and 1, scale by 255 (WHITE), and get the additive inverse
+        gradient = 255 - np.clip((D - L) / G, 0, 1) * 255
+
+        return gradient
+
+    def _gradient_add(self, g1, g2):
+        """
+        Adds two arrays g1 and g2 with equal weight, and normalizes between [0, 255].
+        Assumes the input arrays are normalized between [0, 255].
+
+        Each pair of points is added with equal weight by first subtracting 128,
+        which produces fewer graphical artifacts than summation by average of the two points.
+        """
+        return np.clip((g1 - 128) + (g2 - 128), 0, 255)
+
+    def _set_icon_path(self):
+        self.icon_path = self.default_icon_path
+        custom_path = self.options.icon_path
+
+        if not custom_path:
+            return
+
+        try:
+            icon = Image.open(custom_path)
+
+            if icon.format not in self.ICON_FORMATS:
+                Logger.info(
+                    f"Custom icon format '{icon.format}' is not in allowed formats ({self.ICON_FORMATS}). Using default icon instead."
+                )
+                return
+
+            if (
+                icon.width > self.ICON_MAX_SIZE[0]
+                or icon.height > self.ICON_MAX_SIZE[1]
+            ):
+                Logger.info(
+                    f"Icon of size '{icon.size}' is too large (max size is {self.ICON_MAX_SIZE}). Using default icon instead."
+                )
+                return
+        except Exception as e:
+            Logger.exception(
+                "Encountered exception while loading custom icon. Using default icon instead."
+            )
+            Logger.exception(e)
+            return
+
+        self.icon_path = self.options.icon_path
+
+    def __str__(self):
+        return self.DEBUG_TEXT_TEMPLATE.format(
+            version.__version__,
+            self.options.cols,
+            self.options.rows,
+            self.options.chain_length,
+            self.options.parallel,
+            self.options.pixel_size,
+            self.options.pixel_style.name,
+            self.__class__.__name__,
+        )

RGBMatrixEmulator/adapters/browser_adapter/README.md

@@ -0,0 +1,62 @@
+# `browser` Display Adapter
+
+The `browser` adapter operates differently than other `RGBMatrixEmulator` display adapters. Under the hood, the adapter is a full webserver and WebSocket wrapper and includes its own JS client that can render an emulated image from a Python script within the browser.
+
+![browser-adapter](../../../assets/browser-adapter.gif)
+
+## Running the `browser` Display Adapter Server
+
+For configuration of the display adapter, check the main [README's configuration section](../../../README.md#configuration-options).
+
+Startup of the script remains unchanged, just like with other display adapters. Additional command line flags work as usual.
+
+After running your startup script, you should get a notice that your server is starting on your configured port. For the above example:
+
+```
+C:\Users\tyler\development\RGBMatrixEmulator\samples>python runtext.py
+Press CTRL-C to stop sample
+RGBME v0.6.0 - 32x32 Matrix | 1x1 Chain | 16px per LED (SQUARE) | BrowserAdapter
+Starting server...
+Server started and ready to accept requests on http://localhost:8888/
+```
+
+Once this is configured, your server is up and running and ready to accept requests on the configured port.
+
+## Viewing the Emulator
+
+### Via Websocket
+
+By default, the server is configured to `http://localhost:8888/`. Simply navigate to this in the web browser of your choice and you should see streaming images once loaded.
+
+If you've configured a custom port, you can navigate to the correct URL instead: `http://localhost:$PORT_NUMBER/`.
+
+Once a browser is connected to the server, you will see the following message(s) in your terminal window:
+
+```
+WebSocket opened from: ::1
+WebSocket opened from: 127.0.0.1
+```
+
+This indicates a successful connection has occurred.
+
+### Via Static Image
+
+:warning: **This functionality is experimental!** :warning:
+
+The emulator also exposes static images in a format you configure. By default, the server is configured to expose this endpoint at `http://localhost:8888/image`.
+
+This can be used to allow applications to poll the webserver for updated images or where a websocket is not applicable.
+
+## Error Handling
+
+Exceptions in emulated Python scripts will cause the server to shut down. Fix the errors in the script before attempting to restart.
+
+The Javascript client attempts to handle errors from the browser gracefully. If for some reason the socket is unable to fetch the next frame, it will retry the fetch every 6 seconds up to 10 times (for a total of 1 minute of retries). Once the max retry count is exhausted, it will stop retrying as there is likely another issue occurring.
+
+You can view the errors via a console in the browser (which can be opened with hotkey `F12` or right click -> "Inspect").
+
+## Known Issues
+
+* A socket connection is never re-established when shutting down the server (either via `SIGINT` or unhandled exception) and restarting it before the client hits max retry count
+* Excess blob references do not get cleaned up correctly in some instances, leading to memory leaks in some browsers
+  * Main symptom appears to be a hanging browser when closing the emulator tab

RGBMatrixEmulator/adapters/browser_adapter/adapter.py

@@ -0,0 +1,80 @@
+import io, webbrowser
+from pathlib import Path
+
+from RGBMatrixEmulator.adapters.base import BaseAdapter
+from RGBMatrixEmulator.internal.pixel_style import PixelStyle
+from RGBMatrixEmulator.adapters.browser_adapter.server import Server
+from RGBMatrixEmulator.logger import Logger
+
+
+class BrowserAdapter(BaseAdapter):
+    SUPPORTED_PIXEL_STYLES = [
+        PixelStyle.SQUARE,
+        PixelStyle.CIRCLE,
+        PixelStyle.REAL,
+    ]
+    IMAGE_FORMATS = {"bmp": "BMP", "jpeg": "JPEG", "png": "PNG", "webp": "WebP"}
+
+    def __init__(self, width, height, options):
+        super().__init__(width, height, options)
+        self.__server = None
+        self.image = None
+        self.image_ready = False
+        self.default_image_format = "JPEG"
+
+        image_format = options.browser.image_format
+        if image_format.lower() in self.IMAGE_FORMATS:
+            self.image_format = self.IMAGE_FORMATS[image_format.lower()]
+        else:
+            Logger.warning(
+                "Invalid browser image format '{}', falling back to '{}'".format(
+                    image_format, self.default_image_format
+                )
+            )
+            self.image_format = self.IMAGE_FORMATS.get(
+                self.default_image_format.lower()
+            )
+
+        # Default icon path is browser adapter assets
+        self.default_icon_path = str(
+            (Path(__file__).parent / "static" / "assets" / "icon.ico").resolve()
+        )
+        self._set_icon_path()
+
+    def load_emulator_window(self):
+        if self.loaded:
+            return
+
+        Logger.info(self.emulator_title)
+
+        self.__server = Server(self)
+        self.__server.run()
+
+        self.loaded = True
+
+        self.__open_browser()
+
+    def draw_to_screen(self, pixels):
+        image = self._get_masked_image(pixels)
+        with io.BytesIO() as bytesIO:
+            image.save(
+                bytesIO,
+                self.image_format,
+                quality=self.options.browser.quality,
+                optimize=True,
+            )
+            self.image = bytesIO.getvalue()
+
+        self.image_ready = True
+
+    def __open_browser(self):
+        if self.options.browser.open_immediately:
+            try:
+                uri = f"http://localhost:{self.options.browser.port}"
+                Logger.info(
+                    f"Browser adapter configured to open immediately, opening new window/tab to {uri}"
+                )
+                webbrowser.open(uri)
+            except Exception as e:
+                Logger.exception("Failed to open a browser window")
+                Logger.exception(e)

RGBMatrixEmulator/adapters/browser_adapter/fps.py

@@ -0,0 +1,26 @@
+import time
+from RGBMatrixEmulator.logger import Logger
+
+DEFAULT_UPDATE_RATE = 0.5  # seconds
+
+
+class FPSMonitor:
+    def __init__(self, update_rate=DEFAULT_UPDATE_RATE):
+        self.update_rate = update_rate
+        self.n_frames = 0
+        self.start_time = time.time()
+
+    def tick(self):
+        self.n_frames += 1
+        now = time.time()
+        elapsed = now - self.start_time
+
+        if elapsed >= self.update_rate:
+            fps = round(self.n_frames / elapsed, 2)
+
+            Logger.debug(
+                f"FPS: {fps} (received {self.n_frames} frames over {round(elapsed, 2)}s)"
+            )
+
+            self.n_frames = 0
+            self.start_time = now

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/__init__.py

@@ -0,0 +1,14 @@
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers.base import (
+    NoCacheRequestHandler,
+    NoCacheStaticFileHandler,
+)
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers.main import MainHandler
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers.image import (
+    ImageHandler,
+)
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers.image_web_socket import (
+    ImageWebSocketHandler,
+)
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers.single_file import (
+    SingleFileHandler,
+)

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/base.py

@@ -0,0 +1,25 @@
+import tornado.web
+
+
+class NoCacheRequestHandler(tornado.web.RequestHandler):
+    """Base handler that adds no-cache headers to all responses."""
+
+    def set_default_headers(self):
+        """Set headers to prevent browser caching."""
+        self.set_header(
+            "Cache-Control", "no-store, no-cache, must-revalidate, max-age=0"
+        )
+        self.set_header("Pragma", "no-cache")
+        self.set_header("Expires", "0")
+
+
+class NoCacheStaticFileHandler(tornado.web.StaticFileHandler):
+    """Static file handler that adds no-cache headers to all responses."""
+
+    def set_default_headers(self):
+        """Set headers to prevent browser caching."""
+        self.set_header(
+            "Cache-Control", "no-store, no-cache, must-revalidate, max-age=0"
+        )
+        self.set_header("Pragma", "no-cache")
+        self.set_header("Expires", "0")

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/image.py

@@ -0,0 +1,14 @@
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers import (
+    NoCacheRequestHandler,
+)
+
+
+class ImageHandler(NoCacheRequestHandler):
+    def get(self):
+        self.set_header(
+            "Content-type", "image/{}".format(self.adapter.image_format.lower())
+        )
+        self.write(self.adapter.image)
+
+    def register_adapter(adapter):
+        ImageHandler.adapter = adapter

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/image_web_socket.py

@@ -0,0 +1,60 @@
+import tornado.websocket
+
+from RGBMatrixEmulator.logger import Logger
+from RGBMatrixEmulator.adapters.browser_adapter.fps import FPSMonitor
+
+FPS_UPDATE_RATE = 10  # seconds
+FPS = FPSMonitor(FPS_UPDATE_RATE)
+
+
+class ImageWebSocketHandler(tornado.websocket.WebSocketHandler):
+    clients = set()
+    adapter = None
+
+    @classmethod
+    def broadcast(cls):
+        if not ImageWebSocketHandler.adapter.image_ready:
+            return
+
+        if not ImageWebSocketHandler.adapter.image:
+            Logger.warning(
+                "No image received from {}!".format(
+                    ImageWebSocketHandler.adapter.__class__.__name__
+                )
+            )
+            return
+
+        io_loop = tornado.ioloop.IOLoop.current()
+
+        for client in list(cls.clients):
+            io_loop.add_callback(
+                client.write_message, ImageWebSocketHandler.adapter.image, binary=True
+            )
+
+        FPS.tick()
+
+    def check_origin(self, _origin):
+        # Allow access from every origin
+        return True
+
+    def open(self):
+        ImageWebSocketHandler.clients.add(self)
+        Logger.info("WebSocket opened from: " + self.request.remote_ip)
+
+    def on_message(self, _message):
+        if not ImageWebSocketHandler.adapter.image:
+            Logger.warning(
+                "No image received from {}!".format(
+                    ImageWebSocketHandler.adapter.__class__.__name__
+                )
+            )
+            return
+
+        image_bytes = ImageWebSocketHandler.adapter.image
+        self.write_message(image_bytes, binary=True)
+
+    def on_close(self):
+        ImageWebSocketHandler.clients.remove(self)
+
+    def register_adapter(adapter):
+        ImageWebSocketHandler.adapter = adapter

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/main.py

@@ -0,0 +1,11 @@
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers import (
+    NoCacheRequestHandler,
+)
+
+
+class MainHandler(NoCacheRequestHandler):
+    def get(self):
+        self.render("./../static/index.html", adapter=MainHandler.adapter)
+
+    def register_adapter(adapter):
+        MainHandler.adapter = adapter

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/single_file.py

@@ -0,0 +1,19 @@
+import os
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers import (
+    NoCacheRequestHandler,
+)
+
+
+class SingleFileHandler(NoCacheRequestHandler):
+    def initialize(self, file_path):
+        self.file_path = file_path
+
+    async def get(self):
+        if not os.path.exists(self.file_path):
+            self.set_status(404)
+            return
+
+        self.set_header("Content-Type", "image/x-icon")
+
+        with open(self.file_path, "rb") as f:
+            self.write(f.read())