更新器¶

def add_updater(
    self,
    update_function: Updater[Self],
    index: int | None = None,
    call_updater: bool = False,
) -> Self:
    """添加更新器：一个随时间推移保持 mobject 更新的函数。

    更新器是关于 mobject 的函数，每帧运行一次——以保持某种关系，
    如标签在点旁边——或者，若其有一个名为 `dt` 的参数，则是关于
    mobject 和 `dt` 的函数：`dt` 为自上次运行以来、自添加以来、mobject 加入场景以来
    或其更新恢复以来的场景时间秒数。基于时间的更新器按经过的时间移动 mobject：
    `lambda mob, dt: mob.rotate(dt * PI)` 以每秒半圈的速度旋转它，与帧率无关。
    更新器的返回值被忽略。

    场景在每一帧运行其中各 mobject 的更新器，在正在播放的动画将它们移动到该帧时刻之后，
    以及在每次 play 和 wait 的结束时运行：按 mobject 加入场景的顺序逐个处理，
    mobject 自身的更新器在其子 mobject 的之前运行，而
    [recorder][manimgx.mobject.record] 在所有其余的之后运行。因此，要让一个 mobject
    跟随另一个，应在它之后添加，否则它会看到另一个的更新器在前一时刻将其留在何处。
    更新器在动画播放 mobject 时继续运行，在动画之下（参见
    [animation options][manimgx.animation.timeline.AnimationOptions] 中的
    `suspend_mobject_updating`）。基于时间的更新器在场景的模拟时钟上步进，
    `config.simulation_rate` 每秒滴答一次，因此它在任何帧率下都采取相同的步长；
    将一个无论时间如何划分都做相同之事的更新器声明为 [flow][manimgx.mobject.flow]，
    它便会在每一帧精确运行。

    Args:
        update_function: 更新器：关于 mobject 的函数，或关于 mobject
            和 `dt` 的函数。
        index: 它在 mobject 的更新器中的位置，更新器按顺序运行；None
            表示最后。
        call_updater: 是否立即运行一次；基于时间的更新器收到的
            `dt` 为 0。

    Examples:
        ```python
        import manimgx as m


        class MobjectAddUpdaterExample(m.Scene):
            def construct(self) -> None:
                hand = m.Line(m.ORIGIN, 3 * m.RIGHT, color=m.BLUE)
                # time-based: a quarter turn about the origin every second
                hand.add_updater(
                    lambda mob, dt: mob.rotate(dt * m.PI / 2, about_point=m.ORIGIN)
                )
                dot = m.Dot(radius=0.2, color=m.YELLOW)
                # per frame: at the hand's end, wherever it is
                dot.add_updater(lambda mob: mob.move_to(hand.get_end()))
                self.add(hand, dot)
                self.wait(3)
        ```
    """
    if index is None:
        self.updaters.append(update_function)
    else:
        self.updaters.insert(index, update_function)
    if not _per_frame(update_function):
        self._since[update_function] = clock.now  # it integrates from now
    if call_updater:
        if _per_frame(update_function):
            update_function(self)
        else:
            cast("Callable[[Self, float], object]", update_function)(self, 0)
    return self

def remove_updater(self, update_function: Updater[Never]) -> Self:
    """从 mobject 中移除一个更新器，每次添加的都被移除。

    这还会取消当前更新中尚未运行的调用，
    包括等待其他更新器完成的记录器。

    Args:
        update_function: 要移除的更新器。
    """
    self.updaters = [u for u in self.updaters if u is not update_function]
    since = self.__dict__.get("_since_")
    if since is not None and update_function not in self.updaters:
        since.pop(update_function, None)
    return self

def clear_updaters(self, recursive: bool = True) -> Self:
    """移除 mobject 的所有更新器，包括仍在当前更新中等待运行的调用。

    Args:
        recursive: 其整个家族的更新器是否也被移除。
    """
    self.updaters = []
    self.__dict__.pop("_since_", None)
    if recursive:
        for sub in self.submobjects:
            sub.clear_updaters()
    return self

def get_updaters(self) -> tuple[Updater[Self], ...]:
    """mobject 自身的更新器，按运行顺序排列。

    通过 [add_updater][manimgx.Mobject.add_updater]、
    [remove_updater][manimgx.Mobject.remove_updater] 和
    [clear_updaters][manimgx.Mobject.clear_updaters] 来更改它们，这些方法会保持
    其时钟。

    Returns:
        它们的一个快照。
    """
    return tuple(self.updaters)

