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 volume using a plane widget.
  
  Parameters
  ----------
  volume : pyvista.plotting.volume.Volume or pyvista.ImageData or pyvista.RectilinearGrid
      New dataset of type :class:`pyvista.ImageData` or
      :class:`pyvista.RectilinearGrid`, or the return value from
      :class:`pyvista.plotting.volume.Volume` from :func:`Plotter.add_volume`.
  
  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.
  
  interaction_event : vtk.vtkCommand.EventIds, optional
      The VTK interaction event to use for triggering the callback.
  
  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_volume` to control how the volume is
      displayed. Only applicable if ``volume`` is either a
      :class:`pyvista.ImageData` and :class:`pyvista.RectilinearGrid`.
  
  Returns
  -------
  vtk.vtkPlaneWidget or vtk.vtkImplicitPlaneWidget
      The VTK plane widget depending on the value of ``implicit``.
docstr_tok: ["Clip","a","volume","using","a","plane","widget",".","Parameters","--","--","--","--","--","volume",":","pyvista.plotting.volume.Volume","or","pyvista.ImageData","or","pyvista.RectilinearGrid","New","dataset","of","type",":","class",":","`","pyvista.ImageData","`","or",":","class",":","`","pyvista.RectilinearGrid","`",",","or","the","return","value","from",":","class",":","`","pyvista.plotting.volume.Volume","`","from",":","func",":","`","Plotter.add_volume","`",".","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",".","interaction_event",":","vtk.vtkCommand.EventIds",",","optional","The","VTK","interaction","event","to","use","for","triggering","the","callback",".","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_volume","`","to","control","how","the","volume","is","displayed",".","Only","applicable","if","``","volume","``","is","either","a",":","class",":","`","pyvista.ImageData","`","and",":","class",":","`","pyvista.RectilinearGrid","`",".","Returns","--","--","--","-","vtk.vtkPlaneWidget","or","vtk.vtkImplicitPlaneWidget","The","VTK","plane","widget","depending","on","the","value","of","``","implicit","``","."]
code: def add_volume_clip_plane(
      self,
      volume,
      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,
      interaction_event="end",
      origin=None,
      outline_opacity=None,
      **kwargs,
  ):
      """Clip a volume using a plane widget.
  
      Parameters
      ----------
      volume : pyvista.plotting.volume.Volume or pyvista.ImageData or pyvista.RectilinearGrid
          New dataset of type :class:`pyvista.ImageData` or
          :class:`pyvista.RectilinearGrid`, or the return value from
          :class:`pyvista.plotting.volume.Volume` from :func:`Plotter.add_volume`.
  
      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.
  
      interaction_event : vtk.vtkCommand.EventIds, optional
          The VTK interaction event to use for triggering the callback.
  
      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_volume` to control how the volume is
          displayed. Only applicable if ``volume`` is either a
          :class:`pyvista.ImageData` and :class:`pyvista.RectilinearGrid`.
  
      Returns
      -------
      vtk.vtkPlaneWidget or vtk.vtkImplicitPlaneWidget
          The VTK plane widget depending on the value of ``implicit``.
  
      """
      if isinstance(
          volume, (pyvista.ImageData, pyvista.RectilinearGrid)
      ):
          volume = self.add_volume(volume, **kwargs)
      elif not isinstance(volume, pyvista.plotting.volume.Volume):
          raise TypeError(
              "The `volume` parameter type must be either pyvista.ImageData, "
              "pyvista.RectilinearGrid, or a pyvista.plotting.volume.Volume "
              "from `Plotter.add_volume`."
          )
      else:
          assert_empty_kwargs(**kwargs)
  
      plane = _vtk.vtkPlane()
  
      def callback(normal, origin):  # numpydoc ignore=PR01
          """Update the plane used to clip the volume."""
          plane.SetNormal(normal)
          plane.SetOrigin(origin)
  
      widget = self.add_plane_widget(
          callback=callback,
          bounds=volume.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,
      )
      widget.GetPlane(plane)
      volume.mapper.AddClippingPlane(plane)
      self.plane_widgets.append(widget)
  
      return 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 8 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_volume_clip_plane(volume, normal, invert, widget_color, value, assign_to_axis, tubing, origin_translation, outline_translation, implicit, normal_rotation, interaction_event, origin, outline_opacity) and returns: widget