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

manim/camera/mapping_camera.py

@@ -1,4 +1,4 @@
-"""A camera that allows mapping between objects."""
+"""A camera module that supports spatial mapping between objects for distortion effects."""
 
 from __future__ import annotations
 
@@ -17,8 +17,16 @@ from ..utils.config_ops import DictAsObject
 
 
 class MappingCamera(Camera):
-    """Camera object that allows mapping
-    between objects.
+    """Parameters
+    ----------
+    mapping_func : callable
+        Function to map 3D points to new 3D points (identity by default).
+    min_num_curves : int
+        Minimum number of curves for VMobjects to avoid visual glitches.
+    allow_object_intrusion : bool
+        If True, modifies original mobjects; else works on copies.
+    kwargs : dict
+        Additional arguments passed to Camera base class.
     """
 
     def __init__(
@@ -34,12 +42,18 @@ class MappingCamera(Camera):
         super().__init__(**kwargs)
 
     def points_to_pixel_coords(self, mobject, points):
+        # Map points with custom function before converting to pixels
         return super().points_to_pixel_coords(
             mobject,
             np.apply_along_axis(self.mapping_func, 1, points),
         )
 
     def capture_mobjects(self, mobjects, **kwargs):
+        """Capture mobjects for rendering after applying the spatial mapping.
+
+        Copies mobjects unless intrusion is allowed, and ensures
+        vector objects have enough curves for smooth distortion.
+        """
         mobjects = self.get_mobjects_to_display(mobjects, **kwargs)
         if self.allow_object_intrusion:
             mobject_copies = mobjects
@@ -64,8 +78,16 @@ class MappingCamera(Camera):
 # TODO: Add optional separator borders between cameras (or perhaps peel this off into a
 # CameraPlusOverlay class)
 
+
 # TODO, the classes below should likely be deleted
 class OldMultiCamera(Camera):
+    """Parameters
+    ----------
+    cameras_with_start_positions : tuple
+        Tuples of (Camera, (start_y, start_x)) indicating camera and
+        its pixel offset on the final frame.
+    """
+
     def __init__(self, *cameras_with_start_positions, **kwargs):
         self.shifted_cameras = [
             DictAsObject(
@@ -124,6 +146,15 @@ class OldMultiCamera(Camera):
 
 
 class SplitScreenCamera(OldMultiCamera):
+    """Initializes a split screen camera setup with two side-by-side cameras.
+
+    Parameters
+    ----------
+    left_camera : Camera
+    right_camera : Camera
+    kwargs : dict
+    """
+
     def __init__(self, left_camera, right_camera, **kwargs):
         Camera.__init__(self, **kwargs)  # to set attributes such as pixel_width
         self.left_camera = left_camera

manim/camera/moving_camera.py

@@ -1,45 +1,48 @@
-"""A camera able to move through a scene.
+"""Defines the MovingCamera class, a camera that can pan and zoom through a scene.
 
 .. SEEALSO::
 
     :mod:`.moving_camera_scene`
-
 """
 
 from __future__ import annotations
 
 __all__ = ["MovingCamera"]
 
-import numpy as np
+from collections.abc import Iterable
+from typing import Any
+
+from cairo import Context
+
+from manim.typing import PixelArray, Point3D, Point3DLike
 
 from .. import config
 from ..camera.camera import Camera
 from ..constants import DOWN, LEFT, RIGHT, UP
 from ..mobject.frame import ScreenRectangle
 from ..mobject.mobject import Mobject
-from ..utils.color import WHITE
+from ..utils.color import WHITE, ManimColor
 
 
 class MovingCamera(Camera):
-    """
-    Stays in line with the height, width and position of it's 'frame', which is a Rectangle
+    """A camera that follows and matches the size and position of its 'frame', a Rectangle (or similar Mobject).
+
+    The frame defines the region of space the camera displays and can move or resize dynamically.
 
     .. SEEALSO::
 
         :class:`.MovingCameraScene`
