One thing that makes this tricky is that although a lot of examples / use-cases are 2D, it's hard to determine reliably when we can assume the scene to be 2D. Therefore I went with an approach that more or less assumes 3D but also works well in 2D.

Older images pushed back, so this means if I add a new image it will appear on top of the existing ones? This is desired and most intuitive, and is similar with other plotting libs.

If I add a like and then scatter points, these points will appear on top of the line?

Usually the scene is 3D if the camera.fov > 50

Btw there was this related ideas before: #839

if I add a new image it will appear on top of the existing ones?

Exactly. And yet the top image will still be below the points, lines, and axes.

If I add a like and then scatter points, these points will appear on top of the line?

Yes. But here it's a bit more tricky, since (assuming the data is 2D) they are both at z=0, and depth-fighting may be a thing.

There are a few reasons why depth-fighting should be unlikely:

• The depth range for ortho projection is usually favorable, so we have plenty of precision in the depth buffer.
• The use of depth_compare = '<=' avoids depth-fighting for two objects at exactly the same depth.

For reference, other measures we can take for depth fighting:

• Use the invariant keyword for the position in the vertex shader (in PyGfx), which reduces differences due to float roundoff errors as a cause for depth-fighting.
• Use depth offset, e.g. assign an increasing depth offset to the graphics, in the order they were added.

Usually the scene is 3D if the camera.fov > 50

Usually ... but it's perfectly sensible for sciency 3D data to be rendered using orthographic projection. Whether pan-zoom is used (and looking down z) would be a more appropriate signal. In any case, I really like the idea to create the scene in a way that works for both 2D and 3D cases, so users can switch and all keeps making sense. I think we can make that work.

Btw there was this related ideas before: #839

In the comment in #839 I still assumed the scene was always 2d :)

📚 Docs preview built and uploaded! https://www.fastplotlib.org/ver/z-order

So the release tests are know to fail - we need a new release of PyGfx.

But the other tests keep failing with:

I had a look at the diffs, and it looks like cases where previously the data was over the axes, and now it's under 👌

I tried to update the reference images by downloading them from the screenshots action, and replacing them. I am a little confused about the "screenshots-" vs "screenshots-imgui" artifacts, which both seem to contain the same screenshots?

I think I tried both, but to no avail...

Lines, points, and axes use depth_campare="<=" so that for objects at the same depth, the render order determines which one is on top.

Can you explain this a bit? I also made a issue on pygfx to understand depth_compare better so maybe I'll wait for that.

Lines, points, and axes use depth_campare="<=" so that for objects at the same depth, the render order determines which one is on top.

Can you explain this a bit? I also made a issue on pygfx to understand depth_compare better so maybe I'll wait for that.

See pygfx/pygfx#1213 (comment)