plot_compare

plot_compare(

datasets: Sequence[PlottableType] | Mapping[str, PlottableType],

*,

dataset_kwargs: dict[str, Any] | None = None,

labels: Sequence[str] | None = auto,

label_size: float | Literal['best_fit', 'uniform'] | None = None,

label_position: TextPositionOptions | None = None,

label_kwargs: dict[str, Any] | None = None,

reference_mesh: DataSet | MultiBlock | PartitionedDataSet | None = None,

reference_kwargs: dict[str, Any] | None = None,

shape: Sequence[int] | str | None = None,

normalize: bool = False,

link: bool | None = None,

cpos: CameraPositionOptions | None = None,

zoom: float | str | None = None,

show_axes: bool | None = None,

show_bounds: bool = False,

screenshot: str | bool | None = None,

plotter_kwargs: dict[str, Any] | None = None,

show_kwargs: dict[str, Any] | None = None,

)

Plot a grid comparison of any number of data objects.

Each data object is shown in its own subplot. By default, the subplots are arranged in a compact grid which is never taller than it is wide, e.g. (1, 2) for two datasets, (1, 3) for three, (2, 2) for four, and (2, 3) for five or six. Any leftover subplots are left empty. Use shape to control the layout explicitly.

Added in version 0.49.

Parameters:

datasetsSequence[PlottableType] | Mapping[str, PlottableType]

The data objects to compare, each of which is anything add_mesh() can draw. At least two datasets are required. If a mapping or a MultiBlock is given, its keys are used as the default labels.

dataset_kwargsdict, optional

Additional keyword arguments passed to add_mesh(). The same arguments are used for each dataset.

labelsSequence[str] | None, optional

The labels to display for each data object. Must have the same length as datasets. By default, the keys of datasets are used when it is a mapping or a MultiBlock, and the labels 'A', 'B', 'C', … are generated otherwise. Set to None to disable labels.

If the input has keys and labels are provided, the provided labels take precedence and are used instead of its keys.

label_sizefloat | str, optional

The size of the labels, either as a literal font size integer or as a string denoting how to work one out. A font size is used as given, and the labels will have the same constant size regardless of the window size of the plot. The label sizes which are worked out are:

• 'best_fit': draw each label as large as it fits in its own subplot, up to the font size of the theme. Labels of different lengths, and labels in subplots of different sizes, are drawn at different sizes.

• 'uniform': draw every label at the size of the one which has to be smallest to fit, so that they are all the same size no matter how long they are or which subplot they are in.

