New Feature: Implicit Surface

[BillyLjm]

Overview: What does this pull request change?

• This closes Feature Request: Add ImplicitSurface for visualizing f(x, y, z) = 0 #4428
• This also fixes Surface has incorrect checkerboard coloring #4639
• Refactors the parametric Surface so that is shares a common BaseSurface class and methods with the new ImplicitSurface
• Removed ThreeDVMobject which is now deprecated with the fixed checkerboard coloring above.
• Updated the tests for ImplicitSurface and Surface

Motivation and Explanation: Why and how do your changes improve the library?

New ImplicitSurface Class

This adds a new ImplicitSurface class to plot surfaces specified by implicit equations of f(x,y,z)=0.
This allows plotting of complex surfaces like gyroids which are otherwise difficult to specify via parametric equations.

Example: Gyroid

from manim import *

class ImplicitGyroidDemo(ThreeDScene):
    def construct(self):
        axes = ThreeDAxes()
        gyroid = ImplicitSurface(
            lambda x, y, z: np.cos(x) * np.sin(y) + np.cos(y) * np.sin(z) + np.cos(z) * np.sin(x),
            x_range=(-np.pi, np.pi),
            y_range=(-np.pi, np.pi),
            z_range=(-np.pi, np.pi),
            checkerboard_colors=False
        )
        self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)
        self.add(axes, gyroid)

Example: Sphere

from manim import *

class ImplicitSphereDemo(ThreeDScene):
    def construct(self):
        axes = ThreeDAxes()
        sphere = ImplicitSurface(
            lambda x, y, z: x**2 + y**2 + z**2 - 1,
            x_range=(-1.5, 1.5),
            y_range=(-1.5, 1.5),
            z_range=(-1.5, 1.5),
            checkerboard_colors=False
        )
        self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)
        self.add(axes, sphere)

Checkerboard Coloring Fix

This also fixes an existing bug with checkerboard coloring of Surface which was discovered during refactoring.

After Fix

Before Fix

Code for reproducing the problem

from manim import *

class ParaSphereDemo(ThreeDScene):
    def construct(self):
        axes = ThreeDAxes()
        sphere = Surface(
            lambda u, v: axes.c2p(
                *np.array([
                    np.sin(u) * np.cos(v),
                    np.sin(u) * np.sin(v),
                    np.cos(u)
                ])
            ),
            u_range=(-np.pi, np.pi),
            v_range=(-np.pi, np.pi),
            checkerboard_colors=False
        )
        self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)
        self.add(axes, sphere)

Misc Housekeeping

• This also refactors the Surface class since it shares common methods with the new ImplicitSurface, keeping things tidy.
• This also removes ThreeDVMobject which is deprecated with the refactoring.
• Added a test for the new ImplicitSurface and regenerated the tests associated with Surface

Links to added or changed documentation pages

• manim.mobject.three_d.three_dimensions.ImplicitSurface.html
• manim.mobject.three_d.three_dimensions.html

Further Information and Comments

This uses the existing isosurface package that is already being used in manim.

Reviewer Checklist

• The PR title is descriptive enough for the changelog, and the PR is labeled correctly
• If applicable: newly added non-private functions and classes have a docstring including a short summary and a PARAMETERS section
• If applicable: newly added functions and classes are tested

[behackl]

Hi! Thanks for the nice refactor, I generally like this cleaned up version quite a bit. There are some things I'd need you to take a second look at though:

• You have implemented the new surface using the ConvertToOpenGL metaclass meaning that when users run this with the opengl renderer, some of the mobject's inheritance trees get swapped (its super ugly and somewhat temporary). However, when constructing there are at least two places where you use plain VMobjects or a VGroup; doing that breaks this mechanism.
  • You can use self.get_group_class() instead of VGroup to make the grouping renderer-independent,
  • and in the other place you would have to do something like VMobject if config.renderer == "cairo" else OpenGLVMobject, given that you have replaced the ThreeDVMobject which was able to switch to OpenGL-logic itself.
• except Exception isn't great, and it would be better to at least re-raise the context of the last exception, or just actually catch expected exceptions, as far as possible.

Again, thank you very much for your effort!

[BillyLjm]

Hi, thanks for maintaining this too.

I added OpenGLVGroup and OpenGLVMobject in a similar way as the other parts of the file.
It works fine during runtime, but the mypy static type checker was a bit hard to appease. I can change it if there's a cleaner way to do it.

The except Exception has been changed to except AssertionError.
The original error was a general assert non_zero from the isosurface package, and wasn't very descriptive.
So I re-raised it as the runtime error with a more descriptive message in the else block