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

manim/mobject/geometry/line.py

@@ -17,7 +17,6 @@ __all__ = [
 from typing import TYPE_CHECKING
 
 import numpy as np
-from typing_extensions import Self
 
 from manim import config
 from manim.constants import *
@@ -31,68 +30,115 @@ 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 typing import Any
+
+    from typing_extensions import Literal, Self, TypeAlias
+
+    from manim.typing import Point2DLike, Point3D, Point3DLike, Vector3D
     from manim.utils.color import ParsableManimColor
 
     from ..matrix import Matrix  # Avoid circular import
 
+    AngleQuadrant: TypeAlias = tuple[Literal[-1, 1], Literal[-1, 1]]
+    r"""A tuple of 2 integers which can be either +1 or -1, allowing to select
+    one of the 4 quadrants of the Cartesian plane.
+
+    Let :math:`L_1,\ L_2` be two lines defined by start points
+    :math:`S_1,\ S_2` and end points :math:`E_1,\ E_2`. We define the "positive
+    direction" of :math:`L_1` as the direction from :math:`S_1` to :math:`E_1`,
+    and its "negative direction" as the opposite one. We do the same with
+    :math:`L_2`.
+
+    If :math:`L_1` and :math:`L_2` intersect, they divide the plane into 4
+    quadrants. To pick one quadrant, choose the integers in this tuple in the
+    following way:
+
+    -   If the 1st integer is +1, select one of the 2 quadrants towards the
+        positive direction of :math:`L_1`, i.e. closest to `E_1`. Otherwise, if
+        the 1st integer is -1, select one of the 2 quadrants towards the
+        negative direction of :math:`L_1`, i.e. closest to `S_1`.
+
+    -   Similarly, the sign of the 2nd integer picks the positive or negative
+        direction of :math:`L_2` and, thus, selects one of the 2 quadrants
+        which  are closest to :math:`E_2` or :math:`S_2` respectively.
+    """
+
 
 class Line(TipableVMobject):
     def __init__(
         self,
-        start: Point3D = LEFT,
-        end: Point3D = RIGHT,
+        start: Point3DLike | Mobject = LEFT,
+        end: Point3DLike | Mobject = RIGHT,
         buff: float = 0,
         path_arc: float | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         self.dim = 3
         self.buff = buff
         self.path_arc = path_arc
         self._set_start_and_end_attrs(start, end)
         super().__init__(**kwargs)
+        # TODO: Deal with the situation where path_arc is None
 
     def generate_points(self) -> None:
         self.set_points_by_ends(
             start=self.start,
             end=self.end,
             buff=self.buff,
-            path_arc=self.path_arc,
+            path_arc=self.path_arc,  # type: ignore[arg-type]
         )
 
     def set_points_by_ends(
         self,
-        start: Point3D,
-        end: Point3D,
+        start: Point3DLike | Mobject,
+        end: Point3DLike | Mobject,
         buff: float = 0,
         path_arc: float = 0,
     ) -> None:
+        """Sets the points of the line based on its start and end points.
+        Unlike :meth:`put_start_and_end_on`, this method respects `self.buff` and
+        Mobject bounding boxes.
+
+        Parameters
+        ----------
+        start
+            The start point or Mobject of the line.
+        end
+            The end point or Mobject of the line.
+        buff
+            The empty space between the start and end of the line, by default 0.
+        path_arc
+            The angle of a circle spanned by this arc, by default 0 which is a straight line.
+        """
+        self._set_start_and_end_attrs(start, end)
         if path_arc:
+            # self.path_arc could potentially be None, which is not accepted
+            # as parameter.
+            assert self.path_arc is not None
             arc = ArcBetweenPoints(self.start, self.end, angle=self.path_arc)
             self.set_points(arc.points)
         else:
-            self.set_points_as_corners([start, end])
+            self.set_points_as_corners(np.asarray([self.start, self.end]))
 
         self._account_for_buff(buff)
 
     init_points = generate_points
 
-    def _account_for_buff(self, buff: float) -> Self:
+    def _account_for_buff(self, buff: float) -> None:
         if buff == 0:
             return
         #
-        if self.path_arc == 0:
-            length = self.get_length()
-        else:
-            length = self.get_arc_length()
+        length = self.get_length() if self.path_arc == 0 else self.get_arc_length()
         #
         if length < 2 * buff:
             return
         buff_proportion = buff / length
         self.pointwise_become_partial(self, buff_proportion, 1 - buff_proportion)
-        return self
+        return
 
-    def _set_start_and_end_attrs(self, start: Point3D, end: Point3D) -> None:
+    def _set_start_and_end_attrs(
+        self, start: Point3DLike | Mobject, end: Point3DLike | Mobject
+    ) -> None:
         # If either start or end are Mobjects, this
         # gives their centers
         rough_start = self._pointify(start)
@@ -106,8 +152,8 @@ class Line(TipableVMobject):
 
     def _pointify(
         self,
-        mob_or_point: Mobject | Point3D,
-        direction: Vector | None = None,
+        mob_or_point: Mobject | Point3DLike,
+        direction: Vector3D | None = None,
     ) -> Point3D:
         """Transforms a mobject into its corresponding point. Does nothing if a point is passed.
 
@@ -132,7 +178,11 @@ class Line(TipableVMobject):
         self.path_arc = new_value
         self.init_points()
 
-    def put_start_and_end_on(self, start: Point3D, end: Point3D) -> Self:
+    def put_start_and_end_on(
+        self,
+        start: Point3DLike,
+        end: Point3DLike,
+    ) -> Self:
         """Sets starts and end coordinates of a line.
 
         Examples
@@ -158,21 +208,21 @@ class Line(TipableVMobject):
         if np.all(curr_start == curr_end):
             # TODO, any problems with resetting
             # these attrs?
-            self.start = start
-            self.end = end
+            self.start = np.asarray(start)
+            self.end = np.asarray(end)
             self.generate_points()
         return super().put_start_and_end_on(start, end)
 
-    def get_vector(self) -> Vector:
+    def get_vector(self) -> Vector3D:
         return self.get_end() - self.get_start()
 
-    def get_unit_vector(self) -> Vector:
+    def get_unit_vector(self) -> Vector3D:
         return normalize(self.get_vector())
 
     def get_angle(self) -> float:
         return angle_of_vector(self.get_vector())
 
-    def get_projection(self, point: Point3D) -> Vector:
+    def get_projection(self, point: Point3DLike) -> Point3D:
         """Returns the projection of a point onto a line.
 
         Parameters
@@ -180,16 +230,15 @@ class Line(TipableVMobject):
         point
             The point to which the line is projected.
         """
-
         start = self.get_start()
         end = self.get_end()
         unit_vect = normalize(end - start)
-        return start + np.dot(point - start, unit_vect) * unit_vect
+        return start + float(np.dot(point - start, unit_vect)) * unit_vect
 
     def get_slope(self) -> float:
-        return np.tan(self.get_angle())
+        return float(np.tan(self.get_angle()))
 
-    def set_angle(self, angle: float, about_point: Point3D | None = None) -> Self:
+    def set_angle(self, angle: float, about_point: Point3DLike | None = None) -> Self:
         if about_point is None:
             about_point = self.get_start()
 
@@ -201,7 +250,8 @@ class Line(TipableVMobject):
         return self
 
     def set_length(self, length: float) -> Self:
-        return self.scale(length / self.get_length())
+        scale_factor: float = length / self.get_length()
+        return self.scale(scale_factor)
 
 
 class DashedLine(Line):
@@ -240,10 +290,10 @@ class DashedLine(Line):
 
     def __init__(
         self,
-        *args,
+        *args: Any,
         dash_length: float = DEFAULT_DASH_LENGTH,
         dashed_ratio: float = 0.5,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         self.dash_length = dash_length
         self.dashed_ratio = dashed_ratio
@@ -266,7 +316,6 @@ class DashedLine(Line):
             >>> DashedLine()._calculate_num_dashes()
             20
         """
-
         # Minimum number of dashes has to be 2
         return max(
             2,
@@ -283,7 +332,6 @@ class DashedLine(Line):
             >>> DashedLine().get_start()
             array([-1.,  0.,  0.])
         """
-
         if len(self.submobjects) > 0:
             return self.submobjects[0].get_start()
         else:
@@ -299,7 +347,6 @@ class DashedLine(Line):
             >>> DashedLine().get_end()
             array([1., 0., 0.])
         """
-
         if len(self.submobjects) > 0:
             return self.submobjects[-1].get_end()
         else:
@@ -315,8 +362,11 @@ class DashedLine(Line):
             >>> DashedLine().get_first_handle()
             array([-0.98333333,  0.        ,  0.        ])
         """
-
-        return self.submobjects[0].points[1]
+        # Type inference of extracting an element from a list, is not
+        # supported by numpy, see this numpy issue
+        # https://github.com/numpy/numpy/issues/16544
+        first_handle: Point3D = self.submobjects[0].points[1]
+        return first_handle
 
     def get_last_handle(self) -> Point3D:
         """Returns the point of the last handle.
@@ -328,8 +378,11 @@ class DashedLine(Line):
             >>> DashedLine().get_last_handle()
             array([0.98333333, 0.        , 0.        ])
         """
-
-        return self.submobjects[-1].points[-2]
+        # Type inference of extracting an element from a list, is not
+        # supported by numpy, see this numpy issue
+        # https://github.com/numpy/numpy/issues/16544
+        last_handle: Point3D = self.submobjects[-1].points[2]
+        return last_handle
 
 
 class TangentLine(Line):
@@ -371,7 +424,7 @@ class TangentLine(Line):
         alpha: float,
         length: float = 1,
         d_alpha: float = 1e-6,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         self.length = length
         self.d_alpha = d_alpha
@@ -414,10 +467,10 @@ class Elbow(VMobject, metaclass=ConvertToOpenGL):
                 self.add(elbow_group)
     """
 
-    def __init__(self, width: float = 0.2, angle: float = 0, **kwargs) -> None:
+    def __init__(self, width: float = 0.2, angle: float = 0, **kwargs: Any) -> None:
         self.angle = angle
         super().__init__(**kwargs)
-        self.set_points_as_corners([UP, UP + RIGHT, RIGHT])
+        self.set_points_as_corners(np.array([UP, UP + RIGHT, RIGHT]))
         self.scale_to_fit_width(width, about_point=ORIGIN)
         self.rotate(self.angle, about_point=ORIGIN)
 
@@ -512,24 +565,24 @@ class Arrow(Line):
 
     def __init__(
         self,
-        *args,
+        *args: Any,
         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,
+        **kwargs: Any,
     ) -> 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)
-        super().__init__(*args, buff=buff, stroke_width=stroke_width, **kwargs)
+        super().__init__(*args, buff=buff, stroke_width=stroke_width, **kwargs)  # type: ignore[misc]
         # TODO, should this be affected when
         # Arrow.set_stroke is called?
         self.initial_stroke_width = self.stroke_width
         self.add_tip(tip_shape=tip_shape)
         self._set_stroke_width_from_length()
 
-    def scale(self, factor: float, scale_tips: bool = False, **kwargs) -> Self:
+    def scale(self, factor: float, scale_tips: bool = False, **kwargs: Any) -> Self:  # type: ignore[override]
         r"""Scale an arrow, but keep stroke width and arrow tip size fixed.
 
 
@@ -579,7 +632,7 @@ class Arrow(Line):
             self.add_tip(tip=old_tips[1], at_start=True)
         return self
 
-    def get_normal_vector(self) -> Vector:
+    def get_normal_vector(self) -> Vector3D:
         """Returns the normal of a vector.
 
         Examples
@@ -589,7 +642,6 @@ class Arrow(Line):
             >>> np.round(Arrow().get_normal_vector()) + 0. # add 0. to avoid negative 0 in output
             array([ 0.,  0., -1.])
         """
-
         p0, p1, p2 = self.tip.get_start_anchors()[:3]
         return normalize(np.cross(p2 - p1, p1 - p0))
 
@@ -609,7 +661,6 @@ class Arrow(Line):
             >>> Arrow().get_default_tip_length()
             0.35
         """
-
         max_ratio = self.max_tip_length_to_length_ratio
         return min(self.tip_length, max_ratio * self.get_length())
 
@@ -617,7 +668,11 @@ class Arrow(Line):
         """Sets stroke width based on length."""
         max_ratio = self.max_stroke_width_to_length_ratio
         if config.renderer == RendererType.OPENGL:
-            self.set_stroke(
+            # Mypy does not recognize that the self object in this case
+            # is a OpenGLVMobject and that the set_stroke method is
+            # defined here:
+            # mobject/opengl/opengl_vectorized_mobject.py#L248
+            self.set_stroke(  # type: ignore[call-arg]
                 width=min(self.initial_stroke_width, max_ratio * self.get_length()),
                 recurse=False,
             )
@@ -632,6 +687,11 @@ class Arrow(Line):
 class Vector(Arrow):
     """A vector specialized for use in graphs.
 
+    .. caution::
+        Do not confuse with the :class:`~.Vector2D`,
+        :class:`~.Vector3D` or :class:`~.VectorND` type aliases,
+        which are not Mobjects!
+
     Parameters
     ----------
     direction
@@ -654,7 +714,12 @@ class Vector(Arrow):
                 self.add(plane, vector_1, vector_2)
     """
 
-    def __init__(self, direction: Vector = RIGHT, buff: float = 0, **kwargs) -> None:
+    def __init__(
+        self,
+        direction: Point2DLike | Point3DLike = RIGHT,
+        buff: float = 0,
+        **kwargs: Any,
+    ) -> None:
         self.buff = buff
         if len(direction) == 2:
             direction = np.hstack([direction, 0])
@@ -666,7 +731,7 @@ class Vector(Arrow):
         integer_labels: bool = True,
         n_dim: int = 2,
         color: ParsableManimColor | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> Matrix:
         """Creates a label based on the coordinates of the vector.
 
@@ -702,7 +767,6 @@ class Vector(Arrow):
 
                     self.add(plane, vec_1, vec_2, label_1, label_2)
         """
-
         # avoiding circular imports
         from ..matrix import Matrix
 
@@ -770,7 +834,7 @@ class DoubleArrow(Arrow):
                 self.add(box, d1, d2, d3)
     """
 
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         if "tip_shape_end" in kwargs:
             kwargs["tip_shape"] = kwargs.pop("tip_shape_end")
         tip_shape_start = kwargs.pop("tip_shape_start", ArrowTriangleFilledTip)
@@ -892,14 +956,14 @@ class Angle(VMobject, metaclass=ConvertToOpenGL):
         line1: Line,
         line2: Line,
         radius: float | None = None,
-        quadrant: Point2D = (1, 1),
+        quadrant: AngleQuadrant = (1, 1),
         other_angle: bool = False,
         dot: bool = False,
         dot_radius: float | None = None,
         dot_distance: float = 0.55,
         dot_color: ParsableManimColor = WHITE,
         elbow: bool = False,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         super().__init__(**kwargs)
         self.lines = (line1, line2)
@@ -936,9 +1000,9 @@ class Angle(VMobject, metaclass=ConvertToOpenGL):
                 + quadrant[0] * radius * line1.get_unit_vector()
                 + quadrant[1] * radius * line2.get_unit_vector()
             )
-            angle_mobject = Elbow(**kwargs)
+            angle_mobject: VMobject = Elbow(**kwargs)
             angle_mobject.set_points_as_corners(
-                [anchor_angle_1, anchor_middle, anchor_angle_2],
+                np.array([anchor_angle_1, anchor_middle, anchor_angle_2]),
             )
         else:
             angle_1 = angle_of_vector(anchor_angle_1 - inter)
@@ -1002,11 +1066,10 @@ class Angle(VMobject, metaclass=ConvertToOpenGL):
             >>> angle.get_lines()
             VGroup(Line, Line)
         """
-
         return VGroup(*self.lines)
 
     def get_value(self, degrees: bool = False) -> float:
-        """Get the value of an angle of the :class:`Angle` class.
+        r"""Get the value of an angle of the :class:`Angle` class.
 
         Parameters
         ----------
@@ -1031,17 +1094,18 @@ class Angle(VMobject, metaclass=ConvertToOpenGL):
 
                     angle = Angle(line1, line2, radius=0.4)
 
-                    value = DecimalNumber(angle.get_value(degrees=True), unit="^{\\circ}")
+                    value = DecimalNumber(angle.get_value(degrees=True), unit=r"^{\circ}")
                     value.next_to(angle, UR)
 
                     self.add(line1, line2, angle, value)
         """
-
         return self.angle_value / DEGREES if degrees else self.angle_value
 
     @staticmethod
-    def from_three_points(A: Point3D, B: Point3D, C: Point3D, **kwargs) -> Angle:
-        """The angle between the lines AB and BC.
+    def from_three_points(
+        A: Point3DLike, B: Point3DLike, C: Point3DLike, **kwargs: Any
+    ) -> Angle:
+        r"""The angle between the lines AB and BC.
 
         This constructs the angle :math:`\\angle ABC`.
 
@@ -1116,6 +1180,10 @@ class RightAngle(Angle):
     """
 
     def __init__(
-        self, line1: Line, line2: Line, length: float | None = None, **kwargs
+        self,
+        line1: Line,
+        line2: Line,
+        length: float | None = None,
+        **kwargs: Any,
     ) -> None:
         super().__init__(line1, line2, radius=length, elbow=True, **kwargs)