Implement sections for scenes (#3883)

Reimplement the ManimCE sections API, as well as generic fixes for `Tex`.

Author: JasonGrace2282

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
       - id: python-check-blanket-noqa
         name: Precision flake ignores
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.2
+    rev: v0.5.5
     hooks:
       - id: ruff
         name: ruff lint
@@ -32,16 +32,13 @@ repos:
       - id: flake8
         additional_dependencies:
           [
-            flake8-bugbear==21.4.3,
-            flake8-builtins==1.5.3,
-            flake8-comprehensions>=3.6.1,
             flake8-docstrings==1.6.0,
             flake8-pytest-style==1.5.0,
             flake8-rst-docstrings==0.2.3,
             flake8-simplify==0.14.1,
           ]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.10.1
+    rev: v1.11.0
     hooks:
       - id: mypy
         additional_dependencies:

docs/source/conf.py

@@ -26,7 +26,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "Manim"
-copyright = f"2020-{datetime.now().year}, The Manim Community Dev Team"
+copyright = f"2020-{datetime.now().year}, The Manim Community Dev Team"  # noqa: A001
 author = "The Manim Community Dev Team"
 
 
@@ -63,7 +63,7 @@
     alias_name: f"~manim.{module}.{alias_name}"
     for module, module_dict in ALIAS_DOCS_DICT.items()
     for category_dict in module_dict.values()
-    for alias_name in category_dict.keys()
+    for alias_name in category_dict
 }
 autoclass_content = "both"
 

docs/source/guides/configuration.rst

@@ -357,10 +357,10 @@ A list of all config options
    'log_dir', 'log_to_file', 'max_files_cached', 'media_dir', 'media_width',
    'movie_file_extension', 'notify_outdated_version', 'output_file', 'partial_movie_dir',
    'pixel_height', 'pixel_width', 'plugins', 'preview',
-   'progress_bar', 'quality', 'right_side', 'save_as_gif', 'save_last_frame',
-   'save_pngs', 'scene_names', 'show_in_file_browser', 'sound', 'tex_dir',
+   'progress_bar', 'quality', 'right_side', 'save_last_frame',
+   'scene_names', 'show_in_file_browser', 'sound', 'tex_dir',
    'tex_template', 'tex_template_file', 'text_dir', 'top', 'transparent',
-   'upto_animation_number', 'use_opengl_renderer', 'verbosity', 'video_dir',
+   'upto_animation_number', 'verbosity', 'video_dir',
    'window_position', 'window_monitor', 'window_size', 'write_all', 'write_to_movie',
    'enable_wireframe', 'force_window']
 

docs/source/installation.rst

@@ -68,7 +68,7 @@ in order for Manim to work properly, some additional system
 dependencies need to be installed first. The following pages have
 operating system specific instructions for you to follow.
 
-Manim requires Python version ``3.9`` or above to run.
+Manim requires Python version ``3.10`` or above to run.
 
 .. hint::
 

docs/source/installation/linux.rst

@@ -5,7 +5,7 @@ The installation instructions depend on your particular operating
 system and package manager. If you happen to know exactly what you are doing,
 you can also simply ensure that your system has:
 
-- a reasonably recent version of Python 3 (3.9 or above),
+- a reasonably recent version of Python 3 (3.10 or above),
 - with working Cairo bindings in the form of
   `pycairo <https://cairographics.org/pycairo/>`__,
 - and `Pango <https://pango.gnome.org>`__ headers.

docs/source/installation/windows.rst

@@ -16,7 +16,7 @@ to make one of them available on your system.
 Required Dependencies
 ---------------------
 
-Manim requires a recent version of Python (3.9 or above)
+Manim requires a recent version of Python (3.10 or above)
 in order to work.
 
 Chocolatey
@@ -35,7 +35,7 @@ Pip
 ***
 
 As mentioned above, Manim needs a reasonably recent version of
