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