manim 0.17.0__py3-none-any.whl → 0.19.1__py3-none-any.whl

manim/mobject/svg/brace.py

@@ -4,18 +4,21 @@ from __future__ import annotations
 
 __all__ = ["Brace", "BraceLabel", "ArcBrace", "BraceText", "BraceBetweenPoints"]
 
-from typing import Sequence
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import svgelements as se
+from typing_extensions import Self
 
 from manim._config import config
 from manim.mobject.geometry.arc import Arc
 from manim.mobject.geometry.line import Line
 from manim.mobject.mobject import Mobject
 from manim.mobject.opengl.opengl_compatibility import ConvertToOpenGL
-from manim.mobject.text.tex_mobject import MathTex, Tex
+from manim.mobject.text.tex_mobject import MathTex, SingleStringMathTex, Tex
+from manim.mobject.text.text_mobject import Text
 
+from ...animation.animation import Animation
 from ...animation.composition import AnimationGroup
 from ...animation.fading import FadeIn
 from ...animation.growing import GrowFromCenter
@@ -24,6 +27,10 @@ from ...mobject.types.vectorized_mobject import VMobject
 from ...utils.color import BLACK
 from ..svg.svg_mobject import VMobjectFromSVGPath
 
+if TYPE_CHECKING:
+    from manim.typing import Point3D, Point3DLike, Vector3D, Vector3DLike
+    from manim.utils.color.core import ParsableManimColor
+
 
 class Brace(VMobjectFromSVGPath):
     """Takes a mobject and draws a brace adjacent to it.
@@ -63,14 +70,14 @@ class Brace(VMobjectFromSVGPath):
     def __init__(
         self,
         mobject: Mobject,
-        direction: Sequence[float] | None = DOWN,
-        buff=0.2,
-        sharpness=2,
-        stroke_width=0,
-        fill_opacity=1.0,
-        background_stroke_width=0,
-        background_stroke_color=BLACK,
-        **kwargs,
+        direction: Vector3DLike = DOWN,
+        buff: float = 0.2,
+        sharpness: float = 2,
+        stroke_width: float = 0,
+        fill_opacity: float = 1.0,
+        background_stroke_width: float = 0,
+        background_stroke_color: ParsableManimColor = BLACK,
+        **kwargs: Any,
     ):
         path_string_template = (
             "m0.01216 0c-0.01152 0-0.01216 6.103e-4 -0.01216 0.01311v0.007762c0.06776 "
@@ -123,7 +130,20 @@ class Brace(VMobjectFromSVGPath):
         for mob in mobject, self:
             mob.rotate(angle, about_point=ORIGIN)
 
-    def put_at_tip(self, mob, use_next_to=True, **kwargs):
+    def put_at_tip(self, mob: Mobject, use_next_to: bool = True, **kwargs: Any) -> Self:
+        """Puts the given mobject at the brace tip.
+
+        Parameters
+        ----------
+        mob
+            The mobject to be placed at the tip.
+        use_next_to
+            If true, then :meth:`next_to` is used to place the mobject at the
+            tip.
+        kwargs
+            Any additional keyword arguments are passed to :meth:`next_to` which
+            is used to put the mobject next to the brace tip.
+        """
         if use_next_to:
             mob.next_to(self.get_tip(), np.round(self.get_direction()), **kwargs)
         else:
@@ -133,80 +153,190 @@ class Brace(VMobjectFromSVGPath):
             mob.shift(self.get_direction() * shift_distance)
         return self
 
-    def get_text(self, *text, **kwargs):
+    def get_text(self, *text: str, **kwargs: Any) -> Tex:
+        """Places the text at the brace tip.
+
+        Parameters
+        ----------
+        text
+            The text to be placed at the brace tip.
+        kwargs
+            Any additional keyword arguments are passed to :meth:`.put_at_tip` which
+            is used to position the text at the brace tip.
+
+        Returns
+        -------
+        :class:`~.Tex`
+        """
         text_mob = Tex(*text)
         self.put_at_tip(text_mob, **kwargs)
         return text_mob
 
-    def get_tex(self, *tex, **kwargs):
+    def get_tex(self, *tex: str, **kwargs: Any) -> MathTex:
+        """Places the tex at the brace tip.
+
+        Parameters
+        ----------
+        tex
+            The tex to be placed at the brace tip.
+        kwargs
+            Any further keyword arguments are passed to :meth:`.put_at_tip` which
+            is used to position the tex at the brace tip.
+
+        Returns
+        -------
+        :class:`~.MathTex`
+        """
         tex_mob = MathTex(*tex)
         self.put_at_tip(tex_mob, **kwargs)
         return tex_mob
 
-    def get_tip(self):
+    def get_tip(self) -> Point3D:
+        """Returns the point at the brace tip."""
         # Returns the position of the seventh point in the path, which is the tip.
         if config["renderer"] == "opengl":
             return self.points[34]
 
         return self.points[28]  # = 7*4
 
-    def get_direction(self):
+    def get_direction(self) -> Vector3D:
+        """Returns the direction from the center to the brace tip."""
         vect = self.get_tip() - self.get_center()
         return vect / np.linalg.norm(vect)
 
 
 class BraceLabel(VMobject, metaclass=ConvertToOpenGL):
+    """Create a brace with a label attached.
+
+    Parameters
+    ----------
+    obj
+        The mobject adjacent to which the brace is placed.
+    text
+        The label text.
+    brace_direction
+        The direction of the brace. By default ``DOWN``.
+    label_constructor
+        A class or function used to construct a mobject representing
+        the label. By default :class:`~.MathTex`.
+    font_size
+        The font size of the label, passed to the ``label_constructor``.
+    buff
+        The buffer between the mobject and the brace.
+    brace_config
+        Arguments to be passed to :class:`.Brace`.
+    kwargs
+        Additional arguments to be passed to :class:`~.VMobject`.
+    """
+
     def __init__(
         self,
-        obj,
-        text,
-        brace_direction=DOWN,
-        label_constructor=MathTex,
-        font_size=DEFAULT_FONT_SIZE,
-        buff=0.2,
-        **kwargs,
+        obj: Mobject,
+        text: str,
+        brace_direction: Vector3DLike = DOWN,
+        label_constructor: type[SingleStringMathTex | Text] = MathTex,
+        font_size: float = DEFAULT_FONT_SIZE,
+        buff: float = 0.2,
+        brace_config: dict[str, Any] | None = None,
+        **kwargs: Any,
     ):
         self.label_constructor = label_constructor
         super().__init__(**kwargs)
 
         self.brace_direction = brace_direction
-        self.buff = buff
-        if isinstance(obj, list):
-            obj = self.get_group_class()(*obj)
-        self.brace = Brace(obj, brace_direction, buff, **kwargs)
+        if brace_config is None:
+            brace_config = {}
+        self.brace = Brace(obj, brace_direction, buff, **brace_config)
 
         if isinstance(text, (tuple, list)):
-            self.label = self.label_constructor(font_size=font_size, *text, **kwargs)
+            self.label: VMobject = self.label_constructor(
+                *text, font_size=font_size, **kwargs
+            )
         else:
             self.label = self.label_constructor(str(text), font_size=font_size)
 
         self.brace.put_at_tip(self.label)
         self.add(self.brace, self.label)
 
-    def creation_anim(self, label_anim=FadeIn, brace_anim=GrowFromCenter):
+    def creation_anim(
+        self,
+        label_anim: type[Animation] = FadeIn,
+        brace_anim: type[Animation] = GrowFromCenter,
+    ) -> AnimationGroup:
         return AnimationGroup(brace_anim(self.brace), label_anim(self.label))
 
-    def shift_brace(self, obj, **kwargs):
+    def shift_brace(self, obj: Mobject, **kwargs: Any) -> Self:
         if isinstance(obj, list):
             obj = self.get_group_class()(*obj)
         self.brace = Brace(obj, self.brace_direction, **kwargs)
         self.brace.put_at_tip(self.label)
         return self
 
-    def change_label(self, *text, **kwargs):
-        self.label = self.label_constructor(*text, **kwargs)
-
+    def change_label(self, *text: str, **kwargs: Any) -> Self:
+        self.remove(self.label)
+        self.label = self.label_constructor(*text, **kwargs)  # type: ignore[arg-type]
         self.brace.put_at_tip(self.label)
+        self.add(self.label)
         return self
 
-    def change_brace_label(self, obj, *text, **kwargs):
+    def change_brace_label(self, obj: Mobject, *text: str, **kwargs: Any) -> Self:
         self.shift_brace(obj)
         self.change_label(*text, **kwargs)
         return self
 
 
 class BraceText(BraceLabel):
-    def __init__(self, obj, text, label_constructor=Tex, **kwargs):
+    """Create a brace with a text label attached.
+
+    Parameters
+    ----------
+    obj
+        The mobject adjacent to which the brace is placed.
+    text
+        The label text.
+    brace_direction
+        The direction of the brace. By default ``DOWN``.
+    label_constructor
+        A class or function used to construct a mobject representing
+        the label. By default :class:`~.Text`.
+    font_size
+        The font size of the label, passed to the ``label_constructor``.
+    buff
+        The buffer between the mobject and the brace.
+    brace_config
+        Arguments to be passed to :class:`.Brace`.
+    kwargs
+        Additional arguments to be passed to :class:`~.VMobject`.
+
+
+    Examples
+    --------
+        .. manim:: BraceTextExample
+            :save_last_frame:
+
+            class BraceTextExample(Scene):
+                def construct(self):
+                    s1 = Square().move_to(2*LEFT)
+                    self.add(s1)
+                    br1 = BraceText(s1, "Label")
+                    self.add(br1)
+
+                    s2 = Square().move_to(2*RIGHT)
+                    self.add(s2)
+                    br2 = BraceText(s2, "Label")
+
+                    br2.change_label("new")
+                    self.add(br2)
+                    self.wait(0.1)
+    """
+
+    def __init__(
+        self,
+        obj: Mobject,
+        text: str,
+        label_constructor: type[SingleStringMathTex | Text] = Text,
+        **kwargs: Any,
+    ):
         super().__init__(obj, text, label_constructor=label_constructor, **kwargs)
 
 
@@ -244,10 +374,10 @@ class BraceBetweenPoints(Brace):
 
     def __init__(
         self,
-        point_1: Sequence[float] | None,
-        point_2: Sequence[float] | None,
-        direction: Sequence[float] | None = ORIGIN,
-        **kwargs,
+        point_1: Point3DLike,
+        point_2: Point3DLike,
+        direction: Vector3DLike = ORIGIN,
+        **kwargs: Any,
     ):
         if all(direction == ORIGIN):
             line_vector = np.array(point_2) - np.array(point_1)
@@ -312,10 +442,12 @@ class ArcBrace(Brace):
 
     def __init__(
         self,
-        arc: Arc = Arc(start_angle=-1, angle=2, radius=1),
-        direction: Sequence[float] = RIGHT,
-        **kwargs,
+        arc: Arc | None = None,
+        direction: Vector3DLike = RIGHT,
+        **kwargs: Any,
     ):
+        if arc is None:
+            arc = Arc(start_angle=-1, angle=2, radius=1)
         arc_end_angle = arc.start_angle + arc.angle
         line = Line(UP * arc.start_angle, UP * arc_end_angle)
         scale_shift = RIGHT * np.log(arc.radius)

manim/mobject/svg/svg_mobject.py

@@ -4,14 +4,17 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
+from typing import Any
 from xml.etree import ElementTree as ET
 
 import numpy as np
 import svgelements as se
 
 from manim import config, logger
+from manim.utils.color import ManimColor, ParsableManimColor
 
 from ...constants import RIGHT
+from ...utils.bezier import get_quadratic_approximation_of_cubic
 from ...utils.images import get_full_vector_image_path
 from ...utils.iterables import hash_obj
 from ..geometry.arc import Circle
@@ -81,6 +84,12 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         A dictionary with keyword arguments passed to
         :class:`.VMobjectFromSVGPath` used for importing path elements.
         If ``None`` (the default), no additional arguments are passed.
+    use_svg_cache
+        If True (default), the svg inputs (e.g. file_name, settings)
+        will be used as a key and a copy of the created mobject will
+        be saved using that key to be quickly retrieved if the same
+        inputs need be processed later. For large SVGs which are used
+        only once, this can be omitted to improve performance.
     kwargs
         Further arguments passed to the parent class.
     """
