class_docstr: An internal class to manage widgets.
  
  It also manages and other helper methods involving widgets.
class_docstr_tok: ["An","internal","class","to","manage","widgets",".","It","also","manages","and","other","helper","methods","involving","widgets","."]
docstr: Add a plane widget to the scene.
  
  This is useless without a callback function. You can pass a
  callable function that takes two arguments, the normal and
  origin of the plane in that order output from this widget, and
  performs a task with that plane.
  
  Parameters
  ----------
  callback : callable
      The method called every time the plane is updated. Takes
      two arguments, the normal and origin of the plane in that
      order.
  
  normal : str or tuple(float)
      The starting normal vector of the plane.
  
  origin : tuple(float)
      The starting coordinate of the center of the plane.
  
  bounds : tuple(float)
      Length 6 tuple of the bounding box where the widget is placed.
  
  factor : float, optional
      An inflation factor to expand on the bounds when placing.
  
  color : ColorLike, optional
      Either a string, rgb list, or hex color string.
  
  assign_to_axis : str or int, optional
      Assign the normal of the plane to be parallel with a given
      axis: options are ``(0, 'x')``, ``(1, 'y')``, or ``(2,
      'z')``.
  
  tubing : bool, optional
      When using an implicit plane wiget, this controls whether
      or not tubing is shown around the plane's boundaries.
  
  outline_translation : bool, optional
      If ``False``, the plane widget cannot be translated and is
      strictly placed at the given bounds. Only valid when using
      an implicit plane.
  
  origin_translation : bool, optional
      If ``False``, the plane widget cannot be translated by its
      origin and is strictly placed at the given origin. Only
      valid when using an implicit plane.
  
  implicit : bool, optional
      When ``True``, a ``vtkImplicitPlaneWidget`` is used and
      when ``False``, a ``vtkPlaneWidget`` is used.
  
  pass_widget : bool, optional
      If ``True``, the widget will be passed as the last
      argument of the callback.
  
  test_callback : bool, optional
      If ``True``, run the callback function after the widget is
      created.
  
  normal_rotation : bool, optional
      Set the opacity of the normal vector arrow to 0 such that
      it is effectively disabled. This prevents the user from
      rotating the normal. This is forced to ``False`` when
      ``assign_to_axis`` is set.
  
  interaction_event : vtk.vtkCommand.EventIds, str, optional
      The VTK interaction event to use for triggering the
      callback. Accepts either the strings ``'start'``, ``'end'``,
      ``'always'`` or a ``vtk.vtkCommand.EventIds``.
  
      .. versionchanged:: 0.38.0
         Now accepts either strings and ``vtk.vtkCommand.EventIds``.
  
  outline_opacity : bool or float, optional
      Set the visible of outline. Only valid when using
      an implicit plane. Either a bool or float.
  
      .. versionadded:: 0.44.0
  
  Returns
  -------
  vtk.vtkImplicitPlaneWidget or vtk.vtkPlaneWidget
      Plane widget.
  
  Examples
  --------
  Shows an interactive plane moving along the x-axis in the random-hill example, which is used to mark the max altitude
  at a particular distance x.
  
  >>> import pyvista as pv
  >>> from pyvista import examples
  >>> mesh = examples.load_random_hills()
  >>> pl = pv.Plotter()
  >>> _ = pl.add_mesh(mesh)
  >>> def callback(normal, origin):
  ...     slc = mesh.slice(normal=normal, origin=origin)
  ...     origin = list(origin)
  ...     origin[2] = slc.bounds[5]
  ...     peak_plane = pv.Plane(
  ...         center=origin,
  ...         direction=[0, 0, 1],
  ...         i_size=20,
  ...         j_size=20,
  ...     )
  ...     _ = pl.add_mesh(
  ...         peak_plane, name="Peak", color='red', opacity=0.4
  ...     )
  ...
  >>> _ = pl.add_plane_widget(callback, normal_rotation=False)
  >>> pl.show()
