Scene¶

def construct(self) -> None:
    """Describe the scene, what happens and when: override it.

    [`render`][manimgx.Scene.render] runs it once, from top to bottom, and the film
    is what it leaves behind. It is ordinary Python: loops, functions and variables
    work as they do anywhere.
    """

def setup(self) -> None:
    """Prepare the scene: [`render`][manimgx.Scene.render] calls it before
    `construct`.

    It does nothing unless overridden: override it for what several scenes share, in
    a class they derive from.
    """

def tear_down(self) -> None:
    """Finish the scene: [`render`][manimgx.Scene.render] calls it after
    `construct`, before the closing frame.

    It does nothing unless overridden.
    """

def play(self, *animations: Animation, **options: Unpack[TransformOptions]) -> None:
    """Play animations, together, from the scene's present time.

    Each animation starts now and lasts its own run time, and ends when its time is up,
    whatever else still plays: the play lasts as long as the longest one. Then
    `construct` goes on, at the time the play ended. To play animations one after
    another, or each a little after the one before it, play a
    [`Succession`][manimgx.Succession] or a [`LaggedStart`][manimgx.LaggedStart].

    A play brings into the scene what its animations change, if the scene doesn't
    hold it yet, in the order given. An animation that brings its mobject in
    ([`Create`][manimgx.Create], [`FadeIn`][manimgx.FadeIn], …) adds it as it starts,
    and a replacement adds the mobject it turns into as it ends. One that takes its
    mobject out ([`FadeOut`][manimgx.FadeOut], …) removes it as it ends. A
    [`Wait`][manimgx.Wait] played alone is a [`wait`][manimgx.Scene.wait].

    Args:
        *animations: The animations, or iterables of them; at least one.
        **options: [Transform options][manimgx.animation.transform.TransformOptions]
            for every animation: each option given replaces that animation's own. So
            `run_time=2` plays each for 2 seconds, and a `lag_ratio` staggers the
            parts of each (a [`LaggedStart`][manimgx.LaggedStart] staggers the
            animations).

    Examples:
        ```python
        import manimgx as m


        class ScenePlayExample(m.Scene):
            def construct(self) -> None:
                colors = (m.BLUE, m.YELLOW, m.GREEN)
                dots = m.VGroup(*(m.Dot(radius=0.3, color=c) for c in colors))
                dots.arrange(m.DOWN, buff=1.5).shift(5 * m.LEFT)
                self.add(dots)
                self.play(  # all three begin now; the play lasts 3 s
                    dots[0].animate(run_time=1).shift(10 * m.RIGHT),
                    dots[1].animate(run_time=2).shift(10 * m.RIGHT),
                    dots[2].animate(run_time=3).shift(10 * m.RIGHT),
                    rate_func=m.linear,  # for each of the three
                )
        ```
    """
    from manimgx.animation.timeline import AnimationGroup, Wait, _flatten, prepare
    from manimgx.animation.transform import Compositor

    anims = [prepare(a) for a in _flatten(animations)]
    if not anims:
        raise ValueError("Called Scene.play with no animations")
    for anim in anims:
        for key, value in options.items():
            if value is not None:
                setattr(anim, key, value)
    start, index, where = self.clock, self.num_plays, _written()
    wait = anims[0] if len(anims) == 1 and isinstance(anims[0], Wait) else None
    self.num_plays += 1
    if wait is not None:
        end = start + _exact(wait.run_time)
        self._run(end, stop=wait.stop_condition, frozen=bool(wait.is_static_wait))
    else:
        anim = (
            anims[0]
            if len(anims) == 1
            else AnimationGroup(
                *anims, group=Group(), suspend_mobject_updating=False
            )
        )
        end = start + _exact(anim.run_time)
        self.compositor, self._animation = Compositor(), anim
        try:
            self._play(anim, start, end)
        finally:
            self.compositor, self._animation = None, None
    self.film.played(Play(index, start, self.clock, where), tuple(anims))