@@ -91,16 +100,17 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         should_center: bool = True,
         height: float | None = 2,
         width: float | None = None,
-        color: str | None = None,
+        color: ParsableManimColor | None = None,
         opacity: float | None = None,
-        fill_color: str | None = None,
+        fill_color: ParsableManimColor | None = None,
         fill_opacity: float | None = None,
-        stroke_color: str | None = None,
+        stroke_color: ParsableManimColor | None = None,
         stroke_opacity: float | None = None,
         stroke_width: float | None = None,
         svg_default: dict | None = None,
         path_string_config: dict | None = None,
-        **kwargs,
+        use_svg_cache: bool = True,
+        **kwargs: Any,
     ):
         super().__init__(color=None, stroke_color=None, fill_color=None, **kwargs)
 
@@ -110,13 +120,15 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         self.should_center = should_center
         self.svg_height = height
         self.svg_width = width
-        self.color = color
+        self.color = ManimColor(color)
         self.opacity = opacity
         self.fill_color = fill_color
-        self.fill_opacity = fill_opacity
+        self.fill_opacity = fill_opacity  # type: ignore[assignment]
         self.stroke_color = stroke_color
-        self.stroke_opacity = stroke_opacity
-        self.stroke_width = stroke_width
+        self.stroke_opacity = stroke_opacity  # type: ignore[assignment]
+        self.stroke_width = stroke_width  # type: ignore[assignment]
+        if self.stroke_width is None:
+            self.stroke_width = 0
 
         if svg_default is None:
             svg_default = {
@@ -134,7 +146,7 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
             path_string_config = {}
         self.path_string_config = path_string_config
 
-        self.init_svg_mobject()
+        self.init_svg_mobject(use_svg_cache=use_svg_cache)
 
         self.set_style(
             fill_color=fill_color,
@@ -145,7 +157,7 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         )
         self.move_into_position()
 
-    def init_svg_mobject(self) -> None:
+    def init_svg_mobject(self, use_svg_cache: bool) -> None:
         """Checks whether the SVG has already been imported and
         generates it if not.
 
@@ -153,14 +165,16 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         --------
         :meth:`.SVGMobject.generate_mobject`
         """
-        hash_val = hash_obj(self.hash_seed)
-        if hash_val in SVG_HASH_TO_MOB_MAP:
-            mob = SVG_HASH_TO_MOB_MAP[hash_val].copy()
-            self.add(*mob)
-            return
+        if use_svg_cache:
+            hash_val = hash_obj(self.hash_seed)
+            if hash_val in SVG_HASH_TO_MOB_MAP:
+                mob = SVG_HASH_TO_MOB_MAP[hash_val].copy()
+                self.add(*mob)
+                return
 
         self.generate_mobject()
-        SVG_HASH_TO_MOB_MAP[hash_val] = self.copy()
+        if use_svg_cache:
+            SVG_HASH_TO_MOB_MAP[hash_val] = self.copy()
 
     @property
     def hash_seed(self) -> tuple:
@@ -181,7 +195,7 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         """Parse the SVG and translate its elements to submobjects."""
         file_path = self.get_file_path()
         element_tree = ET.parse(file_path)
-        new_tree = self.modify_xml_tree(element_tree)
+        new_tree = self.modify_xml_tree(element_tree)  # type: ignore[arg-type]
         # Create a temporary svg file to dump modified svg to be parsed
         modified_file_path = file_path.with_name(f"{file_path.stem}_{file_path.suffix}")
         new_tree.write(modified_file_path)
@@ -218,12 +232,12 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
             "style",
         )
         root = element_tree.getroot()
