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