manim 0.17.3__py3-none-any.whl → 0.18.0.post0__py3-none-any.whl

manim/mobject/geometry/labeled.py

@@ -0,0 +1,155 @@
+r"""Mobjects that inherit from lines and contain a label along the length."""
+
+from __future__ import annotations
+
+__all__ = ["LabeledLine", "LabeledArrow"]
+
+from manim.constants import *
+from manim.mobject.geometry.line import Arrow, Line
+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.utils.color import WHITE, ManimColor, ParsableManimColor
+
+
+class LabeledLine(Line):
+    """Constructs a line containing a label box somewhere along its length.
+
+    Parameters
+    ----------
+    label : str | Tex | MathTex | Text
+        Label that will be displayed on the line.
+    label_position : float | optional
+        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.
+    font_size : float | optional
+        Control font size for the label. This parameter is only used when `label` is of type `str`.
+    label_color: ParsableManimColor | optional
+        The color of the label's text. This parameter is only used when `label` is of type `str`.
+    label_frame : Bool | optional
+        Add a `SurroundingRectangle` frame to the label box.
+    frame_fill_color : ParsableManimColor | optional
+        Background color to fill the label box. If no value is provided, the background color of the canvas will be used.
+    frame_fill_opacity : float | optional
+        Determine the opacity of the label box by passing a value in the range [0-1], where 0 indicates complete transparency and 1 means full opacity.
+
+    .. seealso::
+        :class:`LabeledArrow`
+
+    Examples
+    --------
+    .. manim:: LabeledLineExample
+        :save_last_frame:
+
+        class LabeledLineExample(Scene):
+            def construct(self):
+                line = LabeledLine(
+                    label          = '0.5',
+                    label_position = 0.8,
+                    font_size      = 20,
+                    label_color    = WHITE,
+                    label_frame    = True,
+
+                    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,
+        font_size: float = DEFAULT_FONT_SIZE,
+        label_color: ParsableManimColor = WHITE,
+        label_frame: bool = True,
+        frame_fill_color: ParsableManimColor = None,
+        frame_fill_opacity: float = 1,
+        *args,
+        **kwargs,
+    ) -> None:
+        label_color = ManimColor(label_color)
+        frame_fill_color = ManimColor(frame_fill_color)
+        if isinstance(label, str):
+            from manim import MathTex
+
+            rendered_label = MathTex(label, color=label_color, font_size=font_size)
+        else:
+            rendered_label = label
+
+        super().__init__(*args, **kwargs)
+
+        # calculating the vector for the 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
+
+        # rendered_label.move_to(self.get_vector() * label_position)
+        rendered_label.move_to(label_coords)
+
+        box = BackgroundRectangle(
+            rendered_label,
+            buff=0.05,
+            color=frame_fill_color,
+            fill_opacity=frame_fill_opacity,
+            stroke_width=0.5,
+        )
+        self.add(box)
+
+        if label_frame:
+            box_frame = SurroundingRectangle(
+                rendered_label, buff=0.05, color=label_color, stroke_width=0.5
+            )
+
+            self.add(box_frame)
+
+        self.add(rendered_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 : str | Tex | MathTex | Text
+        Label that will be displayed on the line.
+    label_position : float | optional
+        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.
+    font_size : float | optional
+        Control font size for the label. This parameter is only used when `label` is of type `str`.
+    label_color: ParsableManimColor | optional
+        The color of the label's text. This parameter is only used when `label` is of type `str`.
+    label_frame : Bool | optional
+        Add a `SurroundingRectangle` frame to the label box.
+    frame_fill_color : ParsableManimColor | optional
+        Background color to fill the label box. If no value is provided, the background color of the canvas will be used.
+    frame_fill_opacity : float | optional
+        Determine the opacity of the label box by passing a value in the range [0-1], where 0 indicates complete transparency and 1 means full opacity.
+
+
+    .. seealso::
+        :class:`LabeledLine`
+
+    Examples
+    --------
+    .. manim:: LabeledArrowExample
+        :save_last_frame:
+
+        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,
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)

manim/mobject/geometry/line.py

@@ -14,10 +14,10 @@ __all__ = [
     "RightAngle",
 ]
 
-from typing import Any, Sequence
+from typing import TYPE_CHECKING
 
 import numpy as np
-from colour import Color
+from typing_extensions import Self
 
 from manim import config
 from manim.constants import *
@@ -27,20 +27,32 @@ from manim.mobject.mobject import Mobject
 from manim.mobject.opengl.opengl_compatibility import ConvertToOpenGL
 from manim.mobject.opengl.opengl_mobject import OpenGLMobject
 from manim.mobject.types.vectorized_mobject import DashedVMobject, VGroup, VMobject
-from manim.utils.color import *
-from manim.utils.color import Colors
+from manim.utils.color import WHITE
 from manim.utils.space_ops import angle_of_vector, line_intersection, normalize
 
+if TYPE_CHECKING:
+    from manim.typing import Point2D, Point3D, Vector
+    from manim.utils.color import ParsableManimColor
+
+    from ..matrix import Matrix  # Avoid circular import
+
 
 class Line(TipableVMobject):
-    def __init__(self, start=LEFT, end=RIGHT, buff=0, path_arc=None, **kwargs):
+    def __init__(
+        self,
+        start: Point3D = LEFT,
+        end: Point3D = RIGHT,
+        buff: float = 0,
+        path_arc: float | None = None,
+        **kwargs,
+    ) -> None:
         self.dim = 3
         self.buff = buff
         self.path_arc = path_arc
         self._set_start_and_end_attrs(start, end)
         super().__init__(**kwargs)
 
-    def generate_points(self):
+    def generate_points(self) -> None:
         self.set_points_by_ends(
             start=self.start,
             end=self.end,
@@ -48,7 +60,13 @@ class Line(TipableVMobject):
             path_arc=self.path_arc,
         )
 
-    def set_points_by_ends(self, start, end, buff=0, path_arc=0):
+    def set_points_by_ends(
+        self,
+        start: Point3D,
+        end: Point3D,
+        buff: float = 0,
+        path_arc: float = 0,
+    ) -> None:
         if path_arc:
             arc = ArcBetweenPoints(self.start, self.end, angle=self.path_arc)
             self.set_points(arc.points)
@@ -59,7 +77,7 @@ class Line(TipableVMobject):
 
     init_points = generate_points
 
-    def _account_for_buff(self, buff):
+    def _account_for_buff(self, buff: float) -> Self:
         if buff == 0:
             return
         #
@@ -74,7 +92,7 @@ class Line(TipableVMobject):
         self.pointwise_become_partial(self, buff_proportion, 1 - buff_proportion)
         return self
 
-    def _set_start_and_end_attrs(self, start, end):
+    def _set_start_and_end_attrs(self, start: Point3D, end: Point3D) -> None:
         # If either start or end are Mobjects, this
         # gives their centers
         rough_start = self._pointify(start)
@@ -88,9 +106,9 @@ class Line(TipableVMobject):
 
     def _pointify(
         self,
-        mob_or_point: Mobject | Sequence[float],
-        direction: Sequence[float] | None = None,
-    ) -> np.ndarray:
+        mob_or_point: Mobject | Point3D,
+        direction: Vector | None = None,
+    ) -> Point3D:
         """Transforms a mobject into its corresponding point. Does nothing if a point is passed.
 
         ``direction`` determines the location of the point along its bounding box in that direction.
