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')[source]

Bases: vispy.app.canvas.Canvas, vispy.util.frozen.Frozen

A Canvas that automatically draws the contents of a scene

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.

bgcolorColor

The background color to use.

See also

vispy.app.Canvas

Notes

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)[source]

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

Parameters
visualVisual

The visual to draw

eventNone or DrawEvent

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

on_close(event)[source]

Close event handler

Parameters
eventinstance of Event

The event.

on_draw(event)[source]

Draw handler

Parameters
eventinstance of Event

The draw event.

on_resize(event)[source]

Resize handler

Parameters
eventinstance of Event

The resize event.

pop_fbo()[source]

Pop an FBO from the stack.

pop_viewport()[source]

Pop a viewport from the stack.

push_fbo(fbo, offset, csize)[source]

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.

Parameters
fboinstance of FrameBuffer

The framebuffer object .

offsettuple

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

csizetuple

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

push_viewport(viewport)[source]

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

Parameters
viewporttuple

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

render(region=None, size=None, bgcolor=None, crop=None, alpha=True)[source]

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

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

alphabool

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.

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

property scene

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

update(node=None)[source]

Update the scene

Parameters
nodeinstance of Node

Not used.

visual_at(pos)[source]

Return the visual at a given position

Parameters
postuple

The position in logical coordinates to query.

Returns
visualinstance of Visual | None

The visual at the position, if it exists.

visuals_at(pos, radius=10)[source]

Return a list of visuals within radius pixels of pos.

Visuals are sorted by their proximity to pos.

Parameters
postuple

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

radiusint

Distance away from pos to search for visuals.