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

manim/mobject/geometry/polygram.py

@@ -13,21 +13,36 @@ __all__ = [
     "Square",
     "RoundedRectangle",
     "Cutout",
+    "ConvexHull",
 ]
 
-from typing import Iterable, Sequence
+
+from math import ceil
+from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
-from colour import Color
 
 from manim.constants import *
 from manim.mobject.geometry.arc import ArcBetweenPoints
 from manim.mobject.opengl.opengl_compatibility import ConvertToOpenGL
 from manim.mobject.types.vectorized_mobject import VGroup, VMobject
-from manim.utils.color import *
+from manim.utils.color import BLUE, WHITE, ParsableManimColor
 from manim.utils.iterables import adjacent_n_tuples, adjacent_pairs
+from manim.utils.qhull import QuickHull
 from manim.utils.space_ops import angle_between_vectors, normalize, regular_vertices
 
+if TYPE_CHECKING:
+    import numpy.typing as npt
+    from typing_extensions import Self
+
+    from manim.typing import (
+        Point3D,
+        Point3D_Array,
+        Point3DLike,
+        Point3DLike_Array,
+    )
+    from manim.utils.color import ParsableManimColor
+
 
 class Polygram(VMobject, metaclass=ConvertToOpenGL):
     """A generalized :class:`Polygon`, allowing for disconnected sets of edges.
@@ -64,10 +79,17 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
                 self.wait()
     """
 
-    def __init__(self, *vertex_groups: Iterable[Sequence[float]], color=BLUE, **kwargs):
+    def __init__(
+        self,
+        *vertex_groups: Point3DLike_Array,
+        color: ParsableManimColor = BLUE,
+        **kwargs: Any,
+    ):
         super().__init__(color=color, **kwargs)
 
         for vertices in vertex_groups:
+            # The inferred type for *vertices is Any, but it should be
+            # Point3D_Array
             first_vertex, *vertices = vertices
             first_vertex = np.array(first_vertex)
 
@@ -76,7 +98,7 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
                 [*(np.array(vertex) for vertex in vertices), first_vertex],
             )
 
-    def get_vertices(self) -> np.ndarray:
+    def get_vertices(self) -> Point3D_Array:
         """Gets the vertices of the :class:`Polygram`.
 
         Returns
@@ -95,56 +117,94 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
                    [-1., -1.,  0.],
                    [ 1., -1.,  0.]])
         """
-
         return self.get_start_anchors()
 
-    def get_vertex_groups(self) -> np.ndarray:
+    def get_vertex_groups(self) -> list[Point3D_Array]:
         """Gets the vertex groups of the :class:`Polygram`.
 
         Returns
         -------
-        :class:`numpy.ndarray`
-            The vertex groups of the :class:`Polygram`.
+        list[Point3D_Array]
+            The list of vertex groups of the :class:`Polygram`.
 
         Examples
         --------
         ::
 
-            >>> poly = Polygram([ORIGIN, RIGHT, UP], [LEFT, LEFT + UP, 2 * LEFT])
-            >>> poly.get_vertex_groups()
-            array([[[ 0.,  0.,  0.],
-                    [ 1.,  0.,  0.],
-                    [ 0.,  1.,  0.]],
-            <BLANKLINE>
-                   [[-1.,  0.,  0.],
-                    [-1.,  1.,  0.],
-                    [-2.,  0.,  0.]]])
+            >>> poly = Polygram([ORIGIN, RIGHT, UP, LEFT + UP], [LEFT, LEFT + UP, 2 * LEFT])
+            >>> groups = poly.get_vertex_groups()
+            >>> len(groups)
+            2
+            >>> groups[0]
+            array([[ 0.,  0.,  0.],
+                   [ 1.,  0.,  0.],
+                   [ 0.,  1.,  0.],
+                   [-1.,  1.,  0.]])
+            >>> groups[1]
+            array([[-1.,  0.,  0.],
+                   [-1.,  1.,  0.],
+                   [-2.,  0.,  0.]])
         """