@@ -110,11 +128,11 @@ class Line(TipableVMobject):
                 return mob.get_boundary_point(direction)
         return np.array(mob_or_point)
 
-    def set_path_arc(self, new_value):
+    def set_path_arc(self, new_value: float) -> None:
         self.path_arc = new_value
         self.init_points()
 
-    def put_start_and_end_on(self, start: Sequence[float], end: Sequence[float]):
+    def put_start_and_end_on(self, start: Point3D, end: Point3D) -> Self:
         """Sets starts and end coordinates of a line.
 
         Examples
@@ -145,16 +163,16 @@ class Line(TipableVMobject):
             self.generate_points()
         return super().put_start_and_end_on(start, end)
 
-    def get_vector(self):
+    def get_vector(self) -> Vector:
         return self.get_end() - self.get_start()
 
-    def get_unit_vector(self):
+    def get_unit_vector(self) -> Vector:
         return normalize(self.get_vector())
 
-    def get_angle(self):
+    def get_angle(self) -> float:
         return angle_of_vector(self.get_vector())
 
-    def get_projection(self, point: Sequence[float]) -> Sequence[float]:
+    def get_projection(self, point: Point3D) -> Vector:
         """Returns the projection of a point onto a line.
 
         Parameters
@@ -168,10 +186,10 @@ class Line(TipableVMobject):
         unit_vect = normalize(end - start)
         return start + np.dot(point - start, unit_vect) * unit_vect
 
