vispy.app.canvas module

class vispy.app.canvas.Canvas(title='VisPy canvas', size=(800, 600), position=None, show=False, autoswap=True, app=None, create_native=True, vsync=False, resizable=True, decorate=True, fullscreen=False, config=None, shared=None, keys=None, parent=None, dpi=None, always_on_top=False, px_scale=1, backend_kwargs=None)

Bases: object

Representation of a GUI element with an OpenGL context

Parameters:

titlestr

The widget title

size(width, height)

The size of the window.

position(x, y)

The position of the window in screen coordinates.

showbool

Whether to show the widget immediately. Default False.

autoswapbool

Whether to swap the buffers automatically after a draw event. Default True. If True, the swap_buffers Canvas method will be called last (by default) by the canvas.draw event handler.

appApplication | str

Give vispy Application instance to use as a backend. (vispy.app is used by default.) If str, then an application using the chosen backend (e.g., ‘pyglet’) will be created. Note the canvas application can be accessed at canvas.app.

create_nativebool

Whether to create the widget immediately. Default True.

vsyncbool

Enable vertical synchronization.

resizablebool

Allow the window to be resized.

decoratebool

Decorate the window. Default True.

fullscreenbool | int

If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.

configdict

A dict with OpenGL configuration options, which is combined with the default configuration options and used to initialize the context. See canvas.context.config for possible options.

sharedCanvas | GLContext | None

An existing canvas or context to share OpenGL objects with.

keysstr | dict | None

Default key mapping to use. If ‘interactive’, escape and F11 will close the canvas and toggle full-screen mode, respectively. If dict, maps keys to functions. If dict values are strings, they are assumed to be Canvas methods, otherwise they should be callable.

parentwidget-object

The parent widget if this makes sense for the used backend.

dpifloat | None

Resolution in dots-per-inch to use for the canvas. If dpi is None, then the value will be determined by querying the global config first, and then the operating system.

always_on_topbool

If True, try to create the window in always-on-top mode.

px_scaleint > 0

A scale factor to apply between logical and physical pixels in addition to the actual scale factor determined by the backend. This option allows the scale factor to be adjusted for testing.

backend_kwargsdict

Keyword arguments to be supplied to the backend canvas object.

Notes

The Canvas receives the following events:

• initialize

• resize

• draw

• mouse_press

• mouse_release

• mouse_double_click

• mouse_move

• mouse_wheel

• key_press

• key_release

• stylus

• touch

• close

The ordering of the mouse_double_click, mouse_press, and mouse_release events are not guaranteed to be consistent between backends. Only certain backends natively support double-clicking (currently Qt and WX); on other backends, they are detected manually with a fixed time delay. This can cause problems with accessibility, as increasing the OS detection time or using a dedicated double-click button will not be respected.

Backend-specific arguments can be given through the backend_kwargs argument.

property app

The vispy Application instance on which this Canvas is based.

close()

Close the canvas

Notes

This will usually destroy the GL context. For Qt, the context (and widget) will be destroyed only if the widget is top-level. To avoid having the widget destroyed (more like standard Qt behavior), consider making the widget a sub-widget.

connect(fun)

Connect a function to an event

The name of the function should be on_X, with X the name of the event (e.g. ‘on_draw’).

This method is typically used as a decorator on a function definition for an event handler.

Parameters:

funcallable

The function.

property context

The OpenGL context of the native widget

It gives access to OpenGL functions to call on this canvas object, and to the shared context namespace.

create_native()

Create the native widget if not already done so. If the widget is already created, this function does nothing.

property dpi

The physical resolution of the canvas in dots per inch.

property fps

The fps of canvas/window, as the rate that events.draw is emitted.

property fullscreen

measure_fps(window=1, callback='%1.1f FPS')

Measure the current FPS

Sets the update window, connects the draw event to update_fps and sets the callback function.

Parameters:

windowfloat

The time-window (in seconds) to calculate FPS. Default 1.0.

callbackfunction | str

The function to call with the float FPS value, or the string to be formatted with the fps value and then printed. The default is '%1.1f FPS'. If callback evaluates to False, the FPS measurement is stopped.

property native

The native widget object on which this Canvas is based.

property physical_size

The physical size of the canvas/window, which may differ from the size property on backends that expose HiDPI.

property pixel_scale

The ratio between the number of logical pixels, or ‘points’, and the physical pixels on the device. In most cases this will be 1.0, but on certain backends this will be greater than 1. This should be used as a scaling factor when writing your own visualisations with gloo (make a copy and multiply all your logical pixel values by it). When writing Visuals or SceneGraph visualisations, this value is exposed as TransformSystem.px_scale.

