Debian Codegraph @

pyvista/_cli/plot.py

raw
1 """`pyvista plot file.vtp --color=red ...` CLI."""
2
3 from __future__ import annotations
4
5 from ast import literal_eval
6 from typing import TYPE_CHECKING
7 from typing import Annotated
8 from typing import Any
9 from typing import Literal
10
11 from cyclopts import Parameter
12 from cyclopts import Token
13 from rich.console import Group
14 from rich.console import NewLine
15 from rich.panel import Panel
16 from rich.text import Text
17
18 import pyvista as pv
19 from pyvista.core.utilities.misc import StrEnum # type: ignore [attr-defined]
20
21 from .app import app
22 from .utils import HELP_FORMATTER
23 from .utils import _console_error
24 from .utils import _converter_files
25 from .utils import _MeshAndPath
26
27 if TYPE_CHECKING:
28 from collections.abc import Sequence
29
30
31 def _validator_window_size(type_: type, value: list[int] | None) -> None: # noqa: ARG001
32 if value is not None and len(value) != 2:
33 msg = 'Window size must be a list of two integers.'
34 raise ValueError(msg)
35
36
37 def _kwargs_converter(type_, tokens: Sequence[Token]): # noqa: ANN001, ANN202, ARG001
38 for token in tokens:
39 # Check hyphen in keyword value
40 if (h := '-') in (key := token.keys[0]):
41 msg = f'A hyphen `{h}` has been used as supplementary keyword argument and is not converted to underscore `_`. Did you mean --{key.replace("-", "_")}={token.value} ?' # noqa: E501
42 app.console.print(
43 Panel(
44 msg,
45 style='magenta',
46 title='Warning',
47 title_align='left',
48 )
49 )
50
51 # Coerce using literal_eval with fallback to str value
52 try:
53 return literal_eval(token.value)
54 except (ValueError, SyntaxError):
55 return token.value
56 return None
57
58
59 _HELP_KWARGS = """\
60 Additional keyword arguments passed to ``Plotter.add_mesh`` or ``Plotter.add_volume``.
61 See the documentation for more details at https://docs.pyvista.org/api/plotting/_autosummary/pyvista.plotter.add_mesh
62 and https://docs.pyvista.org/api/plotting/_autosummary/pyvista.plotter.add_volume
63
64 Note that contrary to other CLI arguments, hyphens ``-`` are not converted to underscores ``_``
65 before being passed to the corresponding plotter method. For example, you need to use
66 ``--show_edges=True`` instead of ``--show-edges=True`` to show mesh edges in the plotting window.
67
68 """
69
70
71 class Groups(StrEnum):
72 """Groups for plot CLI arguments."""
73
74 PLOTTER = 'Plotter init'
75 RENDERING = 'Rendering'
76 SUPP = 'Supplementary'
77 IN = 'Inputs'
78 RETURN = 'Return'
79
80
81 @app.command(
82 usage=f'Usage: [bold]{pv.__name__} plot file (file2) [OPTIONS]',
83 help_formatter=HELP_FORMATTER,
84 help='Plot one or more mesh files in an interactive window that can be customized with various options.', # noqa: E501
85 )
86 def _plot(
87 var_item: Annotated[
88 list[str],
89 Parameter(
90 name='files',
91 consume_multiple=True,
92 help=(
93 'File(s) to plot. Glob patterns (``*``, ``?``, ``[...]``) are expanded. '
94 'Each match must be readable with ``pyvista.read``.'
95 ),
96 converter=_converter_files,
97 group=Groups.IN,
98 negative='',
99 ),
100 ],
101 *,
102 off_screen: Annotated[bool | None, Parameter(group=Groups.PLOTTER)] = None,
103 full_screen: Annotated[bool | None, Parameter(group=Groups.RENDERING)] = None,
104 screenshot: Annotated[str | None, Parameter(group=Groups.PLOTTER)] = None,
105 interactive: Annotated[bool, Parameter(group=Groups.PLOTTER)] = True,
106 window_size: Annotated[
107 list[int] | None,
108 Parameter(
109 consume_multiple=True,
110 validator=_validator_window_size,
111 group=Groups.PLOTTER,
112 ),
113 ] = None,
114 show_bounds: Annotated[bool, Parameter(group=Groups.RENDERING)] = False,
115 show_axes: Annotated[bool | None, Parameter(group=Groups.RENDERING)] = None,
116 background: Annotated[str | None, Parameter(group=Groups.RENDERING)] = None,
117 text: Annotated[str, Parameter(group=Groups.RENDERING)] = '',
118 eye_dome_lighting: Annotated[bool, Parameter(group=Groups.RENDERING)] = False,
119 volume: Annotated[bool, Parameter(group=Groups.RENDERING)] = False,
120 parallel_projection: Annotated[bool, Parameter(group=Groups.RENDERING)] = False,
121 return_cpos: Annotated[bool, Parameter(group=Groups.RETURN)] = False,
122 anti_aliasing: Annotated[
123 Literal['ssaa', 'msaa', 'fxaa'] | None, Parameter(group=Groups.RENDERING)
124 ] = None,
125 zoom: Annotated[float | str | None, Parameter(group=Groups.RENDERING)] = None,
126 border: Annotated[bool, Parameter(group=Groups.PLOTTER)] = False,
127 border_color: Annotated[str, Parameter(group=Groups.PLOTTER)] = 'k',
128 border_width: Annotated[float, Parameter(group=Groups.PLOTTER)] = 2.0,
129 ssao: Annotated[bool, Parameter(group=Groups.RENDERING)] = False,
130 **kwargs: Annotated[
131 Any,
132 Parameter(help=_HELP_KWARGS, converter=_kwargs_converter, group=Groups.SUPP),
133 ],
134 ) -> None:
135 items: list[_MeshAndPath] = var_item # type: ignore [assignment]
136 try:
137 res = pv.plot(
138 var_item=[m.mesh for m in items], # type: ignore [arg-type]
139 off_screen=off_screen,
140 full_screen=full_screen,
141 screenshot=screenshot,
142 interactive=interactive,
143 window_size=window_size,
144 show_bounds=show_bounds,
145 show_axes=show_axes,
146 background=background,
147 text=text,
148 eye_dome_lighting=eye_dome_lighting,
149 volume=volume,
150 parallel_projection=parallel_projection,
151 return_cpos=return_cpos,
152 anti_aliasing=anti_aliasing,
153 zoom=zoom,
154 border=border,
155 border_color=border_color,
156 border_width=border_width,
157 ssao=ssao,
158 **kwargs,
159 )
160
161 except Exception as ex: # noqa: BLE001
162 # Prevent traceback and output error along with help message
163 app.help_print(tokens='plot')
164
165 msg = Group(
166 ':warning: The following exception has been raised when calling [u]pv.plot[/u]:',
167 NewLine(),
168 Panel(
169 str(ex), title=f'{type(ex).__name__}', title_align='left', style='bold blink red'
170 ),
171 NewLine(),
172 Text('Please check the provided arguments.'),
173 )
174 _console_error(app=app, message=msg)
175 else:
176 return res