-
         vertex_groups = []
 
+        # TODO: If any of the original vertex groups contained the starting vertex N
+        # times, then .get_vertex_groups() splits it into N vertex groups.
         group = []
         for start, end in zip(self.get_start_anchors(), self.get_end_anchors()):
             group.append(start)
 
             if self.consider_points_equals(end, group[0]):
-                vertex_groups.append(group)
+                vertex_groups.append(np.array(group))
                 group = []
 
-        return np.array(vertex_groups)
+        return vertex_groups
 
-    def round_corners(self, radius: float = 0.5):
+    def round_corners(
+        self,
+        radius: float | list[float] = 0.5,
+        evenly_distribute_anchors: bool = False,
+        components_per_rounded_corner: int = 2,
+    ) -> Self:
         """Rounds off the corners of the :class:`Polygram`.
 
         Parameters
         ----------
         radius
             The curvature of the corners of the :class:`Polygram`.
+        evenly_distribute_anchors
+            Break long line segments into proportionally-sized segments.
+        components_per_rounded_corner
+            The number of points used to represent the rounded corner curve.
 
 
         .. seealso::
             :class:`.~RoundedRectangle`
 
+        .. note::
+            If `radius` is supplied as a single value, then the same radius
+            will be applied to all corners.  If `radius` is a list, then the
+            individual values will be applied sequentially, with the first
+            corner receiving `radius[0]`, the second corner receiving
+            `radius[1]`, etc.  The radius list will be repeated as necessary.
+
+            The `components_per_rounded_corner` value is provided so that the
+            fidelity of the rounded corner may be fine-tuned as needed.  2 is
+            an appropriate value for most shapes, however a larger value may be
+            need if the rounded corner is particularly large.  2 is the minimum
+            number allowed, representing the start and end of the curve.  3 will
+            result in a start, middle, and end point, meaning 2 curves will be
+            generated.
+
+            The option to `evenly_distribute_anchors` is provided so that the
+            line segments (the part part of each line remaining after rounding
+            off the corners) can be subdivided to a density similar to that of
+            the average density of the rounded corners.  This may be desirable
+            in situations in which an even distribution of curves is desired
+            for use in later transformation animations.  Be aware, though, that
+            enabling this option can result in an an object containing
+            significantly more points than the original, especially when the
+            rounded corner curves are small.
+
         Examples
         --------
         .. manim:: PolygramRoundCorners
@@ -161,15 +221,24 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
                     shapes.arrange(RIGHT)
                     self.add(shapes)
         """
-
         if radius == 0:
             return self
 
-        new_points = []
+        new_points: list[Point3D] = []
 
-        for vertices in self.get_vertex_groups():
+        for vertex_group in self.get_vertex_groups():
             arcs = []
-            for v1, v2, v3 in adjacent_n_tuples(vertices, 3):
+
+            # Repeat the radius list as necessary in order to provide a radius
+            # for each vertex.
+            if isinstance(radius, (int, float)):
+                radius_list = [radius] * len(vertex_group)
+            else:
+                radius_list = radius * ceil(len(vertex_group) / len(radius))
+
+            for current_radius, (v1, v2, v3) in zip(
+                radius_list, adjacent_n_tuples(vertex_group, 3)
+            ):
                 vect1 = v2 - v1
                 vect2 = v3 - v2
                 unit_vect1 = normalize(vect1)
@@ -177,10 +246,10 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
 
                 angle = angle_between_vectors(vect1, vect2)
                 # Negative radius gives concave curves
-                angle *= np.sign(radius)
+                angle *= np.sign(current_radius)
 
                 # Distance between vertex and start of the arc
-                cut_off_length = radius * np.tan(angle / 2)
+                cut_off_length = current_radius * np.tan(angle / 2)
 
                 # Determines counterclockwise vs. clockwise
                 sign = np.sign(np.cross(vect1, vect2)[2])
