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

manim/mobject/three_d/three_dimensions.py

@@ -16,11 +16,11 @@ __all__ = [
     "Torus",
 ]
 
-
-from typing import *
+from collections.abc import Callable, Iterable, Sequence
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
-from colour import Color
+from typing_extensions import Self
 
 from manim import config, logger
 from manim.constants import *
@@ -29,16 +29,26 @@ from manim.mobject.geometry.polygram import Square
 from manim.mobject.mobject import *
 from manim.mobject.opengl.opengl_compatibility import ConvertToOpenGL
 from manim.mobject.opengl.opengl_mobject import OpenGLMobject
-from manim.mobject.types.vectorized_mobject import VGroup, VMobject
-from manim.utils.color import *
-from manim.utils.color import Colors
-from manim.utils.deprecation import deprecated_params
+from manim.mobject.types.vectorized_mobject import VectorizedPoint, VGroup, VMobject
+from manim.utils.color import (
+    BLUE,
+    BLUE_D,
+    BLUE_E,
+    LIGHT_GREY,
+    WHITE,
+    ManimColor,
+    ParsableManimColor,
+    interpolate_color,
+)
 from manim.utils.iterables import tuplify
 from manim.utils.space_ops import normalize, perpendicular_bisector, z_to_vector
 
+if TYPE_CHECKING:
+    from manim.typing import Point3D, Point3DLike, Vector3DLike
+
 
 class ThreeDVMobject(VMobject, metaclass=ConvertToOpenGL):
-    def __init__(self, shade_in_3d=True, **kwargs):
+    def __init__(self, shade_in_3d: bool = True, **kwargs):
         super().__init__(shade_in_3d=shade_in_3d, **kwargs)
 
 
@@ -63,7 +73,7 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):
         The opacity of the :class:`Surface`, from 0 being fully transparent
         to 1 being fully opaque. Defaults to 1.
     checkerboard_colors
-        Colors individual faces alternating colors. Overrides ``fill_color``.
+        ng individual faces alternating colors. Overrides ``fill_color``.
     stroke_color
         Color of the stroke surrounding each face of :class:`Surface`.
     stroke_width
@@ -101,36 +111,46 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):
         v_range: Sequence[float] = [0, 1],
         resolution: Sequence[int] = 32,
         surface_piece_config: dict = {},
-        fill_color: Color = BLUE_D,
+        fill_color: ParsableManimColor = BLUE_D,
         fill_opacity: float = 1.0,
-        checkerboard_colors: Sequence[Color] = [BLUE_D, BLUE_E],
-        stroke_color: Color = LIGHT_GREY,
+        checkerboard_colors: Sequence[ParsableManimColor] | bool = [BLUE_D, BLUE_E],
+        stroke_color: ParsableManimColor = LIGHT_GREY,
         stroke_width: float = 0.5,
         should_make_jagged: bool = False,
         pre_function_handle_to_anchor_scale_factor: float = 0.00001,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         self.u_range = u_range
         self.v_range = v_range
-        super().__init__(**kwargs)
+        super().__init__(
+            fill_color=fill_color,
+            fill_opacity=fill_opacity,
+            stroke_color=stroke_color,
+            stroke_width=stroke_width,
+            **kwargs,
+        )
         self.resolution = resolution
         self.surface_piece_config = surface_piece_config
-        self.fill_color = fill_color
-        self.fill_opacity = fill_opacity
-        self.checkerboard_colors = checkerboard_colors
-        self.stroke_color = stroke_color
-        self.stroke_width = stroke_width
+        if checkerboard_colors:
+            self.checkerboard_colors: list[ManimColor] = [
+                ManimColor(x) for x in checkerboard_colors
+            ]
+        else:
+            self.checkerboard_colors = checkerboard_colors
         self.should_make_jagged = should_make_jagged
         self.pre_function_handle_to_anchor_scale_factor = (
             pre_function_handle_to_anchor_scale_factor
         )
-        self.func = func
+        self._func = func
         self._setup_in_uv_space()
         self.apply_function(lambda p: func(p[0], p[1]))
         if self.should_make_jagged:
             self.make_jagged()
 
