class_docstr: An internal class to manage filters/algorithms for polydata datasets.
class_docstr_tok: ["An","internal","class","to","manage","filters\/algorithms","for","polydata","datasets","."]
docstr: Perform a single ray trace calculation.
  
  This requires a mesh and a line segment defined by an origin
  and end_point.
  
  Parameters
  ----------
  origin : sequence[float]
      Start of the line segment.
  
  end_point : sequence[float]
      End of the line segment.
  
  first_point : bool, default: False
      Returns intersection of first point only.
  
  plot : bool, default: False
      Whether to plot the ray trace results.
  
  off_screen : bool, optional
      Plots off screen when ``plot=True``.  Used for unit testing.
  
  Returns
  -------
  intersection_points : numpy.ndarray
      Location of the intersection points.  Empty array if no
      intersections.
  
  intersection_cells : numpy.ndarray
      Indices of the intersection cells.  Empty array if no
      intersections.
  
  Examples
  --------
  Compute the intersection between a ray from the origin to
  ``[1, 0, 0]`` and a sphere with radius 0.5 centered at the
  origin.
  
  >>> import pyvista as pv
  >>> sphere = pv.Sphere()
  >>> point, cell = sphere.ray_trace(
  ...     [0, 0, 0], [1, 0, 0], first_point=True
  ... )
  >>> f'Intersected at {point[0]:.3f} {point[1]:.3f} {point[2]:.3f}'
  'Intersected at 0.499 0.000 0.000'
  
  Show a plot of the ray trace.
  
  >>> point, cell = sphere.ray_trace([0, 0, 0], [1, 0, 0], plot=True)
  
  See :ref:`ray_trace_example` for more examples using this filter.
docstr_tok: ["Perform","a","single","ray","trace","calculation",".","This","requires","a","mesh","and","a","line","segment","defined","by","an","origin","and","end_point",".","Parameters","--","--","--","--","--","origin",":","sequence","[","float","]","Start","of","the","line","segment",".","end_point",":","sequence","[","float","]","End","of","the","line","segment",".","first_point",":","bool",",","default",":","False","Returns","intersection","of","first","point","only",".","plot",":","bool",",","default",":","False","Whether","to","plot","the","ray","trace","results",".","off_screen",":","bool",",","optional","Plots","off","screen","when","``","plot=True","``",".","Used","for","unit","testing",".","Returns","--","--","--","-","intersection_points",":","numpy.ndarray","Location","of","the","intersection","points",".","Empty","array","if","no","intersections",".","intersection_cells",":","numpy.ndarray","Indices","of","the","intersection","cells",".","Empty","array","if","no","intersections",".","Examples","--","--","--","--","Compute","the","intersection","between","a","ray","from","the","origin","to","``","[","1",",","0",",","0","]","``","and","a","sphere","with","radius","0.5","centered","at","the","origin",".",">",">",">","import","pyvista","as","pv",">",">",">","sphere","=","pv.Sphere","(",")",">",">",">","point",",","cell","=","sphere.ray_trace","(","...","[","0",",","0",",","0","]",",","[","1",",","0",",","0","]",",","first_point=True","...",")",">",">",">","f'Intersected","at","{","point","[","0","]",":",".3f","}","{","point","[","1","]",":",".3f","}","{","point","[","2","]",":",".3f","}","'","'Intersected","at","0.499","0.000","0.000'","Show","a","plot","of","the","ray","trace",".",">",">",">","point",",","cell","=","sphere.ray_trace","(","[","0",",","0",",","0","]",",","[","1",",","0",",","0","]",",","plot=True",")","See",":","ref",":","`","ray_trace_example","`","for","more","examples","using","this","filter","."]
code: def ray_trace(
      self,
      origin,
      end_point,
      first_point=False,
      plot=False,
      off_screen=None,
  ):
      """Perform a single ray trace calculation.
  
      This requires a mesh and a line segment defined by an origin
      and end_point.
  
      Parameters
      ----------
      origin : sequence[float]
          Start of the line segment.
  
      end_point : sequence[float]
          End of the line segment.
  
      first_point : bool, default: False
          Returns intersection of first point only.
  
      plot : bool, default: False
          Whether to plot the ray trace results.
  
      off_screen : bool, optional
          Plots off screen when ``plot=True``.  Used for unit testing.
  
      Returns
      -------
      intersection_points : numpy.ndarray
          Location of the intersection points.  Empty array if no
          intersections.
  
      intersection_cells : numpy.ndarray
          Indices of the intersection cells.  Empty array if no
          intersections.
  
      Examples
      --------
      Compute the intersection between a ray from the origin to
      ``[1, 0, 0]`` and a sphere with radius 0.5 centered at the
      origin.
  
      >>> import pyvista as pv
      >>> sphere = pv.Sphere()
      >>> point, cell = sphere.ray_trace(
      ...     [0, 0, 0], [1, 0, 0], first_point=True
      ... )
      >>> f'Intersected at {point[0]:.3f} {point[1]:.3f} {point[2]:.3f}'
      'Intersected at 0.499 0.000 0.000'
  
      Show a plot of the ray trace.
  
      >>> point, cell = sphere.ray_trace([0, 0, 0], [1, 0, 0], plot=True)
  
      See :ref:`ray_trace_example` for more examples using this filter.
  
      """
      points = _vtk.vtkPoints()
      cell_ids = _vtk.vtkIdList()
      self.obbTree.IntersectWithLine(
          np.array(origin), np.array(end_point), points, cell_ids
      )
  
      intersection_points = _vtk.vtk_to_numpy(points.GetData())
      has_intersection = intersection_points.shape[0] >= 1
      if first_point and has_intersection:
          intersection_points = intersection_points[0]
  
      intersection_cells = []
      if has_intersection:
          if first_point:
              ncells = 1
          else:
              ncells = cell_ids.GetNumberOfIds()
          for i in range(ncells):
              intersection_cells.append(cell_ids.GetId(i))
      intersection_cells = np.array(intersection_cells)
  
      if plot:
          plotter = pyvista.Plotter(off_screen=off_screen)
          plotter.add_mesh(self, label="Test Mesh")
          segment = np.array([origin, end_point])
          plotter.add_lines(segment, "b", label="Ray Segment")
          plotter.add_mesh(
              intersection_points,
              "r",
              point_size=10,
              label="Intersection Points",
          )
          plotter.add_legend()
          plotter.add_axes()
          plotter.show()
  
      return intersection_points, intersection_cells
  
imports: import collections.abc
  import warnings
  import numpy
  import pyvista
  from pyvista.core import _vtk_core
  from pyvista.core.errors import MissingDataError, NotAllTrianglesError, PyVistaFutureWarning, VTKVersionError
  from pyvista.core.filters import _get_output, _update_alg
  from pyvista.core.filters.data_set import DataSetFilters
  from pyvista.core.utilities.arrays import FieldAssociation, get_array, get_array_association, set_default_active_scalars, vtk_id_list_to_array
  from pyvista.core.utilities.geometric_objects import NORMALS
  from pyvista.core.utilities.helpers import generate_plane, wrap
  from pyvista.core.utilities.misc import abstract_class, assert_empty_kwargs
label_desc: Use image node_id 27 for calling the PolyDataFilters obj's underlying member method code with example usage: obj.ray_trace(origin, end_point, first_point, plot, off_screen) and returns: intersection_points,  intersection_cells