VisPy

Warnings

• gotcha VisPy requires at least one GUI toolkit backend (e.g., PyQt5, PySide2, GLFW) and an up-to-date GPU driver with OpenGL 2.1+ support to function. Without these, applications may fail to run or display correctly.
  Fix: Ensure a compatible GUI toolkit (e.g., `pip install PyQt5`) and the latest GPU drivers are installed.
• gotcha Performance can degrade significantly when creating many individual `Visual` objects. VisPy internally treats each visual as a separate OpenGL program, leading to overhead.
  Fix: Combine multiple graphical elements into a single `Visual` where possible (e.g., one `LineVisual` to draw multiple lines instead of many `LineVisuals`). For complex cases, consider custom visuals with optimized shader code.
• gotcha OpenGL operations, including calls to `self.update()` on VisPy Canvas or Visual objects, must be performed on the main/GUI thread. While data updates can occur in secondary threads, the final redraw command must originate from the main thread.
  Fix: Ensure all drawing and update calls that interact directly with the OpenGL context or VisPy Canvas are executed on the main GUI thread. Use thread-safe mechanisms provided by the GUI backend (e.g., signals/slots in Qt) for inter-thread communication.
• breaking VisPy is pre-1.0 and undergoing heavy development, meaning its internal API and behavior, especially for visuals, can change between minor versions. This has historically caused incompatibilities for applications relying on specific internal implementations.
  Fix: Pin `vispy` to an exact version in `requirements.txt` to prevent unexpected breaking changes. Review release notes carefully when upgrading.
• deprecated The low-level `gloo` interface and GLIR (Graphics Library Intermediate Representation) are likely to be deprecated in future versions as development shifts focus towards higher-level interfaces.
  Fix: For new projects or refactoring, prioritize using the `vispy.scene` and `vispy.plot` high-level interfaces. If `gloo` is necessary, be aware of its potential deprecation and future replacement strategies.

Install

• pip install vispy PyPI

Imports

• app, scene

  from vispy import app, scene

  Common top-level imports for creating applications and working with the scene graph.
• SceneCanvas

  from vispy.scene import SceneCanvas

  For creating an interactive 3D scene canvas.
• visuals

  from vispy.scene import visuals

  For accessing high-level visual objects like Mesh, Cube, etc.
• Color

  from vispy.color import Color

  For defining colors within VisPy.
• gloo

  from vispy import gloo

  For low-level OpenGL programming with VisPy's `gloo` interface. Note that `gloo` is slated for deprecation.

Quickstart

This example creates a simple interactive 3D cube using VisPy's high-level scene graph interface. It demonstrates how to initialize a canvas, set up a 3D camera, add a visual object, and run the VisPy application event loop.

import sys
import numpy as np
from vispy import scene, app
from vispy.color import Color

# Create a canvas
canvas = scene.SceneCanvas(keys='interactive', size=(800, 600), show=True)
canvas.title = "VisPy Cube"

# Create a viewbox
view = canvas.central_widget.add_view()
view.camera = 'turntable' # For 3D interaction

# Create a cube visual and add to the view
cube_mesh = scene.visuals.Cube()
view.add(cube_mesh)

# Set background color
view.bgcolor = Color('black')

# Start the event loop
if __name__ == '__main__':
    print("VisPy window opened. Close it to exit.")
    app.run()