class_docstr: An internal class to hold core picking related features.
class_docstr_tok: ["An","internal","class","to","hold","core","picking","related","features","."]
docstr: Enable picking at points under the cursor.
  
  Enable picking a point at the mouse location in the render
  view using the right mouse button. This point is saved to the
  ``.picked_point`` attribute on the plotter. Pass a callback
  that takes that point as an argument. The picked
  point can either be a point on the first intersecting mesh, or
  a point in the 3D window.
  
  The ``picker`` choice will help determine how the point picking
  is performed.
  
  Parameters
  ----------
  callback : callable, optional
      When input, calls this callable after a pick is made. The
      picked point is input as the first parameter to this
      callable.
  
  tolerance : float, tolerance: 0.025
      Specify tolerance for performing pick operation. Tolerance
      is specified as fraction of rendering window
      size. Rendering window size is measured across diagonal.
      This is only valid for some choices of ``picker``.
  
  left_clicking : bool, default: False
      When ``True``, points can be picked by clicking the left mouse
      button. Default is to use the right mouse button.
  
  picker : str | PickerType, optional
      Choice of VTK picker class type:
  
          * ``'hardware'``: Uses ``vtkHardwarePicker`` which is more
            performant for large geometries (default).
          * ``'cell'``: Uses ``vtkCellPicker``.
          * ``'point'``: Uses ``vtkPointPicker`` which will snap to
            points on the surface of the mesh.
          * ``'volume'``: Uses ``vtkVolumePicker``.
  
  show_message : bool | str, default: True
      Show the message about how to use the point picking
      tool. If this is a string, that will be the message shown.
  
  font_size : int, default: 18
      Sets the size of the message.
  
  color : ColorLike, default: "pink"
      The color of the selected mesh when shown.
  
  point_size : int, default: 10
      Size of picked points if ``show_point`` is ``True``.
  
  show_point : bool, default: True
      Show the picked point after clicking.
  
  use_picker : bool, default: False
      When ``True``, the callback will also be passed the picker.
  
  pickable_window : bool, default: False
      When ``True`` and the chosen picker supports it, points in the
      3D window are pickable.
  
  clear_on_no_selection : bool, default: True
      Clear the selections when no point is selected.
  
  **kwargs : dict, optional
      All remaining keyword arguments are used to control how
      the picked point is interactively displayed.
  
  Examples
  --------
  Enable point picking with a custom message.
  
  >>> import pyvista as pv
  >>> pl = pv.Plotter()
  >>> _ = pl.add_mesh(pv.Sphere())
  >>> _ = pl.add_mesh(pv.Cube(), pickable=False)
  >>> pl.enable_point_picking(show_message='Pick a point')
  
  See :ref:`point_picking_example` for a full example using this method.
