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

manim/mobject/geometry/boolean_ops.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-import typing
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 from pathops import Path as SkiaPath
@@ -12,6 +12,9 @@ from manim import config
 from manim.mobject.opengl.opengl_compatibility import ConvertToOpenGL
 from manim.mobject.types.vectorized_mobject import VMobject
 
+if TYPE_CHECKING:
+    from manim.typing import Point2DLike_Array, Point3D_Array, Point3DLike_Array
+
 from ...constants import RendererType
 
 __all__ = ["Union", "Intersection", "Difference", "Exclusion"]
@@ -23,41 +26,39 @@ class _BooleanOps(VMobject, metaclass=ConvertToOpenGL):
     objects (:class:`~.VMobject`).
     """
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-
     def _convert_2d_to_3d_array(
         self,
-        points: typing.Iterable,
+        points: Point2DLike_Array | Point3DLike_Array,
         z_dim: float = 0.0,
-    ) -> list[np.ndarray]:
-        """Converts an iterable with coordinates in 2d to 3d by adding
-        :attr:`z_dim` as the z coordinate.
+    ) -> Point3D_Array:
+        """Converts an iterable with coordinates in 2D to 3D by adding
+        :attr:`z_dim` as the Z coordinate.
 
         Parameters
         ----------
-        points:
-            An iterable which has the coordinates.
-        z_dim:
-            The default value of z coordinate.
+        points
+            An iterable of points.
+        z_dim
+            Default value for the Z coordinate.
 
         Returns
         -------
-        typing.List[np.ndarray]
-            A list of array converted to 3d.
+        Point3D_Array
+            A list of the points converted to 3D.
 
         Example
         -------
         >>> a = _BooleanOps()
         >>> p = [(1, 2), (3, 4)]
         >>> a._convert_2d_to_3d_array(p)
-        [array([1., 2., 0.]), array([3., 4., 0.])]
+        array([[1., 2., 0.],
+               [3., 4., 0.]])
         """
-        points = list(points)
-        for i, point in enumerate(points):
+        list_of_points = list(points)
+        for i, point in enumerate(list_of_points):
             if len(point) == 2:
-                points[i] = np.array(list(point) + [z_dim])
-        return points
+                list_of_points[i] = np.append(point, z_dim)
+        return np.asarray(list_of_points)
 
     def _convert_vmobject_to_skia_path(self, vmobject: VMobject) -> SkiaPath:
         """Converts a :class:`~.VMobject` to SkiaPath. This method only works for
@@ -70,15 +71,15 @@ class _BooleanOps(VMobject, metaclass=ConvertToOpenGL):
 
         Returns
         -------
-        SkiaPath:
+        SkiaPath
             The converted path.
         """
         path = SkiaPath()
 
-        if not np.all(np.isfinite(vmobject.points)):
-            points = np.zeros((1, 3))  # point invalid?
-        else:
+        if np.all(np.isfinite(vmobject.points)):
             points = vmobject.points
+        else:
+            points = np.zeros((1, 3))  # point invalid?
 
         if len(points) == 0:  # what? No points so return empty path
             return path
@@ -90,17 +91,17 @@ class _BooleanOps(VMobject, metaclass=ConvertToOpenGL):
                 quads = vmobject.get_bezier_tuples_from_points(subpath)
                 start = subpath[0]
                 path.moveTo(*start[:2])
-                for p0, p1, p2 in quads:
+                for _p0, p1, p2 in quads:
                     path.quadTo(*p1[:2], *p2[:2])
                 if vmobject.consider_points_equals(subpath[0], subpath[-1]):
                     path.close()
         elif config.renderer == RendererType.CAIRO:
-            subpaths = vmobject.gen_subpaths_from_points_2d(points)
+            subpaths = vmobject.gen_subpaths_from_points_2d(points)  # type: ignore[assignment]
             for subpath in subpaths:
                 quads = vmobject.gen_cubic_bezier_tuples_from_points(subpath)
                 start = subpath[0]
                 path.moveTo(*start[:2])
-                for p0, p1, p2, p3 in quads:
+                for _p0, p1, p2, p3 in quads:
                     path.cubicTo(*p1[:2], *p2[:2], *p3[:2])
 
                 if vmobject.consider_points_equals_2d(subpath[0], subpath[-1]):
@@ -142,7 +143,7 @@ class _BooleanOps(VMobject, metaclass=ConvertToOpenGL):
                 n1, n2 = self._convert_2d_to_3d_array(points)
                 vmobject.add_quadratic_bezier_curve_to(n1, n2)
             else:
-                raise Exception("Unsupported: %s" % path_verb)
+                raise Exception(f"Unsupported: {path_verb}")
         return vmobject
 
 
