RGBMatrixEmulator


NameRGBMatrixEmulator JSON
Version 0.11.6 PyPI version JSON
download
home_pageNone
SummaryA PC emulator for Raspberry Pi LED matrices driven by rpi-rgb-led-matrix
upload_time2024-05-24 06:30:33
maintainerNone
docs_urlNone
authorNone
requires_pythonNone
licenseNone
keywords led led matrix rpi matrix raspberry raspberry pi
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # `RGBMatrixEmulator`

[![pypi Badge](https://img.shields.io/pypi/v/RGBMatrixEmulator)](https://pypi.org/project/RGBMatrixEmulator/)

![hello-world](assets/hello-world.gif)

`RGBMatrixEmulator` is a Python package for emulating RGB LED matrices that are normally driven by the `rpi-rgb-led-matrix` library. Most commonly, these are used with single-board computers such as the Raspberry Pi.

`RGBMatrixEmulator` (currently) supports a subset of the function calls present in the Python bindings for `rpi-rgb-led-matrix`. As such, it's accuracy is not 100% guaranteed.

## Installation

`RGBMatrixEmulator` is in the [Python Package Index (PyPI)](http://pypi.python.org/pypi/RGBMatrixEmulator/).
Installing with ``pip`` is recommended for all systems.

```sh
pip install RGBMatrixEmulator
```

## Usage

Projects that are able to be emulated will rely on importing classes from `rpi-rgb-led-matrix`. These will need to be replaced by equivalent `RGBMatrixEmulator` classes.

For example, usage on a Rasberry Pi might look like this:

```python
from rgbmatrix import RGBMatrix, RGBMatrixOptions
```

The emulated version will need to use `RGBMatrixEmulator` classes:

```python
from RGBMatrixEmulator import RGBMatrix, RGBMatrixOptions
```

After this, most of the existing command line arguments from the `rpi-rgb-led-matrix` library still apply. You should reference the [project README](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/README.md) for that library when necessary.

Startup of the existing script will be unchanged.

## Customization

The first time you run a script with the emulator enabled, a file called `emulator_config.json` will be created in the script's directory. This enables configurations to be customized on a per-script basis. If you would like to regenerate the default configuration, you can delete the file and a new one will be created the next time the emulator starts.

The default configuration is as follows:

```json
{
  "pixel_outline": 0,
  "pixel_size": 16,
  "pixel_style": "square",
  "display_adapter": "browser",
  "suppress_font_warnings": false,
  "suppress_adapter_load_errors": false,
  "browser": {
    "_comment": "For use with the browser adapter only.",
    "port": 8888,
    "target_fps": 24,
    "fps_display": false,
    "quality": 70,
    "image_border": true,
    "debug_text": false,
    "image_format": "JPEG"
  },
  "log_level": "info"
}
```

### Configuration Options

```
pixel_outline          (Integer): Size of the black border around each pixel. Only works on some adapters; others will ignore this configuration.
pixel_size             (Integer): Size of the emulated LED. Helpful for emulating large matrices on small screens. Actual window size is the matrix size scaled by pixel size.
pixel_style            (String):  Style of the emulated LED. Supported pixel styles are "square" and "circle". Some display adapters do not support all options and will revert to a supported style.
display_adapter        (String):  Display adapter for the emulator. See Display Adapters section for details.
suppress_font_warnings (Boolean): Suppress BDF font parsing errors, such as for missing characters.
browser                (Dict):    Additional configuration options for the "browser" display adapter. Does nothing for other adapters.
  port                 (Integer): Port for the rendering server to attach to. Example: http://localhost:8888
  target_fps           (Integer): Target frames per second. Higher values may lead to lower performance.
  fps_display          (Bool):    Display the FPS.
  quality              (Intger):  Value from 0 - 100 indicating the quality percentage for the rendered image. Higher values may lead to lower performance.
  image_border         (Bool):    Display a slight border around the rendered image.
  debug_text           (Bool):    Display debug text.
```
Altering the `pixel_size` configuration will change how large the LEDs appear on your screen. This is helpful for emulating large matrices or on small screens.

You can also change the `pixel_style` option. By default, the emulator represents LEDs as squares. If you prefer the LEDs to have a more rounded appearance (like they would on an actual matrix), you can change to `pixel_style: "circle"`.

### Display Adapters

By default, `RGBMatrixEmulator` uses `browser` as its display adapter for maximum compatibility with different operating systems as well as thread-safety. However, you can also use other display adapters as well if the default adapter does not suit your needs.

Currently supported display adapters are:

* `browser` (default)
* `pygame`
* `terminal`
* `tkinter`
* `turtle`
* `sixel`

You can swap display adapters by changing the `display_adapter` value to one of the above in `emulator_config.json`.

**Note:** Not all display adapters support all emulator features. Some adapters may require additional setup steps to install. For example, on OSX, it may be necessary to install `tkinter` via Homebrew (`brew install python-tk`).

### Browser Display Adapter

Please see the [README for the `browser` display adapter](RGBMatrixEmulator/adapters/browser_adapter/README.md) for further information regarding its configuration and usage.

## Screenshots

![rotating-block](assets/rotating-block.gif)
![mlb-led-scoreboard](assets/mlb-led-scoreboard.png)
![nhl-led-scoreboard](assets/nhl-clock.png)
![circular-leds](assets/circular-leds.png)
![browser-adapter](assets/browser-adapter.gif)

## Samples

See [Samples README](samples/README.md) for more information about running example scripts.

## Known Issues

- Calling draw functions on an instance of `RGBMatrix` is slow (i.e. `matrix.SetPixel`, `matrix.Fill`)
  - Prefer using on a `Canvas` instance instead
  - `rpi-rgb-led-matrix` uses a threaded implementation to handle single pixel draws with the `RGBMatrix` class, unfortunately `RGBMatrixEmulator` redraws the entire screen on each call
  - NOTE: the implementation is accurate other than speed (you _can_ still drop `RGBMatrixEmulator` into a project that makes calls to the matrix object)
  - <details>
    <summary>Expand Example</summary>
    
    ```python
    # SLOW
    matrix = RGBMatrix(options = RGBMatrixOptions)

    for y in matrix.height:
      for x in matrix.width:
        matrix.SetPixel(x, y, 255, 255, 255) # Redraws entire screen

    # FAST
    matrix = RGBMatrix(options = RGBMatrixOptions)
    canvas = matrix.CreateFrameCanvas()

    for y in matrix.height:
      for x in matrix.width:
        canvas.SetPixel(x, y, 255, 255, 255) # No redraw

    matrix.SwapOnVsync(canvas) # Force screen refresh
    ```
  </details>
- Drawing large strings is slow, partly because of the `linelimit` parameter in the BDF font parser this emulator uses to prevent multiline text from being rendered unintentionally.

## Contributing
If you want to help develop RGBMatrixEmulator, you must also install the dev dependencies, which can be done by running ``pip install -e .[dev]`` from within the directory.

Before submitting a PR, please open an issue to help us track development. All development should be based off of the `dev` branch. This branch is kept up-to-date with `main` after releases. 

## Contact

Tyler Porter

tyler.b.porter@gmail.com

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "RGBMatrixEmulator",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": "LED, LED matrix, RPI, matrix, raspberry, raspberry pi",
    "author": null,
    "author_email": "Tyler Porter <tyler.b.porter@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/fc/42/e08bd80193d30f427838faed0666f15ec25e126b7d6d3bbb97fa9f77cd52/rgbmatrixemulator-0.11.6.tar.gz",
    "platform": null,
    "description": "# `RGBMatrixEmulator`\n\n[![pypi Badge](https://img.shields.io/pypi/v/RGBMatrixEmulator)](https://pypi.org/project/RGBMatrixEmulator/)\n\n![hello-world](assets/hello-world.gif)\n\n`RGBMatrixEmulator` is a Python package for emulating RGB LED matrices that are normally driven by the `rpi-rgb-led-matrix` library. Most commonly, these are used with single-board computers such as the Raspberry Pi.\n\n`RGBMatrixEmulator` (currently) supports a subset of the function calls present in the Python bindings for `rpi-rgb-led-matrix`. As such, it's accuracy is not 100% guaranteed.\n\n## Installation\n\n`RGBMatrixEmulator` is in the [Python Package Index (PyPI)](http://pypi.python.org/pypi/RGBMatrixEmulator/).\nInstalling with ``pip`` is recommended for all systems.\n\n```sh\npip install RGBMatrixEmulator\n```\n\n## Usage\n\nProjects that are able to be emulated will rely on importing classes from `rpi-rgb-led-matrix`. These will need to be replaced by equivalent `RGBMatrixEmulator` classes.\n\nFor example, usage on a Rasberry Pi might look like this:\n\n```python\nfrom rgbmatrix import RGBMatrix, RGBMatrixOptions\n```\n\nThe emulated version will need to use `RGBMatrixEmulator` classes:\n\n```python\nfrom RGBMatrixEmulator import RGBMatrix, RGBMatrixOptions\n```\n\nAfter this, most of the existing command line arguments from the `rpi-rgb-led-matrix` library still apply. You should reference the [project README](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/README.md) for that library when necessary.\n\nStartup of the existing script will be unchanged.\n\n## Customization\n\nThe first time you run a script with the emulator enabled, a file called `emulator_config.json` will be created in the script's directory. This enables configurations to be customized on a per-script basis. If you would like to regenerate the default configuration, you can delete the file and a new one will be created the next time the emulator starts.\n\nThe default configuration is as follows:\n\n```json\n{\n  \"pixel_outline\": 0,\n  \"pixel_size\": 16,\n  \"pixel_style\": \"square\",\n  \"display_adapter\": \"browser\",\n  \"suppress_font_warnings\": false,\n  \"suppress_adapter_load_errors\": false,\n  \"browser\": {\n    \"_comment\": \"For use with the browser adapter only.\",\n    \"port\": 8888,\n    \"target_fps\": 24,\n    \"fps_display\": false,\n    \"quality\": 70,\n    \"image_border\": true,\n    \"debug_text\": false,\n    \"image_format\": \"JPEG\"\n  },\n  \"log_level\": \"info\"\n}\n```\n\n### Configuration Options\n\n```\npixel_outline          (Integer): Size of the black border around each pixel. Only works on some adapters; others will ignore this configuration.\npixel_size             (Integer): Size of the emulated LED. Helpful for emulating large matrices on small screens. Actual window size is the matrix size scaled by pixel size.\npixel_style            (String):  Style of the emulated LED. Supported pixel styles are \"square\" and \"circle\". Some display adapters do not support all options and will revert to a supported style.\ndisplay_adapter        (String):  Display adapter for the emulator. See Display Adapters section for details.\nsuppress_font_warnings (Boolean): Suppress BDF font parsing errors, such as for missing characters.\nbrowser                (Dict):    Additional configuration options for the \"browser\" display adapter. Does nothing for other adapters.\n  port                 (Integer): Port for the rendering server to attach to. Example: http://localhost:8888\n  target_fps           (Integer): Target frames per second. Higher values may lead to lower performance.\n  fps_display          (Bool):    Display the FPS.\n  quality              (Intger):  Value from 0 - 100 indicating the quality percentage for the rendered image. Higher values may lead to lower performance.\n  image_border         (Bool):    Display a slight border around the rendered image.\n  debug_text           (Bool):    Display debug text.\n```\nAltering the `pixel_size` configuration will change how large the LEDs appear on your screen. This is helpful for emulating large matrices or on small screens.\n\nYou can also change the `pixel_style` option. By default, the emulator represents LEDs as squares. If you prefer the LEDs to have a more rounded appearance (like they would on an actual matrix), you can change to `pixel_style: \"circle\"`.\n\n### Display Adapters\n\nBy default, `RGBMatrixEmulator` uses `browser` as its display adapter for maximum compatibility with different operating systems as well as thread-safety. However, you can also use other display adapters as well if the default adapter does not suit your needs.\n\nCurrently supported display adapters are:\n\n* `browser` (default)\n* `pygame`\n* `terminal`\n* `tkinter`\n* `turtle`\n* `sixel`\n\nYou can swap display adapters by changing the `display_adapter` value to one of the above in `emulator_config.json`.\n\n**Note:** Not all display adapters support all emulator features. Some adapters may require additional setup steps to install. For example, on OSX, it may be necessary to install `tkinter` via Homebrew (`brew install python-tk`).\n\n### Browser Display Adapter\n\nPlease see the [README for the `browser` display adapter](RGBMatrixEmulator/adapters/browser_adapter/README.md) for further information regarding its configuration and usage.\n\n## Screenshots\n\n![rotating-block](assets/rotating-block.gif)\n![mlb-led-scoreboard](assets/mlb-led-scoreboard.png)\n![nhl-led-scoreboard](assets/nhl-clock.png)\n![circular-leds](assets/circular-leds.png)\n![browser-adapter](assets/browser-adapter.gif)\n\n## Samples\n\nSee [Samples README](samples/README.md) for more information about running example scripts.\n\n## Known Issues\n\n- Calling draw functions on an instance of `RGBMatrix` is slow (i.e. `matrix.SetPixel`, `matrix.Fill`)\n  - Prefer using on a `Canvas` instance instead\n  - `rpi-rgb-led-matrix` uses a threaded implementation to handle single pixel draws with the `RGBMatrix` class, unfortunately `RGBMatrixEmulator` redraws the entire screen on each call\n  - NOTE: the implementation is accurate other than speed (you _can_ still drop `RGBMatrixEmulator` into a project that makes calls to the matrix object)\n  - <details>\n    <summary>Expand Example</summary>\n    \n    ```python\n    # SLOW\n    matrix = RGBMatrix(options = RGBMatrixOptions)\n\n    for y in matrix.height:\n      for x in matrix.width:\n        matrix.SetPixel(x, y, 255, 255, 255) # Redraws entire screen\n\n    # FAST\n    matrix = RGBMatrix(options = RGBMatrixOptions)\n    canvas = matrix.CreateFrameCanvas()\n\n    for y in matrix.height:\n      for x in matrix.width:\n        canvas.SetPixel(x, y, 255, 255, 255) # No redraw\n\n    matrix.SwapOnVsync(canvas) # Force screen refresh\n    ```\n  </details>\n- Drawing large strings is slow, partly because of the `linelimit` parameter in the BDF font parser this emulator uses to prevent multiline text from being rendered unintentionally.\n\n## Contributing\nIf you want to help develop RGBMatrixEmulator, you must also install the dev dependencies, which can be done by running ``pip install -e .[dev]`` from within the directory.\n\nBefore submitting a PR, please open an issue to help us track development. All development should be based off of the `dev` branch. This branch is kept up-to-date with `main` after releases. \n\n## Contact\n\nTyler Porter\n\ntyler.b.porter@gmail.com\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A PC emulator for Raspberry Pi LED matrices driven by rpi-rgb-led-matrix",
    "version": "0.11.6",
    "project_urls": {
        "Homepage": "https://github.com/ty-porter/RGBMatrixEmulator"
    },
    "split_keywords": [
        "led",
        " led matrix",
        " rpi",
        " matrix",
        " raspberry",
        " raspberry pi"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "612c6dedaba7d56071a4bd0ee310baa9d35768ffa07a09ddfc4a444f4a86cbed",
                "md5": "da5dd02477f6b2f4eff07c47c0e31bc5",
                "sha256": "d71f94f739bc9f0d8604b3767e88b1065c1f0d46f55ce7300182d28d536dab01"
            },
            "downloads": -1,
            "filename": "rgbmatrixemulator-0.11.6-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "da5dd02477f6b2f4eff07c47c0e31bc5",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 57571,
            "upload_time": "2024-05-24T06:30:31",
            "upload_time_iso_8601": "2024-05-24T06:30:31.331083Z",
            "url": "https://files.pythonhosted.org/packages/61/2c/6dedaba7d56071a4bd0ee310baa9d35768ffa07a09ddfc4a444f4a86cbed/rgbmatrixemulator-0.11.6-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "fc42e08bd80193d30f427838faed0666f15ec25e126b7d6d3bbb97fa9f77cd52",
                "md5": "35e355b7208a8e4b70953a9a73f0e0fe",
                "sha256": "b89cd72768a0b84e48dac0c0ca613a47277b78979f07e7941373e378cc102a4c"
            },
            "downloads": -1,
            "filename": "rgbmatrixemulator-0.11.6.tar.gz",
            "has_sig": false,
            "md5_digest": "35e355b7208a8e4b70953a9a73f0e0fe",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 4794,
            "upload_time": "2024-05-24T06:30:33",
            "upload_time_iso_8601": "2024-05-24T06:30:33.515462Z",
            "url": "https://files.pythonhosted.org/packages/fc/42/e08bd80193d30f427838faed0666f15ec25e126b7d6d3bbb97fa9f77cd52/rgbmatrixemulator-0.11.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-05-24 06:30:33",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ty-porter",
    "github_project": "RGBMatrixEmulator",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "rgbmatrixemulator"
}
        
Elapsed time: 3.57445s