3D scenes¶

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:
    """Set where the camera looks from, at once: each setting given; the others stay
    as they are.

    Args:
        phi: The angle between the camera's line of sight and the z axis, in
            radians: 0 looks straight down on the xy plane.
        theta: The camera's angle around the z axis, in radians, counterclockwise
            from the x axis: at −90° it looks from the side of negative y, so that x
            points right.
        gamma: How far the camera turns about its line of sight, in radians.
        zoom: How much the camera magnifies: 2 shows everything twice as large.
        focal_distance: The camera's distance from the point it looks at, in scene
            units: the nearer, the stronger the perspective.
        frame_center: The point the camera looks at, or a mobject whose center it
            is: the camera's frame moves there.
    """
    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:
    """Start turning the camera steadily, through plays and waits alike, until
    `stop_ambient_camera_rotation`.

    One of the camera's angles grows at a steady rate: its tracker gets an updater
    (a [flow][manimgx.mobject.flow]) and joins the scene.

    Args:
        rate: How fast the angle grows, in radians per second; a negative rate turns
            the other way.
        about: The angle: "theta" (around the z axis), "phi" or "gamma", in any
            case.

    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:
    """Stop turning the camera: every updater of the angle's tracker is removed, and
    the tracker leaves the scene. The camera stays where it turned to.

    Args:
        about: The angle: "theta", "phi" or "gamma", in any case.
    """
    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:
    """Start swaying the camera around its orientation, for an illusion of depth,
    through plays and waits alike, until `stop_3dillusion_camera_rotation`.

    The camera circles a little: `theta` swings 0.2 radians either side of
    `origin_theta`, and `phi` between `origin_phi` and 0.2 radians less, a quarter
    of a cycle apart. The trackers of the two angles get updaters (flows) and join
    the scene.

    Args:
        rate: How fast it sways, in radians of its cycle per second: a cycle takes
            2π / `rate` seconds.
        origin_phi: The `phi` it sways from; None for the camera's present one.
        origin_theta: The `theta` it sways about; None for the camera's present one.
    """
    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:
    """Stop swaying the camera: every updater of the `theta` and `phi` trackers is
    removed, and they leave the scene. The camera stays where the sway left it."""
    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:
    """Animate the camera to a new orientation, in one play: each setting given; the
    others stay as they are.

    Each setting moves steadily from its value to the new one, eased by the rate
    function, so a `theta` 2π greater takes the camera once around. The frame moves
    to `frame_center` if given, and `added_anims` play along.

    Args:
        phi: The angle between the camera's line of sight and the z axis, in
            radians: 0 looks straight down on the xy plane.
        theta: The camera's angle around the z axis, in radians, counterclockwise
            from the x axis.
        gamma: How far the camera turns about its line of sight, in radians.
        zoom: How much the camera magnifies: 2 shows everything twice as large.
        focal_distance: The camera's distance from the point it looks at, in scene
            units.
        frame_center: The point for the camera to look at, or a mobject whose center
            it is.
        added_anims: Animations to play along.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play, the added ones too.

    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:
    """Add mobjects pinned to the screen: each is drawn where its points are, as in
    a two-dimensional view centered on the origin, over everything else.

    They are added to the scene, and stay where they are on the screen whatever the
    camera's angles, zoom and center: a title placed with `to_corner` stays in its
    corner. Everything in them is pinned, now and later: a member added later (a
    number's new digits, what an updater or a Transform makes) is pinned too.
    """
    self.add(*mobjects)
    self.camera.add_fixed_in_frame_mobjects(*mobjects)