def suspend_updating(self, recursive: bool = True) -> Self:
    """停止 mobject 的更新器运行，以及其下方的家族的更新器，直到
    [resume_updating][manimgx.Mobject.resume_updating]：通过被暂停的 mobject
    更新的任何东西都不运行。

    动画在播放时暂停其所播放 mobject 的更新，并
    改为运行其下方的更新器（参见
    [add_updater][manimgx.Mobject.add_updater]）。

    Args:
        recursive: 其家族的每个成员是否也被暂停，以使其在
            mobject 之外独立更新的地方保持停止（场景也单独持有的成员），
            以及当 mobject 单独恢复时。
    """
    self.updating_suspended = True
    if recursive:
        for sub in self.submobjects:
            sub.suspend_updating(recursive)
    return self

def resume_updating(self, recursive: bool = True) -> Self:
    """让 mobject 的更新器再次运行，从现在开始：被暂停的
    时间不予补偿。

    它们不在此处运行：场景在它下次将世界推进到的地方运行它们——在
    它正在计算的时刻，当动画在结束时恢复它们时，
    否则在下一个时刻，如下一帧。

    Args:
        recursive: 其整个家族的更新器是否也恢复：单独恢复时，
            mobject 再次运行，以及其下方未被自身暂停的成员。
    """
    # not run here as well: the instant's own pass runs them, and a per-frame
    # updater would run twice at one instant
    self.updating_suspended = False
    if recursive:
        for sub in self.submobjects:
            sub.resume_updating(recursive)
    self._stamp(clock.now, recursive)
    return self

def update(self, dt: float = 0, recursive: bool = True) -> Self:
    """立即运行该 mobject 的每个更新器一次；当其更新被挂起时，不运行任何内容。

    场景本身会在每一帧运行更新器：此方法则是在当下手动运行它们。

    Args:
        dt: 传递给其基于时间的更新器的秒数。
        recursive: 其子 mobject 的更新器是否也随之一并运行。
    """
    # CE's; the scene uses `advance`
    if self.updating_suspended:
        return self
    updaters = self.updaters
    for updater in updaters:
        if updaters is not self.updaters and not _has_updater(
            self.updaters, updater
        ):
            continue
        if _per_frame(updater):
            updater(self)
        else:
            cast("Callable[[Self, float], object]", updater)(self, dt)
    if recursive:
        for sub in self.submobjects:
            sub.update(dt, recursive)
    return self

def flow[U: Callable[..., object]](updater: U) -> U:
    """将一个基于时间的更新器声明为流：即在一段时间内无论该时间如何划分为步长，
    其所做之事都相同的更新器。

    基于时间的更新器会收到 `dt`，即自上次运行以来经过的秒数。大多数更新器是可组合的：
    以某个速率移动 mobject 的更新器（`mob.shift(dt * velocity)`），或按其已运行时间的
    函数来设定它的更新器，在一步 `dt` 中所做之事与在两步 `dt / 2` 中所做之事相同。流在
    场景计算的每个时刻运行——每一帧，以及每次 play 和 wait 的结束——并收到确切的经过
    时间，因此每一帧都显示其在该帧时刻的状态。

    任何其他基于时间的更新器都是被模拟的，因为其所做之事可能依赖于其步长（积分器、
    弹跳的球）：它在自己的时钟上步进，`config.simulation_rate` 每秒滴答一次（60），
    以及每次 play 和 wait 的结束，因此它在任何帧率下都采取相同的步长，而一帧显示的是
    其最后一次滴答留下的状态。当一个模拟更新器在场景中时，场景会计算每一个滴答，
    包括帧之间的滴答。将一个可组合的更新器声明为流，可使它在每一帧都精确，并省去
    那些滴答；[always_shift][manimgx.always_shift] 和 [always_rotate][manimgx.always_rotate]
    添加的是流。一个只读取世界状态的更新器，如追踪路径的更新器，是一个
    [recorder][manimgx.mobject.record]。

    Args:
        updater: 一个基于时间的更新器：关于 mobject 和 `dt` 的函数。

    Returns:
        同一个更新器，被声明为流，可用
        [add_updater][manimgx.Mobject.add_updater] 添加。

    Examples:
        ```python
        import manimgx as m
        from manimgx.mobject import flow


        @flow
        def orbit(dot: m.Mobject, dt: float) -> None:
            dot.rotate(dt * m.PI / 2, about_point=m.ORIGIN)  # a quarter turn a second


        class FlowExample(m.Scene):
            def construct(self) -> None:
                dot = m.Dot(3 * m.RIGHT, radius=0.25, color=m.YELLOW)
                dot.add_updater(orbit)
                self.add(m.Circle(radius=3, color=m.BLUE), dot)
                self.wait(3)
        ```
    """
    _FLOWS.add(_function(updater))
    return updater