-        root_style_dict = {k: v for k, v in root.attrib.items() if k in style_keys}
+        root_style_dict = {k: v for k, v in root.attrib.items() if k in style_keys}  # type: ignore[union-attr]
 
         new_root = ET.Element("svg", {})
         config_style_node = ET.SubElement(new_root, "g", config_style_dict)
         root_style_node = ET.SubElement(config_style_node, "g", root_style_dict)
-        root_style_node.extend(root)
+        root_style_node.extend(root)  # type: ignore[arg-type]
         return ET.ElementTree(new_root)
 
     def generate_config_style_dict(self) -> dict[str, str]:
@@ -252,12 +266,13 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         svg
             The parsed SVG file.
         """
-        result = []
+        result: list[VMobject] = []
         for shape in svg.elements():
-            if isinstance(shape, se.Group):
+            # can we combine the two continue cases into one?
+            if isinstance(shape, se.Group):  # noqa: SIM114
                 continue
             elif isinstance(shape, se.Path):
-                mob = self.path_to_mobject(shape)
+                mob: VMobject = self.path_to_mobject(shape)
             elif isinstance(shape, se.SimpleLine):
                 mob = self.line_to_mobject(shape)
             elif isinstance(shape, se.Rect):
@@ -270,7 +285,7 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
                 mob = self.polyline_to_mobject(shape)
             elif isinstance(shape, se.Text):
                 mob = self.text_to_mobject(shape)
-            elif isinstance(shape, se.Use) or type(shape) == se.SVGElement:
+            elif isinstance(shape, se.Use) or type(shape) is se.SVGElement:
                 continue
             else:
                 logger.warning(f"Unsupported element type: {type(shape)}")
@@ -411,7 +426,7 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
         return vmobject_class().set_points_as_corners(points)
 
     @staticmethod
-    def text_to_mobject(text: se.Text):
+    def text_to_mobject(text: se.Text) -> VMobject:
         """Convert a text element to a vectorized mobject.
 
         .. warning::