-Python 3 (3.9 or above).
+Python 3 (3.10 or above).
 
 **Python:** Head over to https://www.python.org, download an installer
 for a recent version of Python, and follow its instructions to get Python

docs/source/reference.rst

@@ -38,9 +38,9 @@ Cameras
 *******
 
 .. inheritance-diagram::
-   manim.camera.cairo_camera
+   manim.camera.camera
    :parts: 1
-   :top-classes: manim.camera.camera.Camera, manim.mobject.mobject.Mobject
+   :top-classes: manim.camera.camera.Camera, manim.mobject.opengl.opengl_mobject.OpenGLMobject
 
 Mobjects
 ********

docs/source/tutorials/output_and_config.rst

@@ -18,7 +18,7 @@ At this point, you have just executed the following command.
 
 Let's dissect what just happened step by step.  First, this command executes
 manim on the file ``scene.py``, which contains our animation code.  Further,
-this command tells manim exactly which ``Scene`` is to be rendered, in this case,
+this command tells manim exactly which :class:`.Scene` is to be rendered, in this case,
 it is ``SquareToCircle``.  This is necessary because a single scene file may
 contain more than one scene.  Next, the flag `-p` tells manim to play the scene
 once it's rendered, and the `-ql` flag tells manim to render the scene in low
@@ -140,44 +140,73 @@ resolutions, e.g. ``-s -ql``, ``-s -qh``
 Sections
 ********
 
-In addition to the movie output file one can use sections. Each section produces
-its own output video. The cuts between two sections can be set like this:
+In addition to the movie output file one can use sections. If :attr:`ManimConfig.save_sections` is ``True``,
+each section produces its own output video. In order to use sections, set :attr:`~Scene.sections_api` to ``True``.
 
 .. code-block:: python
 
-    def construct(self):
-        # play the first animations...
-        # you don't need a section in the very beginning as it gets created automatically
-        self.next_section()
-        # play more animations...
-        self.next_section("this is an optional name that doesn't have to be unique")
-        # play even more animations...
-        self.next_section("this is a section without any animations, it will be removed")
+    class MyScene(Scene):
+        sections_api = True
+
+        @section
+        def introduction(self):
+            # play the first animations...
+            # the default name of this section is the name of the method
+            ...
+
+        @section(name="this is an optional name that doesn't have to be unique")
+        def second_section(self):
+            # play more animations...
+            ...
+
+        @section(skip=True)
+        def finale(self):
+            # play even more animations...
+            # however, they won't be included in the final output video
+            ...
 
 All the animations between two of these cuts get concatenated into a single output
 video file.
 Be aware that you need at least one animation in each section. For example this wouldn't create an output video:
 
 .. code-block:: python
 
-   def construct(self):
-       self.next_section()
-       # this section doesn't have any animations and will be removed
-       # but no error will be thrown
-       # feel free to tend your flock of empty sections if you so desire
-       self.add(Circle())
-       self.next_section()
+   class SectionsExampleWithNoAnimations(Scene):
+      sections_api = True
+
+      @section
+      def first(self):
+          self.next_section()
+          # this section doesn't have any animations and will be removed
+          # but no error will be thrown
+          # feel free to tend your flock of empty sections if you so desire
+          self.add(Circle())
+
+      @section
+      def next(self):
+          # play some animations
+          ...
 
 One way of fixing this is to wait a little:
 
 .. code-block:: python
 
-   def construct(self):
-       self.next_section()
-       self.add(Circle())
-       # now we wait 1sec and have an animation to satisfy the section
-       self.wait()
-       self.next_section()
+   class SectionsExampleWithNoAnimations(Scene):
+      sections_api = True
+
+      @section
+      def first(self):
+          self.next_section()
+          # this section doesn't have any animations and will be removed
+          # but no error will be thrown
+          # feel free to tend your flock of empty sections if you so desire
+          self.add(Circle())
+          self.wait()
+
+      @section
+      def next(self):
+          # play some animations
+          ...
 
 For videos to be created for each section you have to add the ``--save_sections`` flag to the Manim call like this:
 
