# `RGBMatrixEmulator`
[](https://pypi.org/project/RGBMatrixEmulator/)
`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
## 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/d6/43/d2e4b948ab97ef9481b42fc9875d44667ef0c5339a52bbfe82752d5de862/rgbmatrixemulator-0.11.4.tar.gz",
"platform": null,
"description": "# `RGBMatrixEmulator`\n\n[](https://pypi.org/project/RGBMatrixEmulator/)\n\n\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\n\n\n\n\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.4",
"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": "6e9c2b3764533853ac62f264bb36801f3711b2fe2aca501b00de735f41b78e54",
"md5": "538c8c84038d83d3644a0009483647c0",
"sha256": "81fa4f34079cbd552dd604514239f1fecc1a058e50f543628a8b466721241c13"
},
"downloads": -1,
"filename": "rgbmatrixemulator-0.11.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "538c8c84038d83d3644a0009483647c0",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 57837,
"upload_time": "2024-03-28T17:34:52",
"upload_time_iso_8601": "2024-03-28T17:34:52.213480Z",
"url": "https://files.pythonhosted.org/packages/6e/9c/2b3764533853ac62f264bb36801f3711b2fe2aca501b00de735f41b78e54/rgbmatrixemulator-0.11.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d643d2e4b948ab97ef9481b42fc9875d44667ef0c5339a52bbfe82752d5de862",
"md5": "d1a2911ae956b66a6e21324f13f1aaae",
"sha256": "3ad640c38f1c31f1d76c23535790d01aaa004e8a36eab9f8b758f969076a829d"
},
"downloads": -1,
"filename": "rgbmatrixemulator-0.11.4.tar.gz",
"has_sig": false,
"md5_digest": "d1a2911ae956b66a6e21324f13f1aaae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5162,
"upload_time": "2024-03-28T17:34:53",
"upload_time_iso_8601": "2024-03-28T17:34:53.778424Z",
"url": "https://files.pythonhosted.org/packages/d6/43/d2e4b948ab97ef9481b42fc9875d44667ef0c5339a52bbfe82752d5de862/rgbmatrixemulator-0.11.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-28 17:34:53",
"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"
}
JSON
