Add find_cells_intersecting_line

[MatthewFlamm]

Overview

Closes #4398. This PR first fixes the description of find_cells_along_line to clarify that it is finding cells whose bounds intersect the line and not the cells themselves. The PR adds find_cells_intersecting_line to find cells that directly intersect the lines.

Details

I updated the examples to be better. The original example put the line in the (0, 0, 1) direction which should go through the vertex at the top of the sphere where many many cells converge together. It is better to use the (1, 0, 0) direction where it should only intersect 1 cell. The examples now highlight the difference between the methods where find_cells_along_line returns multiple cells, whereas find_cells_intersecting_line returns only 1 cell.

[MatthewFlamm]

cc @AsimAl-Sofi if you want to test this PR

[codecov]

Codecov Report

Merging #4399 (004c3c7) into main (3e9be97) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main    #4399   +/-   ##
=======================================
  Coverage   95.82%   95.82%           
=======================================
  Files          97       97           
  Lines       20874    20890   +16     
=======================================
+ Hits        20002    20018   +16     
  Misses        872      872           

[MatthewFlamm]

I followed the other method here, but I think it is probably better as ValueError. If so, we should change both which would be a small breaking change.

[akaszynski]

Agree that ValueError would be correct here. It's out of scope of this PR, but let's do it in a different PR and have it merged for 0.40.0

[adeak]

Well with the current wording ("length three tuple of floats") the type error is also correct. Which is just to say that we should probably reword it while we're at it.

[akaszynski]

We might consider reusing:

pyvista/pyvista/utilities/errors.py

Lines 414 to 421 in 461bb5e

	def check_valid_vector(point, name=''):
	"""Check if a vector contains three components."""
	if not isinstance(point, Iterable):
	raise TypeError(f'{name} must be a length three iterable of floats.')
	if len(point) != 3:
	if name == '':
	name = 'Vector'
	raise ValueError(f'{name} must be a length three iterable of floats.')

[akaszynski]

Solid LGTM. Thanks @MatthewFlamm.