Kivy Headless Renderer

This project provides utilities to render Kivy applications headlessly. It can be used in test environments, it also provides tools for snapshot testing. It can also be used on a Raspberry Pi or similar devices to render the Kivy application on a custom display like an SPI display.

The renderer is optimized to not schedule a render when nothing has changed since the last rendered frame.

📦 Installation

pip install headless-kivy

To use its test tools, you can install it with the following command:

pip install headless-kivy[dev]

🛠 Usage

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):
```
setup_headless(
    width=240,
    height=240,
    is_debug_mode=False,
    display_class=ST7789,
    double_buffering=True,
)
```
Inherit the HeadlessWidget class for the root widget of your Kivy application. For example:
```
class FboFloatLayout(FloatLayout, HeadlessWidget):
    pass
```
Run the Kivy app as you normally would.

Checkout 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:

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.

`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 installed on your machine.

To install the required dependencies, run the following command in the root directory of the project:

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 file for more details.

Metadata

Release files for headless-kivy 0.11.1.dev2241027103529910210010054101

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for headless-kivy 0.11.1.dev2241027103529910210010054101
File	Size	Uploaded
headless_kivy-0.11.1.dev2241027103529910210010054101.tar.gz	13.0 kB	Oct 27, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for headless-kivy 0.11.1.dev2241027103529910210010054101
File	Interpreter	ABI	Platform	Reset
headless_kivy-0.11.1.dev2241027103529910210010054101-py3-none-any.whl 15.8 kB Oct 27, 2024	Python 3	none	any	Details

Total release size: 28.8 kB

Release files / headless_kivy-0.11.1.dev2241027103529910210010054101.tar.gz

Download URL	headless_kivy-0.11.1.dev2241027103529910210010054101.tar.gz
Size	13.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`1873d5980af0f35fd15386b121afe906d67991c8741a263ccfa021b537859ecd`
BLAKE2b-256 checksum How to use checksums	`cec6fdf03d4ddc672b20fc13e382a634e7d90bfeb8d9b5f3b44bf3d0bd25979c`
Upload date	Oct 27, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/5.1.1 CPython/3.12.7`

Release files / headless_kivy-0.11.1.dev2241027103529910210010054101-py3-none-any.whl

Download URL	headless_kivy-0.11.1.dev2241027103529910210010054101-py3-none-any.whl
Size	15.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c09977014ef429623701d7ad52587440c16280d515ba5fb913309dfdc65cb012`
BLAKE2b-256 checksum How to use checksums	`cacbcb7a9c193a57464e5a7c9eac37d174f925c88c1d0845bddae2d011b1ca2f`
Upload date	Oct 27, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/5.1.1 CPython/3.12.7`