def wait(
    self,
    duration: float = DEFAULT_WAIT_TIME,
    stop_condition: Callable[[], bool] | None = None,
    frozen_frame: bool | None = None,
) -> None:
    """Let time pass, playing nothing: the updaters keep running.

    The video goes on for `duration` seconds, and `construct` goes on at their end.
    With a `stop_condition`, the wait ends at the first frame at which the condition
    holds, and the scene goes on from that frame's time. With `frozen_frame`, the
    picture holds instead: the video goes on for `duration`, but nothing moves, no
    updater runs, and time-based updaters go on afterward as if no time had passed
    (see [`pause`][manimgx.Scene.pause]).

    Args:
        duration: How long, in seconds.
        stop_condition: A function of no arguments, checked at every frame once it
            is drawn: the wait ends at the first at which it returns True. None: the
            wait lasts its whole duration.
        frozen_frame: Whether the picture holds while the world stands still; it
            cannot be combined with a `stop_condition` (a ValueError). None or
            False: time runs.

    Examples:
        ```python
        import manimgx as m


        class SceneWaitExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
                square.add_updater(lambda mob, dt: mob.rotate(dt * m.PI / 3))
                self.add(square)
                self.wait(2)  # time passes: the updater turns the square
                self.wait(1, frozen_frame=True)  # the picture holds
                self.wait(2)  # it turns on from where it stopped
        ```
    """
    from manimgx.animation.timeline import Wait

    self.play(
        Wait(
            run_time=duration,
            stop_condition=stop_condition,
            frozen_frame=frozen_frame,
        )
    )

def pause(self, duration: float = DEFAULT_WAIT_TIME) -> None:
    """Hold the picture while the world stands still: a [`wait`][manimgx.Scene.wait]
    with `frozen_frame`.

    The video goes on for `duration`; no updater runs, and time-based updaters go on
    afterwards as if no time had passed.

    Args:
        duration: How long, in seconds.
    """
    self.wait(duration, frozen_frame=True)

def wait_until(
    self, stop_condition: Callable[[], bool], max_time: float = 60
) -> None:
    """Let time pass until a condition holds: a [`wait`][manimgx.Scene.wait] that
    ends at the first frame at which `stop_condition` returns True, or after
    `max_time` seconds.

    Args:
        stop_condition: A function of no arguments, checked at every frame once it
            is drawn.
        max_time: The longest it waits, in seconds.
    """
    self.wait(max_time, stop_condition=stop_condition)

def add(self, *mobjects: Mobject) -> Self:
    """Put mobjects in the scene, from now on, in front of those it holds.

    Each is drawn over the mobjects added before it (at an equal z-index), and under
    the foreground mobjects. A mobject the scene holds already moves to the front.
    One that is part of a group the scene holds is taken out of the group's place:
    the group is split, its other members staying where they are, each on its own
    (and the group's own updaters no longer run); a group added takes its members
    from wherever the scene held them. The updaters of the mobjects added run from
    now on: a time-based one's first `dt` counts from the moment its mobject joins
    the scene.

    Args:
        *mobjects: The mobjects, in order: the last is drawn on top.

    Examples:
        ```python
        import manimgx as m


        class SceneAddExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=3.5, color=m.BLUE, fill_opacity=1)
                circle = m.Circle(radius=1.8, color=m.YELLOW, fill_opacity=1)
                circle.shift(1.8 * m.RIGHT)
                self.add(square, circle)  # the circle, added last, is on top
                self.wait()
                self.add(square)  # adding it again brings it to the front
                self.wait()
        ```
    """
    if any(m.updaters for mob in mobjects for m in mob.get_family()):
        present = {id(m) for m in self.get_mobject_family_members()}
        for mob in mobjects:  # joining the world: its updaters are live from now
            for m in mob.get_family():
                if id(m) not in present:
                    m._stamp(clock.now, recursive=False)
    new = remove_list_redundancies([*mobjects, *self.foreground_mobjects])
    self.mobjects = _restructure(self.mobjects, new) + new
    return self

def remove(self, *mobjects: Mobject) -> Self:
    """Take mobjects out of the scene: they are no longer drawn, and their updaters
    stop.

    A mobject that is part of a group the scene holds is taken out the same way: the
    group is split, its other members staying in the scene, each on its own. A
    mobject the scene does not hold is ignored. The mobjects themselves are not
    changed: adding one again shows it as it is then.

    Args:
        *mobjects: The mobjects to take out.
    """
    self.mobjects = _restructure(self.mobjects, mobjects, extract=False)
    self.foreground_mobjects = _restructure(
        self.foreground_mobjects, mobjects, extract=False
    )
    return self

def clear(self) -> Self:
    """Take every mobject out of the scene, the foreground ones too; the scene's own
    updaters stay.
    """
    self.mobjects, self.foreground_mobjects = [], []
    return self

