manim 0.18.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/__main__.py

@@ -3,22 +3,49 @@ from __future__ import annotations
 import click
 import cloup
 
-from . import __version__, cli_ctx_settings, console
-from .cli.cfg.group import cfg
-from .cli.checkhealth.commands import checkhealth
-from .cli.default_group import DefaultGroup
-from .cli.init.commands import init
-from .cli.plugins.commands import plugins
-from .cli.render.commands import render
-from .constants import EPILOG
+from manim import __version__
+from manim._config import cli_ctx_settings, console
+from manim.cli.cfg.group import cfg
+from manim.cli.checkhealth.commands import checkhealth
+from manim.cli.default_group import DefaultGroup
+from manim.cli.init.commands import init
+from manim.cli.plugins.commands import plugins
+from manim.cli.render.commands import render
+from manim.constants import EPILOG
 
 
-def show_splash(ctx, param, value):
+def show_splash(ctx: click.Context, param: click.Option, value: str | None) -> None:
+    """When giving a value by console, show an initial message with the Manim
+    version before executing any other command: ``Manim Community vA.B.C``.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    param
+        A Click option.
+    value
+        A string value given by console, or None.
+    """
     if value:
         console.print(f"Manim Community [green]v{__version__}[/green]\n")
 
 
-def print_version_and_exit(ctx, param, value):
+def print_version_and_exit(
+    ctx: click.Context, param: click.Option, value: str | None
+) -> None:
+    """Same as :func:`show_splash`, but also exit when giving a value by
+    console.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    param
+        A Click option.
+    value
+        A string value given by console, or None.
+    """
     show_splash(ctx, param, value)
     if value:
         ctx.exit()
@@ -53,8 +80,14 @@ def print_version_and_exit(ctx, param, value):
     expose_value=False,
 )
 @cloup.pass_context
-def main(ctx):
-    """The entry point for manim."""
+def main(ctx: click.Context) -> None:
+    """The entry point for Manim.
+
+    Parameters
+    ----------
+    ctx
+        The Click context.
+    """
     pass
 
 

manim/_config/__init__.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Generator
 from contextlib import contextmanager
-from typing import Any, Generator
+from typing import Any
 
 from .cli_colors import parse_cli_ctx
 from .logger_utils import make_logger
