class_docstr: Internal class to contain picking utilities.
class_docstr_tok: ["Internal","class","to","contain","picking","utilities","."]
docstr: Enable composite block picking.
  
  Use this picker to return the index of a DataSet when using composite
  dataset like :class:`pyvista.MultiBlock` and pass it to a callback.
  
  Parameters
  ----------
  callback : callable, optional
      When input, this picker calls this callable after a selection is
      made. The composite index is passed to ``callback`` as the first
      argument and the dataset as the second argument.
  
  side : str, default: "left"
      The mouse button to track (either ``'left'`` or ``'right'``).
      Also accepts ``'r'`` or ``'l'``.
  
  Notes
  -----
  The picked block index can be accessed from :attr:`picked_block_index
  <pyvista.Plotter.picked_block_index>` attribute.
  
  Examples
  --------
  Enable block picking with a multiblock dataset. Left clicking will turn
  blocks blue while right picking will turn the block back to the default
  color.
  
  >>> import pyvista as pv
  >>> multiblock = pv.MultiBlock(
  ...     [pv.Cube(), pv.Sphere(center=(0, 0, 1))]
  ... )
  >>> pl = pv.Plotter()
  >>> actor, mapper = pl.add_composite(multiblock)
  >>> def turn_blue(index, dataset):
  ...     mapper.block_attr[index].color = 'blue'
  ...
  >>> pl.enable_block_picking(callback=turn_blue, side='left')
  >>> def clear_color(index, dataset):
  ...     mapper.block_attr[index].color = None
  ...
  >>> pl.enable_block_picking(callback=clear_color, side='right')
  >>> pl.show()
docstr_tok: ["Enable","composite","block","picking",".","Use","this","picker","to","return","the","index","of","a","DataSet","when","using","composite","dataset","like",":","class",":","`","pyvista.MultiBlock","`","and","pass","it","to","a","callback",".","Parameters","--","--","--","--","--","callback",":","callable",",","optional","When","input",",","this","picker","calls","this","callable","after","a","selection","is","made",".","The","composite","index","is","passed","to","``","callback","``","as","the","first","argument","and","the","dataset","as","the","second","argument",".","side",":","str",",","default",":","``","left","''","The","mouse","button","to","track","(","either","``","'left","'","``","or","``","'right","'","``",")",".","Also","accepts","``","'","r","'","``","or","``","'","l","'","``",".","Notes","--","--","-","The","picked","block","index","can","be","accessed","from",":","attr",":","`","picked_block_index","<","pyvista.Plotter.picked_block_index",">","`","attribute",".","Examples","--","--","--","--","Enable","block","picking","with","a","multiblock","dataset",".","Left","clicking","will","turn","blocks","blue","while","right","picking","will","turn","the","block","back","to","the","default","color",".",">",">",">","import","pyvista","as","pv",">",">",">","multiblock","=","pv.MultiBlock","(","...","[","pv.Cube","(",")",",","pv.Sphere","(","center=","(","0",",","0",",","1",")",")","]","...",")",">",">",">","pl","=","pv.Plotter","(",")",">",">",">","actor",",","mapper","=","pl.add_composite","(","multiblock",")",">",">",">","def","turn_blue","(","index",",","dataset",")",":","...","mapper.block_attr","[","index","]",".color","=","'blue'","...",">",">",">","pl.enable_block_picking","(","callback=turn_blue",",","side='left","'",")",">",">",">","def","clear_color","(","index",",","dataset",")",":","...","mapper.block_attr","[","index","]",".color","=","None","...",">",">",">","pl.enable_block_picking","(","callback=clear_color",",","side='right","'",")",">",">",">","pl.show","(",")"]
code: def enable_block_picking(self, callback=None, side="left"):
      """Enable composite block picking.
  
      Use this picker to return the index of a DataSet when using composite
      dataset like :class:`pyvista.MultiBlock` and pass it to a callback.
  
      Parameters
      ----------
      callback : callable, optional
          When input, this picker calls this callable after a selection is
          made. The composite index is passed to ``callback`` as the first
          argument and the dataset as the second argument.
  
      side : str, default: "left"
          The mouse button to track (either ``'left'`` or ``'right'``).
          Also accepts ``'r'`` or ``'l'``.
  
      Notes
      -----
      The picked block index can be accessed from :attr:`picked_block_index
      <pyvista.Plotter.picked_block_index>` attribute.
  
      Examples
      --------
      Enable block picking with a multiblock dataset. Left clicking will turn
      blocks blue while right picking will turn the block back to the default
      color.
  
      >>> import pyvista as pv
      >>> multiblock = pv.MultiBlock(
      ...     [pv.Cube(), pv.Sphere(center=(0, 0, 1))]
      ... )
      >>> pl = pv.Plotter()
      >>> actor, mapper = pl.add_composite(multiblock)
      >>> def turn_blue(index, dataset):
      ...     mapper.block_attr[index].color = 'blue'
      ...
      >>> pl.enable_block_picking(callback=turn_blue, side='left')
      >>> def clear_color(index, dataset):
      ...     mapper.block_attr[index].color = None
      ...
      >>> pl.enable_block_picking(callback=clear_color, side='right')
      >>> pl.show()
  
      """
      # use a weak reference to enable garbage collection
      renderer_ = weakref.ref(self.renderer)
      self_ = weakref.ref(self)
  
      sel_index = _vtk.vtkSelectionNode.COMPOSITE_INDEX()
      sel_prop = _vtk.vtkSelectionNode.PROP()
  
      def get_picked_block(*args, **kwargs):  # numpydoc ignore=PR01
          """Get the picked block and pass it to the user callback."""
          x, y = self.mouse_position
          selector = _vtk.vtkOpenGLHardwareSelector()
          selector.SetRenderer(renderer_())
          selector.SetArea(x, y, x, y)  # single pixel
          selection = selector.Select()
  
          for ii in range(selection.GetNumberOfNodes()):
              node = selection.GetNode(ii)
              if node is None:  # pragma: no cover
                  continue
              node_prop = node.GetProperties()
              self._picked_block_index = node_prop.Get(sel_index)
  
              # Safely return the dataset as it's possible a non pyvista
              # mapper was added
              mapper = node_prop.Get(sel_prop).GetMapper()
              if isinstance(mapper, CompositePolyDataMapper):
                  dataset = mapper.block_attr.get_block(
                      self._picked_block_index
                  )
              else:  # pragma: no cover
                  dataset = None
  
              if callable(callback):
                  _poked_context_callback(
                      self_(),
                      callback,
                      self._picked_block_index,
                      dataset,
                  )
  
      self.track_click_position(
          callback=get_picked_block, viewport=True, side=side
      )
  
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 14 for calling the PickingMethods obj's underlying member method code with example usage: obj.enable_block_picking(callback, side) without return types