Jupyter Notebook Plotting

Plot with pyvista interactively within a Juptyer notebook!

Demo Using panel

from pyvista import demos
demos.plot_logo(background='white', jupyter_backend='panel')

Demo Using ipygany

from pyvista import demos

# basic glyphs demo
mesh = demos.glyphs(2)

text = demos.logo.text_3d("I'm interactive!", depth=0.2)
text.points *= 0.1
text.translate([0, 1.4, 1.5])
mesh += text
mesh['Example Scalars'] = mesh.points[:, 0]

mesh.plot(cpos='xy', jupyter_backend='ipygany', background='white',
          show_scalar_bar=True)

Supported Modules

The PyVista module supports a variety of backends when plotting within a jupyter notebook:

• Server-side rendering with PyVista streaming to the notebook through ipyvtklink

• Client-side rendering with ipygany using threejs.

• Client-side rendering using panel using vtk.js.

• Client-side rendering with itkwidgets using itk.js and vtk.js.

• Static images.

---

Details for Each Backend

See the individual package pages on each backend for additional details on how to use these plotting backends.

• Using ipygany with PyVista
• Using Panel with PyVista
• Using ipyvtklink with PyVista
• Using itkwidgets with PyVista

State of 3D Interactive Jupyterlab Plotting

Note

3D plotting within Jupyter notebooks is an emerging technology, partially because Jupyter is still relatively new, but also because the web technology used here is also new and rapidly developing as more and more users and developers shift to the cloud or cloud-based visualization. Things here are likely to break and rapidly change

This was written in March 2021, and may already be out of date. Be sure to check the developer websites for any changes.

When plotting using Jupyterlab you have the option of using one of many modules, each of which has its advantages, disadvantages, and quirks. While pyvista attempts to remove some of the differences in the API when using the Plotting class, the plots will still look and feel differently depending on the backend. Additionally, different backends have different requirements and may not support your deployment environment.

This table details various capabilities and technologies used by the jupyter notebook plotting modules:

Jupyter Notebook 3D Modules
	Jupyterlab 3	Rendering Location	Backend	Requires Framebuffer
panel	Yes	Client	vtk.js	Yes
ipygany	Yes	Client	threejs	No
ipyvtklink	Yes	Server	vtk	Yes
itkwidgets	No	Client	vtk.js	Yes

At the moment, itkwidgets and ipyvtklink are incompatible with Jupyterlab 3, and will result in a “Error displaying widget: model not found” message from juptyer. Additionally, all the modules other than ipygany require a framebuffer, which can be setup on a headless environment with pyvista.start_xvfb(). However, on Google Colab, where it’s not possible to install system packages, you should stick with a module like threejs, which does not require any server side rendering or framebuffer.

See Installation for more details installing on a headless environment for the backends requiring a framebuffer. When installing the individual packages, the Jupyterlab 3 compatible packages can be installed with a simple pip install <package>. See the installation instructions for the other packages for more details.

Usage with PyVista

There are two ways to set the jupyter plotting backend. First, it can be done on a plot by plot basis by setting the jupyter_backend in either mesh.plot() or plotter.show(). You can also set it globally with the pyvista.set_jupyter_backend function. For further details:

pyvista.set_jupyter_backend(backend)

Set the plotting backend for a jupyter notebook.

Parameters

backend (str) –

Jupyter backend to use when plotting. Must be one of the following:

• 'ipyvtklink' : Render remotely and stream the resulting VTK images back to the client. Supports all VTK methods, but suffers from lag due to remote rendering. Requires that a virtual framebuffer be setup when displaying on a headless server. Must have ipyvtklink installed.

• 'panel' : Convert the VTK render window to a vtkjs object and then visualize that within jupyterlab. Supports most VTK objects. Requires that a virtual framebuffer be setup when displaying on a headless server. Must have panel installed.

• 'ipygany' : Convert all the meshes into ipygany meshes and streams those to be rendered on the client side. Supports VTK meshes, but few others. Aside from none, this is the only method that does not require a virtual framebuffer. Must have ipygany installed.

• 'static' : Display a single static image within the Jupyterlab environment. Still requires that a virtual framebuffer be setup when displaying on a headless server, but does not require any additional modules to be installed.

• 'none' : Do not display any plots within jupyterlab, instead display using dedicated VTK render windows. This will generate nothing on headless servers even with a virtual framebuffer.

Examples

Enable the ipygany backend.

>>> import pyvista as pv
>>> pv.set_jupyter_backend('ipygany')

Enable the panel backend.

>>> pv.set_jupyter_backend('panel')

Enable the ipyvtklink backend.

>>> pv.set_jupyter_backend('ipyvtklink')

Just show static images.

>>> pv.set_jupyter_backend('static')

Disable all plotting within JupyterLab and display using a standard desktop VTK render window.

>>> pv.set_jupyter_backend(None)  # or 'none'