@@ -189,9 +258,24 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
                     v2 - unit_vect1 * cut_off_length,
                     v2 + unit_vect2 * cut_off_length,
                     angle=sign * angle,
+                    num_components=components_per_rounded_corner,
                 )
                 arcs.append(arc)
 
+            if evenly_distribute_anchors:
+                # Determine the average length of each curve
+                nonzero_length_arcs = [arc for arc in arcs if len(arc.points) > 4]
+                if len(nonzero_length_arcs) > 0:
+                    total_arc_length = sum(
+                        [arc.get_arc_length() for arc in nonzero_length_arcs]
+                    )
+                    num_curves = (
+                        sum([len(arc.points) for arc in nonzero_length_arcs]) / 4
+                    )
+                    average_arc_length = total_arc_length / num_curves
+                else:
+                    average_arc_length = 1.0
+
             # To ensure that we loop through starting with last
             arcs = [arcs[-1], *arcs[:-1]]
             from manim.mobject.geometry.line import Line
@@ -201,14 +285,13 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
 
                 line = Line(arc1.get_end(), arc2.get_start())
 
-                # Make sure anchors are evenly distributed
-                len_ratio = line.get_length() / arc1.get_arc_length()
-
-                line.insert_n_curves(int(arc1.get_num_curves() * len_ratio))
+                # Make sure anchors are evenly distributed, if necessary
+                if evenly_distribute_anchors:
+                    line.insert_n_curves(ceil(line.get_length() / average_arc_length))
 
                 new_points.extend(line.points)
 
-        self.set_points(new_points)
+        self.set_points(np.array(new_points))
 
         return self
 
@@ -243,7 +326,7 @@ class Polygon(Polygram):
                 self.add(isosceles, square_and_triangles)
     """
 
-    def __init__(self, *vertices: Sequence[float], **kwargs):
+    def __init__(self, *vertices: Point3DLike, **kwargs: Any) -> None:
         super().__init__(vertices, **kwargs)
 
 
@@ -286,8 +369,8 @@ class RegularPolygram(Polygram):
         density: int = 2,
         radius: float = 1,
         start_angle: float | None = None,
-        **kwargs,
-    ):
+        **kwargs: Any,
+    ) -> None:
         # Regular polygrams can be expressed by the number of their vertices
         # and their density. This relation can be expressed as its Schläfli
         # symbol: {num_vertices/density}.
@@ -307,7 +390,7 @@ class RegularPolygram(Polygram):
 
         # Utility function for generating the individual
         # polygon vertices.
-        def gen_polygon_vertices(start_angle):
+        def gen_polygon_vertices(start_angle: float | None) -> tuple[list[Any], float]:
             reg_vertices, start_angle = regular_vertices(
                 num_vertices,
                 radius=radius,
@@ -363,7 +446,7 @@ class RegularPolygon(RegularPolygram):
                 self.add(poly_group)
     """
 
-    def __init__(self, n: int = 6, **kwargs):
+    def __init__(self, n: int = 6, **kwargs: Any) -> None:
         super().__init__(n, density=1, **kwargs)
 
 
@@ -403,7 +486,6 @@ class Star(Polygon):
     Examples
     --------
     .. manim:: StarExample
-        :save_as_gif:
 
         class StarExample(Scene):
             def construct(self):
@@ -434,8 +516,8 @@ class Star(Polygon):
         inner_radius: float | None = None,
         density: int = 2,
         start_angle: float | None = TAU / 4,
-        **kwargs,
-    ):
+        **kwargs: Any,
+    ) -> None:
         inner_angle = TAU / (2 * n)
 
         if inner_radius is None:
@@ -466,7 +548,7 @@ class Star(Polygon):
             start_angle=self.start_angle + inner_angle,
         )
 
-        vertices = []
+        vertices: list[npt.NDArray] = []
         for pair in zip(outer_vertices, inner_vertices):
             vertices.extend(pair)
 
@@ -494,7 +576,7 @@ class Triangle(RegularPolygon):
                 self.add(tri_group)
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any) -> None:
         super().__init__(n=3, **kwargs)
 
 
