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

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 

5 

6"""Rate functions, ported from Manim CE 0.21 `utils/rate_functions.py` (MIT).""" 

7 

8import functools 

9import math 

10from collections.abc import Callable 

11from typing import Concatenate 

12 

13import numpy as np 

14 

15from manimgx.typing import RateFunc 

16 

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] 

68 

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.""" 

72 

73 

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]. 

79 

80 Args: 

81 function: The rate function, as it runs from 0 to 1. 

82 

83 Returns: 

84 The rate function: 0 up to 0, 1 from 1 on. 

85 """ 

86 

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 

93 

94 return wrapper 

95 

96 

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]. 

102 

103 Args: 

104 function: The rate function, as it runs from 0 to 1. 

105 

106 Returns: 

107 The rate function, 0 up to 0 and from 1 on. 

108 """ 

109 

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 

113 

114 return wrapper 

115 

116 

117@unit_interval 

118def linear(t: float) -> float: 

119 """Progress in step with time: t.""" 

120 return t 

121 

122 

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. 

126 

127 The default rate function of animations. 

128 

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. 

133 

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) 

140 

141 

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 

146 

147 

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 

152 

153 

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. 

158 

159 Args: 

160 t: The time, from 0 to 1. 

161 inflection: How steep [smooth][manimgx.smooth] is. 

162 

163 Returns: 

164 The progress, from 0 to 1. 

165 """ 

166 return 2 * smooth(t / 2.0, inflection) 

167 

168 

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. 

173 

174 Args: 

175 t: The time, from 0 to 1. 

176 inflection: How steep [smooth][manimgx.smooth] is. 

177 

178 Returns: 

179 The progress, from 0 to 1. 

180 """ 

181 return 2 * smooth(t / 2.0 + 0.5, inflection) - 1 

182 

183 

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))) 

189 

190 

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)) 

196 

197 

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. 

202 

203 Args: 

204 t: The time, from 0 to 1. 

205 inflection: How steep [smooth][manimgx.smooth] is. 

206 

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) 

211 

212 

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. 

217 

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. 

221 

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) 

231 

232 

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. 

237 

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). 

242 

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 ) 

254 

255 

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. 

260 

261 With the default 2 wiggles, it swings to 0.73 and then to −0.73. 

262 

263 Args: 

264 t: The time, from 0 to 1. 

265 wiggles: How many swings, to one side or the other. 

266 

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)) 

271 

272 

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. 

276 

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`. 

282 

283 Returns: 

284 The squeezed rate function. 

285 """ 

286 

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)) 

291 

292 return result 

293 

294 

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. 

297 

298 Args: 

299 func: The rate function. 

300 proportion: How far it goes: its progress is scaled by this. 

301 

302 Returns: 

303 The scaled rate function. 

304 """ 

305 return lambda t: proportion * func(t) 

306 

307 

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) 

312 

313 

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. 

318 

319 With the default time constant, it reaches about 1 − 1/e ≈ 0.63 at t = 0.1. 

320 

321 Args: 

322 t: The time, from 0 to 1. 

323 half_life: The time constant, as a fraction of the time. 

324 

325 Returns: 

326 The progress, from 0 to 1. 

327 """ 

328 return float(np.expm1(-t / half_life) / np.expm1(-1 / half_life)) 

329 

330 

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 

337 

338 

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 

344 

345 

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 

351 

352 

353@unit_interval 

354def ease_in_quad(t: float) -> float: 

355 """t²: starts slow and speeds up.""" 

356 return t * t 

357 

358 

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) 

363 

364 

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 

370 

371 

372@unit_interval 

373def ease_in_cubic(t: float) -> float: 

374 """t³: starts slow and speeds up.""" 

375 return t * t * t 

376 

377 

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) 

382 

383 

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 

389 

390 

391@unit_interval 

392def ease_in_quart(t: float) -> float: 

393 """t⁴: starts slow and speeds up.""" 

394 return t * t * t * t 

395 

396 

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) 

401 

402 

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 

408 

409 

410@unit_interval 

411def ease_in_quint(t: float) -> float: 

412 """t⁵: starts slow and speeds up.""" 

413 return t * t * t * t * t 

414 

415 

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) 

420 

421 

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 

427 

428 

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 

436 

437 

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 

443 

444 

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 

451 

452 

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)) 

457 

458 

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)) 

463 

464 

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 ) 

473 

474 

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 

481 

482 

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) 

489 

490 

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 ) 

501 

502 

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 ) 

510 

511 

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) 

517 

518 

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) 

526 

527 

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) 

533 

534 

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 

549 

550 

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