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: Clip a mesh using a plane widget.
  
  Add a mesh to the scene with a plane widget that is used to clip
  the mesh interactively.
  
  The clipped mesh is saved to the ``.plane_clipped_meshes``
  attribute on the plotter.
  
  Parameters
  ----------
  mesh : pyvista.DataSet or vtk.vtkAlgorithm
      The input dataset to add to the scene and clip or algorithm that
      produces said mesh.
  
  normal : str or tuple(float), optional
      The starting normal vector of the plane.
  
  invert : bool, optional
      Flag on whether to flip/invert the clip.
  
  widget_color : ColorLike, optional
      Either a string, RGB list, or hex color string.
  
  value : float, optional
      Set the clipping value along the normal direction.
      The default value is 0.0.
  
  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.
  
  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.
  
  outline_translation : bool, optional
      If ``False``, the box widget cannot be translated and is
      strictly placed at the given bounds.
  
  implicit : bool, optional
      When ``True``, a ``vtkImplicitPlaneWidget`` is used and
      when ``False``, a ``vtkPlaneWidget`` is used.
  
  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.
  
  crinkle : bool, optional
      Crinkle the clip by extracting the entire cells along the clip.
  
  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 or ``vtk.vtkCommand.EventIds``.
  
  origin : tuple(float), optional
      The starting coordinate of the center of the plane.
  
  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
  
  **kwargs : dict, optional
      All additional keyword arguments are passed to
      :func:`Plotter.add_mesh` to control how the mesh is
      displayed.
  
  Returns
  -------
  vtk.vtkActor
      VTK actor of the mesh.
  
  Examples
  --------
  Shows an interactive plane used to clip the mesh and store it.
  
  >>> import pyvista as pv
  >>> from pyvista import examples
  >>> vol = examples.load_airplane()
  >>> pl = pv.Plotter()
  >>> _ = pl.add_mesh_clip_plane(vol, normal=[0, -1, 0])
  >>> pl.show(cpos=[-2.1, 0.6, 1.5])
  >>> pl.plane_clipped_meshes  # doctest:+SKIP
  
  For a full example see :ref:`plane_widget_example`.