docstr_tok: ["Enable","picking","at","points","under","the","cursor",".","Enable","picking","a","point","at","the","mouse","location","in","the","render","view","using","the","right","mouse","button",".","This","point","is","saved","to","the","``",".picked_point","``","attribute","on","the","plotter",".","Pass","a","callback","that","takes","that","point","as","an","argument",".","The","picked","point","can","either","be","a","point","on","the","first","intersecting","mesh",",","or","a","point","in","the","3D","window",".","The","``","picker","``","choice","will","help","determine","how","the","point","picking","is","performed",".","Parameters","--","--","--","--","--","callback",":","callable",",","optional","When","input",",","calls","this","callable","after","a","pick","is","made",".","The","picked","point","is","input","as","the","first","parameter","to","this","callable",".","tolerance",":","float",",","tolerance",":","0.025","Specify","tolerance","for","performing","pick","operation",".","Tolerance","is","specified","as","fraction","of","rendering","window","size",".","Rendering","window","size","is","measured","across","diagonal",".","This","is","only","valid","for","some","choices","of","``","picker","``",".","left_clicking",":","bool",",","default",":","False","When","``","True","``",",","points","can","be","picked","by","clicking","the","left","mouse","button",".","Default","is","to","use","the","right","mouse","button",".","picker",":","str","|","PickerType",",","optional","Choice","of","VTK","picker","class","type",":","*","``","'hardware","'","``",":","Uses","``","vtkHardwarePicker","``","which","is","more","performant","for","large","geometries","(","default",")",".","*","``","'cell","'","``",":","Uses","``","vtkCellPicker","``",".","*","``","'point","'","``",":","Uses","``","vtkPointPicker","``","which","will","snap","to","points","on","the","surface","of","the","mesh",".","*","``","'volume","'","``",":","Uses","``","vtkVolumePicker","``",".","show_message",":","bool","|","str",",","default",":","True","Show","the","message","about","how","to","use","the","point","picking","tool",".","If","this","is","a","string",",","that","will","be","the","message","shown",".","font_size",":","int",",","default",":","18","Sets","the","size","of","the","message",".","color",":","ColorLike",",","default",":","``","pink","''","The","color","of","the","selected","mesh","when","shown",".","point_size",":","int",",","default",":","10","Size","of","picked","points","if","``","show_point","``","is","``","True","``",".","show_point",":","bool",",","default",":","True","Show","the","picked","point","after","clicking",".","use_picker",":","bool",",","default",":","False","When","``","True","``",",","the","callback","will","also","be","passed","the","picker",".","pickable_window",":","bool",",","default",":","False","When","``","True","``","and","the","chosen","picker","supports","it",",","points","in","the","3D","window","are","pickable",".","clear_on_no_selection",":","bool",",","default",":","True","Clear","the","selections","when","no","point","is","selected",".","*","*","kwargs",":","dict",",","optional","All","remaining","keyword","arguments","are","used","to","control","how","the","picked","point","is","interactively","displayed",".","Examples","--","--","--","--","Enable","point","picking","with","a","custom","message",".",">",">",">","import","pyvista","as","pv",">",">",">","pl","=","pv.Plotter","(",")",">",">",">","_","=","pl.add_mesh","(","pv.Sphere","(",")",")",">",">",">","_","=","pl.add_mesh","(","pv.Cube","(",")",",","pickable=False",")",">",">",">","pl.enable_point_picking","(","show_message='Pick","a","point","'",")","See",":","ref",":","`","point_picking_example","`","for","a","full","example","using","this","method","."]
code: def enable_point_picking(
      self,
      callback=None,
      tolerance=0.025,
      left_clicking=False,
      picker=PickerType.POINT,
      show_message=True,
      font_size=18,
      color="pink",
      point_size=10,
      show_point=True,
      use_picker=False,
      pickable_window=False,
      clear_on_no_selection=True,
      **kwargs,
  ):
      """Enable picking at points under the cursor.
  
      Enable picking a point at the mouse location in the render
      view using the right mouse button. This point is saved to the
      ``.picked_point`` attribute on the plotter. Pass a callback
      that takes that point as an argument. The picked
      point can either be a point on the first intersecting mesh, or
      a point in the 3D window.
  
      The ``picker`` choice will help determine how the point picking
      is performed.
  
      Parameters
      ----------
      callback : callable, optional
          When input, calls this callable after a pick is made. The
          picked point is input as the first parameter to this
          callable.
  
      tolerance : float, tolerance: 0.025
          Specify tolerance for performing pick operation. Tolerance
          is specified as fraction of rendering window
          size. Rendering window size is measured across diagonal.
          This is only valid for some choices of ``picker``.
  
      left_clicking : bool, default: False
          When ``True``, points can be picked by clicking the left mouse
          button. Default is to use the right mouse button.
  
      picker : str | PickerType, optional
          Choice of VTK picker class type:
  
              * ``'hardware'``: Uses ``vtkHardwarePicker`` which is more
                performant for large geometries (default).
              * ``'cell'``: Uses ``vtkCellPicker``.
              * ``'point'``: Uses ``vtkPointPicker`` which will snap to
                points on the surface of the mesh.
              * ``'volume'``: Uses ``vtkVolumePicker``.
  
      show_message : bool | str, default: True
          Show the message about how to use the point picking
          tool. If this is a string, that will be the message shown.
  
      font_size : int, default: 18
          Sets the size of the message.
  
      color : ColorLike, default: "pink"
          The color of the selected mesh when shown.
  
      point_size : int, default: 10
          Size of picked points if ``show_point`` is ``True``.
  
      show_point : bool, default: True
          Show the picked point after clicking.
  
      use_picker : bool, default: False
          When ``True``, the callback will also be passed the picker.
  
      pickable_window : bool, default: False
          When ``True`` and the chosen picker supports it, points in the
          3D window are pickable.
  
      clear_on_no_selection : bool, default: True
          Clear the selections when no point is selected.
  
      **kwargs : dict, optional
          All remaining keyword arguments are used to control how
          the picked point is interactively displayed.
  
      Examples
      --------
      Enable point picking with a custom message.
  
      >>> import pyvista as pv
      >>> pl = pv.Plotter()
      >>> _ = pl.add_mesh(pv.Sphere())
      >>> _ = pl.add_mesh(pv.Cube(), pickable=False)
      >>> pl.enable_point_picking(show_message='Pick a point')
  
      See :ref:`point_picking_example` for a full example using this method.
  
      """
      self._validate_picker_not_in_use()
      if "use_mesh" in kwargs:
          warnings.warn(
              "`use_mesh` is deprecated. See `use_picker` instead.",
              PyVistaDeprecationWarning,
          )
          use_mesh = kwargs.pop("use_mesh")
      else:
          use_mesh = False
  
      self_ = weakref.ref(self)
  
      def _end_pick_event(picker, _event):
          if (
              not pickable_window
              and hasattr(picker, "GetDataSet")
              and picker.GetDataSet() is None
          ):
              # Clear the selection
              self._picked_point = None
              if clear_on_no_selection:
                  with self_().iren.poked_subplot():
                      self_()._clear_picking_representations()
              return
          with self_().iren.poked_subplot():
              point = np.array(picker.GetPickPosition())
              point /= self_().scale  # HACK: handle scale
              self_()._picked_point = point
              if show_point:
                  _kwargs = kwargs.copy()
                  self_().add_mesh(
                      self_().picked_point,
                      color=color,
                      point_size=point_size,
                      name=_kwargs.pop(
                          "name", PICKED_REPRESENTATION_NAMES["point"]
                      ),
                      pickable=_kwargs.pop("pickable", False),
                      reset_camera=_kwargs.pop("reset_camera", False),
                      **_kwargs,
                  )
              if callable(callback):
                  if use_picker:
                      _poked_context_callback(
                          self_(), callback, self.picked_point, picker
                      )
                  elif use_mesh:  # Lower priority
                      _poked_context_callback(
                          self_(),
                          callback,
                          picker.GetDataSet(),
                          picker.GetPointId(),
                      )
                  else:
                      _poked_context_callback(
                          self_(), callback, self.picked_point
                      )
  
      if (
          picker is not None
      ):  # If None, that means use already set picker
          self.iren.picker = picker
      if hasattr(self.iren.picker, "SetTolerance"):
          self.iren.picker.SetTolerance(tolerance)
      self.iren.add_pick_observer(_end_pick_event)
      self._init_click_picking_callback(left_clicking=left_clicking)
      self._picker_in_use = True
  
      # Now add text about cell-selection
      if show_message:
          if show_message is True:
              if left_clicking:
                  show_message = "Left-click"
              else:
                  show_message = "Right-click"
              show_message += " or press P to pick under the mouse"
          self._picking_text = self.add_text(
              str(show_message),
              font_size=font_size,
              name="_point_picking_message",
          )
  
imports: from functools import partial, wraps
  from typing import Tuple, cast
  import warnings
  import weakref
  import numpy
  import pyvista
  from pyvista.core.errors import PyVistaDeprecationWarning
  from pyvista.core.utilities.misc import try_callback
  from .None import _vtk
  from .composite_mapper import CompositePolyDataMapper
  from .errors import PyVistaPickingError
  from .opts import ElementType, PickerType
label_desc: Use image node_id 10 for calling the PickingInterface obj's underlying member method code with example usage: obj.enable_point_picking(callback, tolerance, left_clicking, picker, show_message, font_size, color, point_size, show_point, use_picker, pickable_window, clear_on_no_selection) without return types