Picking overhaul

[banesullivan]

An internal overhaul to the picking interface to improve stability and useability with the following upgrades:

• Picking now works across subplots (see new "poked renderer" APIs)
• Right-click point picking is enabled by default
• A new "element" picking interface to select individual meshes, cells, faces, and edges (not recommended for points)
• Improved setter/getter for picker types

The redesign splits picking into two modes:

1. Point-based picking - use the cursor to pick a single point within the scene and use that point to perform an operation (e.g., select the mesh, cell, face, edge at that point)
2. Rectangle-based picking - use a selection rectangle on the viewport of the scene to make an area-based selection. This will build a frustum from the viewport area to use to select within the scene

All additional picking methods build on those two interfaces.

Backward compatibility is maintained for the most part (some callbacks did change). Specifically, I need to document what changed:

• use_mesh argument for point picking has been removed
• the passed values for some callbacks have changed

Resolves

Resolves #1012
Resolves #3564
Resolves #2578
Resolves #3027 - makes it easier to choose which picker to use
Resolves #3703
Resolves #3915
Resolves #4381
Resolves #2520

To do

• Minor implementation cleanups
• Verify all examples work as expected
• Complete and check documentation
• Improve picker setter/getter interface for tab-completion (not just hardcoded strings)
• Additional tests for coverage
• Provide examples for new capabilities

[codecov]

Codecov Report

Merging #4254 (9f9d7a5) into main (a2fb25e) will decrease coverage by 0.06%.
The diff coverage is 93.19%.

@@            Coverage Diff             @@
##             main    #4254      +/-   ##
==========================================
- Coverage   95.82%   95.77%   -0.06%     
==========================================
  Files         127      127              
  Lines       21105    21357     +252     
==========================================
+ Hits        20224    20454     +230     
- Misses        881      903      +22     

[akaszynski]

@banesullivan, don't take this as a complete review, but local testing (both unit and functional) of this branch on a closed source library that makes heavy use of the existing picking API works with no issues.

Full review will likely happen over the weekend, but don't wait for me if you'd like to merge sooner.

[banesullivan]

@pyvista/developers, ready for review if anyone has the bandwidth

[annehaley]

There are several new methods in plotting/picking.py and plotting/render_window_interactor that codecov is warning about.

[annehaley]

Suggested change

	* Face: pick a single face of a cell on the mesh
	* Edge: pick a single edge of a cell on the mesh
	* Point: pick a single point on the mesh
	* Point: pick a single point on the mesh (equivalent to :func:`enable_point_picking() <pyvista.Plotter.enable_point_picking>`.)

What about helper methods for enable_face_picking and enable_edge_picking?

[annehaley]

I also see a method enable_rectangle_picking, is there a reason it's left out of this group of examples?

[banesullivan]

This is actually a bit different than enable_point_picking. enable_point_picking picks points under the cursor: sometimes in free space, sometimes on a mesh, and if the right picker is chosen, sometimes it will snap to points. enable_element_picking specifically snaps to points on a mesh. This is why I left it out.

enable_rectangle_picking isn't meant to be used directly, so I don't want to advertise it. enable_rectangle_through_picking and enable_rectangle_visible_picking are the interfaces meant to be used for this type of picking. Further, rectangle selection picks under some sort of area or volume whereas these methods are point-based picking

[banesullivan]

Thanks for the review, @annehaley!

There are several new methods in plotting/picking.py and plotting/render_window_interactor that codecov is warning about.

This is a big PR, so things are falling through the cracks. Coverage stands at 93.19% for the diff alone (above my bar) but this is a big PR, so the missing ~7% is still significant. I'm unsure if I have the bandwidth to get us to 100% right now. I'll take another look at the missing coverage and see if anything seems problematic

[akaszynski]

Functional testing passes on my end, and integration testing with a closed source application that uses picking (on windows and linux) works. Made one minor commit as it would fail when running it interactively. Otherwise, LGTM.