-
     """
 
     def __init__(
         self,
-        frame=None,
-        fixed_dimension=0,  # width
-        default_frame_stroke_color=WHITE,
-        default_frame_stroke_width=0,
-        **kwargs,
+        frame: Mobject | None = None,
+        fixed_dimension: int = 0,  # width
+        default_frame_stroke_color: ManimColor = WHITE,
+        default_frame_stroke_width: int = 0,
+        **kwargs: Any,
     ):
-        """
-        Frame is a Mobject, (should almost certainly be a rectangle)
+        """Frame is a Mobject, (should almost certainly be a rectangle)
         determining which region of space the camera displays
         """
         self.fixed_dimension = fixed_dimension
@@ -56,7 +59,7 @@ class MovingCamera(Camera):
 
     # TODO, make these work for a rotated frame
     @property
-    def frame_height(self):
+    def frame_height(self) -> float:
         """Returns the height of the frame.
 
         Returns
@@ -66,30 +69,8 @@ class MovingCamera(Camera):
         """
         return self.frame.height
 
-    @property
-    def frame_width(self):
-        """Returns the width of the frame
-
-        Returns
-        -------
-        float
-            The width of the frame.
-        """
-        return self.frame.width
-
-    @property
-    def frame_center(self):
-        """Returns the centerpoint of the frame in cartesian coordinates.
-
-        Returns
-        -------
-        np.array
-            The cartesian coordinates of the center of the frame.
-        """
-        return self.frame.get_center()
-
     @frame_height.setter
-    def frame_height(self, frame_height: float):
+    def frame_height(self, frame_height: float) -> None:
         """Sets the height of the frame in MUnits.
 
         Parameters
@@ -99,8 +80,19 @@ class MovingCamera(Camera):
         """
         self.frame.stretch_to_fit_height(frame_height)
 
+    @property
+    def frame_width(self) -> float:
+        """Returns the width of the frame
+
+        Returns
+        -------
+        float
+            The width of the frame.
+        """
+        return self.frame.width
+
     @frame_width.setter
-    def frame_width(self, frame_width: float):
+    def frame_width(self, frame_width: float) -> None:
         """Sets the width of the frame in MUnits.
 
         Parameters
@@ -110,8 +102,19 @@ class MovingCamera(Camera):
         """
         self.frame.stretch_to_fit_width(frame_width)
 
+    @property
+    def frame_center(self) -> Point3D:
+        """Returns the centerpoint of the frame in cartesian coordinates.
+
+        Returns
+        -------
+        np.array
+            The cartesian coordinates of the center of the frame.
+        """
+        return self.frame.get_center()
+
     @frame_center.setter
-    def frame_center(self, frame_center: np.ndarray | list | tuple | Mobject):
+    def frame_center(self, frame_center: Point3DLike | Mobject) -> None:
         """Sets the centerpoint of the frame.
 
         Parameters
@@ -123,25 +126,20 @@ class MovingCamera(Camera):
         """
         self.frame.move_to(frame_center)
 
-    def capture_mobjects(self, mobjects, **kwargs):
+    def capture_mobjects(self, mobjects: Iterable[Mobject], **kwargs: Any) -> None:
         # self.reset_frame_center()
         # self.realign_frame_shape()
         super().capture_mobjects(mobjects, **kwargs)
 
-    # Since the frame can be moving around, the cairo
-    # context used for updating should be regenerated
-    # at each frame.  So no caching.
-    def get_cached_cairo_context(self, pixel_array):
-        """
-        Since the frame can be moving around, the cairo
+    def get_cached_cairo_context(self, pixel_array: PixelArray) -> None:
+        """Since the frame can be moving around, the cairo
         context used for updating should be regenerated
         at each frame.  So no caching.
         """
         return None
 
-    def cache_cairo_context(self, pixel_array, ctx):
-        """
-        Since the frame can be moving around, the cairo
+    def cache_cairo_context(self, pixel_array: PixelArray, ctx: Context) -> None:
+        """Since the frame can be moving around, the cairo
         context used for updating should be regenerated
         at each frame.  So no caching.
         """
@@ -158,24 +156,23 @@ class MovingCamera(Camera):
     #         self.frame_shape = (self.frame.height, width)
     #     self.resize_frame_shape(fixed_dimension=self.fixed_dimension)
 