-    def get_slope(self):
+    def get_slope(self) -> float:
         return np.tan(self.get_angle())
 
-    def set_angle(self, angle, about_point=None):
+    def set_angle(self, angle: float, about_point: Point3D | None = None) -> Self:
         if about_point is None:
             about_point = self.get_start()
 
@@ -182,7 +200,7 @@ class Line(TipableVMobject):
 
         return self
 
-    def set_length(self, length):
+    def set_length(self, length: float) -> Self:
         return self.scale(length / self.get_length())
 
 
@@ -222,11 +240,11 @@ class DashedLine(Line):
 
     def __init__(
         self,
-        *args: Any,
+        *args,
         dash_length: float = DEFAULT_DASH_LENGTH,
         dashed_ratio: float = 0.5,
         **kwargs,
-    ):
+    ) -> None:
         self.dash_length = dash_length
         self.dashed_ratio = dashed_ratio
         super().__init__(*args, **kwargs)
@@ -255,7 +273,7 @@ class DashedLine(Line):
             int(np.ceil((self.get_length() / self.dash_length) * self.dashed_ratio)),
         )
 
-    def get_start(self) -> np.ndarray:
+    def get_start(self) -> Point3D:
         """Returns the start point of the line.
 
         Examples
@@ -271,7 +289,7 @@ class DashedLine(Line):
         else:
             return super().get_start()
 
-    def get_end(self) -> np.ndarray:
+    def get_end(self) -> Point3D:
         """Returns the end point of the line.
 
         Examples
@@ -287,7 +305,7 @@ class DashedLine(Line):
         else:
             return super().get_end()
 
-    def get_first_handle(self) -> np.ndarray:
+    def get_first_handle(self) -> Point3D:
         """Returns the point of the first handle.
 
         Examples
@@ -300,7 +318,7 @@ class DashedLine(Line):
 
         return self.submobjects[0].points[1]
 
-    def get_last_handle(self) -> np.ndarray:
+    def get_last_handle(self) -> Point3D:
         """Returns the point of the last handle.
 
         Examples
@@ -354,7 +372,7 @@ class TangentLine(Line):
         length: float = 1,
         d_alpha: float = 1e-6,
         **kwargs,
-    ):
+    ) -> None:
         self.length = length
         self.d_alpha = d_alpha
         da = self.d_alpha
@@ -396,7 +414,7 @@ class Elbow(VMobject, metaclass=ConvertToOpenGL):
                 self.add(elbow_group)
     """
 
-    def __init__(self, width: float = 0.2, angle: float = 0, **kwargs):
+    def __init__(self, width: float = 0.2, angle: float = 0, **kwargs) -> None:
         self.angle = angle
         super().__init__(**kwargs)
         self.set_points_as_corners([UP, UP + RIGHT, RIGHT])
@@ -494,13 +512,13 @@ class Arrow(Line):
 
     def __init__(
         self,
-        *args: Any,
+        *args,
         stroke_width: float = 6,
         buff: float = MED_SMALL_BUFF,
         max_tip_length_to_length_ratio: float = 0.25,
         max_stroke_width_to_length_ratio: float = 5,
         **kwargs,
-    ):
+    ) -> None:
         self.max_tip_length_to_length_ratio = max_tip_length_to_length_ratio
         self.max_stroke_width_to_length_ratio = max_stroke_width_to_length_ratio
         tip_shape = kwargs.pop("tip_shape", ArrowTriangleFilledTip)
@@ -511,7 +529,7 @@ class Arrow(Line):
         self.add_tip(tip_shape=tip_shape)
         self._set_stroke_width_from_length()
 
-    def scale(self, factor, scale_tips=False, **kwargs):
+    def scale(self, factor: float, scale_tips: bool = False, **kwargs) -> Self:
         r"""Scale an arrow, but keep stroke width and arrow tip size fixed.
 
 
