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 box widget.
  
  Add a mesh to the scene with a box widget that is used to clip
  the mesh interactively.
  
  The clipped mesh is saved to the ``.box_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.
  
  invert : bool, optional
      Flag on whether to flip/invert the clip.
  
  rotation_enabled : bool, optional
      If ``False``, the box widget cannot be rotated and is strictly
      orthogonal to the cartesian axes.
  
  widget_color : ColorLike, optional
      Color of the widget.  Either a string, RGB sequence, or
      hex color string.  For example:
  
      * ``color='white'``
      * ``color='w'``
      * ``color=[1.0, 1.0, 1.0]``
      * ``color='#FFFFFF'``
  
  outline_translation : bool, optional
      If ``False``, the plane widget cannot be translated and is
      strictly placed at the given bounds.
  
  merge_points : bool, optional
      If ``True`` (default), coinciding points of independently
      defined mesh elements will be merged.
  
  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
         Changed from ``event_type`` to ``interaction_event`` and now
         accepts either strings and ``vtk.vtkCommand.EventIds``.
  
  **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 clip box.
  
  >>> import pyvista as pv
  >>> mesh = pv.ParametricConicSpiral()
  >>> pl = pv.Plotter()
  >>> _ = pl.add_mesh_clip_box(mesh, color='white')
  >>> pl.show()
  
  For a full example see :ref:`box_widget_example`.
docstr_tok: ["Clip","a","mesh","using","a","box","widget",".","Add","a","mesh","to","the","scene","with","a","box","widget","that","is","used","to","clip","the","mesh","interactively",".","The","clipped","mesh","is","saved","to","the","``",".box_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",".","invert",":","bool",",","optional","Flag","on","whether","to","flip\/invert","the","clip",".","rotation_enabled",":","bool",",","optional","If","``","False","``",",","the","box","widget","can","not","be","rotated","and","is","strictly","orthogonal","to","the","cartesian","axes",".","widget_color",":","ColorLike",",","optional","Color","of","the","widget",".","Either","a","string",",","RGB","sequence",",","or","hex","color","string",".","For","example",":","*","``","color='white","'","``","*","``","color=","'","w","'","``","*","``","color=","[","1.0",",","1.0",",","1.0","]","``","*","``","color=","'","#","FFFFFF","'","``","outline_translation",":","bool",",","optional","If","``","False","``",",","the","plane","widget","can","not","be","translated","and","is","strictly","placed","at","the","given","bounds",".","merge_points",":","bool",",","optional","If","``","True","``","(","default",")",",","coinciding","points","of","independently","defined","mesh","elements","will","be","merged",".","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","Changed","from","``","event_type","``","to","``","interaction_event","``","and","now","accepts","either","strings","and","``","vtk.vtkCommand.EventIds","``",".","*","*","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","clip","box",".",">",">",">","import","pyvista","as","pv",">",">",">","mesh","=","pv.ParametricConicSpiral","(",")",">",">",">","pl","=","pv.Plotter","(",")",">",">",">","_","=","pl.add_mesh_clip_box","(","mesh",",","color='white","'",")",">",">",">","pl.show","(",")","For","a","full","example","see",":","ref",":","`","box_widget_example","`","."]
code: def add_mesh_clip_box(
      self,
      mesh,
      invert=False,
      rotation_enabled=True,
      widget_color=None,
      outline_translation=True,
      merge_points=True,
      crinkle=False,
      interaction_event="end",
      **kwargs,
  ):
      """Clip a mesh using a box widget.
  
      Add a mesh to the scene with a box widget that is used to clip
      the mesh interactively.
  
      The clipped mesh is saved to the ``.box_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.
  
      invert : bool, optional
          Flag on whether to flip/invert the clip.
  
      rotation_enabled : bool, optional
          If ``False``, the box widget cannot be rotated and is strictly
          orthogonal to the cartesian axes.
  
      widget_color : ColorLike, optional
          Color of the widget.  Either a string, RGB sequence, or
          hex color string.  For example:
  
          * ``color='white'``
          * ``color='w'``
          * ``color=[1.0, 1.0, 1.0]``
          * ``color='#FFFFFF'``
  
      outline_translation : bool, optional
          If ``False``, the plane widget cannot be translated and is
          strictly placed at the given bounds.
  
      merge_points : bool, optional
          If ``True`` (default), coinciding points of independently
          defined mesh elements will be merged.
  
      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
             Changed from ``event_type`` to ``interaction_event`` and now
             accepts either strings and ``vtk.vtkCommand.EventIds``.
  
      **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 clip box.
  
      >>> import pyvista as pv
      >>> mesh = pv.ParametricConicSpiral()
      >>> pl = pv.Plotter()
      >>> _ = pl.add_mesh_clip_box(mesh, color='white')
      >>> pl.show()
  
      For a full example see :ref:`box_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)
      )
  
      self.add_mesh(
          outline_algorithm(algo), name=f"{name}-outline", opacity=0.0
      )
  
      port = 1 if invert else 0
  
      clipper = _vtk.vtkBoxClipDataSet()
      if not merge_points:
          # vtkBoxClipDataSet uses vtkMergePoints by default
          clipper.SetLocator(_vtk.vtkNonMergingPointLocator())
      set_algorithm_input(clipper, algo)
      clipper.GenerateClippedOutputOn()
  
      if crinkle:
          crinkler = crinkle_algorithm(
              clipper.GetOutputPort(port), algo
          )
          box_clipped_mesh = _get_output(crinkler)
      else:
          box_clipped_mesh = _get_output(clipper, oport=port)
  
      self.box_clipped_meshes.append(box_clipped_mesh)
  
      def callback(planes):  # numpydoc ignore=GL08
          bounds = []
          for i in range(planes.GetNumberOfPlanes()):
              plane = planes.GetPlane(i)
              bounds.append(plane.GetNormal())
              bounds.append(plane.GetOrigin())
  
          clipper.SetBoxClip(*bounds)
          clipper.Update()
          if crinkle:
              clipped = pyvista.wrap(crinkler.GetOutputDataObject(0))
          else:
              clipped = _get_output(clipper, oport=port)
          box_clipped_mesh.shallow_copy(clipped)
  
      self.add_box_widget(
          callback=callback,
          bounds=mesh.bounds,
          factor=1.25,
          rotation_enabled=rotation_enabled,
          use_planes=True,
          color=widget_color,
          outline_translation=outline_translation,
          interaction_event=interaction_event,
      )
  
      if crinkle:
          return self.add_mesh(crinkler, reset_camera=False, **kwargs)
      return self.add_mesh(
          clipper.GetOutputPort(port), reset_camera=False, **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 4 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_mesh_clip_box(mesh, invert, rotation_enabled, widget_color, outline_translation, merge_points, crinkle, interaction_event) and returns: self, self