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 one or many sphere widgets to a scene.
  
  Use a sphere widget to control a vertex location.
  
  Parameters
  ----------
  callback : callable
      The function to call back when the widget is modified. It takes a
      single argument: the center of the sphere as an XYZ coordinate (a
      3-length sequence), unless ``pass_widget=True``, in which case the
      callback must accept the widget object as the second parameter.  If
      multiple centers are passed in the ``center`` parameter, the
      callback must also accept an index of that widget.
  
  center : sequence[float], optional
      The cartesian coordinate of the sphere's center when placing it in
      the scene. If more than one location is passed, then that many
      widgets will be added and the callback will also be passed the
      integer index of that widget.
  
  radius : float, optional
      The radius of the sphere.
  
  theta_resolution : int, optional
      Set the number of points in the longitude direction.
  
  phi_resolution : int, optional
      Set the number of points in the latitude direction.
  
  color : ColorLike, optional
      The color of the sphere's surface.  If multiple centers
      are passed, then this must be a list of colors.  Each
      color is either a string, rgb list, or hex color string.
      For example:
  
      * ``color='white'``
      * ``color='w'``
      * ``color=[1.0, 1.0, 1.0]``
      * ``color='#FFFFFF'``
  
  style : str, optional
      Representation style: ``'surface'`` or ``'wireframe'``.
  
  selected_color : ColorLike, optional
      Color of the widget when selected during interaction.
  
  indices : sequence[int], optional
      Indices to assign the sphere widgets.
  
  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.
  
  interaction_event : vtk.vtkCommand.EventIds, optional
      The VTK interaction event to use for triggering the callback.
  
  Returns
  -------
  vtk.vtkSphereWidget
      The sphere widget.
