Implement full 3D box clipping by QuLogic · Pull Request #30553 · matplotlib/matplotlib · GitHub

PR summary

Based on @scottshambaugh's comment, I took the existing 2D clipping algorithm and extended it to 3D. That turned out to be quite straightforward as it already worked on each direction independently. Most of the work was actually with regards to the plumbing to get things in and out. Then I implemented it for Poly3DCollection and Patch3D.

There are still a few things to finish this:

Poly3DCollection supports masking on the input, both from the original input and also to allow combining ragged input into a single array for quicker processing. I have not tested either, and don't expect them to work properly.
The 2D code drops any empty polygons after clipping. In 3D, this breaks depth shading since the order is broken. Instead of trying to track this change through clipping, it's probably easiest just to keep the empty polygons, but I have not tested it out.
This is still under the axlim_clip flag; I don't know if we just want to enable this all the time and/or deprecate that option.
Probably could warrant an API/what's new note.

Using the example from #8902 without clipping, the bars are quite misleading, as it seems like they are in a completely different spot initially compared to when looking at them edgewise.

Screencast.From.2025-09-12.05-24-46.mp4

whereas with clipping here, we get something that isn't so weird:

Screencast.From.2025-09-12.05-25-33.mp4

This is based on #30208.

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

... by replacing double pointers by fixed-size `std::array`, or a return `tuple`. With gcc (and optimization enabled?), this has no effect on code size, but gives compile-time (and better runtime) checks that there are no out-of-bounds access.

... by avoiding double pointers.

It is `bool` for the Python wrapper, while internally `int`, but can be `bool` consistently. Also mark it as `inline` since it's used in a template and the compiler warns about a possible ODR violation (which isn't a problem since it's only used in one file.)

By using the existing `XY` type to replace x/y pairs, and taking advantage of struct methods.

Use `XY` type to shorten internals, and `agg::rect_d::normalize` to shorten initialization.

I'll wait for this to come out of draft to do a thorough review, but I played around with the poly clipping and it works really well - pretty excited to see this go in! A somewhat pathological "C" shaped polygon didn't show any issues.

import matplotlib.pyplot as plt
import numpy as np
from mpl_toolkits.mplot3d.art3d import Poly3DCollection

fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
ys = [0, 2, 2, 0, 0, 1, 1, 0, 0]
zs = [0, 0, 3, 3, 2, 2, 1, 1, 0]
xs = np.ones(len(ys))
verts = np.array(list(zip(xs, ys, zs)))

poly1 = Poly3DCollection([verts], alpha=.5, color='C1', axlim_clip=True)
poly2 = Poly3DCollection([verts], alpha=.5, color='C2', axlim_clip=False)
ax.add_collection3d(poly1)
ax.add_collection3d(poly2)

plt.show()

Would it be difficult to extend this to Line3D as well?

This is still under the axlim_clip flag; I don't know if we just want to enable this all the time and/or deprecate that option.

I think "show all the data you can" is probably a better maxim for the default, but could be convinced otherwise.

Probably could warrant an API/what's new note.

Yeah, I think this is a pretty decently large change in behavior that should be highlighted.

Would it be difficult to extend this to Line3D as well?

If I'm not mistaken, 2D line clipping uses a different algorithm:

matplotlib/src/path_converters.h