-    def _get_u_values_and_v_values(self):
+    def func(self, u: float, v: float) -> np.ndarray:
+        return self._func(u, v)
+
+    def _get_u_values_and_v_values(self) -> tuple[np.ndarray, np.ndarray]:
         res = tuplify(self.resolution)
         if len(res) == 1:
             u_res = v_res = res[0]
@@ -142,7 +162,7 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):
 
         return u_values, v_values
 
-    def _setup_in_uv_space(self):
+    def _setup_in_uv_space(self) -> None:
         u_values, v_values = self._get_u_values_and_v_values()
         faces = VGroup()
         for i in range(len(u_values) - 1):
@@ -176,7 +196,9 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):
         if self.checkerboard_colors:
             self.set_fill_by_checkerboard(*self.checkerboard_colors)
 
-    def set_fill_by_checkerboard(self, *colors, opacity=None):
+    def set_fill_by_checkerboard(
+        self, *colors: Iterable[ParsableManimColor], opacity: float | None = None
+    ) -> Self:
         """Sets the fill_color of each face of :class:`Surface` in
         an alternating pattern.
 
@@ -199,14 +221,13 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):
             face.set_fill(colors[c_index], opacity=opacity)
         return self
 
-    @deprecated_params("colors", since="v0.16.0")
     def set_fill_by_value(
         self,
         axes: Mobject,
-        colorscale: Union[Iterable[Color], Color] | None = None,
+        colorscale: list[ParsableManimColor] | ParsableManimColor | None = None,
         axis: int = 2,
         **kwargs,
-    ):
+    ) -> Self:
         """Sets the color of each mobject of a parametric surface to a color
         relative to its axis-value.
 
@@ -316,7 +337,7 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):
 
 
 class Sphere(Surface):
-    """An three-dimensional sphere.
+    """A three-dimensional sphere.
 
     Parameters
     ----------
@@ -360,17 +381,19 @@ class Sphere(Surface):
 
     def __init__(
         self,
-        center=ORIGIN,
-        radius=1,
-        resolution=None,
-        u_range=(0, TAU),
-        v_range=(0, PI),
+        center: Point3DLike = ORIGIN,
+        radius: float = 1,
+        resolution: Sequence[int] | None = None,
+        u_range: Sequence[float] = (0, TAU),
+        v_range: Sequence[float] = (0, PI),
         **kwargs,
-    ):
+    ) -> None:
         if config.renderer == RendererType.OPENGL:
             res_value = (101, 51)
         elif config.renderer == RendererType.CAIRO:
             res_value = (24, 12)
+        else:
+            raise Exception("Unknown renderer")
 
         resolution = resolution if resolution is not None else res_value
 
@@ -386,7 +409,14 @@ class Sphere(Surface):
 
         self.shift(center)
 
-    def func(self, u, v):
+    def func(self, u: float, v: float) -> np.ndarray:
+        """The z values defining the :class:`Sphere` being plotted.
+
+        Returns
+        -------
+        :class:`numpy.array`
+            The z values defining the :class:`Sphere`.
+        """
         return self.radius * np.array(
             [np.cos(u) * np.sin(v), np.sin(u) * np.sin(v), -np.cos(v)],
         )
@@ -428,10 +458,10 @@ class Dot3D(Sphere):
         self,
         point: list | np.ndarray = ORIGIN,
         radius: float = DEFAULT_DOT_RADIUS,
-        color: Colors = WHITE,
-        resolution=(8, 8),
+        color: ParsableManimColor = WHITE,
+        resolution: tuple[int, int] = (8, 8),
         **kwargs,
-    ):
+    ) -> None:
         super().__init__(center=point, radius=radius, resolution=resolution, **kwargs)
         self.set_color(color)
 
@@ -468,12 +498,12 @@ class Cube(VGroup):
 
     def __init__(
         self,
-        side_length=2,
-        fill_opacity=0.75,
-        fill_color=BLUE,
-        stroke_width=0,
+        side_length: float = 2,
+        fill_opacity: float = 0.75,
+        fill_color: ParsableManimColor = BLUE,
+        stroke_width: float = 0,
         **kwargs,
-    ):
+    ) -> None:
         self.side_length = side_length
         super().__init__(
             fill_color=fill_color,
@@ -482,11 +512,13 @@ class Cube(VGroup):
             **kwargs,
         )
 
