Coverage for src/beamme/utils/visualization.py: 42%

1# The MIT License (MIT) 

2# 

3# Copyright (c) 2018-2026 BeamMe Authors 

4# 

5# Permission is hereby granted, free of charge, to any person obtaining a copy 

6# of this software and associated documentation files (the "Software"), to deal 

7# in the Software without restriction, including without limitation the rights 

8# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 

9# copies of the Software, and to permit persons to whom the Software is 

10# furnished to do so, subject to the following conditions: 

11# 

12# The above copyright notice and this permission notice shall be included in 

13# all copies or substantial portions of the Software. 

14# 

15# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 

16# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 

17# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 

18# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 

19# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 

20# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 

21# THE SOFTWARE. 

22"""Helper functions for visualizations.""" 

23 

24import os as _os 

25import uuid as _uuid 

26from pathlib import Path as _Path 

27 

28import ipywidgets as _widgets 

29import pyvista as _pv 

30from IPython.display import HTML as _HTML 

31from IPython.display import IFrame as _IFrame 

32from IPython.display import display as _display 

33 

34from beamme.utils.environment import is_nbsphinx as _is_nbsphinx 

35 

36 

37def show_plotter(plotter: _pv.Plotter, *, nbsphinx_export_3d_view: bool = True) -> None: 

38 """Show a PyVista plotter. 

39 

40 This function displays the plotter according to the current environment: 

41 - For local development, it will directly show the plotter. 

42 - For nbsphinx documentation, it will export a static image of the plotter 

43 and optionally an interactive 3D view that can be embedded in the 

44 documentation. 

45 

46 Args: 

47 plotter: The PyVista plotter to show. 

48 nbsphinx_export_3d_view: For nbsphinx documentation, whether to 

49 export an interactive 3D view alongside the static image. 

50 """ 

51 if not _is_nbsphinx(): 

52 plotter.show() 

53 else: 

54 # Path where static documents are stored for the website. 

55 static_doc_path = _Path(_os.environ["PYVISTA_DOCS_STATIC"]) 

56 

57 # Get a unique identifier for the current plotter 

58 plotter_uid = str(_uuid.uuid4().hex) 

59 

60 # Export a screenshot of the plotter 

61 plotter.screenshot(static_doc_path / f"{plotter_uid}.png") 

62 static_frame_html = f""" 

63 <img src="../_static/pyvista/{plotter_uid}.png" 

64 style="max-width:100%; border-radius:8px;"> 

65 """ 

66 

67 if nbsphinx_export_3d_view: 

68 # Export a html representation of the plotter 

69 plotter.export_html(static_doc_path / f"{plotter_uid}.html") 

70 

71 interactive_frame = _IFrame( 

72 src=f"../_static/pyvista/{plotter_uid}.html", 

73 width="100%", 

74 height=600, 

75 ) 

76 tab = _widgets.Tab( 

77 children=[ 

78 _widgets.HTML(static_frame_html), 

79 _widgets.HTML(interactive_frame._repr_html_()), 

80 ] 

81 ) 

82 tab.set_title(0, "Static Scene") 

83 tab.set_title(1, "Interactive Scene") 

84 

85 _display(tab) 

86 else: 

87 _display(_HTML(static_frame_html))