3D 场景¶

def set_camera_orientation(
    self,
    phi: float | None = None,
    theta: float | None = None,
    gamma: float | None = None,
    zoom: float | None = None,
    focal_distance: float | None = None,
    frame_center: Point3DLike | Mobject | None = None,
) -> None:
    """立即设置相机观察位置：每个给定设置；其余保持不变。

    Args:
        phi: 相机视线与 z 轴之间的夹角，以弧度表示：0 表示从正上方俯视
            xy 平面。
        theta: 相机绕 z 轴的角度，以弧度表示，从 x 轴逆时针方向计量：在
            −90° 时从 y 轴负侧观察，使 x 轴指向右方。
        gamma: 相机绕自身视线转动的角度，以弧度表示。
        zoom: 相机的放大倍数：2 表示将一切放大两倍显示。
        focal_distance: 相机与所观察点的距离，以场景单位表示：越近，
            透视越强。
        frame_center: 相机所观察的点，或其中心为该点的 mobject：相机的帧
            移动到该处。
    """
    cam = self.camera
    for value, tracker in (
        (phi, cam.phi_tracker),
        (theta, cam.theta_tracker),
        (gamma, cam.gamma_tracker),
        (zoom, cam.zoom_tracker),
        (focal_distance, cam.focal_distance_tracker),
    ):
        if value is not None:
            tracker.set_value(value)
    if frame_center is not None:
        cam.frame.move_to(frame_center)

def begin_ambient_camera_rotation(
    self, rate: float = 0.02, about: str = "theta"
) -> None:
    """开始稳定转动相机，贯穿 play 与 wait，直到
    `stop_ambient_camera_rotation`。

    相机的一个角度以稳定速率增长：其跟踪器获得一个更新器
    （一个 [flow][manimgx.mobject.flow]）并加入场景。

    Args:
        rate: 角度增长速率，以弧度每秒表示；负值反方向转动。
        about: 该角度："theta"（绕 z 轴）、"phi" 或 "gamma"，任意大小写。

    Examples:
        ```python
        import manimgx as m


        class ThreeDSceneAmbientRotationExample(m.ThreeDScene):
            def construct(self) -> None:
                self.set_camera_orientation(
                    phi=70 * m.DEGREES, theta=-45 * m.DEGREES
                )
                torus = m.Torus(major_radius=2.5, minor_radius=0.8)
                self.add(m.ThreeDAxes(), torus.set_color(m.TEAL))
                self.begin_ambient_camera_rotation(rate=m.PI / 4)  # 45° a second
                self.wait(4)
        ```
    """
    tracker = self._tracker(about)
    tracker.add_updater(flow(lambda m, dt: m.increment_value(rate * dt)))
    self.add(tracker)

def stop_ambient_camera_rotation(self, about: str = "theta") -> None:
    """停止转动相机：移除该角度跟踪器的每个更新器，跟踪器离开场景。相机
    停留在其转到的位置。

    Args:
        about: 该角度："theta"、"phi" 或 "gamma"，任意大小写。
    """
    tracker = self._tracker(about)
    tracker.clear_updaters()
    self.remove(tracker)

def begin_3dillusion_camera_rotation(
    self,
    rate: float = 1,
    origin_phi: float | None = None,
    origin_theta: float | None = None,
) -> None:
    """开始使相机绕其朝向摇摆，以产生深度错觉，贯穿 play 与 wait，直到
    `stop_3dillusion_camera_rotation`。

    相机小幅环绕：`theta` 在 `origin_theta` 两侧各 0.2 弧度间摆动，
    `phi` 在 `origin_phi` 与少 0.2 弧度之间，二者相差四分之一周期。两个
    角度的跟踪器获得更新器（flow）并加入场景。

    Args:
        rate: 摇摆速度，以每秒其周期的弧度表示：一个周期耗时
            2π / `rate` 秒。
        origin_phi: 摇摆起自的 `phi`；None 表示相机当前值。
        origin_theta: 摇摆所绕的 `theta`；None 表示相机当前值。
    """
    cam = self.camera
    origin_theta = cam.get_theta() if origin_theta is None else origin_theta
    origin_phi = cam.get_phi() if origin_phi is None else origin_phi
    clocks = [0.0, 0.0]

    def swing_theta(m: ValueTracker, dt: float) -> None:
        clocks[0] += dt * rate
        m.set_value(origin_theta + 0.2 * np.sin(clocks[0]))

    def swing_phi(m: ValueTracker, dt: float) -> None:
        clocks[1] += dt * rate
        m.set_value(origin_phi + 0.1 * np.cos(clocks[1]) - 0.1)

    cam.theta_tracker.add_updater(flow(swing_theta))
    cam.phi_tracker.add_updater(flow(swing_phi))
    self.add(cam.theta_tracker, cam.phi_tracker)

