速率函数¶

@unit_interval
def smooth(t: float, inflection: float = 10.0) -> float:
    """慢、快、慢：一条 sigmoid 曲线，拉伸至从 0 运行到 1。

    动画的默认速率函数。

    Args:
        t: 时间，从 0 到 1。
        inflection: 中段陡峭程度：值越大，起点和终点越慢、中段运行越快。

    Returns:
        进度，从 0 到 1。
    """
    error = 1.0 / (1 + np.exp(inflection / 2))  # the logistic curve's value at t = 0
    logistic = 1.0 / (1 + np.exp(-inflection * (t - 0.5)))
    return min(max((logistic - error) / (1 - 2 * error), 0), 1)

@unit_interval
def linear(t: float) -> float:
    """与时间同步推进：t。"""
    return t

@unit_interval
def rush_into(t: float, inflection: float = 10.0) -> float:
    """[smooth][manimgx.smooth] 的前半段，拉伸至整个时间区间：
    缓慢开始，并以最大速度结束。

    Args:
        t: 时间，从 0 到 1。
        inflection: [smooth][manimgx.smooth] 的陡峭程度。

    Returns:
        进度，从 0 到 1。
    """
    return 2 * smooth(t / 2.0, inflection)

@unit_interval
def rush_from(t: float, inflection: float = 10.0) -> float:
    """[smooth][manimgx.smooth] 的后半段，拉伸至整个时间区间：
    以最大速度开始，并向终点逐渐减速。

    Args:
        t: 时间，从 0 到 1。
        inflection: [smooth][manimgx.smooth] 的陡峭程度。

    Returns:
        进度，从 0 到 1。
    """
    return 2 * smooth(t / 2.0 + 0.5, inflection) - 1

@unit_interval
def slow_into(t: float) -> float:
    """√(1 − (1 − t)²)，一条四分之一圆：急剧开始，并减速至
    停止。"""
    return float(np.sqrt(1 - (1 - t) * (1 - t)))

@unit_interval
def double_smooth(t: float) -> float:
    """两次 [smooth][manimgx.smooth] 运动，每次在半程时间内走完半程：
    在中点处达到最慢速度。"""
    return 0.5 * smooth(2 * t) if t < 0.5 else 0.5 * (1 + smooth(2 * t - 1))

@zero
def there_and_back(t: float, inflection: float = 10.0) -> float:
    """去而复返：在中点之前以 [smooth][manimgx.smooth] 推进至终点，
    再返回起点。

    Args:
        t: 时间，从 0 到 1。
        inflection: [smooth][manimgx.smooth] 的陡峭程度。

    Returns:
        进度，起点和终点处为 0，中点处为 1。
    """
    return smooth(2 * t if t < 0.5 else 2 * (1 - t), inflection)

@zero
def there_and_back_with_pause(t: float, pause_ratio: float = 1.0 / 3) -> float:
    """去而复返并带停顿：以 [smooth][manimgx.smooth] 推进至终点，
    在该处停顿，再返回起点。

    Args:
        t: 时间，从 0 到 1。
        pause_ratio: 在中点终点处停留的时间占总时间的比例。

    Returns:
        进度，起点和终点处为 0，停顿期间为 1。
    """
    a = 2.0 / (1.0 - pause_ratio)
    if t < 0.5 - pause_ratio / 2:
        return smooth(a * t)
    if t < 0.5 + pause_ratio / 2:
        return 1
    return smooth(a - a * t)

@unit_interval
def running_start(t: float, pull_factor: float = -0.5) -> float:
    """先后退蓄力起跑，再冲向终点：使用默认拉力时，
    在 t ≈ 0.29 处后退至 −0.18。

    Args:
        t: 时间，从 0 到 1。
        pull_factor: 后退程度：其 Bézier 曲线七个控制值
            (0, 0, pull, pull, 1, 1, 1) 中的第三和第四个。

    Returns:
        进度，从 0 到 1，期间会跌破 0。
    """
    mt = 1 - t
    return (
        15 * t**2 * mt**4 * pull_factor
        + 20 * t**3 * mt**3 * pull_factor
        + 15 * t**4 * mt**2
        + 6 * t**5 * mt
        + t**6
    )