docstr_tok: ["Add","one","or","many","sphere","widgets","to","a","scene",".","Use","a","sphere","widget","to","control","a","vertex","location",".","Parameters","--","--","--","--","--","callback",":","callable","The","function","to","call","back","when","the","widget","is","modified",".","It","takes","a","single","argument",":","the","center","of","the","sphere","as","an","XYZ","coordinate","(","a","3-length","sequence",")",",","unless","``","pass_widget=True","``",",","in","which","case","the","callback","must","accept","the","widget","object","as","the","second","parameter",".","If","multiple","centers","are","passed","in","the","``","center","``","parameter",",","the","callback","must","also","accept","an","index","of","that","widget",".","center",":","sequence","[","float","]",",","optional","The","cartesian","coordinate","of","the","sphere","'s","center","when","placing","it","in","the","scene",".","If","more","than","one","location","is","passed",",","then","that","many","widgets","will","be","added","and","the","callback","will","also","be","passed","the","integer","index","of","that","widget",".","radius",":","float",",","optional","The","radius","of","the","sphere",".","theta_resolution",":","int",",","optional","Set","the","number","of","points","in","the","longitude","direction",".","phi_resolution",":","int",",","optional","Set","the","number","of","points","in","the","latitude","direction",".","color",":","ColorLike",",","optional","The","color","of","the","sphere","'s","surface",".","If","multiple","centers","are","passed",",","then","this","must","be","a","list","of","colors",".","Each","color","is","either","a","string",",","rgb","list",",","or","hex","color","string",".","For","example",":","*","``","color='white","'","``","*","``","color=","'","w","'","``","*","``","color=","[","1.0",",","1.0",",","1.0","]","``","*","``","color=","'","#","FFFFFF","'","``","style",":","str",",","optional","Representation","style",":","``","'surface","'","``","or","``","'wireframe","'","``",".","selected_color",":","ColorLike",",","optional","Color","of","the","widget","when","selected","during","interaction",".","indices",":","sequence","[","int","]",",","optional","Indices","to","assign","the","sphere","widgets",".","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",".","interaction_event",":","vtk.vtkCommand.EventIds",",","optional","The","VTK","interaction","event","to","use","for","triggering","the","callback",".","Returns","--","--","--","-","vtk.vtkSphereWidget","The","sphere","widget","."]
code: def add_sphere_widget(
      self,
      callback,
      center=(0, 0, 0),
      radius=0.5,
      theta_resolution=30,
      phi_resolution=30,
      color=None,
      style="surface",
      selected_color="pink",
      indices=None,
      pass_widget=False,
      test_callback=True,
      interaction_event=_vtk.vtkCommand.EndInteractionEvent,
  ):
      """Add one or many sphere widgets to a scene.
  
      Use a sphere widget to control a vertex location.
  
      Parameters
      ----------
      callback : callable
          The function to call back when the widget is modified. It takes a
          single argument: the center of the sphere as an XYZ coordinate (a
          3-length sequence), unless ``pass_widget=True``, in which case the
          callback must accept the widget object as the second parameter.  If
          multiple centers are passed in the ``center`` parameter, the
          callback must also accept an index of that widget.
  
      center : sequence[float], optional
          The cartesian coordinate of the sphere's center when placing it in
          the scene. If more than one location is passed, then that many
          widgets will be added and the callback will also be passed the
          integer index of that widget.
  
      radius : float, optional
          The radius of the sphere.
  
      theta_resolution : int, optional
          Set the number of points in the longitude direction.
  
      phi_resolution : int, optional
          Set the number of points in the latitude direction.
  
      color : ColorLike, optional
          The color of the sphere's surface.  If multiple centers
          are passed, then this must be a list of colors.  Each
          color is either a string, rgb list, or hex color string.
          For example:
  
          * ``color='white'``
          * ``color='w'``
          * ``color=[1.0, 1.0, 1.0]``
          * ``color='#FFFFFF'``
  
      style : str, optional
          Representation style: ``'surface'`` or ``'wireframe'``.
  
      selected_color : ColorLike, optional
          Color of the widget when selected during interaction.
  
      indices : sequence[int], optional
          Indices to assign the sphere widgets.
  
      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.
  
      interaction_event : vtk.vtkCommand.EventIds, optional
          The VTK interaction event to use for triggering the callback.
  
      Returns
      -------
      vtk.vtkSphereWidget
          The sphere widget.
  
      """
      if color is None:
          color = pyvista.global_theme.color.float_rgb
      selected_color = Color(selected_color)
  
      center = np.array(center)
      num = 1
      if center.ndim > 1:
          num = len(center)
  
      if isinstance(color, (list, tuple, np.ndarray)):
          if len(color) == num and not isinstance(color[0], float):
              colors = color
          else:
              colors = [color] * num
      else:
          colors = [color] * num
  
      def _the_callback(widget, _event):
          point = widget.GetCenter()
          index = widget.WIDGET_INDEX
          if callable(callback):
              if num > 1:
                  args = [point, index]
              else:
                  args = [point]
              if pass_widget:
                  args.append(widget)
              try_callback(callback, *args)
          return
  
      if indices is None:
          indices = list(range(num))
  
      for i in range(num):
          if center.ndim > 1:
              loc = center[i]
          else:
              loc = center
          sphere_widget = _vtk.vtkSphereWidget()
          sphere_widget.WIDGET_INDEX = indices[
              i
          ]  # Monkey patch the index
          if style in "wireframe":
              sphere_widget.SetRepresentationToWireframe()
          else:
              sphere_widget.SetRepresentationToSurface()
          sphere_widget.GetSphereProperty().SetColor(
              Color(colors[i]).float_rgb
          )
          sphere_widget.GetSelectedSphereProperty().SetColor(
              selected_color.float_rgb
          )
          sphere_widget.SetInteractor(self.iren.interactor)
          sphere_widget.SetCurrentRenderer(self.renderer)
          sphere_widget.SetRadius(radius)
          sphere_widget.SetCenter(loc)
          sphere_widget.SetThetaResolution(theta_resolution)
          sphere_widget.SetPhiResolution(phi_resolution)
          sphere_widget.Modified()
          sphere_widget.On()
          sphere_widget.AddObserver(interaction_event, _the_callback)
          self.sphere_widgets.append(sphere_widget)
  
      if test_callback is True:
          # Test call back in the last
          _the_callback(sphere_widget, None)
      if num > 1:
          return self.sphere_widgets
  
      return sphere_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 23 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_sphere_widget(callback, center, radius, theta_resolution, phi_resolution, color, style, selected_color, indices, pass_widget, test_callback, interaction_event) and returns: sphere_widget, self