-    def generate_points(self):
+    def generate_points(self) -> None:
+        """Creates the sides of the :class:`Cube`."""
         for vect in IN, OUT, LEFT, RIGHT, UP, DOWN:
             face = Square(
                 side_length=self.side_length,
                 shade_in_3d=True,
+                joint_type=LineJointType.BEVEL,
             )
             face.flip()
             face.shift(self.side_length * OUT / 2.0)
@@ -494,7 +526,8 @@ class Cube(VGroup):
 
             self.add(face)
 
-    init_points = generate_points
+    def init_points(self) -> None:
+        self.generate_points()
 
 
 class Prism(Cube):
@@ -520,11 +553,14 @@ class Prism(Cube):
                 self.add(prismSmall, prismLarge)
     """
 
-    def __init__(self, dimensions=[3, 2, 1], **kwargs):
+    def __init__(
+        self, dimensions: tuple[float, float, float] | np.ndarray = [3, 2, 1], **kwargs
+    ) -> None:
         self.dimensions = dimensions
         super().__init__(**kwargs)
 
-    def generate_points(self):
+    def generate_points(self) -> None:
+        """Creates the sides of the :class:`Prism`."""
         super().generate_points()
         for dim, value in enumerate(self.dimensions):
             self.rescale_to_fit(value, dim, stretch=True)
@@ -577,8 +613,8 @@ class Cone(Surface):
         v_range: Sequence[float] = [0, TAU],
         u_min: float = 0,
         checkerboard_colors: bool = False,
-        **kwargs,
-    ):
+        **kwargs: Any,
+    ) -> None:
         self.direction = direction
         self.theta = PI - np.arctan(base_radius / height)
 
@@ -590,22 +626,23 @@ class Cone(Surface):
             **kwargs,
         )
         # used for rotations
+        self.new_height = height
         self._current_theta = 0
         self._current_phi = 0
-
+        self.base_circle = Circle(
+            radius=base_radius,
+            color=self.fill_color,
+            fill_opacity=self.fill_opacity,
+            stroke_width=0,
+        )
+        self.base_circle.shift(height * IN)
+        self._set_start_and_end_attributes(direction)
         if show_base:
-            self.base_circle = Circle(
-                radius=base_radius,
-                color=self.fill_color,
-                fill_opacity=self.fill_opacity,
-                stroke_width=0,
-            )
-            self.base_circle.shift(height * IN)
             self.add(self.base_circle)
 
         self._rotate_to_direction()
 
-    def func(self, u: float, v: float):
+    def func(self, u: float, v: float) -> np.ndarray:
         """Converts from spherical coordinates to cartesian.
 
         Parameters
@@ -614,6 +651,11 @@ class Cone(Surface):
             The radius.
         v
             The azimuthal angle.
+
+        Returns
+        -------
+        :class:`numpy.array`
+            Points defining the :class:`Cone`.
         """
         r = u
         phi = v
@@ -625,14 +667,17 @@ class Cone(Surface):
             ],
         )
 
-    def _rotate_to_direction(self):
+    def get_start(self) -> np.ndarray:
+        return self.start_point.get_center()
+
+    def get_end(self) -> np.ndarray:
+        return self.end_point.get_center()
+
+    def _rotate_to_direction(self) -> None:
         x, y, z = self.direction
 
         r = np.sqrt(x**2 + y**2 + z**2)
-        if r > 0:
-            theta = np.arccos(z / r)
-        else:
-            theta = 0
+        theta = np.arccos(z / r) if r > 0 else 0
 
         if x == 0:
             if y == 0:  # along the z axis
@@ -658,18 +703,18 @@ class Cone(Surface):
         self._current_theta = theta
         self._current_phi = phi
 
-    def set_direction(self, direction):
+    def set_direction(self, direction: np.ndarray) -> None:
         """Changes the direction of the apex of the :class:`Cone`.
 
         Parameters
         ----------