@unit_interval
def lingering(t: float) -> float:
    """在 0.8 倍时间内匀速到达终点，随后在该处停留。"""
    return squish_rate_func(lambda x: x, 0, 0.8)(t)

@zero
def wiggle(t: float, wiggles: float = 2) -> float:
    """向起点两侧摆动并返回：sin(`wiggles`·πt)，其幅度如
    [there_and_back][manimgx.there_and_back] 般先涨后落。

    默认 2 次摆动时，先摆至 0.73，再摆至 −0.73。

    Args:
        t: 时间，从 0 到 1。
        wiggles: 摆动次数，向某一侧或另一侧。

    Returns:
        进度，起点和终点处为 0。
    """
    return there_and_back(t) * float(np.sin(wiggles * np.pi * t))

@unit_interval
def exponential_decay(t: float, half_life: float = 0.1) -> float:
    """1 − e^(−t / `half_life`)，缩放至终点为 1：急速出发，
    随后以越来越慢的速度逼近终点。

    使用默认时间常数时，在 t = 0.1 处达到约 1 − 1/e ≈ 0.63。

    Args:
        t: 时间，从 0 到 1。
        half_life: 时间常数，以占总时间的比例表示。

    Returns:
        进度，从 0 到 1。
    """
    return float(np.expm1(-t / half_life) / np.expm1(-1 / half_life))

@unit_interval
def smoothstep(t: float) -> float:
    """3t² − 2t³：起点和终点处静止；比 [smooth][manimgx.smooth] 更平缓。"""
    return 3 * t**2 - 2 * t**3

@unit_interval
def smootherstep(t: float) -> float:
    """6t⁵ − 15t⁴ + 10t³：起点和终点处静止，且在该处无加速度。"""
    return 6 * t**5 - 15 * t**4 + 10 * t**3

def squish_rate_func(func: RateFunc, a: float = 0.4, b: float = 0.6) -> RateFunc:
    """将一个速率函数压缩到部分时间段内：它在 `a` 与 `b` 之间运行，
    在其前其后保持两端值不变。

    Args:
        func: 该速率函数。
        a: 起始时刻，从 0 到 1。
        b: 结束时刻，从 `a` 到 1；若等于 `a`，则该函数在 `a` 处
            从起点直接跳至终点。

    Returns:
        压缩后的速率函数。
    """

    def result(t: float) -> float:
        if t < a:
            return func(0.0)
        return func(1.0) if t >= b else func((t - a) / (b - a))

    return result

def not_quite_there(func: RateFunc = smooth, proportion: float = 0.7) -> RateFunc:
    """对一个速率函数进行缩放，使其只走完部分路程。

    Args:
        func: 该速率函数。
        proportion: 行程比例：其进度按此系数缩放。

    Returns:
        缩放后的速率函数。
    """
    return lambda t: proportion * func(t)

def unit_interval[**P](
    function: Callable[Concatenate[float, P], float],
) -> Callable[Concatenate[float, P], float]:
    """使一个速率函数恰好在 0 处开始、恰好在 1 处结束，并在
    [0, 1] 之外保持其两端值不变。

    Args:
        function: 该速率函数，其运行区间为 0 到 1。

    Returns:
        该速率函数：在 0 之前取 0，从 1 起取 1。
    """

    @functools.wraps(function)
    def wrapper(t: float, /, *args: P.args, **kwargs: P.kwargs) -> float:
        # its ends are exact, whatever rounding its formula does there: an animation lands
        if 0 < t < 1:
            return function(t, *args, **kwargs)
        return 0 if t <= 0 else 1

    return wrapper

def zero[**P](
    function: Callable[Concatenate[float, P], float],
) -> Callable[Concatenate[float, P], float]:
    """使一个速率函数回到 0、其起点和终点都恰为 0，并在
    [0, 1] 之外保持取 0。

    Args:
        function: 该速率函数，其运行区间为 0 到 1。

    Returns:
        该速率函数：在 0 之前取 0，从 1 起取 0。
    """

    @functools.wraps(function)
    def wrapper(t: float, /, *args: P.args, **kwargs: P.kwargs) -> float:
        return function(t, *args, **kwargs) if 0 < t < 1 else 0

    return wrapper