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: Interactively measure distance with a distance widget.
  
  Creates an overlay documenting the selected line and total
  distance between two mouse left-click interactions.
  
  The measurement overlay stays on the rendering until the
  widget is deleted. Only one measurement can be added by each
  widget instance.
  
  Parameters
  ----------
  callback : Callable[[Tuple[float, float, float], [Tuple[float, float, float], int], float]
      The method called every time the widget calculates a
      distance measurement. This callback receives the start
      point and end point as cartesian coordinate tuples
      and the calculated distance between the two points.
  
  color : ColorLike, optional
      The color of the measurement widget.
  
  Returns
  -------
  vtk.vtkDistanceWidget
      The newly created distance widget.
docstr_tok: ["Interactively","measure","distance","with","a","distance","widget",".","Creates","an","overlay","documenting","the","selected","line","and","total","distance","between","two","mouse","left-click","interactions",".","The","measurement","overlay","stays","on","the","rendering","until","the","widget","is","deleted",".","Only","one","measurement","can","be","added","by","each","widget","instance",".","Parameters","--","--","--","--","--","callback",":","Callable","[","[","Tuple","[","float",",","float",",","float","]",",","[","Tuple","[","float",",","float",",","float","]",",","int","]",",","float","]","The","method","called","every","time","the","widget","calculates","a","distance","measurement",".","This","callback","receives","the","start","point","and","end","point","as","cartesian","coordinate","tuples","and","the","calculated","distance","between","the","two","points",".","color",":","ColorLike",",","optional","The","color","of","the","measurement","widget",".","Returns","--","--","--","-","vtk.vtkDistanceWidget","The","newly","created","distance","widget","."]
code: def add_measurement_widget(
      self,
      callback=None,
      color=None,
  ):
      """Interactively measure distance with a distance widget.
  
      Creates an overlay documenting the selected line and total
      distance between two mouse left-click interactions.
  
      The measurement overlay stays on the rendering until the
      widget is deleted. Only one measurement can be added by each
      widget instance.
  
      Parameters
      ----------
      callback : Callable[[Tuple[float, float, float], [Tuple[float, float, float], int], float]
          The method called every time the widget calculates a
          distance measurement. This callback receives the start
          point and end point as cartesian coordinate tuples
          and the calculated distance between the two points.
  
      color : ColorLike, optional
          The color of the measurement widget.
  
      Returns
      -------
      vtk.vtkDistanceWidget
          The newly created distance widget.
  
      """
      if self.iren is None:
          raise RuntimeError("Cannot add a widget to a closed plotter.")
  
      if color is None:
          color = pyvista.global_theme.font.color.float_rgb
      color = Color(color)
  
      compute = lambda a, b: np.sqrt(
          np.sum((np.array(b) - np.array(a)) ** 2)
      )
  
      handle = _vtk.vtkPointHandleRepresentation3D()
      representation = _vtk.vtkDistanceRepresentation3D()
      representation.SetHandleRepresentation(handle)
      widget = _vtk.vtkDistanceWidget()
      widget.SetInteractor(self.iren.interactor)
      widget.SetRepresentation(representation)
  
      handle.GetProperty().SetColor(*color.float_rgb)
      representation.GetLabelProperty().SetColor(*color.float_rgb)
      representation.GetLineProperty().SetColor(*color.float_rgb)
  
      self.iren.picker = PickerType.POINT
  
      def place_point(*_):  # numpydoc ignore=GL08
          p1 = [0, 0, 0]
          p2 = [0, 0, 0]
          representation.GetPoint1DisplayPosition(p1)
          representation.GetPoint2DisplayPosition(p2)
          if self.iren.picker.Pick(p1, self.renderer):
              pos1 = self.iren.picker.GetPickPosition()
              representation.GetPoint1Representation().SetWorldPosition(
                  pos1
              )
          if self.iren.picker.Pick(p2, self.renderer):
              pos2 = self.iren.picker.GetPickPosition()
              representation.GetPoint2Representation().SetWorldPosition(
                  pos2
              )
          representation.BuildRepresentation()
  
          a = (
              representation.GetPoint1Representation().GetWorldPosition()
          )
          b = (
              representation.GetPoint2Representation().GetWorldPosition()
          )
          if callable(callback):
              try_callback(callback, a, b, compute(a, b))
          return
  
      widget.AddObserver(
          _vtk.vtkCommand.EndInteractionEvent, place_point
      )
  
      widget.On()
      self.distance_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 21 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_measurement_widget(callback, color) and returns: widget