@@ -177,7 +178,7 @@ class Union(_BooleanOps):
 
     """
 
-    def __init__(self, *vmobjects: VMobject, **kwargs) -> None:
+    def __init__(self, *vmobjects: VMobject, **kwargs: Any) -> None:
         if len(vmobjects) < 2:
             raise ValueError("At least 2 mobjects needed for Union.")
         super().__init__(**kwargs)
@@ -216,7 +217,7 @@ class Difference(_BooleanOps):
 
     """
 
-    def __init__(self, subject, clip, **kwargs) -> None:
+    def __init__(self, subject: VMobject, clip: VMobject, **kwargs: Any) -> None:
         super().__init__(**kwargs)
         outpen = SkiaPath()
         difference(
@@ -258,7 +259,7 @@ class Intersection(_BooleanOps):
 
     """
 
-    def __init__(self, *vmobjects, **kwargs) -> None:
+    def __init__(self, *vmobjects: VMobject, **kwargs: Any) -> None:
         if len(vmobjects) < 2:
             raise ValueError("At least 2 mobjects needed for Intersection.")
 
@@ -311,7 +312,7 @@ class Exclusion(_BooleanOps):
 
     """
 
-    def __init__(self, subject, clip, **kwargs) -> None:
+    def __init__(self, subject: VMobject, clip: VMobject, **kwargs: Any) -> None:
         super().__init__(**kwargs)
         outpen = SkiaPath()
         xor(

manim/mobject/geometry/labeled.py

@@ -0,0 +1,376 @@
+r"""Mobjects that inherit from lines and contain a label along the length."""
+
+from __future__ import annotations
+
+__all__ = ["Label", "LabeledLine", "LabeledArrow", "LabeledPolygram"]
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from manim.constants import *
+from manim.mobject.geometry.line import Arrow, Line
+from manim.mobject.geometry.polygram import Polygram
+from manim.mobject.geometry.shape_matchers import (
+    BackgroundRectangle,
+    SurroundingRectangle,
+)
+from manim.mobject.text.tex_mobject import MathTex, Tex
+from manim.mobject.text.text_mobject import Text
+from manim.mobject.types.vectorized_mobject import VGroup
+from manim.utils.color import WHITE
+from manim.utils.polylabel import polylabel
+
+if TYPE_CHECKING:
+    from manim.typing import Point3DLike_Array
+
+
+class Label(VGroup):
+    """A Label consisting of text surrounded by a frame.
+
+    Parameters
+    ----------
+    label
+        Label that will be displayed.
+    label_config
+        A dictionary containing the configuration for the label.
+        This is only applied if ``label`` is of type ``str``.
+    box_config
+        A dictionary containing the configuration for the background box.
+    frame_config
+         A dictionary containing the configuration for the frame.
+
+    Examples
+    --------
+    .. manim:: LabelExample
+        :save_last_frame:
+        :quality: high
+
+        class LabelExample(Scene):
+            def construct(self):
+                label = Label(
+                    label=Text('Label Text', font='sans-serif'),
+                    box_config = {
+                        "color" : BLUE,
+                        "fill_opacity" : 0.75
+                    }
+                )
+                label.scale(3)
+                self.add(label)
+    """
+
+    def __init__(
+        self,
+        label: str | Tex | MathTex | Text,
+        label_config: dict[str, Any] | None = None,
+        box_config: dict[str, Any] | None = None,
+        frame_config: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+
+        # Setup Defaults
+        default_label_config: dict[str, Any] = {
+            "color": WHITE,
+            "font_size": DEFAULT_FONT_SIZE,
+        }
+
+        default_box_config: dict[str, Any] = {
+            "color": None,
+            "buff": 0.05,
+            "fill_opacity": 1,
+            "stroke_width": 0.5,
+        }
+
+        default_frame_config: dict[str, Any] = {
+            "color": WHITE,
+            "buff": 0.05,
+            "stroke_width": 0.5,
+        }
+
+        # Merge Defaults
+        label_config = default_label_config | (label_config or {})
+        box_config = default_box_config | (box_config or {})
+        frame_config = default_frame_config | (frame_config or {})
+
+        # Determine the type of label and instantiate the appropriate object
+        self.rendered_label: MathTex | Tex | Text
+        if isinstance(label, str):
+            self.rendered_label = MathTex(label, **label_config)
+        elif isinstance(label, (MathTex, Tex, Text)):
+            self.rendered_label = label
+        else:
+            raise TypeError("Unsupported label type. Must be MathTex, Tex, or Text.")
+
+        # Add a background box
+        self.background_rect = BackgroundRectangle(self.rendered_label, **box_config)
+
+        # Add a frame around the label
+        self.frame = SurroundingRectangle(self.rendered_label, **frame_config)
+
+        # Add components to the VGroup
+        self.add(self.background_rect, self.rendered_label, self.frame)
+
+
+class LabeledLine(Line):
+    """Constructs a line containing a label box somewhere along its length.
+
+    Parameters
+    ----------
+    label
+        Label that will be displayed on the line.
+    label_position
+        A ratio in the range [0-1] to indicate the position of the label with respect to the length of the line. Default value is 0.5.
+    label_config
+        A dictionary containing the configuration for the label.
+        This is only applied if ``label`` is of type ``str``.
+    box_config
+        A dictionary containing the configuration for the background box.
+    frame_config
+         A dictionary containing the configuration for the frame.
+
+        .. seealso::
+            :class:`LabeledArrow`
+
+    Examples
+    --------
+    .. manim:: LabeledLineExample
+        :save_last_frame:
+        :quality: high
+
+        class LabeledLineExample(Scene):
+            def construct(self):
+                line = LabeledLine(
+                    label          = '0.5',
+                    label_position = 0.8,
+                    label_config = {
+                        "font_size" : 20
+                    },
+                    start=LEFT+DOWN,
+                    end=RIGHT+UP)
+
+                line.set_length(line.get_length() * 2)
+                self.add(line)
+    """
+
+    def __init__(
+        self,
+        label: str | Tex | MathTex | Text,
+        label_position: float = 0.5,
+        label_config: dict[str, Any] | None = None,
+        box_config: dict[str, Any] | None = None,
+        frame_config: dict[str, Any] | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+
+        # Create Label
+        self.label = Label(
+            label=label,
+            label_config=label_config,
+            box_config=box_config,
+            frame_config=frame_config,
+        )
+
+        # Compute Label Position
+        line_start, line_end = self.get_start_and_end()
+        new_vec = (line_end - line_start) * label_position
+        label_coords = line_start + new_vec
+
+        self.label.move_to(label_coords)
+        self.add(self.label)
+
+
+class LabeledArrow(LabeledLine, Arrow):
+    """Constructs an arrow containing a label box somewhere along its length.
+    This class inherits its label properties from `LabeledLine`, so the main parameters controlling it are the same.
+
+    Parameters
+    ----------
+    label
+        Label that will be displayed on the Arrow.
+    label_position
+        A ratio in the range [0-1] to indicate the position of the label with respect to the length of the line. Default value is 0.5.
+    label_config
+        A dictionary containing the configuration for the label.
+        This is only applied if ``label`` is of type ``str``.
+    box_config
+        A dictionary containing the configuration for the background box.
+    frame_config
+         A dictionary containing the configuration for the frame.
+
+        .. seealso::
+            :class:`LabeledLine`
+
+    Examples
+    --------
+    .. manim:: LabeledArrowExample
+        :save_last_frame:
+        :quality: high
+
+        class LabeledArrowExample(Scene):
+            def construct(self):
+                l_arrow = LabeledArrow("0.5", start=LEFT*3, end=RIGHT*3 + UP*2, label_position=0.5)
+
+                self.add(l_arrow)
+    """
+
+    def __init__(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+
+
+class LabeledPolygram(Polygram):
+    """Constructs a polygram containing a label box at its pole of inaccessibility.
+
+    Parameters
+    ----------
+    vertex_groups
+        Vertices passed to the :class:`~.Polygram` constructor.
+    label
+        Label that will be displayed on the Polygram.
+    precision
+        The precision used by the PolyLabel algorithm.
+    label_config
+        A dictionary containing the configuration for the label.
+        This is only applied if ``label`` is of type ``str``.
+    box_config
+        A dictionary containing the configuration for the background box.
+    frame_config
+         A dictionary containing the configuration for the frame.
+
+        .. note::
+            The PolyLabel Algorithm expects each vertex group to form a closed ring.
+            If the input is open, :class:`LabeledPolygram` will attempt to close it.
+            This may cause the polygon to intersect itself leading to unexpected results.
+
+        .. tip::
+            Make sure the precision corresponds to the scale of your inputs!
+            For instance, if the bounding box of your polygon stretches from 0 to 10,000, a precision of 1.0 or 10.0 should be sufficient.
+
+    Examples
+    --------
+    .. manim:: LabeledPolygramExample
+        :save_last_frame:
+        :quality: high
+
+        class LabeledPolygramExample(Scene):
+            def construct(self):
+                # Define Rings
+                ring1 = [
+                    [-3.8, -2.4, 0], [-2.4, -2.5, 0], [-1.3, -1.6, 0], [-0.2, -1.7, 0],
+                    [1.7, -2.5, 0], [2.9, -2.6, 0], [3.5, -1.5, 0], [4.9, -1.4, 0],
+                    [4.5, 0.2, 0], [4.7, 1.6, 0], [3.5, 2.4, 0], [1.1, 2.5, 0],
+                    [-0.1, 0.9, 0], [-1.2, 0.5, 0], [-1.6, 0.7, 0], [-1.4, 1.9, 0],
+                    [-2.6, 2.6, 0], [-4.4, 1.2, 0], [-4.9, -0.8, 0], [-3.8, -2.4, 0]
+                ]
+                ring2 = [
+                    [0.2, -1.2, 0], [0.9, -1.2, 0], [1.4, -2.0, 0], [2.1, -1.6, 0],
+                    [2.2, -0.5, 0], [1.4, 0.0, 0], [0.4, -0.2, 0], [0.2, -1.2, 0]
+                ]
+                ring3 = [[-2.7, 1.4, 0], [-2.3, 1.7, 0], [-2.8, 1.9, 0], [-2.7, 1.4, 0]]
+
+                # Create Polygons (for reference)
+                p1 = Polygon(*ring1, fill_opacity=0.75)
+                p2 = Polygon(*ring2, fill_color=BLACK, fill_opacity=1)
+                p3 = Polygon(*ring3, fill_color=BLACK, fill_opacity=1)
+
+                # Create Labeled Polygram
+                polygram = LabeledPolygram(
+                    *[ring1, ring2, ring3],
+                    label=Text('Pole', font='sans-serif'),
+                    precision=0.01,
+                )
+
+                # Display Circle (for reference)
+                circle = Circle(radius=polygram.radius, color=WHITE).move_to(polygram.pole)
+
+                self.add(p1, p2, p3)
+                self.add(polygram)
+                self.add(circle)
+
+    .. manim:: LabeledCountryExample
+        :save_last_frame:
+        :quality: high
+
+        import requests
+        import json
+
+        class LabeledCountryExample(Scene):
+            def construct(self):
+                # Fetch JSON data and process arcs
+                data = requests.get('https://cdn.jsdelivr.net/npm/us-atlas@3/nation-10m.json').json()
+                arcs, transform = data['arcs'], data['transform']
+                sarcs = [np.cumsum(arc, axis=0) * transform['scale'] + transform['translate'] for arc in arcs]
+                ssarcs = sorted(sarcs, key=len, reverse=True)[:1]
+
+                # Compute Bounding Box
+                points = np.concatenate(ssarcs)
+                mins, maxs = np.min(points, axis=0), np.max(points, axis=0)
+
+                # Build Axes
+                ax = Axes(
+                    x_range=[mins[0], maxs[0], maxs[0] - mins[0]], x_length=10,
+                    y_range=[mins[1], maxs[1], maxs[1] - mins[1]], y_length=7,
+                    tips=False
+                )
+
+                # Adjust Coordinates
+                array = [[ax.c2p(*point) for point in sarc] for sarc in ssarcs]
+
+                # Add Polygram
+                polygram = LabeledPolygram(
+                    *array,
+                    label=Text('USA', font='sans-serif'),
+                    precision=0.01,
+                    fill_color=BLUE,
+                    stroke_width=0,
+                    fill_opacity=0.75
+                )
+
+                # Display Circle (for reference)
+                circle = Circle(radius=polygram.radius, color=WHITE).move_to(polygram.pole)
+
+                self.add(ax)
+                self.add(polygram)
+                self.add(circle)
+    """
+
+    def __init__(
+        self,
+        *vertex_groups: Point3DLike_Array,
+        label: str | Tex | MathTex | Text,
+        precision: float = 0.01,
+        label_config: dict[str, Any] | None = None,
+        box_config: dict[str, Any] | None = None,
+        frame_config: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Initialize the Polygram with the vertex groups
+        super().__init__(*vertex_groups, **kwargs)
+
+        # Create Label
+        self.label = Label(
+            label=label,
+            label_config=label_config,
+            box_config=box_config,
+            frame_config=frame_config,
+        )
+
+        # Close Vertex Groups
+        rings = [
+            group if np.array_equal(group[0], group[-1]) else list(group) + [group[0]]
+            for group in vertex_groups
+        ]
+
+        # Compute the Pole of Inaccessibility
+        cell = polylabel(rings, precision=precision)
+        self.pole, self.radius = np.pad(cell.c, (0, 1), "constant"), cell.d
+
+        # Position the label at the pole
+        self.label.move_to(self.pole)
+        self.add(self.label)