def record[U: Callable[..., object]](updater: U) -> U:
    """将一个基于时间的更新器声明为记录器：即读取世界状态且仅改变自身 mobject 的更新器，
    如 [TracedPath][manimgx.TracedPath] 的更新器。

    场景在它计算的每个时刻运行记录器——模拟时钟的每个滴答、每一帧，以及每次 play 和
    wait 的结束——在所有其他东西就位之后：正在播放的动画、mobject 的更新器和场景的更新器。
    在一帧或一次 play 或 wait 的结束时，它运行两次：首先在仅由时间带到那里的世界上运行，
    如一个滴答所看到的那样，然后在每帧更新器运行之后再运行一次，以便它能区分它们的
    变化（追踪路径将其分散到结束于该处的帧上）。记录器是被模拟的（参见
    [flow][manimgx.mobject.flow]）：当记录器在场景中时，场景会计算模拟时钟的滴答。

    Args:
        updater: 一个基于时间的更新器：关于 mobject 和 `dt` 的函数，或此类方法，
            在其类定义处装饰。

    Returns:
        同一个更新器，被声明为记录器，可用
        [add_updater][manimgx.Mobject.add_updater] 添加。
    """
    # the scene computes a frame or an event in two passes (`Scene._instant`) only while
    # a recorder is in it; the second pass is `clock.framing`
    _RECORDERS.add(_function(updater))
    return updater

def always_redraw[M: Mobject](func: Callable[[], M]) -> M:
    """创建一个每帧由函数重新构建的 mobject。

    `func` 现在构建该 mobject，并且每一帧该 mobject 都变为 `func` 当时所构建的对象（参见
    [`become`][manimgx.Mobject.become]）：它在场景中始终是同一个对象，并跟随 `func` 所读取的
    任何内容——值追踪器、其他 mobject。适用于形状以无运动跟随的方式依赖于其他对象的情况：贴合
    不断增长的形状的花括号、两个移动点之间的连线、曲线下方的面积。

    Args:
        func: 一个无参函数，用于构建该 mobject。

    Returns:
        该 mobject，附带其更新器：将其添加到场景中。

    Examples:
        ```python
        import manimgx as m


        class AlwaysRedrawExample(m.Scene):
            def construct(self) -> None:
                width = m.ValueTracker(2)
                box = m.always_redraw(
                    lambda: m.Rectangle(width=width.get_value(), height=3, color=m.BLUE)
                )
                brace = m.always_redraw(lambda: m.Brace(box, m.DOWN, color=m.YELLOW))
                self.add(box, brace)
                self.play(width.animate.set_value(11), run_time=2)
                self.play(width.animate.set_value(5))
        ```
    """
    mob = func()
    mob.add_updater(lambda m: m.become(func()))
    return mob

def always_rotate[M: Mobject](
    mobject: M,
    rate: float = 20 * DEGREES,
    axis: Vector3DLike = OUT,
    **kwargs: Unpack[Pivot],
) -> M:
    """使 mobject 以恒定速度持续旋转。

    它添加一个基于时间的更新器，即 [flow][manimgx.mobject.flow]，因此在每一帧该 mobject 都恰好
    处于其速度所带到的角度，无论在播放还是等待期间皆然。

    Args:
        mobject: 要旋转的 mobject。
        rate: 速度，单位为弧度每秒；正值表示逆时针旋转。
        axis: 旋转所绕的轴。
        **kwargs: [Pivot keywords][manimgx.mobject.Pivot]：旋转所绕的点，
            未指定时为其中心。

    Returns:
        该 mobject，附带其更新器。

    Examples:
        ```python
        import manimgx as m


        class AlwaysRotateExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
                square.shift(3.5 * m.LEFT)
                m.always_rotate(square, rate=m.PI / 2)  # a quarter turn a second
                center = m.Dot(3.5 * m.RIGHT, color=m.YELLOW)
                moon = m.Dot(3.5 * m.RIGHT + 2 * m.UP, radius=0.25, color=m.TEAL)
                m.always_rotate(moon, rate=-m.PI, about_point=center.get_center())
                self.add(square, center, moon)
                self.wait(4)
        ```
    """
    mobject.add_updater(flow(lambda m, dt: m.rotate(dt * rate, axis, **kwargs)))
    return mobject