-        direction : :class:`numpy.array`
+        direction
             The direction of the apex.
         """
         self.direction = direction
         self._rotate_to_direction()
 
-    def get_direction(self):
+    def get_direction(self) -> np.ndarray:
         """Returns the current direction of the apex of the :class:`Cone`.
 
         Returns
@@ -679,6 +724,15 @@ class Cone(Surface):
         """
         return self.direction
 
+    def _set_start_and_end_attributes(self, direction):
+        normalized_direction = direction * np.linalg.norm(direction)
+
+        start = self.base_circle.get_center()
+        end = start + normalized_direction * self.new_height
+        self.start_point = VectorizedPoint(start)
+        self.end_point = VectorizedPoint(end)
+        self.add(self.start_point, self.end_point)
+
 
 class Cylinder(Surface):
     """A cylinder, defined by its height, radius and direction,
@@ -719,9 +773,9 @@ class Cylinder(Surface):
         direction: np.ndarray = Z_AXIS,
         v_range: Sequence[float] = [0, TAU],
         show_ends: bool = True,
-        resolution=(24, 24),
+        resolution: Sequence[int] = (24, 24),
         **kwargs,
-    ):
+    ) -> None:
         self._height = height
         self.radius = radius
         super().__init__(
@@ -737,7 +791,7 @@ class Cylinder(Surface):
         self._current_theta = 0
         self.set_direction(direction)
 
-    def func(self, u: float, v: float):
+    def func(self, u: float, v: float) -> np.ndarray:
         """Converts from cylindrical coordinates to cartesian.
 
         Parameters
@@ -746,13 +800,18 @@ class Cylinder(Surface):
             The height.
         v
             The azimuthal angle.
+
+        Returns
+        -------
+        :class:`numpy.ndarray`
+            Points defining the :class:`Cylinder`.
         """
         height = u
         phi = v
         r = self.radius
         return np.array([r * np.cos(phi), r * np.sin(phi), height])
 
-    def add_bases(self):
+    def add_bases(self) -> None:
         """Adds the end caps of the cylinder."""
         if config.renderer == RendererType.OPENGL:
             color = self.color
@@ -779,14 +838,11 @@ class Cylinder(Surface):
         self.base_bottom.shift(self.u_range[0] * IN)
         self.add(self.base_top, self.base_bottom)
 
-    def _rotate_to_direction(self):
+    def _rotate_to_direction(self) -> None:
         x, y, z = self.direction
 
         r = np.sqrt(x**2 + y**2 + z**2)
-        if r > 0:
-            theta = np.arccos(z / r)
-        else:
-            theta = 0
+        theta = np.arccos(z / r) if r > 0 else 0
 
         if x == 0:
             if y == 0:  # along the z axis
@@ -812,12 +868,12 @@ class Cylinder(Surface):
         self._current_theta = theta
         self._current_phi = phi
 
-    def set_direction(self, direction):
+    def set_direction(self, direction: np.ndarray) -> None:
         """Sets the direction of the central axis of the :class:`Cylinder`.
 
         Parameters
         ----------
-        direction
+        direction : :class:`numpy.array`
             The direction of the central axis of the :class:`Cylinder`.
         """
         # if get_norm(direction) is get_norm(self.direction):
@@ -825,12 +881,12 @@ class Cylinder(Surface):
         self.direction = direction
         self._rotate_to_direction()
 
-    def get_direction(self):
+    def get_direction(self) -> np.ndarray:
         """Returns the direction of the central axis of the :class:`Cylinder`.
 
         Returns
         -------
-        direction
+        direction : :class:`numpy.array`
             The direction of the central axis of the :class:`Cylinder`.
         """
         return self.direction
@@ -849,6 +905,12 @@ class Line3D(Cylinder):
         The thickness of the line.
     color
         The color of the line.
+    resolution
+        The resolution of the line.
+        By default this value is the number of points the line will sampled at.
+        If you want the line to also come out checkered, use a tuple.
+        For example, for a line made of 24 points with 4 checker points on each
+        cylinder, pass the tuple (4, 24).
 
     Examples
     --------
@@ -868,15 +930,23 @@ class Line3D(Cylinder):
         start: np.ndarray = LEFT,
         end: np.ndarray = RIGHT,
         thickness: float = 0.02,
-        color=None,
+        color: ParsableManimColor | None = None,
+        resolution: int | Sequence[int] = 24,
         **kwargs,
     ):
         self.thickness = thickness
