manim-mcp 0.1.0

package/references/manimce/rules/advanced-animations.md

@@ -0,0 +1,594 @@
+---
+name: advanced-animations
+description: Advanced animation patterns from 3b1b including TransformMatchingTex, VShowPassingFlash, UpdateFromAlphaFunc, generate_target, always_redraw, and more
+metadata:
+  tags: advanced, transform, matching-tex, alpha-func, updater, always-redraw, generate-target, move-to-target, homotopy, number-changeable
+---
+
+# Advanced Animation Patterns
+
+These are the advanced animation techniques used throughout 3b1b's videos, translated to ManimCE equivalents.
+
+## TransformMatchingTex for Equation Manipulation
+
+Transform equations term-by-term using matching LaTeX substrings. This is the backbone of algebraic derivation scenes.
+
+```python
+from manim import *
+
+class TransformMatchingTexDemo(Scene):
+    """Smoothly morph one equation into another, matching terms by LaTeX."""
+
+    def construct(self):
+        # Step 1: Start equation
+        eq1 = MathTex(
+            r"x^2", r"+", r"2x", r"+", r"1", r"=", r"0"
+        )
+        self.play(Write(eq1))
+        self.wait()
+
+        # Step 2: Factor
+        eq2 = MathTex(
+            r"(", r"x", r"+", r"1", r")^2", r"=", r"0"
+        )
+        self.play(TransformMatchingTex(eq1, eq2))
+        self.wait()
+
+        # Step 3: Take square root
+        eq3 = MathTex(r"x", r"+", r"1", r"=", r"0")
+        self.play(TransformMatchingTex(eq2, eq3))
+        self.wait()
+
+        # Step 4: Solve
+        eq4 = MathTex(r"x", r"=", r"-1")
+        self.play(TransformMatchingTex(eq3, eq4))
+        self.wait(2)
+```
+
+### TransformMatchingShapes for Non-TeX Morphing
+
+```python
+class TransformMatchingShapesDemo(Scene):
+    """Morph shapes that share visual similarity."""
+
+    def construct(self):
+        text1 = Text("Hello World", font_size=48)
+        text2 = Text("World Hello", font_size=48, color=YELLOW)
+
+        self.play(Write(text1))
+        self.wait()
+        self.play(TransformMatchingShapes(text1, text2))
+        self.wait()
+```
+
+## VShowPassingFlash for Flowing Effects
+
+A flash of light that travels along a path. Used in `custom/end_screen.py` and throughout for highlighting flow/movement.
+
+```python
+class FlashingEffect(Scene):
+    """VShowPassingFlash: a pulse traveling along a path."""
+
+    def construct(self):
+        # Create a path
+        circle = Circle(radius=2, color=BLUE)
+        self.add(circle)
+
+        # Flash traveling around the circle
+        flash_circle = circle.copy().set_stroke(YELLOW, width=8)
+        self.play(
+            ShowPassingFlash(flash_circle, time_width=0.3),
+            run_time=2,
+        )
+        self.wait()
+
+        # Multiple flashes on different paths
+        paths = VGroup(*[
+            Line(3 * LEFT + i * 0.5 * UP, 3 * RIGHT + i * 0.5 * UP, color=BLUE)
+            for i in range(-3, 4)
+        ])
+        self.add(paths)
+
+        flash_paths = paths.copy().set_stroke(WHITE, 5)
+        self.play(
+            LaggedStartMap(
+                ShowPassingFlash, flash_paths,
+                time_width=0.5, lag_ratio=0.15,
+            ),
+            run_time=3,
+        )
+        self.wait()
+```
+
+## UpdateFromAlphaFunc for Custom Interpolation
+
+Directly from `_2020/sir.py` and `_2017/mug.py` -- gives you full control over how a mobject changes as alpha goes from 0 to 1.
+
+```python
+class AlphaFuncDemo(Scene):
+    """UpdateFromAlphaFunc: custom animation via alpha parameter."""
+
+    def construct(self):
+        circle = Circle(radius=1, color=WHITE)
+        self.add(circle)
+
+        # Custom color transition using alpha
+        start_color = BLUE
+        end_color = RED
+
+        self.play(
+            UpdateFromAlphaFunc(
+                circle,
+                lambda mob, alpha: mob.set_color(
+                    interpolate_color(start_color, end_color, alpha)
+                ),
+                run_time=2,
+            )
+        )
+        self.wait()
+
+        # Complex multi-property animation
+        square = Square(side_length=1, color=GREEN, fill_opacity=0.5)
+        self.add(square)
+
+        def complex_update(mob, alpha):
+            mob.set_width(1 + 2 * alpha)
+            mob.set_fill(opacity=1 - 0.5 * alpha)
+            mob.rotate(alpha * PI / 4)
+            mob.set_color(interpolate_color(GREEN, YELLOW, alpha))
+
+        self.play(
+            UpdateFromAlphaFunc(square, complex_update, run_time=3)
+        )
+        self.wait()
+```
+
+## always_redraw vs add_updater
+
+### always_redraw: Rebuild Every Frame
+
+Use when the mobject needs to be completely reconstructed each frame (e.g., geometry that depends on a moving point).
+
+```python
+class AlwaysRedrawDemo(Scene):
+    """always_redraw: complete reconstruction every frame."""
+
+    def construct(self):
+        axes = Axes(x_range=[-3, 3], y_range=[-2, 4], x_length=8, y_length=5)
+        graph = axes.plot(lambda x: x**2, color=YELLOW)
+        self.add(axes, graph)
+
+        # Tracker controls the x-position
+        x_tracker = ValueTracker(-2)
+
+        # Dot on the graph (always_redraw reconstructs it each frame)
+        dot = always_redraw(
+            lambda: Dot(
+                axes.i2gp(x_tracker.get_value(), graph),
+                color=RED,
+            )
+        )
+
+        # Tangent line that follows the dot
+        tangent = always_redraw(
+            lambda: axes.get_secant_slope_group(
+                x_tracker.get_value(), graph, dx=0.01,
+                secant_line_color=BLUE,
+                secant_line_length=4,
+            )
+        )
+
+        # Horizontal and vertical lines to axes
+        h_line = always_redraw(
+            lambda: axes.get_horizontal_line(
+                axes.i2gp(x_tracker.get_value(), graph),
+                line_config={"dashed_ratio": 0.5},
+            )
+        )
+        v_line = always_redraw(
+            lambda: axes.get_vertical_line(
+                axes.i2gp(x_tracker.get_value(), graph),
+                line_config={"dashed_ratio": 0.5},
+            )
+        )
+
+        self.add(dot, tangent, h_line, v_line)
+
+        # Animate the tracker
+        self.play(x_tracker.animate.set_value(2), run_time=5)
+        self.wait()
+```
+
+### add_updater: Modify In-Place
+
+Use when you need to adjust properties of an existing mobject without rebuilding it.
+
+```python
+class AddUpdaterDemo(Scene):
+    """add_updater: modify an existing mobject each frame."""
+
+    def construct(self):
+        # A label that always follows another object
+        dot = Dot(color=YELLOW)
+        label = Text("Point", font_size=24)
+        label.add_updater(lambda m: m.next_to(dot, UR, buff=0.1))
+
+        self.add(dot, label)
+
+        # Move the dot around
+        self.play(dot.animate.shift(3 * RIGHT + UP), run_time=2)
+        self.play(dot.animate.shift(2 * DOWN + LEFT), run_time=2)
+        self.wait()
+
+        # Counter that tracks a value
+        counter = Integer(0, font_size=48)
+        counter.to_corner(UR)
+        value_tracker = ValueTracker(0)
+        counter.add_updater(
+            lambda m: m.set_value(int(value_tracker.get_value()))
+        )
+
+        self.add(counter)
+        self.play(value_tracker.animate.set_value(100), run_time=3)
+        self.wait()
+```
+
+### ManimGL f_always to ManimCE
+
+In ManimGL, `f_always` provides a shorthand for method-calling updaters:
+```python
+# ManimGL:
+dot.f_always.move_to(lambda: axes.i2gp(tracker.get_value(), graph))
+
+# ManimCE equivalent:
+dot.add_updater(lambda m: m.move_to(axes.i2gp(tracker.get_value(), graph)))
+```
+
+## generate_target() / MoveToTarget Pattern
+
+The classic 3b1b pattern for complex repositioning: create a target copy, modify it, then animate to it.
+
+```python
+class GenerateTargetDemo(Scene):
+    """generate_target: set up a target state, then animate to it."""
+
+    def construct(self):
+        # Create initial mobject
+        equation = MathTex(r"E = mc^2", font_size=72)
+        self.play(Write(equation))
+        self.wait()
+
+        # Generate a target and modify it
+        equation.generate_target()
+        equation.target.scale(0.5)
+        equation.target.to_corner(UL)
+        equation.target.set_opacity(0.6)
+
+        # Animate to target
+        self.play(MoveToTarget(equation), run_time=1.5)
+        self.wait()
+
+        # This is equivalent to (but more flexible than):
+        # self.play(equation.animate.scale(0.5).to_corner(UL).set_opacity(0.6))
+        # generate_target is preferred when you need to inspect/adjust the target
+
+        # Complex rearrangement example
+        items = VGroup(*[
+            Circle(radius=0.3, color=random_bright_color(), fill_opacity=0.7)
+            for _ in range(6)
+        ])
+        items.arrange(RIGHT, buff=0.3)
+        self.play(LaggedStartMap(FadeIn, items, lag_ratio=0.1))
+        self.wait()
+
+        # Rearrange into 2x3 grid
+        for i, item in enumerate(items):
+            item.generate_target()
+            row, col = divmod(i, 3)
+            item.target.move_to(
+                2 * DOWN + (col - 1) * 1.2 * RIGHT + row * 1.2 * DOWN
+            )
+
+        self.play(
+            LaggedStartMap(MoveToTarget, items, lag_ratio=0.1),
+            run_time=1.5,
+        )
+        self.wait()
+```
+
+## make_number_changeable() Equivalent
+
+In ManimGL, `label.make_number_changeable("0.00")` creates a dynamic decimal that can be updated. ManimCE uses `DecimalNumber` with updaters.
+
+```python
+class DynamicNumbers(Scene):
+    """ManimCE equivalent of make_number_changeable."""
+
+    def construct(self):
+        # Static template with a placeholder for the number
+        tracker = ValueTracker(0)
+
+        # Create the label with a DecimalNumber
+        prefix = MathTex(r"c = ", font_size=36)
+        number = DecimalNumber(
+            0, num_decimal_places=4, font_size=36, color=RED,
+            include_sign=True,
+        )
+        number.add_updater(lambda m: m.set_value(tracker.get_value()))
+        number.add_updater(lambda m: m.next_to(prefix, RIGHT, buff=0.1))
+
+        label = VGroup(prefix, number)
+        label.to_corner(UR)
+        self.add(label)
+
+        # Animate the value changing
+        self.play(tracker.animate.set_value(0.01), run_time=3)
+        self.wait()
+        self.play(tracker.animate.set_value(1.5), run_time=2)
+        self.wait()
+
+        # Alternative: use a variable
+        var = Variable(0, MathTex(r"\theta"), num_decimal_places=2)
+        var.to_edge(DOWN)
+        self.add(var)
+        self.play(var.tracker.animate.set_value(PI), run_time=2)
+        self.wait()
+```
+
+## Homotopy for Continuous Deformation
+
+From `_2016/eola/chapter1.py` -- continuously deform a mobject via a homotopy function.
+
+```python
+class HomotopyDemo(Scene):
+    """Homotopy: continuously deform space."""
+
+    def construct(self):
+        plane = NumberPlane()
+        self.add(plane)
+
+        # Plane wave homotopy (from EoLA)
+        def wave_homotopy(x, y, z, t):
+            """Deform the plane with a wave effect."""
+            offset = np.sin(x - t * TAU) * 0.5 * t
+            return [x, y + offset, z]
+
+        self.play(
+            Homotopy(wave_homotopy, plane),
+            run_time=3,
+        )
+        self.wait()
+```
+
+## ChangeSpeed / Rate Function Composition
+
+Control animation speed dynamically. In ManimCE, use custom rate functions.
+
+```python
+class SpeedControl(Scene):
+    """Custom rate functions for speed control."""
+
+    def construct(self):
+        circle = Circle(radius=2, color=BLUE)
+
+        # Custom rate function: slow start, fast middle, slow end
+        def custom_rate(t):
+            return smooth(t)  # Built-in smooth (ease in/out)
+
+        # Rush into (accelerating)
+        dot1 = Dot(color=RED)
+        dot1.move_to(3 * LEFT)
+        self.play(
+            dot1.animate.move_to(3 * RIGHT),
+            rate_func=rate_functions.rush_into,
+            run_time=2,
+        )
+
+        # Rush from (decelerating)
+        dot2 = Dot(color=GREEN)
+        dot2.move_to(3 * LEFT + DOWN)
+        self.play(
+            dot2.animate.move_to(3 * RIGHT + DOWN),
+            rate_func=rate_functions.rush_from,
+            run_time=2,
+        )
+
+        # There and back
+        dot3 = Dot(color=YELLOW)
+        self.play(
+            dot3.animate.shift(3 * RIGHT),
+            rate_func=there_and_back,
+            run_time=2,
+        )
+        self.wait()
+
+        # Custom double-speed function
+        def double_speed(t):
+            """Play at 2x speed, then hold."""
+            return min(2 * t, 1)
+
+        square = Square(color=PURPLE)
+        self.play(
+            Create(square),
+            rate_func=double_speed,
+            run_time=2,  # Actually creates in 1s, holds for 1s
+        )
+        self.wait()
+```
+
+## Cycle Animation (Looping)
+
+Create looping animations using updaters or repeated play calls.
+
+```python
+class CycleAnimationDemo(Scene):
+    """Looping animations using updaters."""
+
+    def construct(self):
+        # Method 1: Continuous rotation via updater
+        square = Square(color=BLUE, fill_opacity=0.5)
+        square.add_updater(lambda m, dt: m.rotate(dt * PI / 2))
+        self.add(square)
+        self.wait(4)  # Rotates continuously
+
+        square.clear_updaters()
+
+        # Method 2: Pulsing effect via updater
+        circle = Circle(radius=1, color=RED, fill_opacity=0.3)
+        time_tracker = ValueTracker(0)
+        time_tracker.add_updater(lambda m, dt: m.increment_value(dt))
+
+        circle.add_updater(
+            lambda m: m.set_width(
+                2 + 0.3 * np.sin(time_tracker.get_value() * 2 * PI)
+            )
+        )
+
+        self.add(circle, time_tracker)
+        self.wait(5)
+```
+
+## LaggedStart / LaggedStartMap Patterns
+
+The most-used animation combinator in 3b1b's code.
+
+```python
+class LaggedPatterns(Scene):
+    """The many uses of LaggedStart and LaggedStartMap."""
+
+    def construct(self):
+        # LaggedStartMap: apply the same animation to each submobject
+        dots = VGroup(*[Dot(color=YELLOW) for _ in range(10)])
+        dots.arrange(RIGHT, buff=0.3)
+
+        self.play(
+            LaggedStartMap(FadeIn, dots, shift=0.5 * UP, lag_ratio=0.15),
+            run_time=2,
+        )
+        self.wait()
+
+        # LaggedStart: different animations, staggered
+        anims = [
+            dot.animate.shift(UP * np.random.uniform(0.5, 1.5))
+            for dot in dots
+        ]
+        self.play(LaggedStart(*anims, lag_ratio=0.1, run_time=2))
+        self.wait()
+
+        # LaggedStartMap with GrowArrow
+        arrows = VGroup(*[
+            Arrow(ORIGIN, RIGHT, color=BLUE) for _ in range(5)
+        ])
+        arrows.arrange(DOWN, buff=0.3).shift(3 * LEFT)
+
+        self.play(
+            LaggedStartMap(GrowArrow, arrows, lag_ratio=0.2, run_time=1.5)
+        )
+        self.wait()
+
+        # LaggedStartMap for removal
+        self.play(
+            LaggedStartMap(FadeOut, dots, shift=DOWN, lag_ratio=0.05),
+            run_time=1,
+        )
+        self.wait()
+```
+
+## Succession for Sequential Animations
+
+```python
+class SuccessionDemo(Scene):
+    """Succession: chain animations into one play() call."""
+
+    def construct(self):
+        circle = Circle(color=BLUE)
+        square = Square(color=RED)
+        triangle = Triangle(color=GREEN)
+
+        self.play(
+            Succession(
+                Create(circle),
+                circle.animate.shift(LEFT * 2),
+                FadeIn(square),
+                square.animate.shift(RIGHT * 2),
+                FadeIn(triangle),
+                run_time=6,
+            )
+        )
+        self.wait()
+```
+
+## AnimationGroup with time_span (ManimCE Specific)
+
+```python
+class TimeSpanDemo(Scene):
+    """Control when animations start and stop within a play() call."""
+
+    def construct(self):
+        c1 = Circle(color=BLUE).shift(2 * LEFT)
+        c2 = Circle(color=RED)
+        c3 = Circle(color=GREEN).shift(2 * RIGHT)
+
+        # c1 fades in from 0-1s, c2 from 0.5-1.5s, c3 from 1-2s
+        self.play(
+            FadeIn(c1),
+            FadeIn(c2),
+            FadeIn(c3),
+            run_time=2,
+        )
+        self.wait()
+```
+
+## Indicate / Circumscribe for Emphasis
+
+```python
+class EmphasisAnimations(Scene):
+    """Drawing attention to specific elements."""
+
+    def construct(self):
+        equation = MathTex(r"a^2 + b^2 = c^2")
+        equation.scale(1.5)
+        self.add(equation)
+
+        # Circumscribe: draw a shape around
+        self.play(Circumscribe(equation[0][:2], color=YELLOW))  # a^2
+        self.wait()
+
+        # Indicate: briefly highlight
+        self.play(Indicate(equation[0][4:6], color=RED))  # b^2
+        self.wait()
+
+        # Flash: point flash effect
+        self.play(Flash(equation[0][-2:], color=GREEN))  # c^2
+        self.wait()
+
+        # Wiggle: shake for attention
+        self.play(Wiggle(equation))
+        self.wait()
+```
+
+## CountInFrom for Animated Number Reveal
+
+```python
+class CountInDemo(Scene):
+    """Animate a number counting up from zero."""
+
+    def construct(self):
+        # Large integer counting up
+        number = Integer(12288, font_size=72, color=YELLOW)
+        self.play(CountInFrom(number, 0), run_time=2)
+        self.wait()
+```
+
+## Best Practices
+
+1. **TransformMatchingTex** for equation derivations -- split LaTeX into meaningful substrings
+2. **generate_target / MoveToTarget** for complex repositioning of existing mobjects
+3. **always_redraw** when geometry must be rebuilt from scratch each frame (e.g., tangent lines)
+4. **add_updater** when modifying properties of an existing mobject (position, color, value)
+5. **LaggedStartMap** for any operation applied to a group -- controls the cascade timing
+6. **UpdateFromAlphaFunc** for fully custom animation logic
+7. **DecimalNumber with updater** instead of ManimGL's `make_number_changeable`
+8. **rate_func** for speed control: `smooth`, `rush_into`, `rush_from`, `there_and_back`, `linear`
+9. **ShowPassingFlash** for flowing highlight effects along paths
+10. **Circumscribe / Indicate / Flash** for drawing attention to specific parts