pyvista.PlanesAssembly

class PlanesAssembly(

*,

x_label: str | None = None,

y_label: str | None = None,

z_label: str | None = None,

labels: Sequence[str] | None = None,

label_color: ColorLike = 'black',

show_labels: bool = True,

label_position: float | VectorLike[float] = 0.5,

label_edge: Literal['top', 'bottom', 'right', 'left'] | Sequence[str] = 'right',

label_offset: float = 0.05,

label_size: int = 50,

label_mode: Literal['2D', '3D'] = '3D',

x_color: ColorLike | None = None,

y_color: ColorLike | None = None,

z_color: ColorLike | None = None,

opacity: float | VectorLike[float] = 0.3,

position: VectorLike[float] = (0.0, 0.0, 0.0),

orientation: VectorLike[float] = (0.0, 0.0, 0.0),

origin: VectorLike[float] = (0.0, 0.0, 0.0),

scale: float | VectorLike[float] = (1.0, 1.0, 1.0),

user_matrix: MatrixLike[float] | None = None,

**kwargs: Unpack[_OrthogonalPlanesKwargs],

)

Assembly of orthogonal planes.

Assembly of three orthogonal plane meshes with labels.

The labels can be 2D or 3D, and will follow the camera such that they have the correct orientation and remain parallel to the edges of the planes.

The positioning of the labels may be customized using the label_edge, label_position, and label_offset attributes.

Warning

The camera must be set before rendering the assembly. Otherwise, attempting to render it will cause python to crash.

Added in version 0.45.

Parameters:

x_labelstr, default: ‘YZ’

Text label for the yz-plane. Alternatively, set the label with labels.

y_labelstr, default: ‘ZX’

Text label for the zx-plane. Alternatively, set the label with labels.

z_labelstr, default: ‘XY’

Text label for the xy-plane. Alternatively, set the label with labels.

labelsSequence[str], optional,

Text labels for the planes. This is an alternative parameter to using x_label, y_label, and z_label separately.

label_colorColorLike, default: ‘black’

Color of the text labels.

show_labelsbool, default: True

Show or hide the text labels.

label_positionfloat | VectorLike[float], default: 0.5

Normalized relative position of the text labels along each plane’s respective label_edge. The positions are normalized to have a range of [-1.0, 1.0] such that 0.0 is at the center of the edge and -1.0 and 1.0 are at the corners.

Note

The label text is centered horizontally at the specified positions.

label_edgestr, default: ‘right’

Edge on which to position each plane’s label. Can be 'top', 'bottom', 'right', or 'left'. Use a single value to set the edge for all labels or set each edge independently.

label_offsetfloat | VectorLike[float], optional

Vertical offset of the text labels. The offset is proportional to the length of the assembly. Positive values move the labels away from the center; negative values move them towards it.

label_sizeint, default: 50

Size of the text labels. If label_mode is '2D', this is the font size. If label_mode is '3D', the labels are scaled proportional to the length of the assembly.

label_mode‘2D’ | ‘3D’, default: ‘2D’

Mode to use for text labels. In 2D mode, the label actors are always visible and have a constant size regardless of window size. In 3D mode, the label actors may be occluded by other geometry and will scale with changes to the window size. The two modes also have minor differences in appearance and behavior in terms of how they follow the camera.

x_colorColorLike, optional

Color of the xy-plane.

y_colorColorLike, optional

Color of the yz-plane.

z_colorColorLike, optional

Color of the zx-plane.

opacityfloat, default: 0.3

Opacity of the planes.

positionVectorLike[float], default: (0.0, 0.0, 0.0)

Position of the planes in space.

orientationVectorLike[float], default: (0, 0, 0)

Orientation angles of the assembly which define rotations about the world’s x-y-z axes. The angles are specified in degrees and in x-y-z order. However, the actual rotations are applied in the around the y-axis first, then the x-axis, and finally the z-axis.

originVectorLike[float], default: (0.0, 0.0, 0.0)

Origin of the assembly. This is the point about which all rotations take place. The rotations are defined by the orientation.

scaleVectorLike[float], default: (1.0, 1.0, 1.0)

Scaling factor applied to the assembly.

user_matrixMatrixLike[float], optional

A 4x4 transformation matrix applied to the assembly. Defaults to the identity matrix. The user matrix is the last transformation applied to the actor.

**kwargs

Keyword arguments passed to pyvista.OrthogonalPlanesSource.

Examples

Fit planes to a model of a human.

>>> import numpy as np
>>> import pyvista as pv
>>> from pyvista import examples
>>> human = examples.download_human()
>>> labels = 'Sagittal', 'Coronal', 'Transverse'
>>> planes = pv.PlanesAssembly(
...     bounds=human.bounds, labels=labels, label_size=25
... )

Plot the planes and the model.

>>> pl = pv.Plotter()
>>> human_actor = pl.add_mesh(human, scalars='Color', rgb=True)
>>> _ = pl.add_actor(planes)
>>> planes.camera = pl.camera
>>> pl.show()

Static Scene

Interactive Scene

Apply a transformation to the planes and the model.

>>> transform = np.array(
...     [
...         [0.70645893, 0.69636424, 0.12646197, 1.0],
...         [-0.62246712, 0.69636424, -0.35722756, 2.0],
...         [-0.33682409, 0.17364818, 0.92541658, 3.0],
...         [0.0, 0.0, 0.0, 1.0],
...     ]
... )
>>> planes.user_matrix = transform
>>> human_actor.user_matrix = transform

>>> pl = pv.Plotter()
>>> _ = pl.add_actor(human_actor)
>>> _ = pl.add_actor(planes)
>>> planes.camera = pl.camera
>>> pl.show()

Static Scene

Interactive Scene

Create a new assembly and customize the colors and opacity.

>>> color = pv.global_theme.color
>>> planes = pv.PlanesAssembly(
...     bounds=human.bounds,
...     x_color=color,
...     y_color=color,
...     z_color=color,
...     opacity=1.0,
... )

Since the planes are opaque, the 3D labels may be occluded. Use 2D labels instead so the labels are always visible.

>>> planes.label_mode = '2D'

Offset the labels to position them inside the bounds of the planes.

>>> planes.label_offset = -0.05

Move the labels for the two larger planes closer to the corners.

>>> planes.label_position = (0.8, 0.8, 0.5)

Visualize the result.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(human, scalars='Color', rgb=True)
>>> _ = pl.add_actor(planes)
>>> planes.camera = pl.camera
>>> pl.show()

Static Scene

Interactive Scene

Methods

Attributes

PlanesAssembly.camera	Camera to use for displaying the labels.
PlanesAssembly.label_edge	Edge on which to position each plane's label.
PlanesAssembly.label_mode	Mode to use for text labels.
PlanesAssembly.label_offset	Vertical offset of the text labels.
PlanesAssembly.label_position	Normalized relative position of the text labels along the edge of each plane.
PlanesAssembly.label_size	Size of the text labels.
PlanesAssembly.labels	Return or set the labels for the planes.
PlanesAssembly.opacity	Opacity of the planes.
PlanesAssembly.planes	Get the orthogonal plane datasets of the assembly.
PlanesAssembly.x_color	Color of the yz-plane.
PlanesAssembly.x_label	Text label for the yz-plane.
PlanesAssembly.y_color	Color of the zx-plane.
PlanesAssembly.y_label	Text label for the zx-plane.
PlanesAssembly.z_color	Color of the xy-plane.
PlanesAssembly.z_label	Text label for the xy-plane.