@@ -529,29 +611,37 @@ class Rectangle(Polygon):
             def construct(self):
                 rect1 = Rectangle(width=4.0, height=2.0, grid_xstep=1.0, grid_ystep=0.5)
                 rect2 = Rectangle(width=1.0, height=4.0)
+                rect3 = Rectangle(width=2.0, height=2.0, grid_xstep=1.0, grid_ystep=1.0)
+                rect3.grid_lines.set_stroke(width=1)
 
-                rects = Group(rect1,rect2).arrange(buff=1)
+                rects = Group(rect1, rect2, rect3).arrange(buff=1)
                 self.add(rects)
     """
 
     def __init__(
         self,
-        color: Color = WHITE,
+        color: ParsableManimColor = WHITE,
         height: float = 2.0,
         width: float = 4.0,
         grid_xstep: float | None = None,
         grid_ystep: float | None = None,
         mark_paths_closed: bool = True,
         close_new_points: bool = True,
-        **kwargs,
+        **kwargs: Any,
     ):
         super().__init__(UR, UL, DL, DR, color=color, **kwargs)
         self.stretch_to_fit_width(width)
         self.stretch_to_fit_height(height)
+
         v = self.get_vertices()
-        if grid_xstep is not None:
+        self.grid_lines = VGroup()
+
+        if grid_xstep or grid_ystep:
             from manim.mobject.geometry.line import Line
 
+            v = self.get_vertices()
+
+        if grid_xstep:
             grid_xstep = abs(grid_xstep)
             count = int(width / grid_xstep)
             grid = VGroup(
@@ -564,8 +654,9 @@ class Rectangle(Polygon):
                     for i in range(1, count)
                 )
             )
-            self.add(grid)
-        if grid_ystep is not None:
+            self.grid_lines.add(grid)
+
+        if grid_ystep:
             grid_ystep = abs(grid_ystep)
             count = int(height / grid_ystep)
             grid = VGroup(
@@ -578,7 +669,10 @@ class Rectangle(Polygon):
                     for i in range(1, count)
                 )
             )
-            self.add(grid)
+            self.grid_lines.add(grid)
+
+        if self.grid_lines:
+            self.add(self.grid_lines)
 
 
 class Square(Rectangle):
@@ -604,10 +698,17 @@ class Square(Rectangle):
                 self.add(square_1, square_2, square_3)
     """
 
-    def __init__(self, side_length: float = 2.0, **kwargs):
-        self.side_length = side_length
+    def __init__(self, side_length: float = 2.0, **kwargs: Any) -> None:
         super().__init__(height=side_length, width=side_length, **kwargs)
 
+    @property
+    def side_length(self) -> float:
+        return float(np.linalg.norm(self.get_vertices()[0] - self.get_vertices()[1]))
+
+    @side_length.setter
+    def side_length(self, value: float) -> None:
+        self.scale(value / self.side_length)
+
 
 class RoundedRectangle(Rectangle):
     """A rectangle with rounded corners.
@@ -633,7 +734,7 @@ class RoundedRectangle(Rectangle):
                 self.add(rect_group)
     """
 
-    def __init__(self, corner_radius: float = 0.5, **kwargs):
+    def __init__(self, corner_radius: float | list[float] = 0.5, **kwargs: Any):
         super().__init__(**kwargs)
         self.corner_radius = corner_radius
         self.round_corners(self.corner_radius)
