RGBMatrixEmulator 0.12.0__py2.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,72 @@
+import importlib, json
+
+from RGBMatrixEmulator.logger import Logger
+
+adapters = [
+    {
+        "path": "RGBMatrixEmulator.adapters.browser_adapter.adapter",
+        "class": "BrowserAdapter",
+        "type": "browser",
+    },
+    {
+        "path": "RGBMatrixEmulator.adapters.pygame_adapter",
+        "class": "PygameAdapter",
+        "type": "pygame",
+    },
+    {
+        "path": "RGBMatrixEmulator.adapters.sixel_adapter",
+        "class": "SixelAdapter",
+        "type": "sixel",
+    },
+    {
+        "path": "RGBMatrixEmulator.adapters.terminal_adapter",
+        "class": "TerminalAdapter",
+        "type": "terminal",
+    },
+    {
+        "path": "RGBMatrixEmulator.adapters.tkinter_adapter",
+        "class": "TkinterAdapter",
+        "type": "tkinter",
+    },
+    {
+        "path": "RGBMatrixEmulator.adapters.turtle_adapter",
+        "class": "TurtleAdapter",
+        "type": "turtle",
+    },
+]
+
+ADAPTER_TYPES = {}
+
+try:
+    with open("emulator_config.json") as config_file:
+        suppress_adapter_load_errors = json.load(config_file).get(
+            "suppress_adapter_load_errors", False
+        )
+except:
+    suppress_adapter_load_errors = False
+
+for adapter in adapters:
+    package_path = adapter.get("path")
+    adapter_class = adapter.get("class")
+    adapter_name = adapter.get("type")
+    try:
+        package = importlib.import_module(package_path)
+        adapter = getattr(package, adapter_class)
+
+        ADAPTER_TYPES[adapter_name] = adapter
+    except Exception as ex:
+        if suppress_adapter_load_errors:
+            continue
+
+        Logger.exception(
+            f"""
+Failed to load {adapter_class} for "{adapter_name}" display adapter!
+
+If this is not your configured display adapter, the emulator will continue to load.
+
+You can suppress this error in the `emulator_config.json` by adding:
+
+  "suppress_adapter_load_errors": true
+
+"""
+        )

RGBMatrixEmulator/adapters/base.py

@@ -0,0 +1,109 @@
+import numpy as np
+
+from PIL import Image, ImageDraw
+from RGBMatrixEmulator import version
+
+
+def draw_circle_mask(drawer, x, y, pixel_size, color):
+    drawer.ellipse(
+        (x, y, x + pixel_size - 1, y + pixel_size - 1),
+        fill=color,
+        outline=color,
+    )
+
+
+def draw_square_mask(drawer, x, y, pixel_size, color):
+    drawer.rectangle(
+        (x, y, x + pixel_size, y + pixel_size),
+        fill=color,
+        outline=color,
+    )
+
+
+class BaseAdapter:
+    SUPPORTS_ALTERNATE_PIXEL_STYLE = False
+    INSTANCE = None
+
+    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
+
+    def __draw_mask(self):
+        mask = Image.new("L", self.options.window_size())
+        drawer = ImageDraw.Draw(mask)
+        pixel_size = self.options.pixel_size
+        width, height = self.options.window_size()
+        draw_mask_shape = (
+            draw_circle_mask
+            if self.options.pixel_style == "circle"
+            else draw_square_mask
+        )
+        for y in range(0, height, pixel_size):
+            for x in range(0, width, pixel_size):
+                draw_mask_shape(drawer, x, y, pixel_size, 255)
+
+        return mask
+
+    @classmethod
+    def get_instance(cls, *args, **kwargs):
+        if cls.INSTANCE is None:
+            instance = cls(*args, **kwargs)
+            cls.INSTANCE = instance
+
+        return cls.INSTANCE
+
+    def pixel_out_of_bounds(self, x, y):
+        if x < 0 or x >= self.width:
+            return True
+
+        if y < 0 or y >= self.height:
+            return True
+
+        return False
+
+    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 emulator_details_text(self):
+        details_text = "RGBME v{} - {}x{} Matrix | {}x{} Chain | {}px per LED ({}) | {}"
+
+        return details_text.format(
+            version.__version__,
+            self.options.cols,
+            self.options.rows,
+            self.options.chain_length,
+            self.options.parallel,
+            self.options.pixel_size,
+            self.options.pixel_style.upper(),
+            self.__class__.__name__,
+        )
+
+    # 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

