The app module

The app module defines three classes: Application, Canvas, and Timer. On loading, vispy creates a default Application instance which can be used via functions in the module’s namespace.

---

vispy.app.use_app(backend_name=None, call_reuse=True)

Get/create the default Application object

It is safe to call this function multiple times, as long as backend_name is None or matches the already selected backend.

Parameters:

backend_namestr | None

The name of the backend application to use. If not specified, Vispy tries to select a backend automatically. See vispy.use() for details.

call_reusebool

Whether to call the backend’s reuse() function (True by default). Not implemented by default, but some backends need it. For example, the notebook backends need to inject some JavaScript in a notebook as soon as use_app() is called.

vispy.app.create()

Create the native application.

vispy.app.run()

Enter the native GUI event loop.

vispy.app.quit()

Quit the native GUI event loop.

vispy.app.process_events()

Process all pending GUI events

If the mainloop is not running, this should be done regularly to keep the visualization interactive and to keep the event system going.

---

class vispy.app.Application(backend_name=None)

Representation of the vispy application

This wraps a native GUI application instance. Vispy has a default instance of this class that can be created/obtained via vispy.app.use_app().

Parameters:

backend_namestr | None

The name of the backend application to use. If not specified, Vispy tries to select a backend automatically. See vispy.use() for details.

Notes

Upon creating an Application object, a backend is selected, but the native backend application object is only created when create() is called or native is used. The Canvas and Timer do this automatically.

property backend_module

The module object that defines the backend.

property backend_name

The name of the GUI backend that this app wraps.

create()

Create the native application.

is_interactive()

Determine if the user requested interactive mode.

is_notebook()

Determine if the user is executing in a Jupyter Notebook

property native

The native GUI application instance.

process_events()

Process all pending GUI events. If the mainloop is not running, this should be done regularly to keep the visualization interactive and to keep the event system going.

quit()

Quit the native GUI event loop.

reuse()

Called when the application is reused in an interactive session. This allow the backend to do stuff in the client when use_app() is called multiple times by the user. For example, the notebook backends need to inject JavaScript code as soon as use_app() is called.

run(allow_interactive=True)

Enter the native GUI event loop.

Parameters:

allow_interactivebool

Is the application allowed to handle interactive mode for console terminals? By default, typing python -i main.py results in an interactive shell that also regularly calls the VisPy event loop. In this specific case, the run() function will terminate immediately and rely on the interpreter’s input loop to be run after script execution.

sleep(duration_sec)

Sleep for the given duration in seconds.

This is used to reduce CPU stress when VisPy is run in interactive mode. see inputhook.py for details

Parameters:

duration_sec: float

Time to sleep in seconds

---

class vispy.app.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)

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. Currently this can be used to control the webGL context requested by the ipynb_webgl backend, for example:

canvas = Canvas(backend_kwargs={'webgl': dict(preserveDrawingBuffer=True)})

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

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

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

Returns:

imagearray

Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

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.Timer(interval='auto', connect=None, iterations=- 1, start=False, app=None)

Timer used to schedule events in the future or on a repeating schedule

Parameters:

intervalfloat | ‘auto’

Time between events in seconds. The default is ‘auto’, which attempts to find the interval that matches the refresh rate of the current monitor. Currently this is simply 1/60.

connectfunction | None

The function to call.

iterationsint

Number of iterations. Can be -1 for infinite.

startbool

Whether to start the timer.

appinstance of vispy.app.Application

The application to attach the timer to.

property app

The vispy Application instance on which this Timer is based.

connect(callback)

Alias for self.events.timeout.connect()

disconnect(callback=None)

Alias for self.events.timeout.disconnect()

property native

The native timer on which this Timer is based.

start(interval=None, iterations=None)

Start the timer.

A timeout event will be generated every interval seconds. If interval is None, then self.interval will be used.

If iterations is specified, the timer will stop after emitting that number of events. If unspecified, then the previous value of self.iterations will be used. If the value is negative, then the timer will continue running until stop() is called.

If the timer is already running when this function is called, nothing happens (timer continues running as it did previously, without changing the interval, number of iterations, or emitting a timer start event).

stop()

Stop the timer.