@@ -561,7 +579,7 @@ class Arrow(Line):
             self.add_tip(tip=old_tips[1], at_start=True)
         return self
 
-    def get_normal_vector(self) -> np.ndarray:
+    def get_normal_vector(self) -> Vector:
         """Returns the normal of a vector.
 
         Examples
@@ -575,7 +593,7 @@ class Arrow(Line):
         p0, p1, p2 = self.tip.get_start_anchors()[:3]
         return normalize(np.cross(p2 - p1, p1 - p0))
 
-    def reset_normal_vector(self):
+    def reset_normal_vector(self) -> Self:
         """Resets the normal of a vector"""
         self.normal_vector = self.get_normal_vector()
         return self
@@ -595,7 +613,7 @@ class Arrow(Line):
         max_ratio = self.max_tip_length_to_length_ratio
         return min(self.tip_length, max_ratio * self.get_length())
 
-    def _set_stroke_width_from_length(self):
+    def _set_stroke_width_from_length(self) -> Self:
         """Sets stroke width based on length."""
         max_ratio = self.max_stroke_width_to_length_ratio
         if config.renderer == RendererType.OPENGL:
@@ -636,7 +654,7 @@ class Vector(Arrow):
                 self.add(plane, vector_1, vector_2)
     """
 
-    def __init__(self, direction: list | np.ndarray = RIGHT, buff: float = 0, **kwargs):
+    def __init__(self, direction: Vector = RIGHT, buff: float = 0, **kwargs) -> None:
         self.buff = buff
         if len(direction) == 2:
             direction = np.hstack([direction, 0])
@@ -647,9 +665,9 @@ class Vector(Arrow):
         self,
         integer_labels: bool = True,
         n_dim: int = 2,
-        color: Color | None = None,
+        color: ParsableManimColor | None = None,
         **kwargs,
-    ):
+    ) -> Matrix:
         """Creates a label based on the coordinates of the vector.
 
         Parameters
@@ -752,7 +770,7 @@ class DoubleArrow(Arrow):
                 self.add(box, d1, d2, d3)
     """
 
-    def __init__(self, *args: Any, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
         if "tip_shape_end" in kwargs:
             kwargs["tip_shape"] = kwargs.pop("tip_shape_end")
         tip_shape_start = kwargs.pop("tip_shape_start", ArrowTriangleFilledTip)
@@ -873,16 +891,16 @@ class Angle(VMobject, metaclass=ConvertToOpenGL):
         self,
         line1: Line,
         line2: Line,
-        radius: float = None,
-        quadrant: Sequence[int] = (1, 1),
+        radius: float | None = None,
+        quadrant: Point2D = (1, 1),
         other_angle: bool = False,
         dot: bool = False,
         dot_radius: float | None = None,
         dot_distance: float = 0.55,
-        dot_color: Colors = WHITE,
+        dot_color: ParsableManimColor = WHITE,
         elbow: bool = False,
         **kwargs,
-    ):
+    ) -> None:
         super().__init__(**kwargs)
         self.lines = (line1, line2)
         self.quadrant = quadrant
@@ -1019,14 +1037,10 @@ class Angle(VMobject, metaclass=ConvertToOpenGL):
                     self.add(line1, line2, angle, value)
         """
 
-        if degrees:
-            return self.angle_value / DEGREES
-        return self.angle_value
+        return self.angle_value / DEGREES if degrees else self.angle_value
 
     @staticmethod
-    def from_three_points(
-        A: np.ndarray, B: np.ndarray, C: np.ndarray, **kwargs
-    ) -> Angle:
+    def from_three_points(A: Point3D, B: Point3D, C: Point3D, **kwargs) -> Angle:
         """The angle between the lines AB and BC.
 
         This constructs the angle :math:`\\angle ABC`.
