RemoteFrameBuffer class

class jupyter_rfb.RemoteFrameBuffer(**kwargs: Any)

A widget implementing a remote frame buffer.

This is a subclass of ipywidgets.DOMWidget. To use this class, it should be subclassed, and its .get_frame() and .handle_event() methods should be implemented.

This widget has the following traits:

  • css_width: the logical width of the frame as a CSS string. Default ‘500px’.

  • css_height: the logical height of the frame as a CSS string. Default ‘300px’.

  • resizable: whether the frame can be manually resized. Default True.

  • quality: the quality of the JPEG encoding during interaction/animation as a number between 1 and 100. Default 80. Set to lower numbers for more performance on slow connections. Note that each interaction is ended with a lossless image (PNG). If set to 100 or if JPEG encoding isn’t possible (missing pillow or simplejpeg dependencies), then lossless PNGs will always be sent.

  • max_buffered_frames: the number of frames that is allowed to be “in-flight”, i.e. sent, but not yet confirmed by the client. Default 2. Higher values may result in a higher FPS at the cost of introducing lag.

  • cursor: the cursor style, ex: “crosshair”, “grab”. Valid cursors: https://developer.mozilla.org/en-US/docs/Web/CSS/cursor#keyword

print(*args, **kwargs)

Print to the widget’s output area (for debugging purposes).

In Jupyter, print calls that occur in a callback or an asyncio task may (depending on your version of the notebook/lab) not be shown. Inside .get_frame() and .handle_event() you can use this method instead. The signature of this method is fully compatible with the builtin print function (except for the file argument).

close(*args, **kwargs)

Close all views of the widget and emit a close event.

snapshot(pixel_ratio=None)

Render a frame and include the resulting image in the output.

An initial placeholder output is produced, which is replaced by an html <img> as soon as the next frame is rendered.

If the widget is not displayed yet, a resize event is emitted to mimic a widget size. This happens at most once in the widget’s lifetime. It will use the css_width and css_height if they are expressed in px, and otherwise default to 500 or 300 pixels respectively. The pixel_ratio argument is then used to calculate the physical size.

request_draw()

Schedule a new draw. This method itself returns immediately.

This method is automatically called on each resize event. During a draw, the .get_frame() method is called, and the resulting array is sent to the client. See the docs for details about scheduling.

send_frame(array)

Send a frame to display.

The intended use is for async use-cases, to let get_frame() return None, render the frame asynchronously, and use send_frame() when its done.

This function can be used to push frames to the client, but this is not recommended in general, since it bypasses the frame throughput mechanism, and can therefore overload the IO, resulting in high latency.

reset_stats()

Restart measuring statistics from the next sent frame.

get_stats()

Get the current stats since the last time .reset_stats() was called.

Stats is a dict with the following fields:

  • sent_frames: the number of frames sent.

  • confirmed_frames: number of frames confirmed by the client.

  • roundtrip: avererage time for processing a frame, including receiver confirmation.

  • delivery: average time for processing a frame until it’s received by the client. This measure assumes that the clock of the server and client are precisely synced.

  • img_encoding: the average time spent on encoding the array into an image.

  • b64_encoding: the average time spent on base64 encoding the data.

  • fps: the average FPS, measured from the first frame sent since .reset_stats() was called, until the last confirmed frame.

get_frame()

Return image array for the next frame.

Subclasses should overload this method. It is automatically called during a draw. The returned numpy array must be NxM (grayscale), NxMx3 (RGB) or NxMx4 (RGBA). May also return None to cancel the draw.

As alternative asynchronous usage, the implementation may also return None and then call send_frame() somewhat later.

handle_event(event)

Handle an incoming event.

Subclasses should overload this method. Events include widget resize, mouse/touch interaction, key events, and more. An event is a dict with at least the key type. See jupyter_rfb.events for details.