[ENH]: fill_between extended to 3D

[scottshambaugh]

PR summary

Closes #28142

This extends the 2D fill_between method to 3D plots, and IMO works quite nicely. I’m finding it really powerful to generate surfaces easily. Inspired by @artmenlope's solution here: https://github.com/artmenlope/matplotlib-fill_between-in-3D/blob/master/FillBetween3d.py

Here's the what's new image and fillbetween3d gallery example:

Note that I moved the poly3d example https://matplotlib.org/3.9.0/gallery/mplot3d/polys3d.html to a new example fillunder3d, to use this new method. Then I made a new example for poly3d since adding 3D collections wasn't shown anywhere else afaik.

New fillunder3d example:

New poly3d example:

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

[scottshambaugh]

The white seams between the patches seems to be an instance of #1188, which I don't see a bug report for in 3D rendering. Is rather annoying but doesn't seem like there are easy fixes.

[scottshambaugh]

Note that I decided to not implement the "mode 2" idea in https://github.com/artmenlope/matplotlib-fill_between-in-3D/blob/master/FillBetween3d.py, which concatenates all the points and plots them as one polygon. I think the only benefit is getting rid of the white seams between the patches in the filled flat curves example, but it is degenerate in the general case, and this use case can be handled by users defining their own polygons such as in the new poly3d example.

For example, Mode 1 / Mode 2:

[scottshambaugh]

Here's the new plot types thumbnail showing a double helix:

[timhoffm]

Only doc suggestions.

[greglucas]

Requesting changes just so someone doesn't merge without my comment being addressed.

I think "mode 1" vs "mode 2" should be investigated here, and I'd like to see the new test case with the "mode 2" version as well to see if that applies the edge color to only the rim/boundary of the single fill_between region. Naively thinking about it that would be my preference for how to draw these, but I also haven't given it a ton of thought.

[greglucas]

I think this is in relation to your "mode 2" comment, but I would have naively expected each contiguous region to be a single polygon. Adding additional black edges in the new test case doesn't seem ideal and I would have expected all black "edge colors" to only be around the rim of the fill_between.

I would have expected something like: iterate over all "1" points adding those to the (N*2, 3) list of points for this specific region/poly, move down to "2" and iterate over those in reverse.

I think it will also be much more performant to only have a few polygons instead of one for each quad number of polygons.