Lines 322 to 520 in 5b38f50

    
           /************************************************************ 
        
            PathClipper uses the Liang-Barsky line clipping algorithm (as 
        
            implemented in Agg) to clip the path to a given rectangle.  Lines 
        
            will never extend outside of the rectangle.  Curve segments are not 
        
            clipped, but are always included in their entirety. 
        
            */ 
        
           template <class VertexSource> 
        
           class PathClipper : public EmbeddedQueue<3> 
        
           { 
        
               VertexSource *m_source; 
        
               bool m_do_clipping; 
        
               agg::rect_base<double> m_cliprect; 
        
               double m_lastX; 
        
               double m_lastY; 
        
               bool m_moveto; 
        
               double m_initX; 
        
               double m_initY; 
        
               bool m_has_init; 
        
               bool m_was_clipped; 
        
             public: 
        
               PathClipper(VertexSource &source, bool do_clipping, double width, double height) 
        
                   : m_source(&source), 
        
                     m_do_clipping(do_clipping), 
        
                     m_cliprect(-1.0, -1.0, width + 1.0, height + 1.0), 
        
                     m_lastX(nan("")), 
        
                     m_lastY(nan("")), 
        
                     m_moveto(true), 
        
                     m_initX(nan("")), 
        
                     m_initY(nan("")), 
        
                     m_has_init(false), 
        
                     m_was_clipped(false) 
        
               { 
        
                   // empty 
        
               } 
        
               PathClipper(VertexSource &source, bool do_clipping, const agg::rect_base<double> &rect) 
        
                   : m_source(&source), 
        
                     m_do_clipping(do_clipping), 
        
                     m_cliprect(rect), 
        
                     m_lastX(nan("")), 
        
                     m_lastY(nan("")), 
        
                     m_moveto(true), 
        
                     m_initX(nan("")), 
        
                     m_initY(nan("")), 
        
                     m_has_init(false), 
        
                     m_was_clipped(false) 
        
               { 
        
                   m_cliprect.x1 -= 1.0; 
        
                   m_cliprect.y1 -= 1.0; 
        
                   m_cliprect.x2 += 1.0; 
        
                   m_cliprect.y2 += 1.0; 
        
               } 
        
               inline void rewind(unsigned path_id) 
        
               { 
        
                   m_has_init = false; 
        
                   m_was_clipped = false; 
        
                   m_moveto = true; 
        
                   m_source->rewind(path_id); 
        
               } 
        
               int draw_clipped_line(double x0, double y0, double x1, double y1, 
        
                                     bool closed=false) 
        
               { 
        
                   unsigned moved = agg::clip_line_segment(&x0, &y0, &x1, &y1, m_cliprect); 
        
                   // moved >= 4 - Fully clipped 
        
                   // moved & 1 != 0 - First point has been moved 
        
                   // moved & 2 != 0 - Second point has been moved 
        
                   m_was_clipped = m_was_clipped || (moved != 0); 
        
                   if (moved < 4) { 
        
                       if (moved & 1 || m_moveto) { 
        
                           queue_push(agg::path_cmd_move_to, x0, y0); 
        
                       } 
        
                       queue_push(agg::path_cmd_line_to, x1, y1); 
        
                       if (closed && !m_was_clipped) { 
        
                           // Close the path only if the end point hasn't moved. 
        
                           queue_push(agg::path_cmd_end_poly | agg::path_flags_close, 
        
                                      x1, y1); 
        
                       } 
        
                       m_moveto = false; 
        
                       return 1; 
        
                   } 
        
                   return 0; 
        
               } 
        
               unsigned vertex(double *x, double *y) 
        
               { 
        
                   unsigned code; 
        
                   bool emit_moveto = false; 
        
                   if (!m_do_clipping) { 
        
                       // If not doing any clipping, just pass along the vertices verbatim 
        
                       return m_source->vertex(x, y); 
        
                   } 
        
                   /* This is the slow path where we actually do clipping */ 
        
                   if (queue_pop(&code, x, y)) { 
        
                       return code; 
        
                   } 
        
                   while ((code = m_source->vertex(x, y)) != agg::path_cmd_stop) { 
        
                       emit_moveto = false; 
        
                       switch (code) { 
        
                       case (agg::path_cmd_end_poly | agg::path_flags_close): 
        
                           if (m_has_init) { 
        
                               // Queue the line from last point to the initial point, and 
        
                               // if never clipped, add a close code. 
        
                               draw_clipped_line(m_lastX, m_lastY, m_initX, m_initY, 
        
                                                 true); 
        
                           } else { 
        
                               // An empty path that is immediately closed. 
        
                               queue_push( 
        
                                   agg::path_cmd_end_poly | agg::path_flags_close, 
        
                                   m_lastX, m_lastY); 
        
                           } 
        
                           // If paths were not clipped, then the above code queued 
        
                           // something, and we should exit the loop. Otherwise, continue 
        
                           // to the next point, as there may be a new subpath. 
        
                           if (queue_nonempty()) { 
        
                               goto exit_loop; 
        
                           } 
        
                           break; 
        
                       case agg::path_cmd_move_to: 
        
                           // was the last command a moveto (and we have 
        
                           // seen at least one command ? 
        
                           // if so, shove it in the queue if in clip box 
        
                           if (m_moveto && m_has_init && 
        
                               m_lastX >= m_cliprect.x1 && 
        
                               m_lastX <= m_cliprect.x2 && 
        
                               m_lastY >= m_cliprect.y1 && 
        
                               m_lastY <= m_cliprect.y2) { 
        
                               // push the last moveto onto the queue 
        
                               queue_push(agg::path_cmd_move_to, m_lastX, m_lastY); 
        
                               // flag that we need to emit it 
        
                               emit_moveto = true; 
        
                           } 
        
                           // update the internal state for this moveto 
        
                           m_initX = m_lastX = *x; 
        
                           m_initY = m_lastY = *y; 
        
                           m_has_init = true; 
        
                           m_moveto = true; 
        
                           m_was_clipped = false; 
        
                           // if the last command was moveto exit the loop to emit the code 
        
                           if (emit_moveto) { 
        
                               goto exit_loop; 
        
                           } 
        
                           // else, break and get the next point 
        
                           break; 
        
                       case agg::path_cmd_line_to: 
        
                           if (draw_clipped_line(m_lastX, m_lastY, *x, *y)) { 
        
                               m_lastX = *x; 
        
                               m_lastY = *y; 
        
                               goto exit_loop; 
        
                           } 
        
                           m_lastX = *x; 
        
                           m_lastY = *y; 
        
                           break; 
        
                       default: 
        
                           if (m_moveto) { 
        
                               queue_push(agg::path_cmd_move_to, m_lastX, m_lastY); 
        
                               m_moveto = false; 
        
                           } 
        
                           queue_push(code, *x, *y); 
        
                           m_lastX = *x; 
        
                           m_lastY = *y; 
        
                           goto exit_loop; 
        
                       } 
        
                   } 
        
                   exit_loop: 
        
                       if (queue_pop(&code, x, y)) { 
        
                           return code; 
        
                       } 
        
                       if (m_moveto && m_has_init && 
        
                           m_lastX >= m_cliprect.x1 && 
        
                           m_lastX <= m_cliprect.x2 && 
        
                           m_lastY >= m_cliprect.y1 && 
        
                           m_lastY <= m_cliprect.y2) { 
        
                           *x = m_lastX; 
        
                           *y = m_lastY; 
        
                           m_moveto = false; 
        
                           return agg::path_cmd_move_to; 
        
                       } 
        
                       return agg::path_cmd_stop; 
        
               } 
        
           };

