Coverage for src/manimgx/animation/easing.py: 100%
192 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1# SPDX-FileCopyrightText: 2026 Academa, Inc.
2# SPDX-FileCopyrightText: 2024 the Manim Community Developers
3# SPDX-FileCopyrightText: 2018 3Blue1Brown LLC
4# SPDX-License-Identifier: MIT
6"""Rate functions, ported from Manim CE 0.21 `utils/rate_functions.py` (MIT)."""
8import functools
9import math
10from collections.abc import Callable
11from typing import Concatenate
13import numpy as np
15from manimgx.typing import RateFunc
17__all__ = [
18 "RateFunction",
19 "double_smooth",
20 "ease_in_back",
21 "ease_in_bounce",
22 "ease_in_circ",
23 "ease_in_cubic",
24 "ease_in_elastic",
25 "ease_in_expo",
26 "ease_in_out_back",
27 "ease_in_out_bounce",
28 "ease_in_out_circ",
29 "ease_in_out_cubic",
30 "ease_in_out_elastic",
31 "ease_in_out_expo",
32 "ease_in_out_quad",
33 "ease_in_out_quart",
34 "ease_in_out_quint",
35 "ease_in_out_sine",
36 "ease_in_quad",
37 "ease_in_quart",
38 "ease_in_quint",
39 "ease_in_sine",
40 "ease_out_back",
41 "ease_out_bounce",
42 "ease_out_circ",
43 "ease_out_cubic",
44 "ease_out_elastic",
45 "ease_out_expo",
46 "ease_out_quad",
47 "ease_out_quart",
48 "ease_out_quint",
49 "ease_out_sine",
50 "exponential_decay",
51 "linear",
52 "lingering",
53 "not_quite_there",
54 "running_start",
55 "rush_from",
56 "rush_into",
57 "slow_into",
58 "smooth",
59 "smootherstep",
60 "smoothstep",
61 "squish_rate_func",
62 "there_and_back",
63 "there_and_back_with_pause",
64 "unit_interval",
65 "wiggle",
66 "zero",
67]
69RateFunction = RateFunc
70"""The type of a rate function: a function of the time an animation has run, from 0 to
711, giving how far along it is."""
74def unit_interval[**P](
75 function: Callable[Concatenate[float, P], float],
76) -> Callable[Concatenate[float, P], float]:
77 """Make a rate function start exactly at 0 and end exactly at 1, and hold its ends
78 outside [0, 1].
80 Args:
81 function: The rate function, as it runs from 0 to 1.
83 Returns:
84 The rate function: 0 up to 0, 1 from 1 on.
85 """
87 @functools.wraps(function)
88 def wrapper(t: float, /, *args: P.args, **kwargs: P.kwargs) -> float:
89 # its ends are exact, whatever rounding its formula does there: an animation lands
90 if 0 < t < 1:
91 return function(t, *args, **kwargs)
92 return 0 if t <= 0 else 1
94 return wrapper
97def zero[**P](
98 function: Callable[Concatenate[float, P], float],
99) -> Callable[Concatenate[float, P], float]:
100 """Make a rate function that comes back to 0 start and end exactly at 0, and hold 0
101 outside [0, 1].
103 Args:
104 function: The rate function, as it runs from 0 to 1.
106 Returns:
107 The rate function, 0 up to 0 and from 1 on.
108 """
110 @functools.wraps(function)
111 def wrapper(t: float, /, *args: P.args, **kwargs: P.kwargs) -> float:
112 return function(t, *args, **kwargs) if 0 < t < 1 else 0
114 return wrapper
117@unit_interval
118def linear(t: float) -> float:
119 """Progress in step with time: t."""
120 return t
123@unit_interval
124def smooth(t: float, inflection: float = 10.0) -> float:
125 """Slow, fast, slow: a sigmoid curve, stretched to run from 0 to 1.
127 The default rate function of animations.
129 Args:
130 t: The time, from 0 to 1.
131 inflection: How steep its middle is: higher starts and ends slower and runs
132 faster between.
134 Returns:
135 The progress, from 0 to 1.
136 """
137 error = 1.0 / (1 + np.exp(inflection / 2)) # the logistic curve's value at t = 0
138 logistic = 1.0 / (1 + np.exp(-inflection * (t - 0.5)))
139 return min(max((logistic - error) / (1 - 2 * error), 0), 1)
142@unit_interval
143def smoothstep(t: float) -> float:
144 """3t² − 2t³: starts and ends at rest; gentler than [smooth][manimgx.smooth]."""
145 return 3 * t**2 - 2 * t**3
148@unit_interval
149def smootherstep(t: float) -> float:
150 """6t⁵ − 15t⁴ + 10t³: starts and ends at rest, and without acceleration there."""
151 return 6 * t**5 - 15 * t**4 + 10 * t**3
154@unit_interval
155def rush_into(t: float, inflection: float = 10.0) -> float:
156 """The first half of [smooth][manimgx.smooth], stretched over the whole time:
157 starts slowly and ends at its greatest speed.
159 Args:
160 t: The time, from 0 to 1.
161 inflection: How steep [smooth][manimgx.smooth] is.
163 Returns:
164 The progress, from 0 to 1.
165 """
166 return 2 * smooth(t / 2.0, inflection)
169@unit_interval
170def rush_from(t: float, inflection: float = 10.0) -> float:
171 """The second half of [smooth][manimgx.smooth], stretched over the whole time:
172 starts at its greatest speed and slows toward the end.
174 Args:
175 t: The time, from 0 to 1.
176 inflection: How steep [smooth][manimgx.smooth] is.
178 Returns:
179 The progress, from 0 to 1.
180 """
181 return 2 * smooth(t / 2.0 + 0.5, inflection) - 1
184@unit_interval
185def slow_into(t: float) -> float:
186 """√(1 − (1 − t)²), a quarter circle: starts sharply and slows to a
187 stop."""
188 return float(np.sqrt(1 - (1 - t) * (1 - t)))
191@unit_interval
192def double_smooth(t: float) -> float:
193 """Two [smooth][manimgx.smooth] moves, each half the way in half the time: comes to
194 its slowest speed at the middle."""
195 return 0.5 * smooth(2 * t) if t < 0.5 else 0.5 * (1 + smooth(2 * t - 1))
198@zero
199def there_and_back(t: float, inflection: float = 10.0) -> float:
200 """There and back: [smooth][manimgx.smooth] to the end by the middle, then back to
201 the start.
203 Args:
204 t: The time, from 0 to 1.
205 inflection: How steep [smooth][manimgx.smooth] is.
207 Returns:
208 The progress, 0 at the start and the end and 1 at the middle.
209 """
210 return smooth(2 * t if t < 0.5 else 2 * (1 - t), inflection)
213@zero
214def there_and_back_with_pause(t: float, pause_ratio: float = 1.0 / 3) -> float:
215 """There and back with a pause: [smooth][manimgx.smooth] to the end, a pause there,
216 then back to the start.
218 Args:
219 t: The time, from 0 to 1.
220 pause_ratio: The fraction of the time spent at the end, in the middle.
222 Returns:
223 The progress, 0 at the start and the end and 1 during the pause.
224 """
225 a = 2.0 / (1.0 - pause_ratio)
226 if t < 0.5 - pause_ratio / 2:
227 return smooth(a * t)
228 if t < 0.5 + pause_ratio / 2:
229 return 1
230 return smooth(a - a * t)
233@unit_interval
234def running_start(t: float, pull_factor: float = -0.5) -> float:
235 """Backs up for a running start, then runs to the end: with the default pull, back
236 to −0.18 at t ≈ 0.29.
238 Args:
239 t: The time, from 0 to 1.
240 pull_factor: How far it pulls back: the third and fourth of its Bézier curve's
241 seven control values (0, 0, pull, pull, 1, 1, 1).
243 Returns:
244 The progress, from 0 to 1, after dipping below 0.
245 """
246 mt = 1 - t
247 return (
248 15 * t**2 * mt**4 * pull_factor
249 + 20 * t**3 * mt**3 * pull_factor
250 + 15 * t**4 * mt**2
251 + 6 * t**5 * mt
252 + t**6
253 )
256@zero
257def wiggle(t: float, wiggles: float = 2) -> float:
258 """Swings to either side of the start and comes back: sin(`wiggles`·πt), swelling
259 and fading as [there_and_back][manimgx.there_and_back] does.
261 With the default 2 wiggles, it swings to 0.73 and then to −0.73.
263 Args:
264 t: The time, from 0 to 1.
265 wiggles: How many swings, to one side or the other.
267 Returns:
268 The progress, 0 at the start and the end.
269 """
270 return there_and_back(t) * float(np.sin(wiggles * np.pi * t))
273def squish_rate_func(func: RateFunc, a: float = 0.4, b: float = 0.6) -> RateFunc:
274 """Squeeze a rate function into part of the time: it runs between `a` and `b`, and
275 holds its ends before and after.
277 Args:
278 func: The rate function.
279 a: When it starts, from 0 to 1.
280 b: When it ends, from `a` to 1; if it is `a`, the function steps from its start to
281 its end at `a`.
283 Returns:
284 The squeezed rate function.
285 """
287 def result(t: float) -> float:
288 if t < a:
289 return func(0.0)
290 return func(1.0) if t >= b else func((t - a) / (b - a))
292 return result
295def not_quite_there(func: RateFunc = smooth, proportion: float = 0.7) -> RateFunc:
296 """Scale a rate function so it goes only part of the way.
298 Args:
299 func: The rate function.
300 proportion: How far it goes: its progress is scaled by this.
302 Returns:
303 The scaled rate function.
304 """
305 return lambda t: proportion * func(t)
308@unit_interval
309def lingering(t: float) -> float:
310 """Runs evenly to the end by 0.8 of the time, then lingers there."""
311 return squish_rate_func(lambda x: x, 0, 0.8)(t)
314@unit_interval
315def exponential_decay(t: float, half_life: float = 0.1) -> float:
316 """1 − e^(−t / `half_life`), scaled to end at 1: shoots off, then closes in on the
317 end, ever slower.
319 With the default time constant, it reaches about 1 − 1/e ≈ 0.63 at t = 0.1.
321 Args:
322 t: The time, from 0 to 1.
323 half_life: The time constant, as a fraction of the time.
325 Returns:
326 The progress, from 0 to 1.
327 """
328 return float(np.expm1(-t / half_life) / np.expm1(-1 / half_life))
331# ── the ease family ──
332@unit_interval
333def ease_in_sine(t: float) -> float:
334 """1 − cos(πt/2): starts slow and speeds up."""
335 val: float = 1 - np.cos(t * np.pi / 2)
336 return val
339@unit_interval
340def ease_out_sine(t: float) -> float:
341 """sin(πt/2): starts fast and slows to a stop."""
342 val: float = np.sin(t * np.pi / 2)
343 return val
346@unit_interval
347def ease_in_out_sine(t: float) -> float:
348 """(1 − cos(πt))/2: slow, fast, slow."""
349 val: float = -(np.cos(np.pi * t) - 1) / 2
350 return val
353@unit_interval
354def ease_in_quad(t: float) -> float:
355 """t²: starts slow and speeds up."""
356 return t * t
359@unit_interval
360def ease_out_quad(t: float) -> float:
361 """1 − (1 − t)²: starts fast and slows to a stop."""
362 return 1 - (1 - t) * (1 - t)
365@unit_interval
366def ease_in_out_quad(t: float) -> float:
367 """[ease_in_quad][manimgx.ease_in_quad] up to the middle, then its mirror image:
368 slow, fast, slow."""
369 return 2 * t * t if t < 0.5 else 1 - pow(-2 * t + 2, 2) / 2
372@unit_interval
373def ease_in_cubic(t: float) -> float:
374 """t³: starts slow and speeds up."""
375 return t * t * t
378@unit_interval
379def ease_out_cubic(t: float) -> float:
380 """1 − (1 − t)³: starts fast and slows to a stop."""
381 return 1 - pow(1 - t, 3)
384@unit_interval
385def ease_in_out_cubic(t: float) -> float:
386 """[ease_in_cubic][manimgx.ease_in_cubic] up to the middle, then its mirror image:
387 slow, fast, slow."""
388 return 4 * t * t * t if t < 0.5 else 1 - pow(-2 * t + 2, 3) / 2
391@unit_interval
392def ease_in_quart(t: float) -> float:
393 """t⁴: starts slow and speeds up."""
394 return t * t * t * t
397@unit_interval
398def ease_out_quart(t: float) -> float:
399 """1 − (1 − t)⁴: starts fast and slows to a stop."""
400 return 1 - pow(1 - t, 4)
403@unit_interval
404def ease_in_out_quart(t: float) -> float:
405 """[ease_in_quart][manimgx.ease_in_quart] up to the middle, then its mirror image:
406 slow, fast, slow."""
407 return 8 * t * t * t * t if t < 0.5 else 1 - pow(-2 * t + 2, 4) / 2
410@unit_interval
411def ease_in_quint(t: float) -> float:
412 """t⁵: starts slow and speeds up."""
413 return t * t * t * t * t
416@unit_interval
417def ease_out_quint(t: float) -> float:
418 """1 − (1 − t)⁵: starts fast and slows to a stop."""
419 return 1 - pow(1 - t, 5)
422@unit_interval
423def ease_in_out_quint(t: float) -> float:
424 """[ease_in_quint][manimgx.ease_in_quint] up to the middle, then its mirror image:
425 slow, fast, slow."""
426 return 16 * t * t * t * t * t if t < 0.5 else 1 - pow(-2 * t + 2, 5) / 2
429# Penner's exponential eases, 2^(10t − 10), jump by 2^−10 at their ends: here the exponential
430# runs from 0 at 0 to 1 at 1, (2^(10t) − 1) / 1023 (written out in each: the module's functions
431# are its rate functions)
432@unit_interval
433def ease_in_expo(t: float) -> float:
434 """(2^(10t) − 1) / 1023: barely moves at first, then shoots to the end."""
435 return (pow(2, 10 * t) - 1) / 1023
438@unit_interval
439def ease_out_expo(t: float) -> float:
440 """[ease_in_expo][manimgx.ease_in_expo] turned around: shoots off, then creeps to
441 the end."""
442 return 1 - (pow(2, 10 - 10 * t) - 1) / 1023
445@unit_interval
446def ease_in_out_expo(t: float) -> float:
447 """[ease_in_expo][manimgx.ease_in_expo] up to the middle, then its mirror image."""
448 if t < 0.5:
449 return (pow(2, 20 * t) - 1) / 2046
450 return 1 - (pow(2, 20 - 20 * t) - 1) / 2046
453@unit_interval
454def ease_in_circ(t: float) -> float:
455 """1 − √(1 − t²), a quarter circle: starts at rest and speeds up sharply."""
456 return 1 - math.sqrt(1 - pow(t, 2))
459@unit_interval
460def ease_out_circ(t: float) -> float:
461 """√(1 − (t − 1)²), a quarter circle: starts sharply and comes to rest."""
462 return math.sqrt(1 - pow(t - 1, 2))
465@unit_interval
466def ease_in_out_circ(t: float) -> float:
467 """[ease_in_circ][manimgx.ease_in_circ] up to the middle, then its mirror image."""
468 return (
469 (1 - math.sqrt(1 - pow(2 * t, 2))) / 2
470 if t < 0.5
471 else (math.sqrt(1 - pow(-2 * t + 2, 2)) + 1) / 2
472 )
475@unit_interval
476def ease_in_back(t: float) -> float:
477 """Pulls back first, to −0.1, then speeds to the end."""
478 c1 = 1.70158
479 c3 = c1 + 1
480 return c3 * t * t * t - c1 * t * t
483@unit_interval
484def ease_out_back(t: float) -> float:
485 """Overshoots the end, to 1.1, then settles back to it."""
486 c1 = 1.70158
487 c3 = c1 + 1
488 return 1 + c3 * pow(t - 1, 3) + c1 * pow(t - 1, 2)
491@unit_interval
492def ease_in_out_back(t: float) -> float:
493 """Pulls back to −0.1, then overshoots to 1.1 and settles at the end."""
494 c1 = 1.70158
495 c2 = c1 * 1.525
496 return (
497 pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2) / 2
498 if t < 0.5
499 else (pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2
500 )
503@unit_interval
504def ease_in_elastic(t: float) -> float:
505 """Swings about the start, more and more widely (down to −0.37), then springs to the
506 end: a sine under the envelope of [ease_in_expo][manimgx.ease_in_expo]."""
507 return float(
508 -(pow(2, 10 * t) - 1) / 1023 * np.sin((t * 10 - 10.75) * 2 * np.pi / 3)
509 )
512@unit_interval
513def ease_out_elastic(t: float) -> float:
514 """Springs past the end (to 1.37), then swings about it, less and less widely, like
515 a spring: [ease_in_elastic][manimgx.ease_in_elastic] turned around."""
516 return 1 - ease_in_elastic(1 - t)
519@unit_interval
520def ease_in_out_elastic(t: float) -> float:
521 """Swings about the start, more and more widely (down to −0.12), springs across the
522 middle, then swings about the end, less and less widely (up to 1.12)."""
523 u = 2 * t if t < 0.5 else 2 - 2 * t # the half's own time, from its outer end
524 half = -(pow(2, 10 * u) - 1) / 1023 * np.sin((10 * u - 11.125) * 2 * np.pi / 4.5)
525 return float(half / 2 if t < 0.5 else 1 - half / 2)
528@unit_interval
529def ease_in_bounce(t: float) -> float:
530 """[ease_out_bounce][manimgx.ease_out_bounce] turned around: bounces off the start,
531 higher each time (to 0.02, 0.06 and 0.25), then rises to the end."""
532 return 1 - ease_out_bounce(1 - t)
535@unit_interval
536def ease_out_bounce(t: float) -> float:
537 """Falls to the end and bounces off it like a ball: reaches it at t ≈ 0.36, then
538 bounces back to 0.75, 0.94 and 0.98."""
539 n1 = 7.5625
540 d1 = 2.75
541 if t < 1 / d1:
542 return n1 * t * t
543 elif t < 2 / d1:
544 return n1 * (t - 1.5 / d1) * (t - 1.5 / d1) + 0.75
545 elif t < 2.5 / d1:
546 return n1 * (t - 2.25 / d1) * (t - 2.25 / d1) + 0.9375
547 else:
548 return n1 * (t - 2.625 / d1) * (t - 2.625 / d1) + 0.984375
551@unit_interval
552def ease_in_out_bounce(t: float) -> float:
553 """[ease_in_bounce][manimgx.ease_in_bounce] up to the middle, then
554 [ease_out_bounce][manimgx.ease_out_bounce]."""
555 if t < 0.5:
556 return (1 - ease_out_bounce(1 - 2 * t)) / 2
557 else:
558 return (1 + ease_out_bounce(2 * t - 1)) / 2