Add clipping planes

[ffreyer]

Description

Redo/Continuation of #2783.

Adds a clip_planes attribute to plots, allowing for up to 8 clipping planes to be defined (hard limit set in OpenGL). This will allow for Axis3 to clip a world space rectangle, which is the main blocker for zooming (and camera translation?) in Axis3.

Example Rect-based clip:

f = Figure()
a = LScene(f[1, 1])

# inherit from scene by default for Axis3
a.scene.theme[:clip_planes][] = Makie.planes(Rect3f(Point3f(-0.75), Vec3f(1.5)))

# allow overwrite to e.g. visualize planes
linesegments!(
    a, Rect3f(Point3f(-0.75), Vec3f(1.5)), clip_planes = Plane3f[],
    fxaa = true, transparency = false, linewidth = 3)

p = mesh!(Sphere(Point3f(0,0,1), 1f0), transparency = false, color = :orange, backlight = 1.0)
r = range(-pi, pi, length = 101)
surface!(-pi..pi, -pi..pi, [sin(x + y) for x in r, y in r], transparency = false)
scatter!(r, r)
f

TODO:

• basic GLMakie implementation
• basic WGLMakie implementation
• basic CairoMakie implementation
• use parent plot instead of parent scene for automatic replacement for simpler attribute handling (i.e. avoid every plot needing to inherit explicitly)
• include clipping planes in boundingbox calculation
• fix volume
• fix line clipping (inconsistent length)
• fix line flickering in WGLMakie
• maybe adjust voxels to clip full voxels
• care for space (ignore anything but :data?)
• CairoMakie overrides
• fix boundingboxes clipping (see voxel example)
• fix line color interpolation

Related #1655, #1667
Closes #3908

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• Added an entry in CHANGELOG.md (for new features and breaking changes)
• Added or changed relevant sections in the documentation
• Added unit tests for new algorithms, conversion methods, etc.
• Added reference image tests for new plotting functions, recipes, visual options, etc.

[MakieBot]

Compile Times benchmark

Note, that these numbers may fluctuate on the CI servers, so take them with a grain of salt. All benchmark results are based on the mean time and negative percent mean faster than the base branch. Note, that GLMakie + WGLMakie run on an emulated GPU, so the runtime benchmark is much slower. Results are from running:

using_time = @ctime using Backend
# Compile time
create_time = @ctime fig = scatter(1:4; color=1:4, colormap=:turbo, markersize=20, visible=true)
display_time = @ctime Makie.colorbuffer(display(fig))
# Runtime
create_time = @benchmark fig = scatter(1:4; color=1:4, colormap=:turbo, markersize=20, visible=true)
display_time = @benchmark Makie.colorbuffer(fig)

	using	create	display	create	display
GLMakie	4.29s (4.28, 4.32) 0.02+-	104.82ms (103.57, 107.00) 1.24+-	494.80ms (490.36, 501.14) 3.40+-	8.69ms (8.62, 8.75) 0.05+-	25.68ms (25.55, 26.07) 0.19+-
master	4.26s (4.24, 4.29) 0.02+-	104.77ms (104.22, 105.66) 0.50+-	485.26ms (479.49, 492.57) 4.31+-	8.36ms (8.20, 8.53) 0.14+-	25.56ms (25.47, 25.67) 0.07+-
evaluation	0.99x slower X, 0.03s (1.58d, 0.01p, 0.02std)	1.00x invariant, 0.05ms (0.05d, 0.93p, 0.87std)	0.98x slower X, 9.54ms (2.46d, 0.00p, 3.85std)	0.96x slower X, 0.33ms (3.06d, 0.00p, 0.10std)	1.00x invariant, 0.13ms (0.88d, 0.14p, 0.13std)
CairoMakie	3.95s (3.85, 4.04) 0.08+-	115.43ms (110.06, 122.91) 5.96+-	176.11ms (169.85, 185.98) 6.53+-	8.51ms (8.34, 8.78) 0.15+-	1.16ms (1.14, 1.19) 0.01+-
master	3.64s (3.58, 3.75) 0.07+-	106.90ms (104.49, 113.81) 3.30+-	130.82ms (128.18, 138.27) 3.78+-	8.12ms (8.01, 8.35) 0.14+-	977.43μs (971.52, 985.14) 4.36+-
evaluation	0.92x slower❌, 0.31s (4.37d, 0.00p, 0.07std)	0.93x slower❌, 8.52ms (1.77d, 0.01p, 4.63std)	0.74x slower❌, 45.29ms (8.49d, 0.00p, 5.16std)	0.95x slower X, 0.39ms (2.69d, 0.00p, 0.14std)	0.84x slower❌, 0.19ms (19.42d, 0.00p, 0.01std)
WGLMakie	4.40s (4.35, 4.44) 0.03+-	104.43ms (103.99, 105.55) 0.59+-	8.87s (8.66, 9.13) 0.22+-	10.35ms (10.25, 10.48) 0.08+-	119.22ms (112.75, 123.83) 4.18+-
master	4.38s (4.35, 4.42) 0.03+-	104.18ms (103.12, 106.05) 0.94+-	8.85s (8.79, 8.91) 0.04+-	9.66ms (9.01, 10.49) 0.73+-	69.67ms (68.86, 70.35) 0.57+-
evaluation	0.99x invariant, 0.02s (0.77d, 0.17p, 0.03std)	1.00x invariant, 0.25ms (0.32d, 0.56p, 0.77std)	1.00x invariant, 0.02s (0.14d, 0.80p, 0.13std)	0.93x slower❌, 0.69ms (1.34d, 0.05p, 0.40std)	0.58x slower❌, 49.55ms (16.60d, 0.00p, 2.38std)