@@ -1101,5 +1115,7 @@ class RightAngle(Angle):
                 self.add(plots)
     """
 
-    def __init__(self, line1: Line, line2: Line, length: float | None = None, **kwargs):
+    def __init__(
+        self, line1: Line, line2: Line, length: float | None = None, **kwargs
+    ) -> None:
         super().__init__(line1, line2, radius=length, elbow=True, **kwargs)

manim/mobject/geometry/polygram.py

@@ -15,20 +15,26 @@ __all__ = [
     "Cutout",
 ]
 
+
 from math import ceil
-from typing import Iterable, Sequence
+from typing import TYPE_CHECKING
 
 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.space_ops import angle_between_vectors, normalize, regular_vertices
 
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from manim.typing import Point3D, Point3D_Array
+    from manim.utils.color import ParsableManimColor
+
 
 class Polygram(VMobject, metaclass=ConvertToOpenGL):
     """A generalized :class:`Polygon`, allowing for disconnected sets of edges.
@@ -65,7 +71,9 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
                 self.wait()
     """
 
-    def __init__(self, *vertex_groups: Iterable[Sequence[float]], color=BLUE, **kwargs):
+    def __init__(
+        self, *vertex_groups: Point3D, color: ParsableManimColor = BLUE, **kwargs
+    ):
         super().__init__(color=color, **kwargs)
 
         for vertices in vertex_groups:
@@ -77,7 +85,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
@@ -99,7 +107,7 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
 
         return self.get_start_anchors()
 
-    def get_vertex_groups(self) -> np.ndarray:
+    def get_vertex_groups(self) -> np.ndarray[Point3D_Array]:
         """Gets the vertex groups of the :class:`Polygram`.
 
         Returns
@@ -139,7 +147,7 @@ class Polygram(VMobject, metaclass=ConvertToOpenGL):
         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
@@ -304,7 +312,7 @@ class Polygon(Polygram):
                 self.add(isosceles, square_and_triangles)
     """
 
-    def __init__(self, *vertices: Sequence[float], **kwargs):
+    def __init__(self, *vertices: Point3D, **kwargs) -> None:
         super().__init__(vertices, **kwargs)
 
 
@@ -348,7 +356,7 @@ class RegularPolygram(Polygram):
         radius: float = 1,
         start_angle: float | None = None,
         **kwargs,
-    ):
+    ) -> 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}.
@@ -424,7 +432,7 @@ class RegularPolygon(RegularPolygram):
                 self.add(poly_group)
     """
 
-    def __init__(self, n: int = 6, **kwargs):
+    def __init__(self, n: int = 6, **kwargs) -> None:
         super().__init__(n, density=1, **kwargs)
 
 
@@ -496,7 +504,7 @@ class Star(Polygon):
         density: int = 2,
         start_angle: float | None = TAU / 4,
         **kwargs,
-    ):
+    ) -> None:
         inner_angle = TAU / (2 * n)
 
         if inner_radius is None:
@@ -555,7 +563,7 @@ class Triangle(RegularPolygon):
                 self.add(tri_group)
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs) -> None:
         super().__init__(n=3, **kwargs)
 
 
@@ -597,7 +605,7 @@ class Rectangle(Polygon):
 
     def __init__(
         self,
-        color: Color = WHITE,
+        color: ParsableManimColor = WHITE,
         height: float = 2.0,
         width: float = 4.0,
         grid_xstep: float | None = None,
@@ -665,7 +673,7 @@ class Square(Rectangle):
                 self.add(square_1, square_2, square_3)
     """
 
-    def __init__(self, side_length: float = 2.0, **kwargs):
+    def __init__(self, side_length: float = 2.0, **kwargs) -> None:
         self.side_length = side_length
         super().__init__(height=side_length, width=side_length, **kwargs)
 
@@ -735,7 +743,7 @@ 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) -> None:
         super().__init__(**kwargs)
         self.append_points(main_shape.points)
         if main_shape.get_direction() == "CW":