Using PyVista in Jupyter#
PyVista is designed to be used in Jupyter notebooks. This section of the tutorial will walk you through the basics of using PyVista in Jupyter notebooks and will be a reference guide for you when configuring PyVista to work in Jupyter.
Trame Jupyter Backend for PyVista#
PyVista has the ability to display fully featured plots within a Jupyter environment using Trame. We provide mechanisms to pair PyVista and Trame so that PyVista plotters can be used in a web context with both server and client-side rendering.
The server-side rendering mode of the Trame backend works by streaming the
current render window to a canvas within Jupyter and then passing any user
actions from the canvas back to the VTK render window (this is done under
the hood by the vtkRemoteView in trame-vtk.
For example, both sections of code will display an interactive canvas within Jupyter:
import pyvista as pv
sphere = pv.Sphere()
# short example
sphere.plot(jupyter_backend='trame')
# long example
plotter = pv.Plotter(notebook=True)
plotter.add_mesh(sphere)
plotter.show(jupyter_backend='trame')
For convenience, you can enable trame with (this is the default):
import pyvista as pv
pv.set_jupyter_backend('trame')
Trame Jupyter Modes#
The PyVista Trame jupyter backend provides three modes of operation (technically as three separate backend choices):
'trame': Uses a view that can switch between client- and server-rendering modes.'server': Uses a view that is purely server-rendering.'client': Uses a view that is purely client-rendering (generally safe without a virtual frame buffer)
You can choose your backend either by using set_jupyter_backend()
or passing jupyter_backend on the show() call.
import pyvista as pv
pv.set_jupyter_backend('client')
pv.Cone().plot()
import pyvista as pv
pv.set_jupyter_backend('trame')
pl = pv.Plotter()
pl.add_mesh(pv.Cone())
pl.show(jupyter_backend='client')
Installation#
Using pip, you can set up your jupyter environment with:
pip install 'jupyterlab>=3' ipywidgets 'pyvista[all,trame]'
Jupyter-Server-Proxy#
When using PyVista in Jupyter that is hosted remotely (docker, cloud JupyterHub,
or otherwise), you will need to pair the Trame backend with jupyter-server-proxy.
Jupyter Server Proxy lets you access the Trame server hosting the views of the PyVista plotters alongside your notebook, and provide authenticated web access to them directly through Jupyter.
Note
In a future version of wslink
(the driving mechanism behind Trame’s server), we plan to add support such that
the server can communicate via the
Jupyter Comms
to avoid the need for a secondary web server and thus jupyter-server-proxy.
To configure PyVista and Trame to work with jupyter-server-proxy in a remote
environment, you will need to set some options on the global PyVista theme:
pyvista.global_theme.trame.server_proxy_enabledpyvista.global_theme.trame.server_proxy_prefix
The default for server_proxy_prefix is '/proxy/' and this should be sufficient
for most remote Jupyter environment and use within Docker.
This can also be set with an environment variable:
export PYVISTA_TRAME_SERVER_PROXY_PREFIX='/proxy/'
The prefix will need to be modified for JupyterHub deployments.
On MyBinder, the JUPYTERHUB_SERVICE_PREFIX string often needs to prefix
'/proxy/'. This makes it so the prefix includes the users ID in the URL.
In PyVista, we automatically check for the presence of this variable and
prepend it to the server_proxy_prefix.