def replace(self, old: Mobject, new: Mobject) -> None:
    """Put a mobject in the scene in another's place: where the other is drawn, even
    inside a group, which then holds the new one.

    `new` is first taken out of the list it joins, if it is there.
    [`ReplacementTransform`][manimgx.ReplacementTransform] ends with it. A mobject
    the scene does not hold raises a ValueError.

    Args:
        old: The mobject to replace: one the scene holds, or a part of one.
        new: The mobject to put in its place.
    """

    def replace_in(lst: list[Mobject]) -> bool:
        if new in lst:
            lst.remove(new)
        for i, m in enumerate(lst):
            if m is old:
                lst[i] = new
                return True
        return any(replace_in(m.submobjects) for m in lst)

    if not (replace_in(self.mobjects) or replace_in(self.foreground_mobjects)):
        raise ValueError(f"Could not find {old} in scene")
    self._holding = None  # (what it holds changed in place)

def bring_to_front(self, *mobjects: Mobject) -> Self:
    """Draw mobjects over the others, but under the foreground mobjects: the same as
    [`add`][manimgx.Scene.add].

    Args:
        *mobjects: The mobjects, in order: the last is drawn on top.
    """
    return self.add(*mobjects)

def bring_to_back(self, *mobjects: Mobject) -> Self:
    """Draw mobjects under all the others, at an equal z-index: they move to the
    start of the scene's mobjects, out of the foreground if they were in it.

    A mobject the scene does not hold is added there, at the bottom.

    Args:
        *mobjects: The mobjects, in order: the first is drawn at the bottom.
    """
    self.remove(*mobjects)
    self.mobjects = [*mobjects, *self.mobjects]
    return self

def add_foreground_mobjects(self, *mobjects: Mobject) -> Self:
    """Put mobjects in the scene, in front: drawn over all the others, at an equal
    z-index, even those added after them.

    Args:
        *mobjects: The mobjects, in order: the last is drawn on top.
    """
    self.foreground_mobjects = remove_list_redundancies(
        [*self.foreground_mobjects, *mobjects]
    )
    return self.add(*mobjects)

def remove_foreground_mobjects(self, *mobjects: Mobject) -> Self:
    """Take mobjects out of the front: they stay in the scene, where they are in its
    drawing order, and mobjects added later are drawn over them.
    """
    self.foreground_mobjects = _restructure(self.foreground_mobjects, mobjects)
    return self

def add_updater(self, func: Callable[[float], object]) -> None:
    """Add an updater to the scene itself: a function it calls with the time that
    passed.

    It is handed `dt`, the scene time in seconds since it last ran (or was added),
    at each instant the scene computes, after the updaters of the mobjects. It steps
    as a mobject's time-based updater does: on the simulation clock
    ([`config.simulation_rate`][manimgx.config.Config.simulation_rate] ticks a
    second, and the end of each play and wait), unless it is a
    [flow][manimgx.mobject.flow], which runs at every frame. What it returns is
    ignored.

    Args:
        func: The updater: a function of one parameter, named `dt`.
    """
    self.updaters.append(func)
    self._since[func] = clock.now

def remove_updater(self, func: Callable[[float], object]) -> None:
    """Remove an updater from the scene, every time it was added.

    This also cancels calls that have not yet run in the current update.

    Args:
        func: The updater.
    """
    self.updaters = [f for f in self.updaters if f is not func]
    if func not in self.updaters:
        self._since.pop(func, None)

def next_section(
    self,
    name: str = "unnamed",
    section_type: SectionType = "default.normal",
    skip_animations: bool = False,
    *,
    notes: str = "",
) -> None:
    """Begin a section of the film here: a slide, when the film is presented.

    A film is a row of sections, each lasting until the next begins (the first begins
    with the film). Presented (`manimgx present`), the film plays a section and, by
    its type, stops at its end until the presenter goes on, goes on by itself, or
    plays it again and again until the presenter goes on. A section begins at a
    frame, whose picture a presentation stops on: if the scene's time falls between
    two frames, the world holds still until the next one. Rendered, a film just plays
    through its sections.

    Args:
        name: The section's name.
        section_type: How a presentation plays the section that begins here:
            `"default.normal"` (or `"presentation.normal"`) stops at its end;
            `"presentation.skip"` goes on by itself; `"presentation.loop"` plays it
            again until the presenter goes on; `"presentation.complete_loop"` too,
            finishing its round first.
        skip_animations: Accepted for Manim compatibility; ignored.
        notes: What the presenter reads during the section.
    """
    fps = self._fps()
    at = Fraction(self.frame) / fps
    if at != self.clock:  # to its frame, the world held still
        self._run(at, frozen=True)
    self.film.section(name, self.clock, section_type, notes)