+        self.resolution = (2, resolution) if isinstance(resolution, int) else resolution
+
+        start = np.array(start, dtype=np.float64)
+        end = np.array(end, dtype=np.float64)
+
         self.set_start_and_end_attrs(start, end, **kwargs)
         if color is not None:
             self.set_color(color)
 
-    def set_start_and_end_attrs(self, start, end, **kwargs):
+    def set_start_and_end_attrs(
+        self, start: np.ndarray, end: np.ndarray, **kwargs
+    ) -> None:
         """Sets the start and end points of the line.
 
         If either ``start`` or ``end`` are :class:`Mobjects <.Mobject>`,
@@ -903,11 +973,30 @@ class Line3D(Cylinder):
             height=np.linalg.norm(self.vect),
             radius=self.thickness,
             direction=self.direction,
+            resolution=self.resolution,
             **kwargs,
         )
         self.shift((self.start + self.end) / 2)
 
-    def pointify(self, mob_or_point, direction=None):
+    def pointify(
+        self,
+        mob_or_point: Mobject | Point3DLike,
+        direction: Vector3DLike | None = None,
+    ) -> Point3D:
+        """Gets a point representing the center of the :class:`Mobjects <.Mobject>`.
+
+        Parameters
+        ----------
+        mob_or_point
+            :class:`Mobjects <.Mobject>` or point whose center should be returned.
+        direction
+            If an edge of a :class:`Mobjects <.Mobject>` should be returned, the direction of the edge.
+
+        Returns
+        -------
+        :class:`numpy.array`
+            Center of the :class:`Mobjects <.Mobject>` or point, or edge if direction is given.
+        """
         if isinstance(mob_or_point, (Mobject, OpenGLMobject)):
             mob = mob_or_point
             if direction is None:
@@ -916,7 +1005,7 @@ class Line3D(Cylinder):
                 return mob.get_boundary_point(direction)
         return np.array(mob_or_point)
 
-    def get_start(self):
+    def get_start(self) -> np.ndarray:
         """Returns the starting point of the :class:`Line3D`.
 
         Returns
@@ -926,7 +1015,7 @@ class Line3D(Cylinder):
         """
         return self.start
 
-    def get_end(self):
+    def get_end(self) -> np.ndarray:
         """Returns the ending point of the :class:`Line3D`.
 
         Returns
@@ -938,8 +1027,12 @@ class Line3D(Cylinder):
 
     @classmethod
     def parallel_to(
-        cls, line: Line3D, point: Sequence[float] = ORIGIN, length: float = 5, **kwargs
-    ):
+        cls,
+        line: Line3D,
+        point: Point3DLike = ORIGIN,
+        length: float = 5,
+        **kwargs,
+    ) -> Line3D:
         """Returns a line parallel to another line going through
         a given point.
 
@@ -949,9 +1042,16 @@ class Line3D(Cylinder):
             The line to be parallel to.
         point
             The point to pass through.
+        length
+            Length of the parallel line.
         kwargs
             Additional parameters to be passed to the class.
 
+        Returns
+        -------
+        :class:`Line3D`
+            Line parallel to ``line``.
+
         Examples
         --------
         .. manim:: ParallelLineExample
@@ -965,18 +1065,22 @@ class Line3D(Cylinder):
                     line2 = Line3D.parallel_to(line1, color=YELLOW)
                     self.add(ax, line1, line2)
         """