docstr_tok: ["Add","a","plane","widget","to","the","scene",".","This","is","useless","without","a","callback","function",".","You","can","pass","a","callable","function","that","takes","two","arguments",",","the","normal","and","origin","of","the","plane","in","that","order","output","from","this","widget",",","and","performs","a","task","with","that","plane",".","Parameters","--","--","--","--","--","callback",":","callable","The","method","called","every","time","the","plane","is","updated",".","Takes","two","arguments",",","the","normal","and","origin","of","the","plane","in","that","order",".","normal",":","str","or","tuple","(","float",")","The","starting","normal","vector","of","the","plane",".","origin",":","tuple","(","float",")","The","starting","coordinate","of","the","center","of","the","plane",".","bounds",":","tuple","(","float",")","Length","6","tuple","of","the","bounding","box","where","the","widget","is","placed",".","factor",":","float",",","optional","An","inflation","factor","to","expand","on","the","bounds","when","placing",".","color",":","ColorLike",",","optional","Either","a","string",",","rgb","list",",","or","hex","color","string",".","assign_to_axis",":","str","or","int",",","optional","Assign","the","normal","of","the","plane","to","be","parallel","with","a","given","axis",":","options","are","``","(","0",",","'","x","'",")","``",",","``","(","1",",","'","y","'",")","``",",","or","``","(","2",",","'","z","'",")","``",".","tubing",":","bool",",","optional","When","using","an","implicit","plane","wiget",",","this","controls","whether","or","not","tubing","is","shown","around","the","plane","'s","boundaries",".","outline_translation",":","bool",",","optional","If","``","False","``",",","the","plane","widget","can","not","be","translated","and","is","strictly","placed","at","the","given","bounds",".","Only","valid","when","using","an","implicit","plane",".","origin_translation",":","bool",",","optional","If","``","False","``",",","the","plane","widget","can","not","be","translated","by","its","origin","and","is","strictly","placed","at","the","given","origin",".","Only","valid","when","using","an","implicit","plane",".","implicit",":","bool",",","optional","When","``","True","``",",","a","``","vtkImplicitPlaneWidget","``","is","used","and","when","``","False","``",",","a","``","vtkPlaneWidget","``","is","used",".","pass_widget",":","bool",",","optional","If","``","True","``",",","the","widget","will","be","passed","as","the","last","argument","of","the","callback",".","test_callback",":","bool",",","optional","If","``","True","``",",","run","the","callback","function","after","the","widget","is","created",".","normal_rotation",":","bool",",","optional","Set","the","opacity","of","the","normal","vector","arrow","to","0","such","that","it","is","effectively","disabled",".","This","prevents","the","user","from","rotating","the","normal",".","This","is","forced","to","``","False","``","when","``","assign_to_axis","``","is","set",".","interaction_event",":","vtk.vtkCommand.EventIds",",","str",",","optional","The","VTK","interaction","event","to","use","for","triggering","the","callback",".","Accepts","either","the","strings","``","'start","'","``",",","``","'end","'","``",",","``","'always","'","``","or","a","``","vtk.vtkCommand.EventIds","``",".","..","versionchanged",":",":","0.38.0","Now","accepts","either","strings","and","``","vtk.vtkCommand.EventIds","``",".","outline_opacity",":","bool","or","float",",","optional","Set","the","visible","of","outline",".","Only","valid","when","using","an","implicit","plane",".","Either","a","bool","or","float",".","..","versionadded",":",":","0.44.0","Returns","--","--","--","-","vtk.vtkImplicitPlaneWidget","or","vtk.vtkPlaneWidget","Plane","widget",".","Examples","--","--","--","--","Shows","an","interactive","plane","moving","along","the","x-axis","in","the","random-hill","example",",","which","is","used","to","mark","the","max","altitude","at","a","particular","distance","x",".",">",">",">","import","pyvista","as","pv",">",">",">","from","pyvista","import","examples",">",">",">","mesh","=","examples.load_random_hills","(",")",">",">",">","pl","=","pv.Plotter","(",")",">",">",">","_","=","pl.add_mesh","(","mesh",")",">",">",">","def","callback","(","normal",",","origin",")",":","...","slc","=","mesh.slice","(","normal=normal",",","origin=origin",")","...","origin","=","list","(","origin",")","...","origin","[","2","]","=","slc.bounds","[","5","]","...","peak_plane","=","pv.Plane","(","...","center=origin",",","...","direction=","[","0",",","0",",","1","]",",","...","i_size=20",",","...","j_size=20",",","...",")","...","_","=","pl.add_mesh","(","...","peak_plane",",","name=","''","Peak","''",",","color='red","'",",","opacity=0.4","...",")","...",">",">",">","_","=","pl.add_plane_widget","(","callback",",","normal_rotation=False",")",">",">",">","pl.show","(",")"]
code: def add_plane_widget(
      self,
      callback,
      normal="x",
      origin=None,
      bounds=None,
      factor=1.25,
      color=None,
      assign_to_axis=None,
      tubing=False,
      outline_translation=False,
      origin_translation=True,
      implicit=True,
      pass_widget=False,
      test_callback=True,
      normal_rotation=True,
      interaction_event="end",
      outline_opacity=None,
  ):
      """Add a plane widget to the scene.
  
      This is useless without a callback function. You can pass a
      callable function that takes two arguments, the normal and
      origin of the plane in that order output from this widget, and
      performs a task with that plane.
  
      Parameters
      ----------
      callback : callable
          The method called every time the plane is updated. Takes
          two arguments, the normal and origin of the plane in that
          order.
  
      normal : str or tuple(float)
          The starting normal vector of the plane.
  
      origin : tuple(float)
          The starting coordinate of the center of the plane.
  
      bounds : tuple(float)
          Length 6 tuple of the bounding box where the widget is placed.
  
      factor : float, optional
          An inflation factor to expand on the bounds when placing.
  
      color : ColorLike, optional
          Either a string, rgb list, or hex color string.
  
      assign_to_axis : str or int, optional
          Assign the normal of the plane to be parallel with a given
          axis: options are ``(0, 'x')``, ``(1, 'y')``, or ``(2,
          'z')``.
  
      tubing : bool, optional
          When using an implicit plane wiget, this controls whether
          or not tubing is shown around the plane's boundaries.
  
      outline_translation : bool, optional
          If ``False``, the plane widget cannot be translated and is
          strictly placed at the given bounds. Only valid when using
          an implicit plane.
  
      origin_translation : bool, optional
          If ``False``, the plane widget cannot be translated by its
          origin and is strictly placed at the given origin. Only
          valid when using an implicit plane.
  
      implicit : bool, optional
          When ``True``, a ``vtkImplicitPlaneWidget`` is used and
          when ``False``, a ``vtkPlaneWidget`` is used.
  
      pass_widget : bool, optional
          If ``True``, the widget will be passed as the last
          argument of the callback.
  
      test_callback : bool, optional
          If ``True``, run the callback function after the widget is
          created.
  
      normal_rotation : bool, optional
          Set the opacity of the normal vector arrow to 0 such that
          it is effectively disabled. This prevents the user from
          rotating the normal. This is forced to ``False`` when
          ``assign_to_axis`` is set.
  
      interaction_event : vtk.vtkCommand.EventIds, str, optional
          The VTK interaction event to use for triggering the
          callback. Accepts either the strings ``'start'``, ``'end'``,
          ``'always'`` or a ``vtk.vtkCommand.EventIds``.
  
          .. versionchanged:: 0.38.0
             Now accepts either strings and ``vtk.vtkCommand.EventIds``.
  
      outline_opacity : bool or float, optional
          Set the visible of outline. Only valid when using
          an implicit plane. Either a bool or float.
  
          .. versionadded:: 0.44.0
  
      Returns
      -------
      vtk.vtkImplicitPlaneWidget or vtk.vtkPlaneWidget
          Plane widget.
  
      Examples
      --------
      Shows an interactive plane moving along the x-axis in the random-hill example, which is used to mark the max altitude
      at a particular distance x.
  
      >>> import pyvista as pv
      >>> from pyvista import examples
      >>> mesh = examples.load_random_hills()
      >>> pl = pv.Plotter()
      >>> _ = pl.add_mesh(mesh)
      >>> def callback(normal, origin):
      ...     slc = mesh.slice(normal=normal, origin=origin)
      ...     origin = list(origin)
      ...     origin[2] = slc.bounds[5]
      ...     peak_plane = pv.Plane(
      ...         center=origin,
      ...         direction=[0, 0, 1],
      ...         i_size=20,
      ...         j_size=20,
      ...     )
      ...     _ = pl.add_mesh(
      ...         peak_plane, name="Peak", color='red', opacity=0.4
      ...     )
      ...
      >>> _ = pl.add_plane_widget(callback, normal_rotation=False)
      >>> pl.show()
  
      """
      interaction_event = _parse_interaction_event(interaction_event)
  
      if origin is None:
          origin = self.center
      if bounds is None:
          bounds = self.bounds
  
      if isinstance(normal, str):
          normal = NORMALS[normal.lower()]
  
      color = Color(
          color, default_color=pyvista.global_theme.font.color
      )
  
      if assign_to_axis:
          normal_rotation = False
  
      def _the_callback(widget, _event):
          the_plane = _vtk.vtkPlane()
          widget.GetPlane(the_plane)
          normal = the_plane.GetNormal()
          origin = the_plane.GetOrigin()
          if callable(callback):
              if pass_widget:
                  try_callback(callback, normal, origin, widget)
              else:
                  try_callback(callback, normal, origin)
          return
  
      if implicit:
          plane_widget = _vtk.vtkImplicitPlaneWidget()
          plane_widget.GetNormalProperty().SetColor(color.float_rgb)
          plane_widget.GetOutlineProperty().SetColor(color.float_rgb)
          plane_widget.GetOutlineProperty().SetColor(color.float_rgb)
          plane_widget.GetOutlineProperty().SetOpacity(color.opacity)
          plane_widget.SetTubing(tubing)
          plane_widget.SetOutlineTranslation(outline_translation)
          plane_widget.SetOriginTranslation(origin_translation)
  
          _start_interact = (
              lambda plane_widget, event: plane_widget.SetDrawPlane(
                  True
              )
          )
          _stop_interact = (
              lambda plane_widget, event: plane_widget.SetDrawPlane(
                  False
              )
          )
  
          plane_widget.SetDrawPlane(False)
          plane_widget.AddObserver(
              _vtk.vtkCommand.StartInteractionEvent, _start_interact
          )
          plane_widget.AddObserver(
              _vtk.vtkCommand.EndInteractionEvent, _stop_interact
          )
          plane_widget.SetPlaceFactor(factor)
          plane_widget.PlaceWidget(bounds)
          plane_widget.SetOrigin(origin)
  
          if not normal_rotation:
              plane_widget.GetNormalProperty().SetOpacity(0)
  
          if outline_opacity is not None:
              plane_widget.GetOutlineProperty().SetOpacity(
                  float(outline_opacity)
              )
  
      else:
          # Position of the small plane
          source = _vtk.vtkPlaneSource()
          source.SetNormal(normal)
          source.SetCenter(origin)
          source.SetPoint1(
              origin[0] + (bounds[1] - bounds[0]) * 0.01,
              origin[1] - (bounds[3] - bounds[2]) * 0.01,
              origin[2],
          )
          source.SetPoint2(
              origin[0] - (bounds[1] - bounds[0]) * 0.01,
              origin[1] + (bounds[3] - bounds[2]) * 0.01,
              origin[2],
          )
          source.Update()
          plane_widget = _vtk.vtkPlaneWidget()
          plane_widget.SetHandleSize(0.01)
          # Position of the widget
          plane_widget.SetInputData(source.GetOutput())
          plane_widget.SetRepresentationToOutline()
          plane_widget.SetPlaceFactor(factor)
          plane_widget.PlaceWidget(bounds)
          plane_widget.SetCenter(origin)  # Necessary
          plane_widget.GetPlaneProperty().SetColor(
              color.float_rgb
          )  # self.C_LOT[fn])
          plane_widget.GetHandleProperty().SetColor(color.float_rgb)
  
          if not normal_rotation:
              plane_widget.GetHandleProperty().SetOpacity(0)
  
      plane_widget.GetPlaneProperty().SetOpacity(0.5)
      plane_widget.SetInteractor(self.iren.interactor)
      plane_widget.SetCurrentRenderer(self.renderer)
  
      if assign_to_axis:
          # Note that normal_rotation was forced to False
          if assign_to_axis in [0, "x", "X"]:
              plane_widget.NormalToXAxisOn()
              plane_widget.SetNormal(NORMALS["x"])
          elif assign_to_axis in [1, "y", "Y"]:
              plane_widget.NormalToYAxisOn()
              plane_widget.SetNormal(NORMALS["y"])
          elif assign_to_axis in [2, "z", "Z"]:
              plane_widget.NormalToZAxisOn()
              plane_widget.SetNormal(NORMALS["z"])
          else:
              raise RuntimeError("assign_to_axis not understood")
      else:
          plane_widget.SetNormal(normal)
  
      plane_widget.Modified()
      plane_widget.UpdatePlacement()
      plane_widget.On()
      plane_widget.AddObserver(
          interaction_event,
          # _vtk.vtkCommand.InteractionEvent,
          _the_callback,
      )
      if test_callback:
          _the_callback(plane_widget, None)  # Trigger immediate update
  
      self.plane_widgets.append(plane_widget)
      return plane_widget
  
imports: import pathlib
  from typing import Optional, Sequence, Tuple, Union
  import numpy
  import pyvista
  from pyvista.core.utilities.arrays import get_array, get_array_association
  from pyvista.core.utilities.geometric_objects import NORMALS
  from pyvista.core.utilities.helpers import generate_plane
  from pyvista.core.utilities.misc import assert_empty_kwargs, try_callback
  from .None import _vtk
  from .affine_widget import AffineWidget3D
  from .colors import Color
  from .opts import PickerType
  from .utilities.algorithms import add_ids_algorithm, algorithm_to_mesh_handler, crinkle_algorithm, outline_algorithm, pointset_to_polydata_algorithm, set_algorithm_input
label_desc: Use image node_id 5 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_plane_widget(callback, normal, origin, bounds, factor, color, assign_to_axis, tubing, outline_translation, origin_translation, implicit, pass_widget, test_callback, normal_rotation, interaction_event, outline_opacity) and returns: plane_widget