Debian Codegraph @

pyvista/plotting/helpers.py

raw
1 """Convenience helper functions."""
2
3 from __future__ import annotations
4
5 from typing import TYPE_CHECKING
6
7 import numpy as np
8
9 import pyvista as pv
10 from pyvista._deprecate_positional_args import _deprecate_positional_args
11 from pyvista.core.utilities.helpers import is_pyvista_dataset
12
13 if TYPE_CHECKING:
14 from pyvista.core._typing_core import NumpyArray
15
16
17 def plot_arrows(cent, direction, **kwargs):
18 """Plot arrows as vectors.
19
20 Parameters
21 ----------
22 cent : array_like[float]
23 Accepts a single 3d point or array of 3d points.
24
25 direction : array_like[float]
26 Accepts a single 3d point or array of 3d vectors.
27 Must contain the same number of items as ``cent``.
28
29 **kwargs : dict, optional
30 See :func:`pyvista.plot`.
31
32 Returns
33 -------
34 tuple
35 See the returns of :func:`pyvista.plot`.
36
37 See Also
38 --------
39 pyvista.plot
40
41 Examples
42 --------
43 Plot a single random arrow.
44
45 >>> import numpy as np
46 >>> import pyvista as pv
47 >>> rng = np.random.default_rng(seed=0)
48 >>> cent = rng.random(3)
49 >>> direction = rng.random(3)
50 >>> pv.plot_arrows(cent, direction)
51
52 Plot 100 random arrows.
53
54 >>> import numpy as np
55 >>> import pyvista as pv
56 >>> cent = rng.random((100, 3))
57 >>> direction = rng.random((100, 3))
58 >>> pv.plot_arrows(cent, direction)
59
60 """
61 return pv.plot([cent, direction], **kwargs)
62
63
64 @_deprecate_positional_args(allowed=['data_a', 'data_b', 'data_c', 'data_d'], n_allowed=4)
65 def plot_compare_four( # noqa: PLR0917
66 data_a,
67 data_b,
68 data_c,
69 data_d,
70 display_kwargs=None,
71 plotter_kwargs=None,
72 show_kwargs=None,
73 screenshot=None,
74 camera_position=None,
75 outline=None,
76 outline_color='k',
77 labels=('A', 'B', 'C', 'D'),
78 link: bool = True, # noqa: FBT001, FBT002
79 notebook=None,
80 ):
81 """Plot a 2 by 2 comparison of data objects.
82
83 Parameters
84 ----------
85 data_a : pyvista.DataSet
86 The data object to display in the top-left corner.
87
88 data_b : pyvista.DataSet
89 The data object to display in the top-right corner.
90
91 data_c : pyvista.DataSet
92 The data object to display in the bottom-left corner.
93
94 data_d : pyvista.DataSet
95 The data object to display in the bottom-right corner.
96
97 display_kwargs : dict, default: None
98 Additional keyword arguments to pass to the ``add_mesh`` method.
99
100 plotter_kwargs : dict, default: None
101 Additional keyword arguments to pass to the ``Plotter`` constructor.
102
103 show_kwargs : dict, default: None
104 Additional keyword arguments to pass to the ``show`` method.
105
106 screenshot : str | bool, default: None
107 File name or path to save screenshot of the plot, or ``True`` to return
108 a screenshot array.
109
110 camera_position : list, default: None
111 The camera position to use in the plot.
112
113 outline : pyvista.DataSet, default: None
114 An outline to plot around the data objects.
115
116 outline_color : str, default: 'k'
117 The color of the outline.
118
119 labels : tuple[str, str, str, str], default: ('A', 'B', 'C', 'D')
120 The labels to display for each data object.
121
122 link : bool, default: True
123 If ``True``, link the views of the subplots.
124
125 notebook : bool, default: None
126 If ``True``, display the plot in a Jupyter notebook.
127
128 Returns
129 -------
130 pyvista.Plotter
131 The plotter object.
132
133 """
134 datasets = [[data_a, data_b], [data_c, data_d]]
135 labels = [labels[0:2], labels[2:4]]
136
137 if plotter_kwargs is None:
138 plotter_kwargs = {}
139 if display_kwargs is None:
140 display_kwargs = {}
141 if show_kwargs is None:
142 show_kwargs = {}
143
144 plotter_kwargs['notebook'] = notebook
145
146 pl = pv.Plotter(shape=(2, 2), **plotter_kwargs)
147
148 for i in range(2):
149 for j in range(2):
150 pl.subplot(i, j)
151 pl.add_mesh(datasets[i][j], **display_kwargs)
152 pl.add_text(labels[i][j])
153 if is_pyvista_dataset(outline):
154 pl.add_mesh(outline, color=outline_color)
155 if camera_position is not None:
156 pl.camera_position = camera_position
157
158 if link:
159 pl.link_views()
160 # when linked, camera must be reset such that the view range
161 # of all subrender windows matches
162 pl.reset_camera()
163
164 return pl.show(screenshot=screenshot, **show_kwargs)
165
166
167 @_deprecate_positional_args(allowed=['view'])
168 def view_vectors(view: str, negative: bool = False) -> tuple[NumpyArray[int], NumpyArray[int]]: # noqa: FBT001, FBT002
169 """Given a plane to view, return vectors for setting up camera.
170
171 Parameters
172 ----------
173 view : {'xy', 'yx', 'xz', 'zx', 'yz', 'zy'}
174 Plane to return vectors for.
175
176 negative : bool, default: False
177 Whether to view from opposite direction.
178
179 Returns
180 -------
181 vec : numpy.ndarray
182 ``[x, y, z]`` vector that points in the viewing direction.
183
184 viewup : numpy.ndarray
185 ``[x, y, z]`` vector that points to the viewup direction.
186
187 """
188 if view == 'xy':
189 vec = np.array([0, 0, 1])
190 viewup = np.array([0, 1, 0])
191 elif view == 'yx':
192 vec = np.array([0, 0, -1])
193 viewup = np.array([1, 0, 0])
194 elif view == 'xz':
195 vec = np.array([0, -1, 0])
196 viewup = np.array([0, 0, 1])
197 elif view == 'zx':
198 vec = np.array([0, 1, 0])
199 viewup = np.array([1, 0, 0])
200 elif view == 'yz':
201 vec = np.array([1, 0, 0])
202 viewup = np.array([0, 0, 1])
203 elif view == 'zy':
204 vec = np.array([-1, 0, 0])
205 viewup = np.array([0, 1, 0])
206 else:
207 msg = (
208 f'Unexpected value for direction {view}\n'
209 " Expected: 'xy', 'yx', 'xz', 'zx', 'yz', 'zy'"
210 )
211 raise ValueError(msg)
212
213 if negative:
214 vec *= -1
215 return vec, viewup