vispy.scene.canvas module#

class vispy.scene.canvas.SceneCanvas(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, bgcolor='black')#

Bases: Canvas, Frozen

A Canvas that automatically draws the contents of a scene


The widget title

size(width, height)

The size of the window.

position(x, y)

The position of the window in screen coordinates.


Whether to show the widget immediately. Default False.


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. ( 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


Whether to create the widget immediately. Default True.


Enable vertical synchronization.


Allow the window to be resized.


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.


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.


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.


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.


The background color to use.

See also


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.

property bgcolor#
property central_widget#

Returns the default widget that occupies the entire area of the canvas.

draw_visual(visual, event=None)#

Draw a visual and its children to the canvas or currently active framebuffer.


The visual to draw

eventNone or DrawEvent

Optionally specifies the original canvas draw event that initiated this draw.


Close event handler

eventinstance of Event

The event.


Draw handler

eventinstance of Event

The draw event.


Resize handler

eventinstance of Event

The resize event.


Pop an FBO from the stack.


Pop a viewport from the stack.

push_fbo(fbo, offset, csize)#

Push an FBO on the stack.

This activates the framebuffer and causes subsequent rendering to be written to the framebuffer rather than the canvas’s back buffer. This will also set the canvas viewport to cover the boundaries of the framebuffer.

fboinstance of FrameBuffer

The framebuffer object .


The location of the fbo origin relative to the canvas’s framebuffer origin.


The size of the region in the canvas’s framebuffer that should be covered by this framebuffer object.


Push a viewport (x, y, w, h) on the stack. Values must be integers relative to the active framebuffer.


The viewport as (x, y, w, h).

render(region=None, size=None, bgcolor=None, crop=None, alpha=True)#

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

regiontuple | None

Specifies the region of the canvas to render. Format is (x, y, w, h). By default, the entire canvas is rendered.

sizetuple | None

Specifies the size of the image array to return. If no size is given, then the size of the region is used, multiplied by the pixel scaling factor of the canvas (see pixel_scale). This argument allows the scene to be rendered at resolutions different from the native canvas resolution.

bgcolorinstance of Color | None

The background color to use.

croparray-like | None

If specified it determines the pixels read from the framebuffer. In the format (x, y, w, h), relative to the region being rendered.


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


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).

property scene#

The SubScene object that represents the root node of the scene graph to be displayed.


Update the scene

nodeinstance of Node

Not used.


Return the visual at a given position


The position in logical coordinates to query.

visualinstance of Visual | None

The visual at the position, if it exists.

visuals_at(pos, radius=10)#

Return a list of visuals within radius pixels of pos.

Visuals are sorted by their proximity to pos.


(x, y) position at which to find visuals.


Distance away from pos to search for visuals.