@@ -424,16 +439,16 @@ class SVGMobject(VMobject, metaclass=ConvertToOpenGL):
             The parsed SVG text.
         """
         logger.warning(f"Unsupported element type: {type(text)}")
-        return
+        return  # type: ignore[return-value]
 
     def move_into_position(self) -> None:
         """Scale and move the generated mobject into position."""
         if self.should_center:
             self.center()
         if self.svg_height is not None:
-            self.set_height(self.svg_height)
+            self.set(height=self.svg_height)
         if self.svg_width is not None:
-            self.set_width(self.svg_width)
+            self.set(width=self.svg_width)
 
 
 class VMobjectFromSVGPath(VMobject, metaclass=ConvertToOpenGL):
@@ -469,7 +484,7 @@ class VMobjectFromSVGPath(VMobject, metaclass=ConvertToOpenGL):
         long_lines: bool = False,
         should_subdivide_sharp_curves: bool = False,
         should_remove_null_curves: bool = False,
-        **kwargs,
+        **kwargs: Any,
     ):
         # Get rid of arcs
         path_obj.approximate_arcs_with_quads()
@@ -481,7 +496,7 @@ class VMobjectFromSVGPath(VMobject, metaclass=ConvertToOpenGL):
 
         super().__init__(**kwargs)
 
-    def init_points(self) -> None:
+    def generate_points(self) -> None:
         # TODO: cache mobject in a re-importable way
 
         self.handle_commands()
@@ -494,31 +509,102 @@ class VMobjectFromSVGPath(VMobject, metaclass=ConvertToOpenGL):
                 # Get rid of any null curves
                 self.set_points(self.get_points_without_null_curves())
 
-    generate_points = init_points
+    def init_points(self) -> None:
+        self.generate_points()
 
     def handle_commands(self) -> None:
-        segment_class_to_func_map = {
-            se.Move: (self.start_new_path, ("end",)),
-            se.Close: (self.close_path, ()),
-            se.Line: (self.add_line_to, ("end",)),
-            se.QuadraticBezier: (
-                self.add_quadratic_bezier_curve_to,
-                ("control", "end"),
-            ),
-            se.CubicBezier: (
-                self.add_cubic_bezier_curve_to,
-                ("control1", "control2", "end"),
-            ),
-        }
+        all_points: list[np.ndarray] = []
+        last_move: np.ndarray = None
+        curve_start = None
+        last_true_move = None
+
+        def move_pen(pt: np.ndarray, *, true_move: bool = False) -> None:
+            nonlocal last_move, curve_start, last_true_move
+            last_move = pt
+            if curve_start is None:
+                curve_start = last_move
+            if true_move:
+                last_true_move = last_move
+
+        if self.n_points_per_curve == 4:
+
+            def add_cubic(
+                start: np.ndarray, cp1: np.ndarray, cp2: np.ndarray, end: np.ndarray
+            ) -> None:
+                nonlocal all_points
+                assert len(all_points) % 4 == 0, len(all_points)
+                all_points += [start, cp1, cp2, end]
+                move_pen(end)
+
+            def add_quad(start: np.ndarray, cp: np.ndarray, end: np.ndarray) -> None:
+                add_cubic(start, (start + cp + cp) / 3, (cp + cp + end) / 3, end)
+                move_pen(end)
+
+            def add_line(start: np.ndarray, end: np.ndarray) -> None:
+                add_cubic(
+                    start, (start + start + end) / 3, (start + end + end) / 3, end
+                )
+                move_pen(end)
+
+        else:
+
+            def add_cubic(
+                start: np.ndarray, cp1: np.ndarray, cp2: np.ndarray, end: np.ndarray
+            ) -> None:
+                nonlocal all_points
+                assert len(all_points) % 3 == 0, len(all_points)
+                two_quads = get_quadratic_approximation_of_cubic(
+                    start,
+                    cp1,
+                    cp2,
+                    end,
+                )
+                all_points += two_quads[:3].tolist()
+                all_points += two_quads[3:].tolist()
+                move_pen(end)
+
+            def add_quad(start: np.ndarray, cp: np.ndarray, end: np.ndarray) -> None:
+                nonlocal all_points
+                assert len(all_points) % 3 == 0, len(all_points)
+                all_points += [start, cp, end]
+                move_pen(end)
+
+            def add_line(start: np.ndarray, end: np.ndarray) -> None:
+                add_quad(start, (start + end) / 2, end)
+                move_pen(end)
+
         for segment in self.path_obj:
             segment_class = segment.__class__
-            func, attr_names = segment_class_to_func_map[segment_class]
-            points = [
-                _convert_point_to_3d(*segment.__getattribute__(attr_name))
-                for attr_name in attr_names
-            ]
-            func(*points)
-
-        # Get rid of the side effect of trailing "Z M" commands.
-        if self.has_new_path_started():
-            self.resize_points(self.get_num_points() - 1)
+            if segment_class == se.Move:
+                move_pen(_convert_point_to_3d(*segment.end), true_move=True)
+            elif segment_class == se.Line:
+                add_line(last_move, _convert_point_to_3d(*segment.end))
+            elif segment_class == se.QuadraticBezier:
+                add_quad(
+                    last_move,
+                    _convert_point_to_3d(*segment.control),
+                    _convert_point_to_3d(*segment.end),
+                )
+            elif segment_class == se.CubicBezier:
+                add_cubic(
+                    last_move,
+                    _convert_point_to_3d(*segment.control1),
+                    _convert_point_to_3d(*segment.control2),
+                    _convert_point_to_3d(*segment.end),
+                )
+            elif segment_class == se.Close:
+                # If the SVG path naturally ends at the beginning of the curve,
+                # we do *not* need to draw a closing line. To account for floating
+                # point precision, we use a small value to compare the two points.
+                if abs(np.linalg.norm(last_move - last_true_move)) > 0.0001:
+                    add_line(last_move, last_true_move)
+                curve_start = None
+            else:
+                raise AssertionError(f"Not implemented: {segment_class}")
+
+        self.points = np.array(all_points, ndmin=2, dtype="float64")
+        # If we have no points, make sure the array is shaped properly
+        # (0 rows tall by 3 columns wide) so future operations can
+        # add or remove points correctly.
+        if len(all_points) == 0:
+            self.points = np.reshape(self.points, (0, 3))