Add force_zorder parameter

[kentcr]

Draft PR to add force_zorder parameter to Axes3D

[WeatherGod]

I am still torn about this change. On the one hand, I would rather see do_3d_projection() be the sole arbiter of an object's z-value (it can easily check the parent axes for the force_zorder flag). If do_3d_projection() is the only place where z-value is determined, then the end user has no need to do anything else for managing rendering during interactivity.

On the other hand, it does seem weird to me for a method that performs a projection calculation to return a value that didn't come from the projection computation.

[kentcr]

@WeatherGod
The Axes3D.draw() function already modifies the zorder relative to the grids, so do_3d_projection() is already not the sole arbiter. There are also multiple do_3d_projection() functions, so if you moved it inside those functions you'd be duplicating code and each would only be the sole arbiter for its class.

If the concern is that the underlying code could use some refactoring, I agree, but I don't think that needs to be addressed as part of this change so long as it's not making things worse, e.g. a bad API change or changes that make it harder to refactor going forward.

So my main concern is that some ultimate future API would be different than I'm proposing here, but I haven't noticed anyone mention that yet. Axes3D seems like a decent fit to me, but I'm not sure if there are any decent alternatives to consider.

[anntzer]

Milestoning as 3.2 to at least try to avoid this falling through the cracks into oblivion like #12744 (or perhaps #12744 is better, I didn't review them carefully).

[ImportanceOfBeingErnest]

This PR adds an attribute force_zorder to the Axes3D. It can be used as

ax = fig.add_subplot(111, projection="3d")
ax.force_zorder = True

or

ax = fig.add_subplot(111, projection="3d", force_zorder=True)

Here is something to show the effect of this PR. The examples are adapted from https://stackoverflow.com/questions/14824893/how-to-draw-intersecting-planes and #12620 (comment)

Complete code for reproduction

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


fig = plt.figure()
ax1 = fig.add_subplot(221, projection="3d")
ax2 = fig.add_subplot(222, projection="3d")
ax2.force_zorder = True

ax1.set_title("default", pad=15)
ax2.set_title("force_zorder = True", pad=15)

# create an orizontal plane
corners = [[0,0,0],[0,5,0],[5,5,0],[5,0,0]]
for ax  in [ax1,ax2]:
    
    tri = Poly3DCollection([corners], alpha=1, zorder=1)
    tri.set_color('w')
    tri.set_edgecolor('k')
    ax.add_collection3d(tri)
    
    # plot a vector
    ax.plot([2,2],[2,2],[0,4], c = 'r', zorder=2)
    
    # plot some points
    ax.scatter([3,3],[1,3],[1,3], c = 'r', zorder=10)
    
    ax.set_xlim([0, 5.0])
    ax.set_ylim([0, 5.0])
    ax.set_zlim([0, 2.5])


ax3 = fig.add_subplot(223, projection="3d")
ax4 = fig.add_subplot(224, projection="3d")
ax4.force_zorder = True

dim = 10

X, Y = np.meshgrid([-dim, dim], [-dim, dim])
Z = np.zeros((2, 2))

angle = .5
X2, Y2 = np.meshgrid([-dim, dim], [0, dim])
Z2 = Y2 * angle
X3, Y3 = np.meshgrid([-dim, dim], [-dim, 0])
Z3 = Y3 * angle

r = 7
M = 1000
th = np.linspace(0, 2 * np.pi, M)

x, y, z = r * np.cos(th),  r * np.sin(th), angle * r * np.sin(th)

for ax in [ax3,ax4]:
    ax.plot_surface(X2, Y3, Z3, color='blue', alpha=.5, linewidth=0, zorder=-1)
    
    ax.plot(x[y < 0], y[y < 0], z[y < 0], lw=5, linestyle='--', color='green',
            zorder=0)
    
    ax.plot_surface(X, Y, Z, color='red', alpha=.5, linewidth=0, zorder=1)
    
    ax.plot(r * np.sin(th), r * np.cos(th), np.zeros(M), lw=5, linestyle='--',
            color='k', zorder=2)
    
    ax.plot_surface(X2, Y2, Z2, color='blue', alpha=.5, linewidth=0, zorder=3)
    
    ax.plot(x[y > 0], y[y > 0], z[y > 0], lw=5, linestyle='--', color='green',
            zorder=4)
    ax.view_init(azim=-20, elev=20)
    ax.axis('off')

