Jupyter Notebook Plotting

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.

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

  • Static images.

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(). Custom backends are also supported with pyvista.register_jupyter_backend(). For further details:

import pyvista as pv

pv.set_jupyter_backend('trame')
set_jupyter_backend(backend: JupyterBackendOptions | str, name=None, **kwargs)[source]#

Set the plotting backend for a jupyter notebook.

Parameters:
backendstr

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

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

  • 'html' : Export/serialize the scene graph to be rendered with the Trame client backend but in a static HTML file.

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

Custom backends registered via register_jupyter_backend() are also accepted. Pass None to reset to auto-detection at display time.

namestr, optional

The unique name identifier for the server.

**kwargsdict, optional

Any additional keyword arguments to pass to the server launch.

Examples

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

Reset to auto-detect the best available backend.

>>> pv.set_jupyter_backend(None)
register_jupyter_backend(
name: str,
handler: Callable[[...], object],
*,
override: bool = False,
) → None[source]#

Register a custom Jupyter backend handler.

Added in version 0.48.0.

Parameters:
namestr

Name of the backend (e.g. 'custom'). Must not collide with a built-in backend name unless override=True is passed.

handlercallable()

A callable with signature handler(plotter, **kwargs) that returns an IPython-displayable object.

overridebool, default: False

If True, allow registering a name that collides with a built-in backend. Also silences the warning emitted when replacing an existing custom registration.

Raises:
ValueError

If name collides with a built-in backend and override is False.

Warns:
UserWarning

If name already refers to a registered custom backend. The new registration replaces the old one (last wins); pass override=True to silence the warning.

Examples

>>> import pyvista as pv
>>> def my_handler(plotter, **kwargs): ...
>>> pv.register_jupyter_backend('my_backend', my_handler)
Contents