def stop_3dillusion_camera_rotation(self) -> None:
    """停止摇摆相机：移除 `theta` 与 `phi` 跟踪器的每个更新器，它们离开
    场景。相机停留在摇摆所留位置。"""
    for tracker in (self.camera.theta_tracker, self.camera.phi_tracker):
        tracker.clear_updaters()
        self.remove(tracker)

def move_camera(
    self,
    phi: float | None = None,
    theta: float | None = None,
    gamma: float | None = None,
    zoom: float | None = None,
    focal_distance: float | None = None,
    frame_center: Point3DLike | Mobject | None = None,
    added_anims: Sequence[Animation] = (),
    **kwargs: Unpack[TransformOptions],
) -> None:
    """在一次 play 中为相机添加动画到新朝向：每个给定设置；其余保持不变。

    每个设置从其值稳定移动到新值，由速率函数缓动，因此大 2π 的 `theta`
    使相机绕一周。帧在给定 `frame_center` 时移动到该处，`added_anims` 一同
    播放。

    Args:
        phi: 相机视线与 z 轴之间的夹角，以弧度表示：0 表示从正上方俯视
            xy 平面。
        theta: 相机绕 z 轴的角度，以弧度表示，从 x 轴逆时针方向计量。
        gamma: 相机绕自身视线转动的角度，以弧度表示。
        zoom: 相机的放大倍数：2 表示将一切放大两倍显示。
        focal_distance: 相机与所观察点的距离，以场景单位表示。
        frame_center: 相机要观察的点，或其中心为该点的 mobject。
        added_anims: 一同播放的动画。
        **kwargs: play 中每个动画的[变换选项][manimgx.animation.transform.TransformOptions]，
            附加动画亦然。

    Examples:
        ```python
        import manimgx as m


        class ThreeDSceneMoveCameraExample(m.ThreeDScene):
            def construct(self) -> None:
                cube = m.Cube(side_length=2.5, fill_opacity=0.8, fill_color=m.BLUE)
                self.add(m.ThreeDAxes(), cube)
                self.move_camera(
                    phi=70 * m.DEGREES, theta=-45 * m.DEGREES, run_time=2
                )
                self.move_camera(theta=45 * m.DEGREES, zoom=1.5, run_time=2)
        ```
    """
    cam = self.camera
    pairs = (
        (phi, cam.phi_tracker),
        (theta, cam.theta_tracker),
        (focal_distance, cam.focal_distance_tracker),
        (gamma, cam.gamma_tracker),
        (zoom, cam.zoom_tracker),
    )
    anims: list[Animation] = [
        tracker.animate.set_value(value)
        for value, tracker in pairs
        if value is not None
    ]
    if frame_center is not None:
        anims.append(cam.frame.animate.move_to(frame_center))
    self.play(*anims, *added_anims, **kwargs)
    if frame_center is not None:
        self.remove(cam.frame)

def add_fixed_in_frame_mobjects(self, *mobjects: Mobject) -> None:
    """添加固定到屏幕的 mobject：每个按其点所在位置绘制，如同在以原点为中心的
    二维视图中，绘制在一切之上。

    它们被添加到场景，无论相机的角度、缩放与中心如何都保持在屏幕上的位置：
    用 `to_corner` 放置的标题停留在其角落。其中的一切现在及以后都被固定：
    之后添加的成员（一个数字的新数位、更新器或 Transform 产生的部分）也
    被固定。
    """
    self.add(*mobjects)
    self.camera.add_fixed_in_frame_mobjects(*mobjects)