1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
"""Jupyter notebook plotting module."""
from __future__ import annotations
import importlib.util
from typing import Literal
from typing import get_args
from typing_extensions import TypeIs
import pyvista
from pyvista.core.errors import PyVistaDeprecationWarning as PyVistaDeprecationWarning
JupyterBackendOptions = Literal['static', 'client', 'server', 'trame', 'html', 'none']
ALLOWED_BACKENDS = get_args(JupyterBackendOptions)
def _is_jupyter_backend(backend: str) -> TypeIs[JupyterBackendOptions]:
"""Return True if backend is allowed jupyter backend."""
return backend in ALLOWED_BACKENDS
def _validate_jupyter_backend(
backend: str | None,
) -> JupyterBackendOptions:
"""Validate that a jupyter backend is valid.
Returns the normalized name of the backend. Raises if the backend is invalid.
"""
# Must be a string
if backend is None:
backend = 'none'
backend = backend.lower()
if not importlib.util.find_spec('IPython'):
msg = 'Install IPython to display with pyvista in a notebook.'
raise ImportError(msg)
if not _is_jupyter_backend(backend):
backend_list_str = ', '.join([f'"{item}"' for item in ALLOWED_BACKENDS])
msg = (
f'Invalid Jupyter notebook plotting backend "{backend}".\n'
f'Use one of the following:\n{backend_list_str}'
)
raise ValueError(msg)
if backend in ['server', 'client', 'trame', 'html']:
try:
from pyvista.trame.jupyter import show_trame as show_trame # noqa: PLC0415
except ImportError: # pragma: no cover
msg = 'Please install trame dependencies: pip install "pyvista[jupyter]"'
raise ImportError(msg)
return backend
def set_jupyter_backend(backend, name=None, **kwargs): # noqa: ARG001
"""Set the plotting backend for a jupyter notebook.
Parameters
----------
backend : str
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.
name : str, optional
The unique name identifier for the server.
**kwargs : dict, optional
Any additional keyword arguments to pass to the server launch.
Examples
--------
Enable the trame Trame backend.
>>> pv.set_jupyter_backend('trame') # doctest:+SKIP
Just show static images.
>>> pv.set_jupyter_backend('static') # doctest:+SKIP
Disable all plotting within JupyterLab and display using a
standard desktop VTK render window.
>>> pv.set_jupyter_backend(None) # doctest:+SKIP
"""
pyvista.global_theme._jupyter_backend = _validate_jupyter_backend(backend)
|