@@ -67,7 +68,6 @@ def tempconfig(temp: ManimConfig | dict[str, Any]) -> Generator[None, None, None
        8.0
        >>> with tempconfig({"frame_height": 100.0}):
        ...     print(config["frame_height"])
-       ...
        100.0
        >>> config["frame_height"]
        8.0

manim/_config/cli_colors.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 import configparser
+from typing import Any
 
 from cloup import Context, HelpFormatter, HelpTheme, Style
 
 __all__ = ["parse_cli_ctx"]
 
 
-def parse_cli_ctx(parser: configparser.SectionProxy) -> Context:
+def parse_cli_ctx(parser: configparser.SectionProxy) -> dict[str, Any]:
     formatter_settings: dict[str, str | int] = {
         "indent_increment": int(parser["indent_increment"]),
         "width": int(parser["width"]),
@@ -35,15 +36,18 @@ def parse_cli_ctx(parser: configparser.SectionProxy) -> Context:
     theme = parser["theme"] if parser["theme"] else None
     if theme is None:
         formatter = HelpFormatter.settings(
-            theme=HelpTheme(**theme_settings), **formatter_settings  # type: ignore[arg-type]
+            theme=HelpTheme(**theme_settings),
+            **formatter_settings,  # type: ignore[arg-type]
         )
     elif theme.lower() == "dark":
         formatter = HelpFormatter.settings(
-            theme=HelpTheme.dark().with_(**theme_settings), **formatter_settings  # type: ignore[arg-type]
+            theme=HelpTheme.dark().with_(**theme_settings),
+            **formatter_settings,  # type: ignore[arg-type]
         )
     elif theme.lower() == "light":
         formatter = HelpFormatter.settings(
-            theme=HelpTheme.light().with_(**theme_settings), **formatter_settings  # type: ignore[arg-type]
+            theme=HelpTheme.light().with_(**theme_settings),
+            **formatter_settings,  # type: ignore[arg-type]
         )
 
     return Context.settings(

manim/_config/default.cfg

@@ -221,8 +221,6 @@ repr_number = green
 # Uncomment the following line to manually set the loglevel for ffmpeg. See
 # ffmpeg manpage for accepted values
 loglevel = ERROR
-# defaults to the one present in path
-ffmpeg_executable = ffmpeg
 
 [jupyter]
 media_embed = False

manim/_config/logger_utils.py

@@ -99,6 +99,11 @@ def make_logger(
     logger = logging.getLogger("manim")
     logger.addHandler(rich_handler)
     logger.setLevel(verbosity)
+    logger.propagate = False
+
+    if not (libav_logger := logging.getLogger()).hasHandlers():
+        libav_logger.addHandler(rich_handler)
+        libav_logger.setLevel(verbosity)
 
     return logger, console, error_console
 

manim/_config/utils.py

@@ -20,9 +20,9 @@ import logging
 import os
 import re
 import sys
-from collections.abc import Mapping, MutableMapping
+from collections.abc import Iterable, Iterator, Mapping, MutableMapping
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, ClassVar, Iterable, Iterator, NoReturn
+from typing import TYPE_CHECKING, Any, ClassVar, NoReturn
 
 import numpy as np
 
@@ -40,6 +40,8 @@ if TYPE_CHECKING:
 
 __all__ = ["config_file_paths", "make_config_parser", "ManimConfig", "ManimFrame"]
 
+logger = logging.getLogger("manim")
+
 
 def config_file_paths() -> list[Path]:
     """The paths where ``.cfg`` files will be searched for.
@@ -263,7 +265,6 @@ class ManimConfig(MutableMapping):
         "dry_run",
         "enable_wireframe",
         "ffmpeg_loglevel",
-        "ffmpeg_executable",
         "format",
         "flush_cache",
         "frame_height",
@@ -322,7 +323,7 @@ class ManimConfig(MutableMapping):
     }
 
     def __init__(self) -> None:
-        self._d: dict[str, Any | None] = {k: None for k in self._OPTS}
+        self._d: dict[str, Any | None] = dict.fromkeys(self._OPTS)
 
     # behave like a dict
     def __iter__(self) -> Iterator[str]:
@@ -371,7 +372,6 @@ class ManimConfig(MutableMapping):
         :meth:`~ManimConfig.digest_parser`
 
         """
-
         if isinstance(obj, ManimConfig):
             self._d.update(obj._d)
             if obj.tex_template:
@@ -642,21 +642,18 @@ class ManimConfig(MutableMapping):
         gui_location = tuple(
             map(int, re.split(r"[;,\-]", parser["CLI"]["gui_location"])),
         )
-        setattr(self, "gui_location", gui_location)
+        self.gui_location = gui_location
 
         window_size = parser["CLI"][
             "window_size"
         ]  # if not "default", get a tuple of the position
         if window_size != "default":
             window_size = tuple(map(int, re.split(r"[;,\-]", window_size)))
-        setattr(self, "window_size", window_size)
+        self.window_size = window_size
 
         # plugins
         plugins = parser["CLI"].get("plugins", fallback="", raw=True)
-        if plugins == "":
-            plugins = []
-        else:
-            plugins = plugins.split(",")
+        plugins = [] if plugins == "" else plugins.split(",")
         self.plugins = plugins
         # the next two must be set AFTER digesting pixel_width and pixel_height
         self["frame_height"] = parser["CLI"].getfloat("frame_height", 8.0)
@@ -673,25 +670,21 @@ class ManimConfig(MutableMapping):
 
         val = parser["CLI"].get("progress_bar")
         if val:
-            setattr(self, "progress_bar", val)
+            self.progress_bar = val
 
         val = parser["ffmpeg"].get("loglevel")
         if val:
             self.ffmpeg_loglevel = val
 
-        # TODO: Fix the mess above and below
-        val = parser["ffmpeg"].get("ffmpeg_executable")
-        setattr(self, "ffmpeg_executable", val)
-
         try:
             val = parser["jupyter"].getboolean("media_embed")
         except ValueError:
             val = None
-        setattr(self, "media_embed", val)
+        self.media_embed = val
 
         val = parser["jupyter"].get("media_width")
         if val:
-            setattr(self, "media_width", val)
+            self.media_width = val
 
         val = parser["CLI"].get("quality", fallback="", raw=True)
         if val:
@@ -804,7 +797,7 @@ class ManimConfig(MutableMapping):
             try:
                 self.upto_animation_number = nflag[1]
             except Exception:
-                logging.getLogger("manim").info(
+                logger.info(
                     f"No end scene number specified in -n option. Rendering from {nflag[0]} onwards...",
                 )
 
@@ -842,15 +835,12 @@ class ManimConfig(MutableMapping):
         if args.tex_template:
             self.tex_template = TexTemplate.from_file(args.tex_template)
 
-        if (
-            self.renderer == RendererType.OPENGL
-            and getattr(args, "write_to_movie") is None
-        ):
+        if self.renderer == RendererType.OPENGL and args.write_to_movie is None:
             # --write_to_movie was not passed on the command line, so don't generate video.
             self["write_to_movie"] = False
 
         # Handle --gui_location flag.
-        if getattr(args, "gui_location") is not None:
+        if args.gui_location is not None:
             self.gui_location = args.gui_location
 
         return self
@@ -1043,7 +1033,7 @@ class ManimConfig(MutableMapping):
             val,
             ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
         )
-        logging.getLogger("manim").setLevel(val)
+        logger.setLevel(val)
 
     @property
     def format(self) -> str:
@@ -1057,8 +1047,9 @@ class ManimConfig(MutableMapping):
             val,
             [None, "png", "gif", "mp4", "mov", "webm"],
         )
+        self.resolve_movie_file_extension(self.transparent)
         if self.format == "webm":
-            logging.getLogger("manim").warning(
+            logger.warning(
                 "Output format set as webm, this can be slower than other formats",
             )
 
@@ -1074,15 +1065,7 @@ class ManimConfig(MutableMapping):
             val,
             ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
         )
-
-    @property
-    def ffmpeg_executable(self) -> str:
-        """Custom path to the ffmpeg executable."""
-        return self._d["ffmpeg_executable"]
-
-    @ffmpeg_executable.setter
-    def ffmpeg_executable(self, value: str) -> None:
-        self._set_str("ffmpeg_executable", value)
+        logging.getLogger("libav").setLevel(self.ffmpeg_loglevel)
 
     @property
     def media_embed(self) -> bool:
@@ -1284,6 +1267,8 @@ class ManimConfig(MutableMapping):
     @background_opacity.setter
     def background_opacity(self, value: float) -> None:
         self._set_between("background_opacity", value, 0, 1)
+        if self.background_opacity < 1:
+            self.resolve_movie_file_extension(is_transparent=True)
 
     @property
     def frame_size(self) -> tuple[int, int]:
@@ -1318,8 +1303,8 @@ class ManimConfig(MutableMapping):
 
     @property
     def transparent(self) -> bool:
-        """Whether the background opacity is 0.0 (-t)."""
-        return self._d["background_opacity"] == 0.0
+        """Whether the background opacity is less than 1.0 (-t)."""
+        return self._d["background_opacity"] < 1.0
 
     @transparent.setter
     def transparent(self, value: bool) -> None:
@@ -1437,6 +1422,7 @@ class ManimConfig(MutableMapping):
         self._d.__setitem__("window_size", value)
 
     def resolve_movie_file_extension(self, is_transparent: bool) -> None:
+        prev_file_extension = self.movie_file_extension
         if is_transparent:
             self.movie_file_extension = ".webm" if self.format == "webm" else ".mov"
         elif self.format == "webm":
@@ -1445,6 +1431,11 @@ class ManimConfig(MutableMapping):
             self.movie_file_extension = ".mov"
         else:
             self.movie_file_extension = ".mp4"
+        if self.movie_file_extension != prev_file_extension:
+            logger.warning(
+                f"Output format changed to '{self.movie_file_extension}' "
+                "to support transparency",
+            )
 
     @property
     def enable_gui(self) -> bool:
@@ -1790,7 +1781,7 @@ class ManimConfig(MutableMapping):
     def tex_template_file(self, val: str) -> None:
         if val:
             if not os.access(val, os.R_OK):
-                logging.getLogger("manim").warning(
+                logger.warning(
                     f"Custom TeX template {val} not found or not readable.",
                 )
             else:

manim/animation/animation.py

@@ -7,15 +7,17 @@ from manim.mobject.opengl.opengl_mobject import OpenGLMobject
 from .. import config, logger
 from ..constants import RendererType
 from ..mobject import mobject
-from ..mobject.mobject import Mobject
+from ..mobject.mobject import Group, Mobject
 from ..mobject.opengl import opengl_mobject
 from ..utils.rate_functions import linear, smooth
 
-__all__ = ["Animation", "Wait", "override_animation"]
+__all__ = ["Animation", "Wait", "Add", "override_animation"]
 
 
+from collections.abc import Iterable, Sequence
 from copy import deepcopy
-from typing import TYPE_CHECKING, Callable, Iterable, Sequence
+from functools import partialmethod
+from typing import TYPE_CHECKING, Any, Callable
 
 from typing_extensions import Self
 
@@ -170,6 +172,19 @@ class Animation:
                 ),
             )
 
+    @property
+    def run_time(self) -> float:
+        return self._run_time
+
+    @run_time.setter
+    def run_time(self, value: float) -> None:
+        if value < 0:
+            raise ValueError(
+                f"The run_time of {self.__class__.__name__} cannot be "
+                f"negative. The given value was {value}."
+            )
+        self._run_time = value
+
     def _typecheck_input(self, mobject: Mobject | None) -> None:
         if mobject is None:
             logger.debug("Animation with empty mobject")
@@ -192,11 +207,6 @@ class Animation:
         method.
 
         """
-        if self.run_time <= 0:
-            raise ValueError(
-                f"{self} has a run_time of <= 0 seconds, this cannot be rendered correctly. "
-                "Please set the run_time to be positive"
-            )
         self.starting_mobject = self.create_starting_mobject()
         if self.suspend_mobject_updating:
             # All calls to self.mobject's internal updaters
@@ -483,6 +493,52 @@ class Animation:
         """
         return self.introducer
 
+    @classmethod
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+
+        cls._original__init__ = cls.__init__
+
+    @classmethod
+    def set_default(cls, **kwargs) -> None:
+        """Sets the default values of keyword arguments.
+
+        If this method is called without any additional keyword
+        arguments, the original default values of the initialization
+        method of this class are restored.
+
+        Parameters
+        ----------
+
+        kwargs
+            Passing any keyword argument will update the default
+            values of the keyword arguments of the initialization
+            function of this class.
+
+        Examples
+        --------
+
+        .. manim:: ChangeDefaultAnimation
+
+            class ChangeDefaultAnimation(Scene):
+                def construct(self):
+                    Rotate.set_default(run_time=2, rate_func=rate_functions.linear)
+                    Indicate.set_default(color=None)
+
+                    S = Square(color=BLUE, fill_color=BLUE, fill_opacity=0.25)
+                    self.add(S)
+                    self.play(Rotate(S, PI))
+                    self.play(Indicate(S))
+
+                    Rotate.set_default()
+                    Indicate.set_default()
+
+        """
+        if kwargs:
+            cls.__init__ = partialmethod(cls.__init__, **kwargs)
+        else:
+            cls.__init__ = cls._original__init__
+
 
 def prepare_animation(
     anim: Animation | mobject._AnimationBuilder,
@@ -582,6 +638,90 @@ class Wait(Animation):
         pass
 
 
+class Add(Animation):
+    """Add Mobjects to a scene, without animating them in any other way. This
+    is similar to the :meth:`.Scene.add` method, but :class:`Add` is an
+    animation which can be grouped into other animations.
+
+    Parameters
+    ----------
+    mobjects
+        One :class:`~.Mobject` or more to add to a scene.
+    run_time
+        The duration of the animation after adding the ``mobjects``. Defaults
+        to 0, which means this is an instant animation without extra wait time
+        after adding them.
+    **kwargs
+        Additional arguments to pass to the parent :class:`Animation` class.
+
+    Examples
+    --------
+
+    .. manim:: DefaultAddScene
+
+        class DefaultAddScene(Scene):
+            def construct(self):
+                text_1 = Text("I was added with Add!")
+                text_2 = Text("Me too!")
+                text_3 = Text("And me!")
+                texts = VGroup(text_1, text_2, text_3).arrange(DOWN)
+                rect = SurroundingRectangle(texts, buff=0.5)
+
+                self.play(
+                    Create(rect, run_time=3.0),
+                    Succession(
+                        Wait(1.0),
+                        # You can Add a Mobject in the middle of an animation...
+                        Add(text_1),
+                        Wait(1.0),
+                        # ...or multiple Mobjects at once!
+                        Add(text_2, text_3),
+                    ),
+                )
+                self.wait()
+
+    .. manim:: AddWithRunTimeScene
+
+        class AddWithRunTimeScene(Scene):
+            def construct(self):
+                # A 5x5 grid of circles
+                circles = VGroup(
+                    *[Circle(radius=0.5) for _ in range(25)]
+                ).arrange_in_grid(5, 5)
+
+                self.play(
+                    Succession(
+                        # Add a run_time of 0.2 to wait for 0.2 seconds after
+                        # adding the circle, instead of using Wait(0.2) after Add!
+                        *[Add(circle, run_time=0.2) for circle in circles],
+                        rate_func=smooth,
+                    )
+                )
+                self.wait()
+    """
+
+    def __init__(
+        self, *mobjects: Mobject, run_time: float = 0.0, **kwargs: Any
+    ) -> None:
+        mobject = mobjects[0] if len(mobjects) == 1 else Group(*mobjects)
+        super().__init__(mobject, run_time=run_time, introducer=True, **kwargs)
+
+    def begin(self) -> None:
+        pass
+
+    def finish(self) -> None:
+        pass
+
+    def clean_up_from_scene(self, scene: Scene) -> None:
+        pass
+
+    def update_mobjects(self, dt: float) -> None:
+        pass
+
+    def interpolate(self, alpha: float) -> None:
+        pass
+
+
 def override_animation(
     animation_class: type[Animation],
 ) -> Callable[[Callable], Callable]:

manim/animation/composition.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import types
-from typing import TYPE_CHECKING, Callable, Iterable, Sequence
+from collections.abc import Iterable, Sequence
+from typing import TYPE_CHECKING, Callable
 
 import numpy as np
 
@@ -81,15 +82,10 @@ class AnimationGroup(Animation):
         return list(self.group)
 
     def begin(self) -> None:
-        if self.run_time <= 0:
-            tmp = (
-                "Please set the run_time to be positive"
-                if len(self.animations) != 0
-                else "Please add at least one Animation with positive run_time"
-            )
+        if not self.animations:
             raise ValueError(
-                f"{self} has a run_time of 0 seconds, this cannot be "
-                f"rendered correctly. {tmp}."
+                f"Trying to play {self} without animations, this is not supported. "
+                "Please add at least one subanimation."
             )
         self.anim_group_time = 0.0
         if self.suspend_mobject_updating:
@@ -102,7 +98,8 @@ class AnimationGroup(Animation):
             anim._setup_scene(scene)
 
     def finish(self) -> None:
-        self.interpolate(1)
+        for anim in self.animations:
+            anim.finish()
         self.anims_begun[:] = True
         self.anims_finished[:] = True
         if self.suspend_mobject_updating:
@@ -178,11 +175,13 @@ class AnimationGroup(Animation):
         ]
 
         run_times = to_update["end"] - to_update["start"]
+        with_zero_run_time = run_times == 0
+        run_times[with_zero_run_time] = 1
         sub_alphas = (anim_group_time - to_update["start"]) / run_times
         if time_goes_back:
-            sub_alphas[sub_alphas < 0] = 0
+            sub_alphas[(sub_alphas < 0) | with_zero_run_time] = 0
         else:
-            sub_alphas[sub_alphas > 1] = 1
+            sub_alphas[(sub_alphas > 1) | with_zero_run_time] = 1
 
         for anim_to_update, sub_alpha in zip(to_update["anim"], sub_alphas):
             anim_to_update.interpolate(sub_alpha)
@@ -233,7 +232,11 @@ class Succession(AnimationGroup):
         super().__init__(*animations, lag_ratio=lag_ratio, **kwargs)
 
     def begin(self) -> None:
-        assert len(self.animations) > 0
+        if not self.animations:
+            raise ValueError(
+                f"Trying to play {self} without animations, this is not supported. "
+                "Please add at least one subanimation."
+            )
         self.update_active_animation(0)
 
     def finish(self) -> None: