Jupyter Notebook Plotting#

Plot with pyvista interactively within a Jupyter notebook!

Demo Using pythreejs#

Create interactive physically based rendering using pythreejs.

import pyvista as pv
from pyvista import examples

# download an example and display it using physically based rendering.
mesh = examples.download_lucy()
mesh.plot(color='lightgrey', pbr=True, metallic=0.2,
          jupyter_backend='pythreejs')

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], inplace=True)
mesh += text
mesh['Example Scalars'] = mesh.points[:, 0]

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

Demo Using panel#

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

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 pythreejs using threejs.

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

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 updated in August 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

pythreejs

Yes

Client

threejs

No

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 and pythreejs require a framebuffer, which can be set up 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 parameter in either Plotter.show() or dataset.plot(). You can also set it globally with the pyvista.set_jupyter_backend(). For further details:

set_jupyter_backend(backend)[source]#

Set the plotting backend for a jupyter notebook.

Parameters
backendstr

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 set up 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 set up 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.

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

  • 'static' : Display a single static image within the Jupyterlab environment. Still requires that a virtual framebuffer be set up 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 pythreejs backend.

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

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'