By default, 'uniform' is used when shape is a grid and all subplots have the same width; ‘best_fit’` is used otherwise when shape is a string descriptor and the subplots have different widths. A label too long to fit at a readable size has its middle elided, e.g. this is a very long label may become this is...g label.

With the 'best_fit' and 'uniform' options, the actual font size is dynamically re-computed whenever the window is resized. Has no effect when labels is None.

label_positionstr, optional

Where in its subplot to draw each of the labels: 'upper_left', 'upper_right', 'lower_left', 'lower_right', 'upper_edge', 'lower_edge', 'left_edge' or 'right_edge'.

Defaults to 'upper_left'. Has no effect when labels is None.

label_kwargsdict, optional

Additional keyword arguments for the Text actor which draws each of the labels, e.g. {'color': 'red'}. Takes what add_text() takes. Has no effect when labels is None.

reference_meshDataSet | MultiBlock, optional

A mesh to draw in every subplot to give the comparison a common frame of reference, e.g. an outline of the dataset the compared results are derived from. The same mesh is drawn in each subplot, so it does not follow the bounds of the individual datasets. See the warning in normalize before using both.

reference_kwargsdict, optional

Additional keyword arguments to pass to the add_mesh() method used to show the reference_mesh. Defaults to {'color': 'k'}.

shapeSequence[int] | str, optional

The shape of the subplot layout, in any form accepted by Plotter. Either a (n_rows, n_cols) sequence, or a string descriptor such as '3|1' for three subplots on the left and one on the right, or '4/2' for four on top and two on the bottom. Must define at least as many subplots as there are datasets. By default, the compact grid described above in the summary is used.

normalizebool, default: False

Resize every dataset to a diagonal length of one, centered on the origin, so that datasets of very different sizes are compared shape by shape. The datasets given are left as they are, and the resized copies of them are what is drawn, as is a reference_mesh.

Normalized datasets are all the same size and in the same place, so they are linked by default, which datasets of very different sizes are not.

Warning

A reference_mesh says much less about normalized datasets. Each of them is resized by a factor of its own, so the one mesh drawn in every subplot no longer relates them to each other, and is drawn at the size of each rather than around it.

linkbool, optional

If True, link the views of the subplots so that they share a single camera. The shared camera is fit to the bounds of every dataset, so the datasets are shown at a common scale and the framing does not depend on the order they are given in. If False, each subplot keeps its own camera and is fit to its own dataset.

By default, the views are linked when every dataset is at least half the size of all of them together, which means they occupy the same space at a comparable scale and one camera suits them all. Datasets which are much smaller than the rest, or which are far apart, are not linked, since a shared camera would leave some of them too small to make out.

In every case the camera is only fit when cpos is None or a string, since a fully-specified camera position is used as given.

cposCameraPositionOptions, optional

The camera position to use in every subplot, as a list of the position, the focal point and the view up, or as one of the views camera_position names, e.g. 'xy' or 'iso'. A view is fit to the datasets, and a fully specified position is used as it is.

zoomfloat | str, optional

Camera zoom, applied after the camera is fit to the datasets. Either 'tight' or a float, where a value greater than 1 is a zoom-in.

show_axesbool, optional

Show the axes orientation widget in every subplot. By default, the axes setting of the theme is used.

show_boundsbool, default: False

Show the bounds axes in every subplot.

screenshotstr | bool, optional

File name or path to save screenshot of the plot, or True to return a screenshot array.

plotter_kwargsdict, optional

Additional keyword arguments to pass to the Plotter constructor.

show_kwargsdict, optional

Additional keyword arguments to pass to the show() method.

Returns:

cposCameraPosition

See the returns of pyvista.Plotter.show().

See also

pyvista.plot

pyvista.plot_arrows

pyvista.Plotter

pyvista.Plotter.subplot

Examples

Compare three filtered versions of a dataset.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.load_airplane()
>>> pv.plot_compare(
...     [mesh.clip('x'), mesh.clip('y'), mesh.clip('z')],
...     dataset_kwargs={'color': 'w'},
... )

Static Scene

Interactive Scene

Use a dictionary to label each dataset and set the camera position explicitly.

>>> pv.plot_compare(
...     {
...         'clip x': mesh.clip('x'),
...         'clip y': mesh.clip('y'),
...         'clip z': mesh.clip('z'),
...     },
...     dataset_kwargs={'color': 'w'},
...     cpos='xy',
... )

Static Scene

Interactive Scene

A MultiBlock is compared block-by-block, and its block names are used as labels.

>>> blocks = pv.MultiBlock(
...     {'sphere': pv.Sphere(), 'cube': pv.Cube(), 'cone': pv.Cone()}
... )
>>> pv.plot_compare(blocks)

Static Scene

Interactive Scene

Control the shape of the plot explicitly.

>>> pv.plot_compare(blocks, shape=(3, 1))

Static Scene

Interactive Scene

A shape with more subplots than datasets shows blank plots.

>>> pv.plot_compare(blocks, shape=(2, 2))

Static Scene

Interactive Scene

Use a string descriptor to plot one on top, two on the bottom.

>>> pv.plot_compare(blocks, shape='2/1')

Static Scene

Interactive Scene

Datasets of very different sizes are compared shape by shape by normalizing them. The airplane is some forty times the size of the ant, which is a speck beside it otherwise.

>>> pv.plot_compare(
...     {
...         'airplane': examples.load_airplane(),
...         'ant': examples.load_ant(),
...     },
...     normalize=True,
... )

Static Scene

Interactive Scene

Anything the Plotter itself takes is given to it through plotter_kwargs. Draw a border around each subplot to tell them apart.

>>> pv.plot_compare(
...     blocks,
...     plotter_kwargs={'border': True, 'border_color': 'grey'},
... )

Static Scene

Interactive Scene

Plot on a dark background by giving the plotter a theme of its own, which also decides the color the labels are drawn in.

>>> pv.plot_compare(blocks, plotter_kwargs={'theme': pv.themes.DarkTheme()})

Static Scene

Interactive Scene