def always_shift[M: Mobject](
    mobject: M, direction: Vector3DLike = RIGHT, rate: float = 0.1
) -> M:
    """使 mobject 沿某方向以恒定速度持续移动。

    它添加一个基于时间的更新器，即 [flow][manimgx.mobject.flow]，因此在每一帧该 mobject 都恰好
    位于其速度所带到的位置，无论在播放还是等待期间皆然。

    Args:
        mobject: 要移动的 mobject。
        direction: 移动的方向；仅方向起作用，长度不起作用。
        rate: 速度，单位为场景单位每秒。

    Returns:
        该 mobject，附带其更新器。

    Examples:
        ```python
        import manimgx as m


        class AlwaysShiftExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=2, color=m.BLUE, fill_opacity=0.8)
                square.shift(5 * m.LEFT)
                m.always_shift(square, m.RIGHT, rate=2.5)
                self.add(square)
                self.play(square.animate.set_color(m.YELLOW), run_time=2)
                self.wait(2)
        ```
    """
    unit = normalize(direction)
    mobject.add_updater(flow(lambda m, dt: m.shift(dt * rate * unit)))
    return mobject

def turn_animation_into_updater(
    animation: Animation, cycle: bool = False, delay: float = 0
) -> Mobject:
    """从 mobject 的更新器播放动画，按 mobject 自身的时间运行，而非在 play 中播放。

    动画立即开始：它取该 mobject 当前的样子，并显示其起始状态。随后其时间随场景时间一同推进，
    从现在起或从该 mobject 加入场景时起；经过 `delay` 秒后开始播放，按其运行时间和速率函数运行。
    当动画结束时，它完成并移除其更新器；若使用 `cycle`，则改为从头开始，周而复始。不会向场景添加
    或从中移除任何内容：请自行添加该 mobject。动画及其时间属于该 mobject：其副本播放它们的副本，
    作用于自身。

    Args:
        cycle: 是否永远重复。
        delay: 开始前等待的时间，单位为秒。

    Returns:
        动画的 mobject，附带其更新器。

    Examples:
        ```python
        import manimgx as m


        class TurnAnimationIntoUpdaterExample(m.Scene):
            def construct(self) -> None:
                shape = m.Square(side_length=2, color=m.BLUE, fill_opacity=0.5)
                squares = m.VGroup(*(shape.copy() for _ in range(3))).arrange(buff=1.5)
                self.add(squares)
                for i, square in enumerate(squares):  # half a second apart
                    m.turn_animation_into_updater(
                        m.Rotate(square, m.PI / 2, run_time=1), delay=0.5 * i
                    )
                self.wait(2.5)
        ```
    """
    mobject = animation.mobject
    animation.suspend_mobject_updating = False
    animation.begin()
    animation.interpolate(
        0
    )  # the object is the animation's from now: at its start, until then
    # the animation and its time are kept on the mobject, so that a copy of it plays a copy
    # of them: the updater holds only their key, and plays those of the mobject it runs on
    key = next(_PLAYED_KEYS)
    played: dict[int, _Played] = mobject.__dict__.setdefault("_played", {})
    played[key] = _Played(animation, -delay)

    def update(m: Mobject, dt: float) -> None:
        state = m.__dict__.get("_played", {}).get(key)
        if state is None:  # nothing of its own to play
            return
        state.elapsed += dt  # its time now: what this frame shows
        if state.elapsed < 0:
            return
        animation, elapsed = state.animation, state.elapsed
        run_time = animation.get_run_time()
        if run_time > 0 and (cycle or elapsed < run_time):
            animation.interpolate(
                (elapsed / run_time) % 1 if cycle else elapsed / run_time
            )
            animation.advance(clock.now)
        else:
            animation.finish()
            m.remove_updater(update)
            del m.__dict__["_played"][key]

    mobject.add_updater(flow(update))  # the animation at the time it has run
    return mobject

def cycle_animation(animation: Animation, delay: float = 0) -> Mobject:
    """从 mobject 的更新器一遍又一遍地播放动画：即带 `cycle` 的
    [`turn_animation_into_updater`][manimgx.turn_animation_into_updater]。

    每个周期都从头开始播放动画：若动画的终点与起点不同，则在每个周期处跳回起点。

    Args:
        delay: 第一个周期开始前等待的时间，单位为秒。

    Returns:
        动画的 mobject，附带其更新器。

    Examples:
        ```python
        import manimgx as m


        class CycleAnimationExample(m.Scene):
            def construct(self) -> None:
                orbit = m.Circle(radius=3, color=m.BLUE)
                planet = m.Dot(orbit.get_start(), radius=0.25, color=m.YELLOW)
                m.cycle_animation(
                    m.MoveAlongPath(planet, orbit, rate_func=m.linear, run_time=2)
                )
                self.add(orbit, planet)
                self.wait(4)
        ```
    """
    return turn_animation_into_updater(animation, cycle=True, delay=delay)