@@ -674,12 +775,77 @@ class Cutout(VMobject, metaclass=ConvertToOpenGL):
                 self.wait()
     """
 
-    def __init__(self, main_shape: VMobject, *mobjects: VMobject, **kwargs):
+    def __init__(
+        self, main_shape: VMobject, *mobjects: VMobject, **kwargs: Any
+    ) -> None:
         super().__init__(**kwargs)
         self.append_points(main_shape.points)
-        if main_shape.get_direction() == "CW":
-            sub_direction = "CCW"
-        else:
-            sub_direction = "CW"
+        sub_direction: Literal["CCW", "CW"] = (
+            "CCW" if main_shape.get_direction() == "CW" else "CW"
+        )
         for mobject in mobjects:
             self.append_points(mobject.force_direction(sub_direction).points)
+
+
+class ConvexHull(Polygram):
+    """Constructs a convex hull for a set of points in no particular order.
+
+    Parameters
+    ----------
+    points
+        The points to consider.
+    tolerance
+        The tolerance used by quickhull.
+    kwargs
+        Forwarded to the parent constructor.
+
+    Examples
+    --------
+    .. manim:: ConvexHullExample
+        :save_last_frame:
+        :quality: high
+
+        class ConvexHullExample(Scene):
+            def construct(self):
+                points = [
+                    [-2.35, -2.25, 0],
+                    [1.65, -2.25, 0],
+                    [2.65, -0.25, 0],
+                    [1.65, 1.75, 0],
+                    [-0.35, 2.75, 0],
+                    [-2.35, 0.75, 0],
+                    [-0.35, -1.25, 0],
+                    [0.65, -0.25, 0],
+                    [-1.35, 0.25, 0],
+                    [0.15, 0.75, 0]
+                ]
+                hull = ConvexHull(*points, color=BLUE)
+                dots = VGroup(*[Dot(point) for point in points])
+                self.add(hull)
+                self.add(dots)
+    """
+
+    def __init__(
+        self, *points: Point3DLike, tolerance: float = 1e-5, **kwargs: Any
+    ) -> None:
+        # Build Convex Hull
+        array = np.array(points)[:, :2]
+        hull = QuickHull(tolerance)
+        hull.build(array)
+
+        # Extract Vertices
+        facets = set(hull.facets) - hull.removed
+        facet = facets.pop()
+        subfacets = list(facet.subfacets)
+        while len(subfacets) <= len(facets):
+            sf = subfacets[-1]
+            (facet,) = hull.neighbors[sf] - {facet}
+            (sf,) = facet.subfacets - {sf}
+            subfacets.append(sf)
+
+        # Setup Vertices as Point3D
+        coordinates = np.vstack([sf.coordinates for sf in subfacets])
+        vertices = np.hstack((coordinates, np.zeros((len(coordinates), 1))))
+
+        # Call Polygram
+        super().__init__(vertices, **kwargs)

manim/mobject/geometry/shape_matchers.py

@@ -4,13 +4,25 @@ from __future__ import annotations
 
 __all__ = ["SurroundingRectangle", "BackgroundRectangle", "Cross", "Underline"]
 
-from manim import config, logger
-from manim.constants import *
+from typing import Any
+
+from typing_extensions import Self
+
+from manim import logger
+from manim._config import config
+from manim.constants import (
+    DOWN,
+    LEFT,
+    RIGHT,
+    SMALL_BUFF,
+    UP,
+)
 from manim.mobject.geometry.line import Line
 from manim.mobject.geometry.polygram import RoundedRectangle
 from manim.mobject.mobject import Mobject
+from manim.mobject.opengl.opengl_mobject import OpenGLMobject
 from manim.mobject.types.vectorized_mobject import VGroup
-from manim.utils.color import BLACK, RED, YELLOW, Color, Colors
+from manim.utils.color import BLACK, RED, YELLOW, ManimColor, ParsableManimColor
 
 
 class SurroundingRectangle(RoundedRectangle):
@@ -38,17 +50,36 @@ class SurroundingRectangle(RoundedRectangle):
     """
 
     def __init__(
-        self, mobject, color=YELLOW, buff=SMALL_BUFF, corner_radius=0.0, **kwargs
-    ):
+        self,
+        *mobjects: Mobject,
+        color: ParsableManimColor = YELLOW,
+        buff: float | tuple[float, float] = SMALL_BUFF,
+        corner_radius: float = 0.0,
+        **kwargs: Any,
+    ) -> None:
+        from manim.mobject.mobject import Group
+
+        if not all(isinstance(mob, (Mobject, OpenGLMobject)) for mob in mobjects):
+            raise TypeError(
+                "Expected all inputs for parameter mobjects to be a Mobjects"
+            )
+
+        if isinstance(buff, tuple):
+            buff_x = buff[0]
+            buff_y = buff[1]
+        else:
+            buff_x = buff_y = buff
+
+        group = Group(*mobjects)
         super().__init__(
             color=color,
-            width=mobject.width + 2 * buff,
-            height=mobject.height + 2 * buff,
+            width=group.width + 2 * buff_x,
+            height=group.height + 2 * buff_y,
             corner_radius=corner_radius,
             **kwargs,
         )
         self.buff = buff