[asinghvi17]

A CairoMakie implementation would have multiple approaches:

• For lines and linesegments, cut the line at the clipping plane. This will require a 3D geometry framework.
• For scatter and meshscatter, don't render markers at the clipping plane. Some markers will not be partially clipped but I think that's fine.
• For mesh, actually cut the mesh segments that intersect the plane. Again requires a 3D geometry framework. For now we can also simply not render those mesh elements which are completely outside the plane.
• The overridden recipes will also need handling, that would be a bit simpler though.

[ffreyer]

A CairoMakie implementation would have multiple approaches:

• For lines and linesegments, cut the line at the clipping plane. This will require a 3D geometry framework.
• For scatter and meshscatter, don't render markers at the clipping plane. Some markers will not be partially clipped but I think that's fine.
• For mesh, actually cut the mesh segments that intersect the plane. Again requires a 3D geometry framework. For now we can also simply not render those mesh elements which are completely outside the plane.
• The overridden recipes will also need handling, that would be a bit simpler though.

I think of these changes as mostly for 3D, so I'm looking to keep CairoMakie rather simple. Lines probably need the same manual clipping code across CairoMakie, GLMakie and WGLMakie so I'll implement that in CairoMakie too. Maybe voxels too. But everything else will probably just be a form of "if vertex is clipped don't draw". E.g. all the mesh-like plots just drop a face when one vertex is clipped atm.

[ffreyer]

I'm wondering if I should rename clip_planes to clipping_planes

[jkrumbiegel]

sounds good, otherwise it's a bit like you want to clip planes

[ffreyer]

Refimg tests I've added:

[ffreyer]

d1ca4bf fixes an issue where lines just disappear in CairoMakie when one of their coordinates is far enough outside the screen limits. From Discord:

data = 1e7*[0, 0.5, 10];
fig = Figure(); 
ax = Axis(fig[1,1]); 
ylims!(ax, 0, 1000); 
lines!(ax, 0.0:0.5:1.0, 1e3*[0, 0.5, 10]); 
lines!(ax, 0.0:0.5:1.0, data); 
fig

Before	After

The fix I'm doing here is just adding clip planes for the scene boundary (i.e. -1..1 in clip space). This results in a point at the scene edge being added and points outside being discard. Thus the orange line draws:

Adding that caused "Lines form outside" to fail in CairoMakie due to different colors. The reason for that was that color interpolation did not consider clipping. So even if, for example, the second point was moved due to clipping, it would still be assigned the same color, thus squishing the interpolation on a shorter segment.
Clip planes make this easier to see. If we draw a line with color interpolation, then adding a clip plane should not affect the colors of the visible part. This is now the case:

Before	After

"Lines from outside" should be expected to fail as the refimg doesn't adjust color interpolation to clipping.