Skip to content

Commit c081a57

Browse files
alembckesparshgbehackl
authored
Added documentation for lagged animations (#2953)
* Add docs for lagged animations. * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Update manim/animation/composition.py Co-authored-by: Sparsh Goenka <[email protected]> * Apply suggestions from code review Co-authored-by: Sparsh Goenka <[email protected]> Co-authored-by: Benjamin Hackl <[email protected]>
1 parent 0bbebc3 commit c081a57

File tree

1 file changed

+157
-4
lines changed

1 file changed

+157
-4
lines changed

‎manim/animation/composition.py‎

Lines changed: 157 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,29 @@
2929

3030

3131
class AnimationGroup(Animation):
32+
"""Plays a group or series of :class:`~.Animation`.
33+
34+
Parameters
35+
----------
36+
animations
37+
Sequence of :class:`~.Animation` objects to be played.
38+
group
39+
A group of multiple :class:`~.Mobject`.
40+
run_time
41+
The duration of the animation in seconds.
42+
rate_func
43+
The function defining the animation progress based on the relative
44+
runtime (see :mod:`~.rate_functions`) .
45+
lag_ratio
46+
Defines the delay after which the animation is applied to submobjects. A lag_ratio of
47+
``n.nn`` means the next animation will play when ``nnn%`` of the current animation has played.
48+
Defaults to 0.0, meaning that all animations will be played together.
49+
50+
This does not influence the total runtime of the animation. Instead the runtime
51+
of individual animations is adjusted so that the complete animation has the defined
52+
run time.
53+
"""
54+
3255
def __init__(
3356
self,
3457
*animations: Animation,
@@ -85,6 +108,18 @@ def update_mobjects(self, dt: float) -> None:
85108
anim.update_mobjects(dt)
86109

87110
def init_run_time(self, run_time) -> float:
111+
"""Calculates the run time of the animation, if different from ``run_time``.
112+
113+
Parameters
114+
----------
115+
run_time
116+
The duration of the animation in seconds.
117+
118+
Returns
119+
-------
120+
run_time
121+
The duration of the animation in seconds.
122+
"""
88123
self.build_animations_with_timings()
89124
if self.anims_with_timings:
90125
self.max_end_time = np.max([awt[2] for awt in self.anims_with_timings])
@@ -93,10 +128,7 @@ def init_run_time(self, run_time) -> float:
93128
return self.max_end_time if run_time is None else run_time
94129

95130
def build_animations_with_timings(self) -> None:
96-
"""
97-
Creates a list of triplets of the form
98-
(anim, start_time, end_time)
99-
"""
131+
"""Creates a list of triplets of the form (anim, start_time, end_time)."""
100132
self.anims_with_timings = []
101133
curr_time: float = 0
102134
for anim in self.animations:
@@ -123,6 +155,42 @@ def interpolate(self, alpha: float) -> None:
123155

124156

125157
class Succession(AnimationGroup):
158+
"""Plays a series of animations in succession.
159+
160+
Parameters
161+
----------
162+
animations
163+
Sequence of :class:`~.Animation` objects to be played.
164+
lag_ratio
165+
Defines the delay after which the animation is applied to submobjects. A lag_ratio of
166+
``n.nn`` means the next animation will play when ``nnn%`` of the current animation has played.
167+
Defaults to 1.0, meaning that the next animation will begin when 100% of the current
168+
animation has played.
169+
170+
This does not influence the total runtime of the animation. Instead the runtime
171+
of individual animations is adjusted so that the complete animation has the defined
172+
run time.
173+
174+
Examples
175+
--------
176+
.. manim:: SuccessionExample
177+
178+
class SuccessionExample(Scene):
179+
def construct(self):
180+
dot1 = Dot(point=LEFT * 2 + UP * 2, radius=0.16, color=BLUE)
181+
dot2 = Dot(point=LEFT * 2 + DOWN * 2, radius=0.16, color=MAROON)
182+
dot3 = Dot(point=RIGHT * 2 + DOWN * 2, radius=0.16, color=GREEN)
183+
dot4 = Dot(point=RIGHT * 2 + UP * 2, radius=0.16, color=YELLOW)
184+
self.add(dot1, dot2, dot3, dot4)
185+
186+
self.play(Succession(
187+
dot1.animate.move_to(dot2),
188+
dot2.animate.move_to(dot3),
189+
dot3.animate.move_to(dot4),
190+
dot4.animate.move_to(dot1)
191+
))
192+
"""
193+
126194
def __init__(self, *animations: Animation, lag_ratio: float = 1, **kwargs) -> None:
127195
super().__init__(*animations, lag_ratio=lag_ratio, **kwargs)
128196

@@ -162,6 +230,10 @@ def update_active_animation(self, index: int) -> None:
162230
self.active_end_time = self.anims_with_timings[index][2]
163231

164232
def next_animation(self) -> None:
233+
"""Proceeds to the next animation.
234+
235+
This method is called right when the active animation finishes.
236+
"""
165237
if self.active_animation is not None:
166238
self.active_animation.finish()
167239
self.update_active_animation(self.active_index + 1)
@@ -178,6 +250,50 @@ def interpolate(self, alpha: float) -> None:
178250

179251

180252
class LaggedStart(AnimationGroup):
253+
"""Adjusts the timing of a series of :class:`~.Animation` according to ``lag_ratio``.
254+
255+
Parameters
256+
----------
257+
animations
258+
Sequence of :class:`~.Animation` objects to be played.
259+
lag_ratio
260+
Defines the delay after which the animation is applied to submobjects. A lag_ratio of
261+
``n.nn`` means the next animation will play when ``nnn%`` of the current animation has played.
262+
Defaults to 0.05, meaning that the next animation will begin when 5% of the current
263+
animation has played.
264+
265+
This does not influence the total runtime of the animation. Instead the runtime
266+
of individual animations is adjusted so that the complete animation has the defined
267+
run time.
268+
269+
Examples
270+
--------
271+
.. manim:: LaggedStartExample
272+
273+
class LaggedStartExample(Scene):
274+
def construct(self):
275+
title = Text("lag_ratio = 0.25").to_edge(UP)
276+
277+
dot1 = Dot(point=LEFT * 2 + UP, radius=0.16)
278+
dot2 = Dot(point=LEFT * 2, radius=0.16)
279+
dot3 = Dot(point=LEFT * 2 + DOWN, radius=0.16)
280+
line_25 = DashedLine(
281+
start=LEFT + UP * 2,
282+
end=LEFT + DOWN * 2,
283+
color=RED
284+
)
285+
label = Text("25%", font_size=24).next_to(line_25, UP)
286+
self.add(title, dot1, dot2, dot3, line_25, label)
287+
288+
self.play(LaggedStart(
289+
dot1.animate.shift(RIGHT * 4),
290+
dot2.animate.shift(RIGHT * 4),
291+
dot3.animate.shift(RIGHT * 4),
292+
lag_ratio=0.25,
293+
run_time=4
294+
))
295+
"""
296+
181297
def __init__(
182298
self,
183299
*animations: Animation,
@@ -188,6 +304,43 @@ def __init__(
188304

189305

190306
class LaggedStartMap(LaggedStart):
307+
"""Plays a series of :class:`~.Animation` while mapping a function to submobjects.
308+
309+
Parameters
310+
----------
311+
AnimationClass
312+
:class:`~.Animation` to apply to mobject.
313+
mobject
314+
:class:`~.Mobject` whose submobjects the animation, and optionally the function,
315+
are to be applied.
316+
arg_creator
317+
Function which will be applied to :class:`~.Mobject`.
318+
run_time
319+
The duration of the animation in seconds.
320+
321+
Examples
322+
--------
323+
.. manim:: LaggedStartMapExample
324+
325+
class LaggedStartMapExample(Scene):
326+
def construct(self):
327+
title = Tex("LaggedStartMap").to_edge(UP, buff=LARGE_BUFF)
328+
dots = VGroup(
329+
*[Dot(radius=0.16) for _ in range(35)]
330+
).arrange_in_grid(rows=5, cols=7, buff=MED_LARGE_BUFF)
331+
self.add(dots, title)
332+
333+
# Animate yellow ripple effect
334+
for mob in dots, title:
335+
self.play(LaggedStartMap(
336+
ApplyMethod, mob,
337+
lambda m : (m.set_color, YELLOW),
338+
lag_ratio = 0.1,
339+
rate_func = there_and_back,
340+
run_time = 2
341+
))
342+
"""
343+
191344
def __init__(
192345
self,
193346
AnimationClass: Callable[..., Animation],

0 commit comments

Comments
 (0)