[ENH] Implement dynamic clipping to axes limits for 3D plots #27349

scottshambaugh · 2023-11-20T05:35:54Z

PR summary

This PR introduces "dynamic clipping" of the data in 3D plots, such that data outside the axis limits is not shown. I did a deep dive into stackoverflow and found 12 separate questions asking for this sort of functionality (see that list in this comment).

All 3D plotting functions now support the axlim_clip keyword argument (default False), which when True will clip the data to the axes view limits, hiding all data outside those bounds. This clipping will be dynamically applied in real time while panning and zooming.

Please note that if one vertex of a line segment or 3D patch is clipped, the entire segment or patch will be hidden. Not being able to show partial lines or patches such that they are "smoothly" cut off at the boundaries of the view box is a limitation of the current renderer.

What's new and new gallery example image (I'm not in love with this example, but it'll do for now):

Video of the dynamic behavior, please excuse my sluggish machine:

2023-11-25.22-47-45-1.mp4

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 · 2023-11-27T18:54:48Z

Current test failures are due to minor pixel differences in the contours unrelated to this change, will keep tweaking until it passes.

scottshambaugh · 2023-11-27T20:41:31Z

TODO:

Fix marginal test failures
Check to see if this fixes mplot3d failed to clip bar charts if zlim is set. #8902
[n/a] Does it make more sense for patches on the boundary to just drop a vertex instead of the entire patch? -> defer to a new issue
Make a gallery example

QuLogic · 2023-11-28T23:36:43Z

Not being able to show partial lines or patches such that they are "smoothly" cut off at the boundaries of the view box is a limitation of the current renderer.

I don't think that's the case; we can definitely clip partial lines or patches to the Axes. Unless you mean the 3D renderer?

In that case, you would have to do some magic to calculate the clipping path of the Axes3D box with the artist in flattened 2D space, and apply it with set_clip_path. I'm not sure if that is worth it or not.

scottshambaugh · 2024-08-10T21:10:01Z

Thank you for the review @QuLogic! I believe all your comments are addressed now

scottshambaugh · 2024-08-10T22:24:11Z

The docs build error is unrelated:

The version switcher "https://output.circle-artifacts.com/output/job/29bcafd2-ffe3-4f64-ba51-f8cfa5bce2b5/artifacts/0/doc/build/html/_static/switcher.json" file cannot be read due to the following error:
HTTPError('404 Client Error: Not Found for url: https://output.circle-artifacts.com/output/job/29bcafd2-ffe3-4f64-ba51-f8cfa5bce2b5/artifacts/0/doc/build/html/_static/switcher.json')

scottshambaugh · 2024-08-23T22:31:24Z

I think that the docs error isn't actually generic, will investigate.

QuLogic · 2024-08-23T23:00:04Z

/home/circleci/project/lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:45: WARNING: py:meth reference target not found: matplotlib.collections._CollectionWithSizes.set_sizes [ref.meth]

The missing reference handler is now a bit more specific about these things, so if you've added/removed some lines in a docstring, you may have to update the line numbers in the json file to get it to skip again.

scottshambaugh · 2024-08-24T03:59:44Z

This is a rather confusing error. It traces back to ./doc/missing-references.json, which has the below section:

matplotlib/doc/missing-references.json

Lines 301 to 329 in b01462c

    
           "matplotlib.collections._CollectionWithSizes.set_sizes": [ 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.barbs:179", 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.broken_barh:84", 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_between:120", 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:120", 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:213", 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:182", 
        
             "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:215", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.AsteriskPolygonCollection.set:44", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.CircleCollection.set:44", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.PathCollection.set:44", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.PolyCollection.set:44", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.PolyQuadMesh.set:44", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.RegularPolyCollection.set:44", 
        
             "lib/matplotlib/collections.py:docstring of matplotlib.artist.StarPolygonCollection.set:44", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.barbs:179", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.broken_barh:84", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_between:120", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:120", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:213", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:182", 
        
             "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:215", 
        
             "lib/matplotlib/quiver.py:docstring of matplotlib.artist.Barbs.set:45", 
        
             "lib/matplotlib/quiver.py:docstring of matplotlib.artist.Quiver.set:45", 
        
             "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Barbs:212", 
        
             "lib/matplotlib/quiver.py:docstring of matplotlib.quiver.Quiver:251", 
        
             "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Path3DCollection.set:46", 
        
             "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:44" 
        
           ],