property position

The position of canvas/window relative to screen.

render(alpha=True)

Render the canvas to an offscreen buffer and return the image array.

Parameters:

alphabool

If True (default) produce an RGBA array (M, N, 4). If False, remove the Alpha channel and return the RGB array (M, N, 3). This may be useful if blending of various elements requires a solid background to produce the expected visualization.

Returns:

imagearray

Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region. If alpha is False, then only 3 channels will be returned (RGB).

set_current(event=None)

Make this the active GL canvas

Parameters:

eventNone

Not used.

show(visible=True, run=False)

Show or hide the canvas

Parameters:

visiblebool

Make the canvas visible.

runbool

Run the backend event loop.

property size

The size of canvas/window.

swap_buffers(event=None)

Swap GL buffers such that the offscreen buffer becomes visible

Parameters:

eventNone

Not used.

property title

The title of canvas/window.

update(event=None)

Inform the backend that the Canvas needs to be redrawn

Parameters:

eventNone

Not used.

class vispy.app.canvas.DrawEvent(type, region=None, **kwargs)

Bases: Event

Draw event class

This type of event is sent to Canvas.events.draw when a redraw is required.

Note that each event object has an attribute for each of the input arguments listed below.

Parameters:

typestr

String indicating the event type (e.g. mouse_press, key_release)

region(int, int, int, int) or None

The region of the canvas which needs to be redrawn (x, y, w, h). If None, the entire canvas must be redrawn.

nativeobject (optional)

The native GUI event object

**kwargsextra keyword arguments

All extra keyword arguments become attributes of the event object.

property region

class vispy.app.canvas.KeyEvent(type, key=None, text='', modifiers=None, **kwargs)

Bases: Event

Key event class

Note that each event object has an attribute for each of the input arguments listed below.

Parameters:

typestr

String indicating the event type (e.g. mouse_press, key_release)

keyvispy.keys.Key instance

The Key object for this event. Can be compared to string names.

textstr

The text representation of the key (can be an empty string).

modifierstuple of Key instances

Tuple that specifies which modifier keys were pressed down at the time of the event (shift, control, alt, meta).

nativeobject (optional)

The native GUI event object

**kwargskeyword arguments

All extra keyword arguments become attributes of the event object.

property key

property modifiers

property text

class vispy.app.canvas.MouseEvent(type, pos=None, button=None, buttons=None, modifiers=None, delta=None, last_event=None, press_event=None, **kwargs)

Bases: Event

Mouse event class

Note that each event object has an attribute for each of the input arguments listed below, as well as a “time” attribute with the event’s precision start time.

Parameters:

typestr

String indicating the event type (e.g. mouse_press, key_release)

pos(int, int)

The position of the mouse (in screen coordinates).

buttonint | None

The button that generated this event (can be None). Left=1, right=2, middle=3. During a mouse drag, this will return the button that started the drag (same thing as event.press_event.button).

buttons[int, …]

The list of buttons pressed during this event.

modifierstuple of Key instances

Tuple that specifies which modifier keys were pressed down at the time of the event (shift, control, alt, meta).

delta(float, float)

The amount of scrolling in horizontal and vertical direction. One “tick” corresponds to a delta of 1.0.

press_eventMouseEvent

The press event that was generated at the start of the current drag, if any.

last_eventMouseEvent

The MouseEvent immediately preceding the current event. During drag operations, all generated events retain their last_event properties, allowing the entire drag to be reconstructed.

nativeobject (optional)

The native GUI event object

**kwargskeyword arguments

All extra keyword arguments become attributes of the event object.

property button

property buttons

property delta

drag_events()

Return a list of all mouse events in the current drag operation.

Returns None if there is no current drag operation.

property is_dragging

Indicates whether this event is part of a mouse drag operation.

property last_event

property modifiers

property pos

property press_event

property time

trail()

Return an (N, 2) array of mouse coordinates for every event in the current mouse drag operation.

Returns None if there is no current drag operation.

class vispy.app.canvas.ResizeEvent(type, size=None, physical_size=None, **kwargs)

Bases: Event

Resize event class

Note that each event object has an attribute for each of the input arguments listed below.

Parameters:

typestr

String indicating the event type (e.g. mouse_press, key_release)

size(int, int)

The new size of the Canvas, in points (logical pixels).

physical_size(int, int)

The new physical size of the Canvas, in pixels.

nativeobject (optional)

The native GUI event object

**kwargsextra keyword arguments

All extra keyword arguments become attributes of the event object.

property physical_size

property size