Debian Codegraph @

pyvista/jupyter/notebook.py

raw
1 """Support dynamic or static jupyter notebook plotting.
2
3 Includes:
4
5 * ``trame``
6 * ``client``
7 * ``server``
8 * ``html``
9
10 """
11
12 from __future__ import annotations
13
14 from typing import TYPE_CHECKING
15 from typing import cast
16
17 from pyvista._warn_external import warn_external
18 from pyvista.jupyter import _custom_backends
19 from pyvista.jupyter import _ensure_entry_points
20 from pyvista.jupyter import _get_custom_backend_handler
21 from pyvista.jupyter import _resolve_backend
22
23 if TYPE_CHECKING:
24 import io
25 from pathlib import Path
26
27 from IPython.lib.display import IFrame
28 from PIL.Image import Image
29
30 from pyvista import pyvista_ndarray
31 from pyvista.jupyter import JupyterBackendOptions
32 from pyvista.plotting.plotter import Plotter
33 from pyvista.trame.jupyter import EmbeddableWidget
34 from pyvista.trame.jupyter import Widget
35
36
37 def handle_plotter(
38 plotter: Plotter,
39 backend: JupyterBackendOptions | str | None = None,
40 screenshot: str | Path | io.BytesIO | bool | None = None, # noqa: FBT001
41 **kwargs,
42 ) -> EmbeddableWidget | IFrame | Widget | Image:
43 """Show the ``pyvista`` plot in a jupyter environment.
44
45 Returns
46 -------
47 IPython Widget
48 IPython widget or image.
49
50 """
51 if screenshot is False:
52 screenshot = None
53
54 # Auto-detect the best available backend when not specified
55 if backend is None:
56 backend = _resolve_backend()
57 if backend == 'static':
58 warn_external(
59 'Using static image for notebook display.\n'
60 'Install trame for interactive backends:'
61 ' pip install "pyvista[jupyter]"'
62 )
63
64 # Custom backends (registered or from entry points)
65 custom_handler = _get_custom_backend_handler(backend)
66 if custom_handler is not None:
67 return custom_handler(plotter, screenshot=screenshot, **kwargs)
68
69 # Built-in trame backends
70 try:
71 if backend in ['server', 'client', 'trame', 'html']:
72 from pyvista.trame.jupyter import show_trame # noqa: PLC0415
73
74 return show_trame(plotter, mode=backend, **kwargs)
75
76 except ImportError as e:
77 # Trame was explicitly requested but not available
78 _ensure_entry_points()
79 if _custom_backends:
80 fallback_name, fallback_handler = next(iter(_custom_backends.items()))
81 available = [f'"{b}"' for b in sorted(_custom_backends.keys())]
82 available += ['"static"', '"none"']
83 warn_external(
84 f'Failed to use notebook backend "{backend}": {e}\n\n'
85 f'Using registered backend "{fallback_name}" instead.\n'
86 f'Available backends: {", ".join(available)}'
87 )
88 return fallback_handler(plotter, screenshot=screenshot, **kwargs)
89
90 warn_external(
91 f'Failed to use notebook backend "{backend}": {e}\n\n'
92 'Falling back to a static output.\n'
93 'Available backends: "static", "none"\n'
94 'Install trame for interactive backends:'
95 ' pip install "pyvista[jupyter]"'
96 )
97
98 return show_static_image(plotter, screenshot)
99
100
101 def show_static_image(
102 plotter: Plotter,
103 screenshot: str | Path | io.BytesIO | bool | None, # noqa: FBT001
104 ) -> Image: # numpydoc ignore=RT01
105 """Display a static image to be displayed within a jupyter notebook."""
106 import PIL.Image # noqa: PLC0415
107
108 if plotter.last_image is None:
109 # Must render here, otherwise plotter will segfault.
110 plotter.render()
111 plotter.last_image = plotter.screenshot(screenshot, return_img=True)
112 last_image = cast('pyvista_ndarray', plotter.last_image)
113 return PIL.Image.fromarray(last_image)