Skip to content

Implement full 3D box clipping#30553

Draft
QuLogic wants to merge 8 commits into
matplotlib:mainfrom
QuLogic:clip3d
Draft

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

Conversation

@QuLogic
Copy link
Copy Markdown
Member

@QuLogic QuLogic commented Sep 12, 2025

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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

@QuLogic
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.
@QuLogic
Make path clipping a bit safer
6d5dd9a 
... by avoiding double pointers.
@QuLogic
MNT: Fix type of _finalize_polygon::closed_only
5ba391b 
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.)
@QuLogic
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.
@QuLogic
path: Simplify parts of clip_path_to_rect
b64f3d7 
Use `XY` type to shorten internals, and `agg::rect_d::normalize` to
shorten initialization.
@QuLogic
Implement a 3D version of the clipping algorithm
a55ad73
@QuLogic
Implement full clipping for Poly3DCollection
341809c
@QuLogic
Implement full clipping for Patch3D
2fda01e
@scottshambaugh
Copy link
Copy Markdown
Contributor

scottshambaugh commented Sep 15, 2025 •
edited
Loading

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()
image

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.

@QuLogic
Copy link
Copy Markdown
Member Author

QuLogic commented Sep 16, 2025

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.

@QuLogic
Copy link
Copy Markdown
Member Author

QuLogic commented Sep 18, 2025

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

status: needs rebase topic: mplot3d topic: path handling

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@QuLogic @scottshambaugh