-        self.move_to(mobject)
+        self.move_to(group)
 
 
 class BackgroundRectangle(SurroundingRectangle):
@@ -78,19 +109,19 @@ class BackgroundRectangle(SurroundingRectangle):
 
     def __init__(
         self,
-        mobject,
-        color: Colors | None = None,
+        *mobjects: Mobject,
+        color: ParsableManimColor | None = None,
         stroke_width: float = 0,
         stroke_opacity: float = 0,
         fill_opacity: float = 0.75,
-        buff: float = 0,
-        **kwargs,
-    ):
+        buff: float | tuple[float, float] = 0,
+        **kwargs: Any,
+    ) -> None:
         if color is None:
             color = config.background_color
 
         super().__init__(
-            mobject,
+            *mobjects,
             color=color,
             stroke_width=stroke_width,
             stroke_opacity=stroke_opacity,
@@ -98,13 +129,13 @@ class BackgroundRectangle(SurroundingRectangle):
             buff=buff,
             **kwargs,
         )
-        self.original_fill_opacity = self.fill_opacity
+        self.original_fill_opacity: float = self.fill_opacity
 
-    def pointwise_become_partial(self, mobject, a, b):
+    def pointwise_become_partial(self, mobject: Mobject, a: Any, b: float) -> Self:
         self.set_fill(opacity=b * self.original_fill_opacity)
         return self
 
-    def set_style(self, fill_opacity, **kwargs):
+    def set_style(self, fill_opacity: float, **kwargs: Any) -> Self:  # type: ignore[override]
         # Unchangeable style, except for fill_opacity
         # All other style arguments are ignored
         super().set_style(
@@ -120,8 +151,11 @@ class BackgroundRectangle(SurroundingRectangle):
             )
         return self
 
-    def get_fill_color(self):
-        return Color(self.color)
+    def get_fill_color(self) -> ManimColor:
+        # The type of the color property is set to Any using the property decorator
+        # vectorized_mobject.py#L571
+        temp_color: ManimColor = self.color
+        return temp_color
 
 
 class Cross(VGroup):
@@ -152,11 +186,11 @@ class Cross(VGroup):
     def __init__(
         self,
         mobject: Mobject | None = None,
-        stroke_color: Color = RED,
-        stroke_width: float = 6,
-        scale_factor: float = 1,
-        **kwargs,
-    ):
+        stroke_color: ParsableManimColor = RED,
+        stroke_width: float = 6.0,
+        scale_factor: float = 1.0,
+        **kwargs: Any,
+    ) -> None:
         super().__init__(
             Line(UP + LEFT, DOWN + RIGHT), Line(UP + RIGHT, DOWN + LEFT), **kwargs
         )
@@ -181,7 +215,9 @@ class Underline(Line):
                 self.add(man, ul)
     """
 
-    def __init__(self, mobject, buff=SMALL_BUFF, **kwargs):
+    def __init__(
+        self, mobject: Mobject, buff: float = SMALL_BUFF, **kwargs: Any
+    ) -> None:
         super().__init__(LEFT, RIGHT, buff=buff, **kwargs)
         self.match_width(mobject)
         self.next_to(mobject, DOWN, buff=self.buff)