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
, andlabel_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_label
str
, default: ‘YZ’ Text label for the yz-plane. Alternatively, set the label with
labels
.- y_label
str
, default: ‘ZX’ Text label for the zx-plane. Alternatively, set the label with
labels
.- z_label
str
, default: ‘XY’ Text label for the xy-plane. Alternatively, set the label with
labels
.- labels
Sequence
[str
], optional, Text labels for the planes. This is an alternative parameter to using
x_label
,y_label
, andz_label
separately.- label_color
ColorLike
, default: ‘black’ Color of the text labels.
- show_labelsbool, default:
True
Show or hide the text labels.
- label_position
float
|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 that0.0
is at the center of the edge and-1.0
and1.0
are at the corners.Note
The label text is centered horizontally at the specified positions.
- label_edge
str
, 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_offset
float
|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_size
int
, default: 50 Size of the text labels. If
label_mode
is'2D'
, this is the font size. Iflabel_mode
is'3D'
, the labels are scaled proportional to thelength
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_color
ColorLike
,optional
Color of the xy-plane.
- y_color
ColorLike
,optional
Color of the yz-plane.
- z_color
ColorLike
,optional
Color of the zx-plane.
- opacity
float
, default: 0.3 Opacity of the planes.
- position
VectorLike
[float
], default: (0.0, 0.0, 0.0) Position of the planes in space.
- orientation
VectorLike
[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.
- origin
VectorLike
[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
.- scale
VectorLike
[float
], default: (1.0, 1.0, 1.0) Scaling factor applied to the assembly.
- user_matrix
MatrixLike
[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
.
- x_label
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()
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()
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()
Methods
Attributes
Camera to use for displaying the labels.
Edge on which to position each plane's label.
Mode to use for text labels.
Vertical offset of the text labels.
Normalized relative position of the text labels along the edge of each plane.
Size of the text labels.
Return or set the labels for the planes.
Opacity of the planes.
Get the orthogonal plane datasets of the assembly.
Color of the yz-plane.
Text label for the yz-plane.
Color of the zx-plane.
Text label for the zx-plane.
Color of the xy-plane.
Text label for the xy-plane.