-    def get_mobjects_indicating_movement(self):
-        """
-        Returns all mobjects whose movement implies that the camera
+    def get_mobjects_indicating_movement(self) -> list[Mobject]:
+        """Returns all mobjects whose movement implies that the camera
         should think of all other mobjects on the screen as moving
 
         Returns
         -------
-        list
+        list[Mobject]
         """
         return [self.frame]
 
     def auto_zoom(
         self,
-        mobjects: list[Mobject],
+        mobjects: Iterable[Mobject],
         margin: float = 0,
         only_mobjects_in_frame: bool = False,
         animate: bool = True,
-    ):
+    ) -> Mobject:
         """Zooms on to a given array of mobjects (or a singular mobject)
         and automatically resizes to frame all the mobjects.
 
@@ -205,10 +202,36 @@ class MovingCamera(Camera):
             or ScreenRectangle with position and size updated to zoomed position.
 
         """
-        scene_critical_x_left = None
-        scene_critical_x_right = None
-        scene_critical_y_up = None
-        scene_critical_y_down = None
+        (
+            scene_critical_x_left,
+            scene_critical_x_right,
+            scene_critical_y_up,
+            scene_critical_y_down,
+        ) = self._get_bounding_box(mobjects, only_mobjects_in_frame)
+
+        # calculate center x and y
+        x = (scene_critical_x_left + scene_critical_x_right) / 2
+        y = (scene_critical_y_up + scene_critical_y_down) / 2
+
+        # calculate proposed width and height of zoomed scene
+        new_width = abs(scene_critical_x_left - scene_critical_x_right)
+        new_height = abs(scene_critical_y_up - scene_critical_y_down)
+
+        m_target = self.frame.animate if animate else self.frame
+        # zoom to fit all mobjects along the side that has the largest size
+        if new_width / self.frame.width > new_height / self.frame.height:
+            return m_target.set_x(x).set_y(y).set(width=new_width + margin)
+        else:
+            return m_target.set_x(x).set_y(y).set(height=new_height + margin)
+
+    def _get_bounding_box(
+        self, mobjects: Iterable[Mobject], only_mobjects_in_frame: bool
+    ) -> tuple[float, float, float, float]:
+        bounding_box_located = False
+        scene_critical_x_left: float = 0
+        scene_critical_x_right: float = 1
+        scene_critical_y_up: float = 1
+        scene_critical_y_down: float = 0
 
         for m in mobjects:
             if (m == self.frame) or (
@@ -218,11 +241,12 @@ class MovingCamera(Camera):
                 continue
 
             # initialize scene critical points with first mobjects critical points
-            if scene_critical_x_left is None:
+            if not bounding_box_located:
                 scene_critical_x_left = m.get_critical_point(LEFT)[0]
                 scene_critical_x_right = m.get_critical_point(RIGHT)[0]
                 scene_critical_y_up = m.get_critical_point(UP)[1]
                 scene_critical_y_down = m.get_critical_point(DOWN)[1]
+                bounding_box_located = True
 
             else:
                 if m.get_critical_point(LEFT)[0] < scene_critical_x_left:
@@ -237,17 +261,14 @@ class MovingCamera(Camera):
                 if m.get_critical_point(DOWN)[1] < scene_critical_y_down:
                     scene_critical_y_down = m.get_critical_point(DOWN)[1]
 
-        # calculate center x and y
-        x = (scene_critical_x_left + scene_critical_x_right) / 2
-        y = (scene_critical_y_up + scene_critical_y_down) / 2
-
-        # calculate proposed width and height of zoomed scene
-        new_width = abs(scene_critical_x_left - scene_critical_x_right)
-        new_height = abs(scene_critical_y_up - scene_critical_y_down)
+        if not bounding_box_located:
+            raise Exception(
+                "Could not determine bounding box of the mobjects given to 'auto_zoom'."
+            )
 
-        m_target = self.frame.animate if animate else self.frame
-        # zoom to fit all mobjects along the side that has the largest size
-        if new_width / self.frame.width > new_height / self.frame.height:
-            return m_target.set_x(x).set_y(y).set(width=new_width + margin)
-        else:
-            return m_target.set_x(x).set_y(y).set(height=new_height + margin)
+        return (
+            scene_critical_x_left,
+            scene_critical_x_right,
+            scene_critical_y_up,
+            scene_critical_y_down,
+        )

manim/camera/multi_camera.py

@@ -5,7 +5,13 @@ from __future__ import annotations
 __all__ = ["MultiCamera"]
 
 
-from manim.mobject.types.image_mobject import ImageMobject
+from collections.abc import Iterable
+from typing import Any
+
+from typing_extensions import Self
+
+from manim.mobject.mobject import Mobject
+from manim.mobject.types.image_mobject import ImageMobjectFromCamera
 
 from ..camera.moving_camera import MovingCamera
 from ..utils.iterables import list_difference_update
@@ -16,10 +22,10 @@ class MultiCamera(MovingCamera):
 
     def __init__(
         self,
-        image_mobjects_from_cameras: ImageMobject | None = None,
-        allow_cameras_to_capture_their_own_display=False,
-        **kwargs,
-    ):
+        image_mobjects_from_cameras: Iterable[ImageMobjectFromCamera] | None = None,
+        allow_cameras_to_capture_their_own_display: bool = False,
+        **kwargs: Any,
+    ) -> None:
         """Initialises the MultiCamera
 
         Parameters