RGBMatrixEmulator/adapters/browser_adapter/README.md

@@ -0,0 +1,89 @@
+# `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.
+
+#### Tydbit Support
+
+Tydbit requires `WebP` images to be exposed over a static HTTP endpoint. You can use the browser adapter's static image endpoint to provide cross-functional compatibility to Tydbit boards.
+
+An example configuration that works for Tydbit matrices is provided:
+
+```json
+{
+  "pixel_outline": 0,
+  "pixel_size": 1,
+  "pixel_style": "square",
+  "display_adapter": "browser",
+  "suppress_font_warnings": false,
+  "suppress_adapter_load_errors": false,
+  "browser": {
+    "port": 8888,
+    "target_fps": 24,
+    "fps_display": false,
+    "quality": 70,
+    "image_border": true,
+    "debug_text": false,
+    "image_format": "WebP"
+  },
+  "log_level": "info"
+}
+```
+
+## 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,51 @@
+import io
+
+from RGBMatrixEmulator.adapters.base import BaseAdapter
+from RGBMatrixEmulator.adapters.browser_adapter.server import Server
+from RGBMatrixEmulator.logger import Logger
+
+
+class BrowserAdapter(BaseAdapter):
+    SUPPORTS_ALTERNATE_PIXEL_STYLE = True
+    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.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()
+            )
+
+    def load_emulator_window(self):
+        if self.loaded:
+            return
+
+        Logger.info(self.emulator_details_text())
+
+        self.__server = Server(self)
+        self.__server.run()
+
+        self.loaded = True
+
+    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()

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/__init__.py

@@ -0,0 +1,7 @@
+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,
+)

RGBMatrixEmulator/adapters/browser_adapter/request_handlers/image.py

@@ -0,0 +1,12 @@
+import tornado.web
+
+
+class ImageHandler(tornado.web.RequestHandler):
+    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,34 @@
+import tornado.websocket
+
+from RGBMatrixEmulator.logger import Logger
+
+
+class ImageWebSocketHandler(tornado.websocket.WebSocketHandler):
+    clients = set()
+    adapter = None
+
+    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,9 @@
+import tornado.web
+
+
+class MainHandler(tornado.web.RequestHandler):
+    def get(self):
+        self.render("./../static/index.html", adapter=MainHandler.adapter)
+
+    def register_adapter(adapter):
+        MainHandler.adapter = adapter

RGBMatrixEmulator/adapters/browser_adapter/server.py

@@ -0,0 +1,86 @@
+import asyncio
+import signal
+import sys
+import threading
+import tornado.web
+import tornado.ioloop
+
+from os import path
+from tornado.platform.asyncio import AnyThreadEventLoopPolicy
+
+from RGBMatrixEmulator.adapters.browser_adapter.request_handlers import *
+from RGBMatrixEmulator.logger import Logger
+
+
+asyncio.set_event_loop_policy(AnyThreadEventLoopPolicy())
+
+
+class Server:
+    instance = None
+
+    # Singleton class for the server.
+    # No more than one webserver can be running at a given time.
+    class __Singleton:
+        def __init__(self, adapter):
+            self.adapter = adapter
+            self.io_loop = None
+            self.listening = False
+
+            MainHandler.register_adapter(self.adapter)
+            ImageWebSocketHandler.register_adapter(self.adapter)
+            ImageHandler.register_adapter(self.adapter)
+
+            script_path = path.dirname(path.realpath(__file__))
+            asset_path = path.normpath(script_path + "/static/assets/")
+
+            self.app = tornado.web.Application(
+                [
+                    (r"/websocket", ImageWebSocketHandler),
+                    (r"/image", ImageHandler),
+                    (r"/", MainHandler),
+                    (
+                        r"/assets/(.*)",
+                        tornado.web.StaticFileHandler,
+                        {"path": asset_path, "default_filename": "client.js"},
+                    ),
+                ]
+            )
+
+    def __init__(self, adapter):
+        if not Server.instance:
+            Server.instance = Server.__Singleton(adapter)
+
+    def run(self):
+        if not self.instance.listening:
+            Logger.info("Starting server...")
+
+            self.instance.listening = True
+            self.instance.app.listen(self.instance.adapter.options.browser.port)
+            self.instance.io_loop = tornado.ioloop.IOLoop.current()
+            thread = threading.Thread(
+                target=self.instance.io_loop.start,
+                name="RGBMEServerThread",
+                daemon=True,
+            )
+            self.__initialize_interrupts()
+            thread.start()
+
+            Logger.info(
+                "Server started and ready to accept requests on http://localhost:"
+                + str(self.instance.adapter.options.browser.port)
+                + "/"
+            )
+
+    def __initialize_interrupts(self):
+        """
+        Add custom signal handling to ensure webserver thread exits appropriately.
+
+        Not thread-safe, signal handling must happen on the main thread.
+        """
+        if threading.current_thread() is threading.main_thread():
+            signal.signal(signal.SIGINT, self.__kill)
+            signal.signal(signal.SIGTERM, self.__kill)
+
+    def __kill(self, *_args):
+        self.instance.io_loop.add_callback(self.instance.io_loop.stop)
+        sys.exit()