... but set_sizes is not in the art3d.py.Poly3DCollection docstrings so I'm not sure how to adjust the numbering. Any pointers?

I did add 3 lines to the __init__() docstring, so will try adding 3 to each of these lines.

   "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Path3DCollection.set:46", 
   "lib/mpl_toolkits/mplot3d/art3d.py:docstring of matplotlib.artist.Poly3DCollection.set:44"

QuLogic · 2024-08-24T04:17:19Z

It's not complaining about Poly3DCollection.__init__, but Poly3DCollection.set, which is one of the weird automatic substitutions of all possible keyword arguments, but I'm not sure which one changed. It's probably easiest to build locally with missing_references_write_json = True and see what lines changed.

Also, I just noticed this looking at other arguments, but axlim_clip should probably get a .. versionadded:: directive in its docs.

scottshambaugh · 2024-08-29T14:38:42Z

@QuLogic I'm not seeing this error on local docs builds. Do you know of another way to track it down?

Make axlim_clip flag keyword only Updates test image test image restore

Implement dynamic clipping to axes box for 3D plots Make axlim_clip flag keyword only Updates test image test image restore Implement dynamic clipping to axes box for 3D plots Make axlim_clip flag keyword only Updates test image test image restore Implement dynamic clipping to axes box for 3D plots Make axlim_clip flag keyword only Updates test image test image restore Code review comments on 3D axlim clipping Code review comments on 3D axlim clipping

scottshambaugh · 2024-08-31T16:30:31Z

Ok, fixed the issue with WARNING: py:meth reference target not found! For future reference, I deleted the two lines in ./doc/missing-references.json, pushed and waited for CI to throw the build error, and then re-added the lines with the errored line numbers.

The remaining docs error is an instance of #28744 and is unrelated.

@QuLogic I also added in .. versionadded:: 3.10 everywhere applicable, think this is good to go now.

nbfazel · 2024-10-05T22:51:31Z

Thank you for addressing this issue!

Which version of matplotlib will incorporate the fix? My current version is 3.9.2.

scottshambaugh · 2024-10-05T22:53:04Z

Hi @nbfazel, this will be out in the future 3.10 release.

nbfazel · 2024-10-06T02:33:24Z

Thank you!

scottshambaugh added New feature topic: mplot3d labels Nov 20, 2023

scottshambaugh force-pushed the 3d_dynamic_masking branch 7 times, most recently from 74a0810 to 6bed144 Compare November 26, 2023 05:47

scottshambaugh marked this pull request as ready for review November 26, 2023 05:49

scottshambaugh mentioned this pull request Nov 26, 2023

[Bug]: Issue with setting axis limits on 3D plots #25804

Closed

scottshambaugh force-pushed the 3d_dynamic_masking branch 2 times, most recently from 490ad58 to b73d8dc Compare November 26, 2023 06:08

scottshambaugh changed the title ~~DRAFT: Implement dynamic clipping to axes limits for 3D plots~~ [ENH] Implement dynamic clipping to axes limits for 3D plots Nov 26, 2023

scottshambaugh force-pushed the 3d_dynamic_masking branch 5 times, most recently from 674235d to faf74b6 Compare November 27, 2023 16:52

scottshambaugh marked this pull request as draft November 27, 2023 22:21

scottshambaugh force-pushed the 3d_dynamic_masking branch from faf74b6 to 7b9bb21 Compare November 28, 2023 01:42

scottshambaugh mentioned this pull request Nov 28, 2023

mplot3d failed to clip bar charts if zlim is set. #8902

Open

scottshambaugh force-pushed the 3d_dynamic_masking branch 2 times, most recently from b2a9978 to be117e7 Compare November 28, 2023 03:06

scottshambaugh marked this pull request as ready for review November 28, 2023 03:24