@@ -29,7 +35,7 @@ class MultiCamera(MovingCamera):
         kwargs
             Any valid keyword arguments of MovingCamera.
         """
-        self.image_mobjects_from_cameras = []
+        self.image_mobjects_from_cameras: list[ImageMobjectFromCamera] = []
         if image_mobjects_from_cameras is not None:
             for imfc in image_mobjects_from_cameras:
                 self.add_image_mobject_from_camera(imfc)
@@ -38,7 +44,9 @@ class MultiCamera(MovingCamera):
         )
         super().__init__(**kwargs)
 
-    def add_image_mobject_from_camera(self, image_mobject_from_camera: ImageMobject):
+    def add_image_mobject_from_camera(
+        self, image_mobject_from_camera: ImageMobjectFromCamera
+    ) -> None:
         """Adds an ImageMobject that's been obtained from the camera
         into the list ``self.image_mobject_from_cameras``
 
@@ -53,20 +61,20 @@ class MultiCamera(MovingCamera):
         assert isinstance(imfc.camera, MovingCamera)
         self.image_mobjects_from_cameras.append(imfc)
 
-    def update_sub_cameras(self):
+    def update_sub_cameras(self) -> None:
         """Reshape sub_camera pixel_arrays"""
         for imfc in self.image_mobjects_from_cameras:
             pixel_height, pixel_width = self.pixel_array.shape[:2]
-            imfc.camera.frame_shape = (
-                imfc.camera.frame.height,
-                imfc.camera.frame.width,
-            )
+            # imfc.camera.frame_shape = (
+            #     imfc.camera.frame.height,
+            #     imfc.camera.frame.width,
+            # )
             imfc.camera.reset_pixel_shape(
                 int(pixel_height * imfc.height / self.frame_height),
                 int(pixel_width * imfc.width / self.frame_width),
             )
 
-    def reset(self):
+    def reset(self) -> Self:
         """Resets the MultiCamera.
 
         Returns
@@ -79,7 +87,7 @@ class MultiCamera(MovingCamera):
         super().reset()
         return self
 
-    def capture_mobjects(self, mobjects, **kwargs):
+    def capture_mobjects(self, mobjects: Iterable[Mobject], **kwargs: Any) -> None:
         self.update_sub_cameras()
         for imfc in self.image_mobjects_from_cameras:
             to_add = list(mobjects)
@@ -88,7 +96,7 @@ class MultiCamera(MovingCamera):
             imfc.camera.capture_mobjects(to_add, **kwargs)
         super().capture_mobjects(mobjects, **kwargs)
 
-    def get_mobjects_indicating_movement(self):
+    def get_mobjects_indicating_movement(self) -> list[Mobject]:
         """Returns all mobjects whose movement implies that the camera
         should think of all other mobjects on the screen as moving