rendercanvas

One canvas API, multiple backends 🚀

This project is part of pygfx.org

Introduction

See how the two windows above look the same? That's the idea; they also look the same to the code that renders to them. Yet, the GUI systems are very different (Qt vs glfw in this case). Now that's a powerful abstraction!

Purpose

Providing a generic API for:

• managing a canvas window (BaseRenderCanvas).
• presenting rendered results with wgpu (WgpuContext).
• presenting rendered results as a bitmap (BitmapContext).
• working with events that have standardized behavior.

The following backends are currently available:

• auto - automatically selects an appropriate backend.
• glfw - a native desktop window.
• offscreen - for offscreen rendering.
• terminal - to render in the terminal (e.g. over SSH).
• qt (pyside6 / pyside2 / pyqt6 / pyqt5) - to embed a render canvas in a qt GUI.
• wx - to embed a render canvas in a wx GUI.
• anywidget - for notebooks like Jupyter, VSCode, and Marimo.
• jupyter - previous backend for notebooks that uses jupyter_rfb.
• http - for server side rendering, display in a browser connected via the internet.
• pyodide - to run in the browser with Pyodide or PyScript.

In addition to the GUI libraries mentioned above, the following event loops are supported:

* asyncio * trio * raw

Installation

pip install rendercanvas

To have at least one backend, we recommend:

pip install rendercanvas glfw

Usage

Also see the online documentation and the examples.

A minimal example that renders noise:

import numpy as np from rendercanvas.auto import RenderCanvas, loop

canvas = RenderCanvas(update_mode="continuous") context = canvas.getbitmapcontext()
@canvas.request_draw def animate():     w, h = canvas.getlogicalsize()     bitmap = np.random.uniform(0, 255, (h, w)).astype(np.uint8)     context.set_bitmap(bitmap)
loop.run()

Run wgpu visualizations:

from rendercanvas.auto import RenderCanvas, loop from rendercanvas.utils.cube import setupdrawingsync

canvas = RenderCanvas(     title="The wgpu cube example on $backend", update_mode="continuous" ) drawframe = setupdrawing_sync(canvas) canvas.requestdraw(drawframe)
loop.run()

Embed in a Qt application: <pre><code class="lang-py">from PySide6 import QtWidgets from rendercanvas.qt import QRenderWidget

class Main(QtWidgets.QWidget):

def init(self): super().init()

splitter = QtWidgets.QSplitter() self.canvas = QRenderWidget(splitter) ...

app = QtWidgets.QApplication([]) main = Main() app.exec()</code></pre>

Async or not async

We support both; a render canvas can be used in a fully async setting using e.g. Asyncio or Trio, or in an event-driven framework like Qt. If you like callbacks, loop.calllater() always works. If you like async, use loop.addtask(). See the docs on async for details.

License

This code is distributed under the 2-clause BSD license.

Contributing

See the contribution guide.

Development install

• Clone the repo.
• Install rendercanvas and developer deps using pip install -e .[dev].

Quick tips

• Use ruff format to apply autoformatting.
• Use ruff check to check for linting errors.
• Use pytest tests to run the tests.
• Use pytest examples` to run a subset of the examples.

Code of Conduct

This repository follows the PyGfx Code of Conduct