plt.show()

The solution here is pretty non-invasive. As long as you do not set the attribute to True, everything stays as it is.

Given that

(a) It seems no-short term (or even long-term) solution to 3d plotting order is in sight,
(b) this solves a whole class of long-standing problems,
(c) it does not prevent future improvements on the algorithms for automatic drawing order

I'm very much in favor of getting this in (potentially even into 3.2).

[ImportanceOfBeingErnest]

It was asked what needs to be done here:

• It needs to leave the draft status
• We need a test of this new functionality. (And all tests need to run successfully.)
• At the end this will need a "what's new entry" and possibly an example of how to use it.
• At least two people need to be convinced of this being the correct thing to do. I already said that this has my vote (once the above points are handled), but ideally @WeatherGod would be one of them because he raised a concern above.

[MuellerSeb]

Anything new on this? I would love to use this!

[aomader]

I second this. I run into this issue basically once a year, and this seems to be an easy fix for the common case (I would argue) to produce a static image rather than an interactive plot.

[ImportanceOfBeingErnest]

Everyone feel free to take this up and finish it.

[ceriottm]

This is really useful to make static 3D plots with the same "look and feel" as standard mpl graphics.
We often end up having to merge it manually on top of local installation to be able to use it.
Is there anything I can do to help getting it approved and merged?

[kentcr]

@ceriottm

Is there anything I can do to help getting it approved and merged?

@ImportanceOfBeingErnest kindly provided a list of todos (#14508 (comment)), but I ran into issues trying to get the test suite to work. It looks like the documentation surrounding it has been updated so maybe that's now addressed, but given that there isn't an accord that this is the "correct thing to do", it's an extremely low priority for me. That may be something you want to take a shot at though.

[ceriottm]

Thanks. I agree it is discouraging not to know if people who eventually can merge this are satisfied this is conceptually something they'll want to merge. To me, it is a pragmatic solution that will make it possible to do plots that are currently unfeasible with mpl, and the changes are so limited that the risk it has unintended consequences seems low.
Also, I am a bit intimidated by the overhead of gettign to grips with the workflow for contributing to mpl, so it'd be good to know that someone who is familiar with the "way it should be done" will be looking over my shoulder.

[dopplershift]

@WeatherGod, as the resident expert on the 3D support, have you developed any more firm feelings on this?

[WeatherGod]

I guess this would be the pragmatic approach. In addition to the above points by @ImportanceOfBeingErnest, I think it needs to be absolutely clear what this option is for, and what the downsides are (in particular that rotated results may not look correct). Perhaps an example linked to from the keyword argument in the docstring?

[MuellerSeb]

in particular that rotated results may not look correct

Rotated results don't look good either way as a result of unwanted z-fights. And that is the reason for this PR: to have a chance to make static 3D plot look correct/good.

[tacaswell]

I am in favor of this, but I think the kwarg name is confusing. Once we get to 3D zorder is ambiguous and the name is only clear in the context that we are forcing what mpl calls zorder to ignore the depth sorting which is also reasonably called "zorder" as it is the order as we look at the 3D scene!).

Maybe fixed_zorder=False or depth_sorted=True as alternatives?

[tacaswell]

auto_zorder, computed_zorder, respect_user_zorder also candidates.

[tacaswell]

computed_zorder=True was the winner on the call.

[kentcr]

@tacaswell

computed_zorder=True was the winner on the call.

Sounds good. The change is implemented.

[jklymak]

Looks good to me other than the two small issues...

[jklymak]

I don't know that we do these annotations?

[kentcr]

Should I remove both then?

[timhoffm]

Yes, please.

[kentcr]

Done, though for what it's worth there are still a couple dozen similar 'versionadded' notes elsewhere in the file.

[jklymak]

stray new line?

[kentcr]

It's a flake8 rule violation to only have one empty line after a class definition (E305), so I figured I'd risk fixing it

[timhoffm]

👍

[timhoffm]

This should get a what's new entry. See `doc/users/next_whats_new/README.rst

[timhoffm]

👍

[timhoffm]

Thanks @kentcr, and congratulations on your first contribution to Matplotlib! We hope to see you back.