docstr_tok: ["Clip","a","mesh","using","a","plane","widget",".","Add","a","mesh","to","the","scene","with","a","plane","widget","that","is","used","to","clip","the","mesh","interactively",".","The","clipped","mesh","is","saved","to","the","``",".plane_clipped_meshes","``","attribute","on","the","plotter",".","Parameters","--","--","--","--","--","mesh",":","pyvista.DataSet","or","vtk.vtkAlgorithm","The","input","dataset","to","add","to","the","scene","and","clip","or","algorithm","that","produces","said","mesh",".","normal",":","str","or","tuple","(","float",")",",","optional","The","starting","normal","vector","of","the","plane",".","invert",":","bool",",","optional","Flag","on","whether","to","flip\/invert","the","clip",".","widget_color",":","ColorLike",",","optional","Either","a","string",",","RGB","list",",","or","hex","color","string",".","value",":","float",",","optional","Set","the","clipping","value","along","the","normal","direction",".","The","default","value","is","0.0.","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",".","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",".","outline_translation",":","bool",",","optional","If","``","False","``",",","the","box","widget","can","not","be","translated","and","is","strictly","placed","at","the","given","bounds",".","implicit",":","bool",",","optional","When","``","True","``",",","a","``","vtkImplicitPlaneWidget","``","is","used","and","when","``","False","``",",","a","``","vtkPlaneWidget","``","is","used",".","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",".","crinkle",":","bool",",","optional","Crinkle","the","clip","by","extracting","the","entire","cells","along","the","clip",".","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","or","``","vtk.vtkCommand.EventIds","``",".","origin",":","tuple","(","float",")",",","optional","The","starting","coordinate","of","the","center","of","the","plane",".","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","*","*","kwargs",":","dict",",","optional","All","additional","keyword","arguments","are","passed","to",":","func",":","`","Plotter.add_mesh","`","to","control","how","the","mesh","is","displayed",".","Returns","--","--","--","-","vtk.vtkActor","VTK","actor","of","the","mesh",".","Examples","--","--","--","--","Shows","an","interactive","plane","used","to","clip","the","mesh","and","store","it",".",">",">",">","import","pyvista","as","pv",">",">",">","from","pyvista","import","examples",">",">",">","vol","=","examples.load_airplane","(",")",">",">",">","pl","=","pv.Plotter","(",")",">",">",">","_","=","pl.add_mesh_clip_plane","(","vol",",","normal=","[","0",",","-1",",","0","]",")",">",">",">","pl.show","(","cpos=","[","-2.1",",","0.6",",","1.5","]",")",">",">",">","pl.plane_clipped_meshes","#","doctest",":","+SKIP","For","a","full","example","see",":","ref",":","`","plane_widget_example","`","."]
code: def add_mesh_clip_plane(
      self,
      mesh,
      normal="x",
      invert=False,
      widget_color=None,
      value=0.0,
      assign_to_axis=None,
      tubing=False,
      origin_translation=True,
      outline_translation=False,
      implicit=True,
      normal_rotation=True,
      crinkle=False,
      interaction_event="end",
      origin=None,
      outline_opacity=None,
      **kwargs,
  ):
      """Clip a mesh using a plane widget.
  
      Add a mesh to the scene with a plane widget that is used to clip
      the mesh interactively.
  
      The clipped mesh is saved to the ``.plane_clipped_meshes``
      attribute on the plotter.
  
      Parameters
      ----------
      mesh : pyvista.DataSet or vtk.vtkAlgorithm
          The input dataset to add to the scene and clip or algorithm that
          produces said mesh.
  
      normal : str or tuple(float), optional
          The starting normal vector of the plane.
  
      invert : bool, optional
          Flag on whether to flip/invert the clip.
  
      widget_color : ColorLike, optional
          Either a string, RGB list, or hex color string.
  
      value : float, optional
          Set the clipping value along the normal direction.
          The default value is 0.0.
  
      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.
  
      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.
  
      outline_translation : bool, optional
          If ``False``, the box widget cannot be translated and is
          strictly placed at the given bounds.
  
      implicit : bool, optional
          When ``True``, a ``vtkImplicitPlaneWidget`` is used and
          when ``False``, a ``vtkPlaneWidget`` is used.
  
      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.
  
      crinkle : bool, optional
          Crinkle the clip by extracting the entire cells along the clip.
  
      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 or ``vtk.vtkCommand.EventIds``.
  
      origin : tuple(float), optional
          The starting coordinate of the center of the plane.
  
      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
  
      **kwargs : dict, optional
          All additional keyword arguments are passed to
          :func:`Plotter.add_mesh` to control how the mesh is
          displayed.
  
      Returns
      -------
      vtk.vtkActor
          VTK actor of the mesh.
  
      Examples
      --------
      Shows an interactive plane used to clip the mesh and store it.
  
      >>> import pyvista as pv
      >>> from pyvista import examples
      >>> vol = examples.load_airplane()
      >>> pl = pv.Plotter()
      >>> _ = pl.add_mesh_clip_plane(vol, normal=[0, -1, 0])
      >>> pl.show(cpos=[-2.1, 0.6, 1.5])
      >>> pl.plane_clipped_meshes  # doctest:+SKIP
  
      For a full example see :ref:`plane_widget_example`.
  
      """
      from pyvista.core.filters import (
          _get_output,
      )  # avoids circular import
  
      mesh, algo = algorithm_to_mesh_handler(
          add_ids_algorithm(mesh, point_ids=False, cell_ids=True)
      )
  
      name = kwargs.get("name", mesh.memory_address)
      rng = mesh.get_data_range(kwargs.get("scalars", None))
      kwargs.setdefault("clim", kwargs.pop("rng", rng))
      mesh.set_active_scalars(
          kwargs.get("scalars", mesh.active_scalars_name)
      )
      if origin is None:
          origin = mesh.center
  
      self.add_mesh(
          outline_algorithm(algo), name=f"{name}-outline", opacity=0.0
      )
  
      if isinstance(mesh, _vtk.vtkPolyData):
          clipper = _vtk.vtkClipPolyData()
      # elif isinstance(mesh, vtk.vtkImageData):
      #     clipper = vtk.vtkClipVolume()
      #     clipper.SetMixed3DCellGeneration(True)
      else:
          clipper = _vtk.vtkTableBasedClipDataSet()
      set_algorithm_input(clipper, algo)
      clipper.SetValue(value)
      clipper.SetInsideOut(invert)  # invert the clip if needed
  
      if crinkle:
          crinkler = crinkle_algorithm(clipper, algo)
          plane_clipped_mesh = _get_output(crinkler)
      else:
          plane_clipped_mesh = _get_output(clipper)
      self.plane_clipped_meshes.append(plane_clipped_mesh)
  
      def callback(normal, loc):  # numpydoc ignore=GL08
          function = generate_plane(normal, loc)
          clipper.SetClipFunction(function)  # the implicit function
          clipper.Update()  # Perform the Cut
          if crinkle:
              clipped = pyvista.wrap(crinkler.GetOutputDataObject(0))
          else:
              clipped = pyvista.wrap(clipper.GetOutput())
          plane_clipped_mesh.shallow_copy(clipped)
  
      self.add_plane_widget(
          callback=callback,
          bounds=mesh.bounds,
          factor=1.25,
          normal=normal,
          color=widget_color,
          tubing=tubing,
          assign_to_axis=assign_to_axis,
          origin_translation=origin_translation,
          outline_translation=outline_translation,
          implicit=implicit,
          origin=origin,
          normal_rotation=normal_rotation,
          interaction_event=interaction_event,
          outline_opacity=outline_opacity,
      )
  
      if crinkle:
          return self.add_mesh(crinkler, **kwargs)
      return self.add_mesh(clipper, **kwargs)
  
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 7 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_mesh_clip_plane(mesh, normal, invert, widget_color, value, assign_to_axis, tubing, origin_translation, outline_translation, implicit, normal_rotation, crinkle, interaction_event, origin, outline_opacity) and returns: self, self