-        point = np.array(point)
+        np_point = np.asarray(point)
         vect = normalize(line.vect)
         return cls(
-            point + vect * length / 2,
-            point - vect * length / 2,
+            np_point + vect * length / 2,
+            np_point - vect * length / 2,
             **kwargs,
         )
 
     @classmethod
     def perpendicular_to(
-        cls, line: Line3D, point: Sequence[float] = ORIGIN, length: float = 5, **kwargs
-    ):
+        cls,
+        line: Line3D,
+        point: Vector3DLike = ORIGIN,
+        length: float = 5,
+        **kwargs,
+    ) -> Line3D:
         """Returns a line perpendicular to another line going through
         a given point.
 
@@ -986,9 +1090,16 @@ class Line3D(Cylinder):
             The line to be perpendicular to.
         point
             The point to pass through.
+        length
+            Length of the perpendicular line.
         kwargs
             Additional parameters to be passed to the class.
 
+        Returns
+        -------
+        :class:`Line3D`
+            Line perpendicular to ``line``.
+
         Examples
         --------
         .. manim:: PerpLineExample
@@ -1002,17 +1113,17 @@ class Line3D(Cylinder):
                     line2 = Line3D.perpendicular_to(line1, color=BLUE)
                     self.add(ax, line1, line2)
         """
-        point = np.array(point)
+        np_point = np.asarray(point)
 
-        norm = np.cross(line.vect, point - line.start)
+        norm = np.cross(line.vect, np_point - line.start)
         if all(np.linalg.norm(norm) == np.zeros(3)):
             raise ValueError("Could not find the perpendicular.")
 
         start, end = perpendicular_bisector([line.start, line.end], norm)
         vect = normalize(end - start)
         return cls(
-            point + vect * length / 2,
-            point - vect * length / 2,
+            np_point + vect * length / 2,
+            np_point - vect * length / 2,
             **kwargs,
         )
 
@@ -1034,6 +1145,8 @@ class Arrow3D(Line3D):
         The base radius of the conical tip.
     color
         The color of the arrow.
+    resolution
+        The resolution of the arrow line.
 
     Examples
     --------
@@ -1059,11 +1172,17 @@ class Arrow3D(Line3D):
         thickness: float = 0.02,
         height: float = 0.3,
         base_radius: float = 0.08,
-        color=WHITE,
+        color: ParsableManimColor = WHITE,
+        resolution: int | Sequence[int] = 24,
         **kwargs,
-    ):
+    ) -> None:
         super().__init__(
-            start=start, end=end, thickness=thickness, color=color, **kwargs
+            start=start,
+            end=end,
+            thickness=thickness,
+            color=color,
+            resolution=resolution,
+            **kwargs,
         )
 
         self.length = np.linalg.norm(self.vect)
@@ -1072,14 +1191,21 @@ class Arrow3D(Line3D):
             self.end - height * self.direction,
             **kwargs,
         )
-
         self.cone = Cone(
-            direction=self.direction, base_radius=base_radius, height=height, **kwargs
+            direction=self.direction,
+            base_radius=base_radius,
+            height=height,
+            **kwargs,
         )
-        self.cone.shift(end)
-        self.add(self.cone)
+        np_end = np.asarray(end, dtype=np.float64)
+        self.cone.shift(np_end)
+        self.end_point = VectorizedPoint(np_end)
+        self.add(self.end_point, self.cone)
         self.set_color(color)
 
+    def get_end(self) -> np.ndarray:
+        return self.end_point.get_center()
+
 
 class Torus(Surface):
     """A torus.
@@ -1115,11 +1241,11 @@ class Torus(Surface):
         self,
         major_radius: float = 3,
         minor_radius: float = 1,
-        u_range=(0, TAU),
-        v_range=(0, TAU),
-        resolution=None,
+        u_range: Sequence[float] = (0, TAU),
+        v_range: Sequence[float] = (0, TAU),
+        resolution: tuple[int, int] | None = None,
         **kwargs,
-    ):
+    ) -> None:
         if config.renderer == RendererType.OPENGL:
             res_value = (101, 101)
         elif config.renderer == RendererType.CAIRO:
@@ -1137,6 +1263,13 @@ class Torus(Surface):
             **kwargs,
         )
 
-    def func(self, u, v):
+    def func(self, u: float, v: float) -> np.ndarray:
+        """The z values defining the :class:`Torus` being plotted.
+
+        Returns
+        -------
+        :class:`numpy.ndarray`
+            The z values defining the :class:`Torus`.
+        """
         P = np.array([np.cos(u), np.sin(u), 0])
         return (self.R - self.r * np.cos(v)) * P - self.r * np.sin(v) * OUT