Jupyter Notebook Plotting#

Plot with pyvista interactively within a Jupyter notebook.

Note

We recommend using the Trame-based backed. See Trame Jupyter Backend for PyVista.

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 and client-side rendering with PyVista streaming to the notebook through trame

  • Client-side rendering with pythreejs using threejs.

  • Client-side rendering with ipygany using threejs.

  • Client-side rendering using panel using 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 Jupyter 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 January 2023, and may already be out of date. Be sure to check the developer websites for any changes.

When plotting using Jupyter 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

Rendering Location

Backend

Requires Framebuffer

trame

Client & Server

vtk.js & vtk

Optional

panel

Client

vtk.js

Yes

pythreejs

Client

threejs

No

ipygany

Client

threejs

No

All the modules other than trame, 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 or the 'client' variant of the trame-backend (see Trame Jupyter Backend for PyVista), which do 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:

import pyvista as pv
pv.set_jupyter_backend('trame')
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.

  • 'client' : Export/serialize the scene graph to be rendered with VTK.js client-side through trame. Requires trame and jupyter-server-proxy to be installed.

  • 'server': Render remotely and stream the resulting VTK images back to the client using trame. This replaces the 'ipyvtklink' backend with better performance. Supports the most VTK features, but suffers from minor lag due to remote rendering. Requires that a virtual framebuffer be set up when displaying on a headless server. Must have at least trame and jupyter-server-proxy installed for cloud/remote Jupyter instances. This mode is also aliased by 'trame'.

  • 'trame': The full Trame-based backend that combines both 'server' and 'client' into one backend. This requires a virtual frame buffer.

  • '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')

Enable the trame Trame backend.

>>> pv.set_jupyter_backend('trame')

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)