@@ -258,13 +287,20 @@ You can also skip rendering all animations belonging to a section like this:
 
 .. code-block:: python
 
-    def construct(self):
-        self.next_section(skip_animations=True)
-        # play some animations that shall be skipped...
-        self.next_section()
-        # play some animations that won't get skipped...
+   class SkippingSections(Scene):
+      sections_api = True
 
+      @section(skip=True)
+      def first(self):
+          # play some animations
+          # things here will execute, but they
+          # won't be written to the output file
+          ...
 
+      @section
+      def next(self):
+          # play some animations
+          ...
 
 
 Some command line flags
@@ -277,9 +313,9 @@ When executing the command
    manim -pql scene.py SquareToCircle
 
 it specifies the scene to render.  This is not necessary now.  When a single
-file contains only one ``Scene`` class, it will just render the ``Scene``
-class.  When a single file contains more than one ``Scene`` class, manim will
-let you choose a ``Scene`` class. If your file contains multiple ``Scene``
+file contains only one :class:`.Scene` class, it will just render the :class:`.Scene`
+class.  When a single file contains more than one :class:`.Scene` class, manim will
+let you choose a :class:`.Scene` class. If your file contains multiple :class:`.Scene`
 classes, and you want to render them all, you can use the ``-a`` flag.
 
 As discussed previously, the ``-ql`` specifies low render quality (854x480
@@ -294,7 +330,7 @@ the file browser at the location of the animation instead of playing it, you
 can use the ``-f`` flag.  You can also omit these two flags.
 
 Finally, by default manim will output .mp4 files.  If you want your animations
-in .gif format instead, use the ``--format gif`` flag.  The output files will
+in .gif format instead, use the ``--format=gif`` flag.  The output files will
 be in the same folder as the .mp4 files, and with the same name, but a
 different file extension.
 

example_scenes/test_new_rendering.py

@@ -2,20 +2,26 @@
 
 
 class Test(Scene):
-    def construct(self) -> None:
-        self.play(
-            Create(
-                t := Tex(
-                    "Hello, world!", stroke_color=RED, fill_color=BLUE, stroke_width=2
-                )
-            )
-        )
-        self.play(FadeOut(t))
+    sections_api = True
+
+    @section(name="spinning_math")
+    def first_section(self) -> None:
+        line = Line()
+        line.add_updater(lambda m, dt: m.rotate(PI * dt))
+        t = Tex(r"Math! $\sum e^{i\theta}$").add_updater(lambda m: m.next_to(line, UP))
+        line.to_edge(LEFT)
+        self.add(line, t)
         s = Square()
-        self.add(s)
-        self.play(Rotate(s, PI / 2))
-        self.wait(7)
+        t = Tex(
+            "Hello, world!", stroke_color=RED, fill_color=BLUE, stroke_width=2
+        ).to_edge(RIGHT)
+        self.add(t)
+        self.play(Create(t), Rotate(s, PI / 2))
+        self.wait(1)
         self.play(FadeOut(s))
+
+    @section
+    def three_mobjects(self) -> None:
         sq = RegularPolygon(6)
         c = Circle()
         st = Star()
@@ -27,7 +33,11 @@ def construct(self) -> None:
                 Create(st),
             )
         )
-        self.play(FadeOut(VGroup(*self.mobjects)))
+        self.play(FadeOut(VGroup(sq, c, st)))
+
+    @section(skip=True)
+    def never_run(self) -> None:
+        self.play(Write(Text("This should never be run")))
 
 
 if __name__ == "__main__":

manim/__init__.py

@@ -72,6 +72,7 @@
 from manim.mobject.value_tracker import *
 from manim.mobject.vector_field import *
 from manim.scene.scene import *
+from manim.scene.sections import *
 from manim.scene.vector_space_scene import *
 from manim.utils import color, rate_functions, unit
 from manim.utils.bezier import *