# Headless Kivy
Provides utilities to render Kivy applications headlessly. It calls a callback whenever something has changed in the framebuffer in a locality.
It can be used to render the Kivy application on a custom display like an SPI display, it provides tools for local updates, limiting the bandwidth and limiting the fps based on the spec of the display.
It can also be used in test environments with it tools for snapshot testing.
You can control the orientation of the display and flipping the display horizontally and vertically.
The renderer is optimized to not schedule a render when nothing has changed since the last rendered frame, by default it divides the screen into tiles and checks each tile for changes separately.
It can be configured to use double buffering, so that the next frame is generated while the last frame is being transmitted to the display.
You can have multiple instances of the headless renderer in the same application, each works as a portal to your display (or multiple different displays).
## 📦 Installation
```sh
pip install headless-kivy
```
To use its test tools, you can install it with the following command:
```sh
pip install headless-kivy[test]
```
## 🛠 Usage
1. Call setup_headless() before inheriting the `HeadlessWidget` class for the root
widget of your application, and provide the optional parameters as needed. For
example (these are all default values, you only need to provide the ones you want
to change):
```python
setup_headless(
width=240,
height=240,
bandwidth_limit=1000000, # number of pixels per second
bandwidth_limit_window=.1, # allow bandwidth_limit x bandwidth_limit_window pixels to be transmitted in bandwidth_limit_window seconds
bandwidth_limit_overhead=1000, # each draw command, regardless of the size, has equivalent of this many pixels of cost in bandwidth
is_debug_mode=False,
rotation=1, # gets multiplied by 90 degrees
flip_horizontal=True,
double_buffering=True, # let headless kivy generate the next frame while the previous callback is still running
)
```
1. Inherit the `HeadlessWidget` class for the root widget of your Kivy application.
For example:
```python
class FboFloatLayout(FloatLayout, HeadlessWidget):
pass
```
1. Run the Kivy app as you normally would.
Checkout [Ubo App](https://github.com/ubopod/ubo-app) to see a sample implementation.
### ⚙️ Parameters
These parameters can be set to control the behavior of headless kivy:
#### `callback`
A callback function that will be called when the screen data changes. It should
have this signature:
```python
def render(
*,
rectangle: tuple[int, int, int, int],
data: NDArray[np.uint8],
data_hash: int,
last_render_thread: Thread,
) -> None: ...
```
`rectangle` is a tuple with the coordinates and size of the changed area in the
`(x, y, width, height)` format.
`data` is a numpy array with the screen RGB data in the `uint8` format. So its
dimensions are `(width, height, 3)`.
`data_hash` is probably not very useful for most cases, it is mostly for logging
and debugging purposes.
It always runs in a new thread, the previous thread is provided so that it can call
its `join` if desired.
#### `bandwidth_limit`
Maximum bandwidth usage in pixels per second, no limit if set to 0.
#### `bandwidth_limit_window`
Length of the time window in seconds to check the bandwidth limit.
#### `bandwidth_limit_overhead`
The overhead of each draw command in pixels, regardless of its size.
#### `width`
The width of the display in pixels.
#### `height`
The height of the display in pixels.
#### `is_debug_mode`
If set to True, the application will print debug information, including FPS.
#### `double_buffering`
Is set to `True`, it will let Kivy generate the next frame while sending the last
frame to the display.
#### `rotation`
The rotation of the display. It will be multiplied by 90 degrees.
#### `flip_horizontal`
If set to `True`, it will flip the display horizontally.
#### `flip_vertical`
If set to `True`, it will flip the display vertically.
## 🤝 Contributing
You need to have [uv](https://github.com/astral-sh/uv) installed on your machine.
To install the required dependencies, run the following command in the root directory of the project:
```sh
uv sync
```
## ⚠️ Important Note
This project has only been tested with the ST7789 SPI display module. Other display
modules might not be compatible or may require changing the parameters or even modifications
to the code.
## 🔒 License
This project is released under the Apache-2.0 License. See the [LICENSE](./LICENSE)
file for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "headless-kivy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Sassan Haradji <me@sassanh.com>",
"keywords": "display, headless, kivy, pytest, test",
"author": null,
"author_email": "Sassan Haradji <me@sassanh.com>",
"download_url": "https://files.pythonhosted.org/packages/3a/35/76f66467e0534319fdb001febfd54b681a478cb966d0617ebb242e8ec2d0/headless_kivy-0.12.2.tar.gz",
"platform": null,
"description": "# Headless Kivy\n\nProvides utilities to render Kivy applications headlessly. It calls a callback whenever something has changed in the framebuffer in a locality.\n\nIt can be used to render the Kivy application on a custom display like an SPI display, it provides tools for local updates, limiting the bandwidth and limiting the fps based on the spec of the display.\n\nIt can also be used in test environments with it tools for snapshot testing.\n\nYou can control the orientation of the display and flipping the display horizontally and vertically.\n\nThe renderer is optimized to not schedule a render when nothing has changed since the last rendered frame, by default it divides the screen into tiles and checks each tile for changes separately.\n\nIt can be configured to use double buffering, so that the next frame is generated while the last frame is being transmitted to the display.\n\nYou can have multiple instances of the headless renderer in the same application, each works as a portal to your display (or multiple different displays).\n\n## \ud83d\udce6 Installation\n\n```sh\npip install headless-kivy\n```\n\nTo use its test tools, you can install it with the following command:\n\n```sh\npip install headless-kivy[test]\n```\n\n## \ud83d\udee0 Usage\n\n1. Call setup_headless() before inheriting the `HeadlessWidget` class for the root\n widget of your application, and provide the optional parameters as needed. For\n example (these are all default values, you only need to provide the ones you want\n to change):\n\n ```python\n setup_headless(\n width=240,\n height=240,\n bandwidth_limit=1000000, # number of pixels per second\n bandwidth_limit_window=.1, # allow bandwidth_limit x bandwidth_limit_window pixels to be transmitted in bandwidth_limit_window seconds\n bandwidth_limit_overhead=1000, # each draw command, regardless of the size, has equivalent of this many pixels of cost in bandwidth\n is_debug_mode=False,\n rotation=1, # gets multiplied by 90 degrees\n flip_horizontal=True,\n double_buffering=True, # let headless kivy generate the next frame while the previous callback is still running\n )\n ```\n\n1. Inherit the `HeadlessWidget` class for the root widget of your Kivy application.\n For example:\n\n ```python\n class FboFloatLayout(FloatLayout, HeadlessWidget):\n pass\n ```\n\n1. Run the Kivy app as you normally would.\n\nCheckout [Ubo App](https://github.com/ubopod/ubo-app) to see a sample implementation.\n\n### \u2699\ufe0f Parameters\n\nThese parameters can be set to control the behavior of headless kivy:\n\n#### `callback`\n\nA callback function that will be called when the screen data changes. It should\nhave this signature:\n\n```python\ndef render(\n *,\n rectangle: tuple[int, int, int, int],\n data: NDArray[np.uint8],\n data_hash: int,\n last_render_thread: Thread,\n) -> None: ...\n```\n\n`rectangle` is a tuple with the coordinates and size of the changed area in the\n`(x, y, width, height)` format.\n\n`data` is a numpy array with the screen RGB data in the `uint8` format. So its\ndimensions are `(width, height, 3)`.\n\n`data_hash` is probably not very useful for most cases, it is mostly for logging\nand debugging purposes.\n\nIt always runs in a new thread, the previous thread is provided so that it can call\nits `join` if desired.\n\n#### `bandwidth_limit`\n\nMaximum bandwidth usage in pixels per second, no limit if set to 0.\n\n#### `bandwidth_limit_window`\n\nLength of the time window in seconds to check the bandwidth limit.\n\n#### `bandwidth_limit_overhead`\n\nThe overhead of each draw command in pixels, regardless of its size.\n\n#### `width`\n\nThe width of the display in pixels.\n\n#### `height`\n\nThe height of the display in pixels.\n\n#### `is_debug_mode`\n\nIf set to True, the application will print debug information, including FPS.\n\n#### `double_buffering`\n\nIs set to `True`, it will let Kivy generate the next frame while sending the last\nframe to the display.\n\n#### `rotation`\n\nThe rotation of the display. It will be multiplied by 90 degrees.\n\n#### `flip_horizontal`\n\nIf set to `True`, it will flip the display horizontally.\n\n#### `flip_vertical`\n\nIf set to `True`, it will flip the display vertically.\n\n## \ud83e\udd1d Contributing\n\nYou need to have [uv](https://github.com/astral-sh/uv) installed on your machine.\n\nTo install the required dependencies, run the following command in the root directory of the project:\n\n```sh\nuv sync\n```\n\n## \u26a0\ufe0f Important Note\n\nThis project has only been tested with the ST7789 SPI display module. Other display\nmodules might not be compatible or may require changing the parameters or even modifications\nto the code.\n\n## \ud83d\udd12 License\n\nThis project is released under the Apache-2.0 License. See the [LICENSE](./LICENSE)\nfile for more details.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Headless renderer for Kivy framework",
"version": "0.12.2",
"project_urls": {
"changelog": "https://github.com/sassanh/headless-kivy/blob/main/CHANGELOG.md",
"documentation": "https://github.com/sassanh/headless-kivy/",
"homepage": "https://github.com/sassanh/headless-kivy/",
"repository": "https://github.com/sassanh/headless-kivy/"
},
"split_keywords": [
"display",
" headless",
" kivy",
" pytest",
" test"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5fd3a75a04872c96a5d52eb1b6ba37cead0e036aba4e479cc69aab52041598b2",
"md5": "b8b37ba285ae881a433ce9f5158eb455",
"sha256": "d91d90304bc333cb24a36720a1caf21856cb6b050523dd38a01a9f78b626fe5a"
},
"downloads": -1,
"filename": "headless_kivy-0.12.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8b37ba285ae881a433ce9f5158eb455",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 19926,
"upload_time": "2024-11-24T15:59:30",
"upload_time_iso_8601": "2024-11-24T15:59:30.411550Z",
"url": "https://files.pythonhosted.org/packages/5f/d3/a75a04872c96a5d52eb1b6ba37cead0e036aba4e479cc69aab52041598b2/headless_kivy-0.12.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3a3576f66467e0534319fdb001febfd54b681a478cb966d0617ebb242e8ec2d0",
"md5": "3b6998bf965709bb8702515d248e0685",
"sha256": "14a6db1c8af3e5dcd5cd71296d053ff4465c1fa8f54f093105fd7a68c0a953df"
},
"downloads": -1,
"filename": "headless_kivy-0.12.2.tar.gz",
"has_sig": false,
"md5_digest": "3b6998bf965709bb8702515d248e0685",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 16288,
"upload_time": "2024-11-24T15:59:32",
"upload_time_iso_8601": "2024-11-24T15:59:32.277451Z",
"url": "https://files.pythonhosted.org/packages/3a/35/76f66467e0534319fdb001febfd54b681a478cb966d0617ebb242e8ec2d0/headless_kivy-0.12.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 15:59:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sassanh",
"github_project": "headless-kivy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "headless-kivy"
}
JSON