This makes some sense as it doesn't need to preserve polygon fills, but I'm not sure if the one implemented here can be "downgraded" to simple lines or whether I'd have to implement that one as well.

So I went looking through the 2D code again, and surprisingly, nothing uses the Sutherland-Hodgman algorithm. The C++ code is called by Path.clip_to_bbox but the only things that use it are tests. All the 2D code uses the Liang-Barsky clipping algorithm in PathClipper that's really implemented in Agg. I tend to find Agg code a bit more obtuse, but this one doesn't look too bad to copy, though it'll need to be adjusted to 3D as well.

QuLogic added 8 commits September 11, 2025 05:12

Make path-to-string conversion a little safer

2bdc786

... by replacing double pointers by fixed-size `std::array`, or a return `tuple`. With gcc (and optimization enabled?), this has no effect on code size, but gives compile-time (and better runtime) checks that there are no out-of-bounds access.

Make path clipping a bit safer

6d5dd9a

... by avoiding double pointers.

path: Simplify extent_limits implementation a bit

3f920bf

By using the existing `XY` type to replace x/y pairs, and taking advantage of struct methods.

path: Simplify parts of clip_path_to_rect

b64f3d7

Use `XY` type to shorten internals, and `agg::rect_d::normalize` to shorten initialization.

Implement a 3D version of the clipping algorithm

a55ad73

Implement full clipping for Poly3DCollection

341809c

Implement full clipping for Patch3D

2fda01e

QuLogic added the status: waiting for other PR label Sep 12, 2025

github-actions Bot added topic: mplot3d topic: path handling labels Sep 12, 2025

github-actions Bot added the status: needs rebase label Sep 18, 2025

scottshambaugh removed the status: waiting for other PR label Sep 18, 2025

scottshambaugh mentioned this pull request May 22, 2026

ENH: add geometric axlim clipping for 3D surfaces and line collections #31732

Closed

4 tasks done

Implement full 3D box clipping by QuLogic · Pull Request #30553 · matplotlib/matplotlib · GitHub

Repository navigation

Implement full 3D box clipping - #30553

Implement full 3D box clipping#30553
QuLogic wants to merge 8 commits into
matplotlib:mainfrom
QuLogic:clip3d

QuLogic commented Sep 12, 2025

Uh oh!

scottshambaugh commented Sep 15, 2025 •
edited
Loading

Uh oh!

Uh oh!

QuLogic commented Sep 16, 2025

Uh oh!

QuLogic commented Sep 18, 2025

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Implement full 3D box clipping by QuLogic · Pull Request #30553 · matplotlib/matplotlib · GitHub

Repository navigation

Implement full 3D box clipping - #30553

Implement full 3D box clipping#30553QuLogic wants to merge 8 commits intomatplotlib:mainmatplotlib/matplotlib:mainfrom QuLogic:clip3dQuLogic/matplotlib:clip3dCopy head branch name to clipboard

Conversation

QuLogic commented Sep 12, 2025

PR summary

PR checklist

Uh oh!

scottshambaugh commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

QuLogic commented Sep 16, 2025

Uh oh!

QuLogic commented Sep 18, 2025

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Implement full 3D box clipping#30553
QuLogic wants to merge 8 commits into
matplotlib:mainfrom
QuLogic:clip3d

scottshambaugh commented Sep 15, 2025 •
edited
Loading