RGBMatrixEmulator/adapters/browser_adapter/static/assets/client.js

@@ -0,0 +1,91 @@
+function init() {
+    const WS_RETRY_DELAY = 2000;
+    const FPS_DEFAULT    = 24;
+
+    let img       = document.getElementById("liveImg");
+    let fpsText   = document.getElementById("fps");
+    let fpsTarget = parseInt(document.getElementById("targetFps").value) || FPS_DEFAULT;
+
+    let requestStartTime = performance.now();
+    let startTime = performance.now();
+    let time = 0;
+    let requestTime = 0;
+    let timeSmoothing = 0.9;           // larger=more smoothing
+    let requestTimeSmoothing = 0.2;    // larger=more smoothing
+    let targetTime = 1000 / fpsTarget;
+
+    let socket = generateSocket();
+
+    function requestImage() {
+        requestStartTime = performance.now();
+        socket.send('more');
+    }
+
+    function generateSocket() {
+        let path = location.pathname;
+
+        if (path.endsWith("index.html")) {
+            path = path.substring(0, path.length - "index.html".length);
+        }
+
+        if(!path.endsWith("/")) {
+            path = path + "/";
+        }
+
+        let wsProtocol = (location.protocol === "https:") ? "wss://" : "ws://";
+        let ws = new WebSocket(wsProtocol + location.host + path + "websocket");
+
+        ws.binaryType = 'arraybuffer';
+
+        ws.onopen = function() {
+            console.log("RGBME WebSocket connection established!");
+            startTime = performance.now();
+            requestImage();
+        };
+
+        ws.onclose = function() {
+            // Handle retries by recreating the connection to websocket.
+            console.warn(`RGBME WebSocket connection lost. Retrying in ${WS_RETRY_DELAY / 1000}s.`)
+            setTimeout(function() {
+                // We generate socket with a timeout to make sure server has time to recover.
+                socket = generateSocket();
+            }, WS_RETRY_DELAY);
+        }
+
+        ws.onerror = function() {
+            ws.close();
+        }
+
+        ws.onmessage = function(evt) {
+            let arrayBuffer = evt.data;
+            let blob  = new Blob([new Uint8Array(arrayBuffer)], {type: "image/jpeg"});
+            let old_img = img.src.slice()
+            img.src   = window.URL.createObjectURL(blob);
+            window.URL.revokeObjectURL(old_img);
+
+            let endTime = performance.now();
+            let currentTime = endTime - startTime;
+            // smooth with moving average
+            time = (time * timeSmoothing) + (currentTime * (1.0 - timeSmoothing));
+            startTime = endTime;
+            let fps = Math.round(1000 / time);
+
+            if (fpsText) {
+                fpsText.textContent = fps;
+            }
+
+            let currentRequestTime = performance.now() - requestStartTime;
+            // smooth with moving average
+            requestTime = (requestTime * requestTimeSmoothing) + (currentRequestTime * (1.0 - requestTimeSmoothing));
+            let timeout = Math.max(0, targetTime - requestTime);
+
+            setTimeout(requestImage, timeout);
+        };
+
+        return ws;
+    }
+
+    console.log(`TARGET FPS: ${fpsTarget}`);
+};
+
+init();

RGBMatrixEmulator/adapters/browser_adapter/static/assets/styles.css

@@ -0,0 +1,25 @@
+body {
+  background-color: black;
+  color: white;
+  font-family: monospace;
+}
+
+img#liveImg {
+  border: 1px solid gray;
+}
+
+img#liveImg.no-border {
+  border: none;
+}
+
+.emulatorDetailsTableRow { 
+  display: flex;
+}
+
+.tableContainer {
+  margin-right: 20px;
+}
+
+td {
+  padding-right: 10px;
+}