pyvista.Plotter.add_affine_transform_widget

Plotter.add_affine_transform_widget(

actor,

origin=None,

start: bool = True,

scale=0.15,

line_radius=0.02,

always_visible: bool = True,

axes_colors=None,

axes=None,

release_callback=None,

interact_callback=None,

)

Add a 3D affine transform widget.

This widget allows interactive transformations including translation and rotation using the left mouse button.

Parameters:

actorpyvista.Actor

The actor to which the widget is attached to.

originsequence[float], optional

Origin of the widget. Default is the origin of the main actor.

startbool, default: True

If True, start the widget immediately.

scalefloat, default: 0.15

Scale factor for the widget relative to the length of the actor.

line_radiusfloat, default: 0.02

Relative radius of the lines composing the widget.

always_visiblebool, default: True

Make the widget always visible. Setting this to False will cause the widget geometry to be hidden by other actors in the plotter.

axes_colorstuple[ColorLike], optional

Uses the theme by default. Configure the individual axis colors by modifying either the theme with pyvista.global_theme.axes.x_color = <COLOR> or setting this with a tuple as in ('r', 'g', 'b').

axesnumpy.ndarray, optional

(3, 3) Numpy array defining the X, Y, and Z axes. By default this matches the default coordinate system.

release_callbackcallable(), optional

Call this method when releasing the left mouse button. It is passed the user_matrix of the actor.

interact_callbackcallable(), optional

Call this method when moving the mouse with the left mouse button pressed down and a valid movement actor selected. It is passed the user_matrix of the actor.

Returns:

pyvista.plotting.widgets.AffineWidget3D

The affine widget.

Notes

After interacting with the actor, the transform will be stored within pyvista.Prop3D.user_matrix but will not be applied to the dataset. Use this matrix in conjunction with pyvista.DataSetFilters.transform() to transform the dataset.

Examples

Add the 3d affine widget.

>>> import pyvista as pv
>>> pl = pv.Plotter()
>>> actor = pl.add_mesh(pv.Sphere())
>>> widget = pl.add_affine_transform_widget(actor)
>>> pl.show()

Static Scene

Interactive Scene

Access the transform from the actor.

>>> actor.user_matrix
array([[1., 0., 0., 0.],
       [0., 1., 0., 0.],
       [0., 0., 1., 0.],
       [0., 0., 0., 1.]])