scottshambaugh force-pushed the 3d_dynamic_masking branch 2 times, most recently from 857252a to 8931e3a Compare November 28, 2023 05:18

github-actions bot removed the topic: collections and mappables label Aug 10, 2024

scottshambaugh force-pushed the 3d_dynamic_masking branch from bcb8a41 to 7506e37 Compare August 10, 2024 21:00

scottshambaugh force-pushed the 3d_dynamic_masking branch from 7506e37 to c52b9a0 Compare August 23, 2024 22:08

github-actions bot added the topic: transforms and scales label Aug 31, 2024

scottshambaugh added 3 commits August 31, 2024 08:52

Implement dynamic clipping to axes box for 3D plots

29d886e

Make axlim_clip flag keyword only Updates test image test image restore

Extend 3D axlim_clip to fill_between

d31c0d1

Code review comments on 3D axlim clipping

01fada9

scottshambaugh force-pushed the 3d_dynamic_masking branch from d1c41de to ee9f0a9 Compare August 31, 2024 14:54

github-actions bot removed the topic: transforms and scales label Aug 31, 2024

scottshambaugh force-pushed the 3d_dynamic_masking branch 4 times, most recently from 70c8344 to 439841a Compare August 31, 2024 15:44

scottshambaugh force-pushed the 3d_dynamic_masking branch from 439841a to cc5e8d5 Compare August 31, 2024 16:16

QuLogic merged commit 9dceafc into matplotlib:main Oct 2, 2024
41 of 43 checks passed

QuLogic mentioned this pull request Oct 10, 2024

matplotlib 3d interactive plot boundaries #24679

Open

scottshambaugh mentioned this pull request Oct 16, 2024

DOC / BUG: Better example for 3D axlim_clip argument #28984

Merged

2 tasks

moorepants mentioned this pull request Feb 4, 2025

Provide a way to clip lines outside the xyz limits tjstienstra/symmeplot#39

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ENH] Implement dynamic clipping to axes limits for 3D plots #27349

[ENH] Implement dynamic clipping to axes limits for 3D plots #27349

scottshambaugh commented Nov 20, 2023 •

edited

Loading

scottshambaugh commented Nov 27, 2023

scottshambaugh commented Nov 27, 2023 •

edited

Loading

QuLogic commented Nov 28, 2023

scottshambaugh commented Aug 10, 2024

scottshambaugh commented Aug 10, 2024

scottshambaugh commented Aug 23, 2024

QuLogic commented Aug 23, 2024

scottshambaugh commented Aug 24, 2024 •

edited

Loading

QuLogic commented Aug 24, 2024

scottshambaugh commented Aug 29, 2024

scottshambaugh commented Aug 31, 2024 •

edited

Loading

nbfazel commented Oct 5, 2024

scottshambaugh commented Oct 5, 2024

nbfazel commented Oct 6, 2024

[ENH] Implement dynamic clipping to axes limits for 3D plots #27349

[ENH] Implement dynamic clipping to axes limits for 3D plots #27349

Conversation

scottshambaugh commented Nov 20, 2023 • edited Loading

PR summary

PR checklist

scottshambaugh commented Nov 27, 2023

scottshambaugh commented Nov 27, 2023 • edited Loading

QuLogic commented Nov 28, 2023

scottshambaugh commented Aug 10, 2024

scottshambaugh commented Aug 10, 2024

scottshambaugh commented Aug 23, 2024

QuLogic commented Aug 23, 2024

scottshambaugh commented Aug 24, 2024 • edited Loading

QuLogic commented Aug 24, 2024

scottshambaugh commented Aug 29, 2024

scottshambaugh commented Aug 31, 2024 • edited Loading

nbfazel commented Oct 5, 2024

scottshambaugh commented Oct 5, 2024

nbfazel commented Oct 6, 2024

scottshambaugh commented Nov 20, 2023 •

edited

Loading

scottshambaugh commented Nov 27, 2023 •

edited

Loading

scottshambaugh commented Aug 24, 2024 •

edited

Loading

scottshambaugh commented Aug 31, 2024 •

edited

Loading