Renamed distance parameter of :class:.ThreeDScene and :class:.ThreeDCamera to focal_distance (ManimCommunity#2123)

* deprecate distance

* updated deprecation

Co-authored-by: Benjamin Hackl <[email protected]>

Author: icedcoffeeee

manim/camera/three_d_camera.py

@@ -17,14 +17,15 @@
 from ..mobject.types.point_cloud_mobject import Point
 from ..mobject.value_tracker import ValueTracker
 from ..utils.color import get_shaded_rgb
+from ..utils.deprecation import deprecated
 from ..utils.family import extract_mobject_family_members
 from ..utils.space_ops import rotation_about_z, rotation_matrix
 
 
 class ThreeDCamera(Camera):
     def __init__(
         self,
-        distance=20.0,
+        focal_distance=20.0,
         shading_factor=0.2,
         default_distance=5.0,
         light_source_start_point=9 * DOWN + 7 * LEFT + 10 * OUT,
@@ -47,7 +48,7 @@ def __init__(
         """
         self._frame_center = Point(kwargs.get("frame_center", ORIGIN), stroke_width=0)
         super().__init__(**kwargs)
-        self.distance = distance
+        self.focal_distance = focal_distance
         self.phi = phi
         self.theta = theta
         self.gamma = gamma
@@ -61,7 +62,7 @@ def __init__(
         self.max_allowable_norm = 3 * config["frame_width"]
         self.phi_tracker = ValueTracker(self.phi)
         self.theta_tracker = ValueTracker(self.theta)
-        self.distance_tracker = ValueTracker(self.distance)
+        self.focal_distance_tracker = ValueTracker(self.focal_distance)
         self.gamma_tracker = ValueTracker(self.gamma)
         self.zoom_tracker = ValueTracker(self.zoom)
         self.fixed_orientation_mobjects = {}
@@ -81,7 +82,7 @@ def capture_mobjects(self, mobjects, **kwargs):
         super().capture_mobjects(mobjects, **kwargs)
 
     def get_value_trackers(self):
-        """Returns list of ValueTrackers of phi, theta, distance and gamma
+        """Returns list of ValueTrackers of phi, theta, focal_distance and gamma
 
         Returns
         -------
@@ -91,7 +92,7 @@ def get_value_trackers(self):
         return [
             self.phi_tracker,
             self.theta_tracker,
-            self.distance_tracker,
+            self.focal_distance_tracker,
             self.gamma_tracker,
             self.zoom_tracker,
         ]
@@ -163,15 +164,23 @@ def get_theta(self):
         """
         return self.theta_tracker.get_value()
 
+    @deprecated(
+        since="v0.11.0",
+        until="v0.12.0",
+        message="use focal_distance instead.",
+    )
     def get_distance(self):
-        """Returns radial distance from ORIGIN.
+        return self.get_focal_distance()
+
+    def get_focal_distance(self):
+        """Returns focal_distance of the Camera.
 
         Returns
         -------
         float
-            The radial distance from ORIGIN in MUnits.
+            The focal_distance of the Camera in MUnits.
         """
-        return self.distance_tracker.get_value()
+        return self.focal_distance_tracker.get_value()
 
     def get_gamma(self):
         """Returns the rotation of the camera about the vector from the ORIGIN to the Camera.
@@ -214,15 +223,23 @@ def set_theta(self, value):
         """
         self.theta_tracker.set_value(value)
 
+    @deprecated(
+        since="v0.11.0",
+        until="v0.12.0",
+        message="use focal_distance instead.",
+    )
     def set_distance(self, value):
-        """Sets the radial distance between the camera and ORIGIN.
+        return self.set_focal_distance(value)
+
+    def set_focal_distance(self, value):
+        """Sets the focal_distance of the Camera.
 
         Parameters
         ----------
         value : int, float
-            The new radial distance.
+            The focal_distance of the Camera.
         """
-        self.distance_tracker.set_value(value)
+        self.focal_distance_tracker.set_value(value)
 
     def set_gamma(self, value):
         """Sets the angle of rotation of the camera about the vector from the ORIGIN to the Camera.
@@ -296,7 +313,7 @@ def project_points(self, points):
             The points after projecting.
         """
         frame_center = self.frame_center
-        distance = self.get_distance()
+        focal_distance = self.get_focal_distance()
         zoom = self.get_zoom()
         rot_matrix = self.get_rotation_matrix()
 
@@ -309,12 +326,12 @@ def project_points(self, points):
                 # x and y by d / (d-z).  But for points with high
                 # z value that causes weird artifacts, and applying
                 # the exponential helps smooth it out.
-                factor = np.exp(zs / distance)
+                factor = np.exp(zs / focal_distance)
                 lt0 = zs < 0
-                factor[lt0] = distance / (distance - zs[lt0])
+                factor[lt0] = focal_distance / (focal_distance - zs[lt0])
             else:
-                factor = distance / (distance - zs)
-                factor[(distance - zs) < 0] = 10 ** 6
+                factor = focal_distance / (focal_distance - zs)
+                factor[(focal_distance - zs) < 0] = 10 ** 6
             points[:, i] *= factor * zoom
         return points
 

manim/scene/three_d_scene.py

@@ -23,6 +23,7 @@
 from ..renderer.opengl_renderer import OpenGLCamera
 from ..scene.scene import Scene
 from ..utils.config_ops import merge_dicts_recursively
+from ..utils.deprecation import deprecated_params
 
 
 class ThreeDScene(Scene):
@@ -49,14 +50,21 @@ def __init__(
         )
         super().__init__(camera_class=camera_class, **kwargs)
 
+    @deprecated_params(
+        params="distance",
+        since="v0.11.0",
+        until="v0.12.0",
+        message="Use focal_distance instead.",
+    )
     def set_camera_orientation(
         self,
         phi: Optional[float] = None,
         theta: Optional[float] = None,
         gamma: Optional[float] = None,
         zoom: Optional[float] = None,
-        distance: Optional[float] = None,
+        focal_distance: Optional[float] = None,
         frame_center: Optional[Union["Mobject", Sequence[float]]] = None,
+        **kwargs,
     ):
         """
         This method sets the orientation of the camera in the scene.
@@ -69,8 +77,8 @@ def set_camera_orientation(
         theta : int or float, optional
             The azimuthal angle i.e the angle that spins the camera around the Z_AXIS.
 
-        distance : int or float, optional
-            The radial distance between ORIGIN and Camera.
+        focal_distance : int or float, optional
+            The focal_distance of the Camera.
 
         gamma : int or float, optional
             The rotation of the camera about the vector from the ORIGIN to the Camera.
@@ -82,12 +90,13 @@ def set_camera_orientation(
             The new center of the camera frame in cartesian coordinates.
 
         """
+        focal_distance = kwargs.pop("distance", focal_distance)
         if phi is not None:
             self.renderer.camera.set_phi(phi)
         if theta is not None:
             self.renderer.camera.set_theta(theta)
-        if distance is not None:
-            self.renderer.camera.set_distance(distance)
+        if focal_distance is not None:
+            self.renderer.camera.set_focal_distance(focal_distance)
         if gamma is not None:
             self.renderer.camera.set_gamma(gamma)
         if zoom is not None:
@@ -188,13 +197,19 @@ def stop_3dillusion_camera_rotation(self):
         self.renderer.camera.phi_tracker.clear_updaters()
         self.remove(self.renderer.camera.phi_tracker)
 
+    @deprecated_params(
+        params="distance",
+        since="v0.11.0",
+        until="v0.12.0",
+        message="Use focal_distance instead.",
+    )
     def move_camera(
         self,
         phi: Optional[float] = None,
         theta: Optional[float] = None,
         gamma: Optional[float] = None,
         zoom: Optional[float] = None,
-        distance: Optional[float] = None,
+        focal_distance: Optional[float] = None,
         frame_center: Optional[Union["Mobject", Sequence[float]]] = None,
         added_anims: Iterable["Animation"] = [],
         **kwargs,
@@ -211,8 +226,8 @@ def move_camera(
         theta : int or float, optional
             The azimuthal angle i.e the angle that spins the camera around the Z_AXIS.
 
-        distance : int or float, optional
-            The radial distance between ORIGIN and Camera.
+        focal_distance : int or float, optional
+            The radial focal_distance between ORIGIN and Camera.
 
         gamma : int or float, optional
             The rotation of the camera about the vector from the ORIGIN to the Camera.
@@ -228,13 +243,14 @@ def move_camera(
 
         """
         anims = []
+        focal_distance = kwargs.pop("distance", focal_distance)
 
         if config.renderer != "opengl":
             self.camera: ThreeDCamera
             value_tracker_pairs = [
                 (phi, self.camera.phi_tracker),
                 (theta, self.camera.theta_tracker),
-                (distance, self.camera.distance_tracker),
+                (focal_distance, self.camera.focal_distance_tracker),
                 (gamma, self.camera.gamma_tracker),
                 (zoom, self.camera.zoom_tracker),
             ]
@@ -273,7 +289,7 @@ def move_camera(
                 if value is not None:
                     methods[method](value)
 
-            if distance is not None:
+            if focal_distance is not None:
                 warnings.warn(
                     "focal distance of OpenGLCamera can not be adjusted.",
                     stacklevel=2,
@@ -380,7 +396,7 @@ def set_to_default_angled_camera_orientation(self, **kwargs):
         Parameters
         ----------
         **kwargs
-            Some recognised kwargs are phi, theta, distance, gamma,
+            Some recognised kwargs are phi, theta, focal_distance, gamma,
             which have the same meaning as the parameters in set_camera_orientation.
         """
         config = dict(
@@ -491,7 +507,7 @@ def get_default_camera_position(self):
         Returns
         -------
         dict
-            Dictionary of phi, theta, distance, and gamma.
+            Dictionary of phi, theta, focal_distance, and gamma.
         """
         return self.default_angled_camera_position