Skip to main content
`Ctrl`+`K`

# 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

  Parameters:
    title str

      The widget title

    size(width, height)

      The size of the window.

    position(x, y)

      The position of the window in screen coordinates.

    show bool

      Whether to show the widget immediately. Default False.

    autoswap bool

      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.

    app Application | 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_native bool

      Whether to create the widget immediately. Default True.

    vsync bool

      Enable vertical synchronization. Note for some backends (ex. Qt-based backends) and some platforms this setting may not work as expected. Some GPU drivers may require modifying vsync settings at a system or driver level (ex. NVIDIA control panel). See documentation for the specific backend engine and your system’s GPU in the case of unexpected behavior.

    resizable bool

      Allow the window to be resized.

    decorate bool

      Decorate the window. Default True.

    fullscreen bool | int

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

    config dict

      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.

    shared Canvas | GLContext | None

      An existing canvas or context to share OpenGL objects with.

    keys str | 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.

    parent widget-object

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

    dpi float | 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_top bool

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

    px_scale int > 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.

    bgcolor Color

      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)

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

    Parameters:
      visual Visual

        The visual to draw

      event None or DrawEvent

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

  on_close(event)

    Close event handler

    Parameters:
      event instance of Event

        The event.

  on_draw(event)

    Draw handler

    Parameters:
      event instance of Event

        The draw event.

  on_resize(event)

    Resize handler

    Parameters:
      event instance of Event

        The resize event.

  pop_fbo()

    Pop an FBO from the stack.

  pop_viewport()

    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.

    Parameters:
      fbo instance of FrameBuffer

        The framebuffer object .

      offset tuple

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

      csize tuple

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

  push_viewport(viewport)

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

    Parameters:
      viewport tuple

        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.

    Parameters:
      region tuple | None

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

      size tuple | 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.

      bgcolor instance of Color | None

        The background color to use.

      crop array-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.

      alpha bool

        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:
      image array

        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)

    Update the scene

    Parameters:
      node instance of Node

        Not used.

  visual_at(pos)

    Return the visual at a given position

    Parameters:
      pos tuple

        The position in logical coordinates to query.

    Returns:
      visual instance 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.

    Parameters:
      pos tuple

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

      radius int

        Distance away from pos to search for visuals.