manim-mcp 0.1.0

package/references/manimce/rules/animation-groups.md

@@ -0,0 +1,212 @@
+---
+name: animation-groups
+description: AnimationGroup, LaggedStart, Succession for complex animation sequences
+metadata:
+  tags: animationgroup, laggedstart, succession, lag_ratio, sequence
+---
+
+# Animation Groups
+
+Control how multiple animations play together.
+
+## AnimationGroup
+
+Play multiple animations with controlled timing.
+
+```python
+from manim import *
+
+class AnimationGroupExample(Scene):
+    def construct(self):
+        circles = VGroup(*[Circle() for _ in range(5)]).arrange(RIGHT)
+
+        # All animations play simultaneously (lag_ratio=0)
+        self.play(AnimationGroup(
+            *[Create(c) for c in circles],
+            lag_ratio=0
+        ))
+```
+
+### lag_ratio Parameter
+
+Controls the delay between animation starts:
+- `lag_ratio=0`: All start simultaneously
+- `lag_ratio=0.5`: Each starts when previous is 50% complete
+- `lag_ratio=1`: Each starts when previous finishes (sequential)
+
+```python
+class LagRatioDemo(Scene):
+    def construct(self):
+        squares = VGroup(*[Square() for _ in range(4)]).arrange(RIGHT)
+
+        # Staggered start - each begins when previous is 25% done
+        self.play(AnimationGroup(
+            *[FadeIn(s) for s in squares],
+            lag_ratio=0.25,
+            run_time=2
+        ))
+```
+
+## LaggedStart
+
+Convenience class with default `lag_ratio=0.05` (5% overlap).
+
+```python
+class LaggedStartExample(Scene):
+    def construct(self):
+        dots = VGroup(*[Dot() for _ in range(10)]).arrange(RIGHT)
+
+        # Rapid staggered animation
+        self.play(LaggedStart(
+            *[GrowFromCenter(d) for d in dots],
+            lag_ratio=0.1
+        ))
+```
+
+### Common LaggedStart Patterns
+
+```python
+# Staggered fade in
+self.play(LaggedStart(*[FadeIn(m) for m in mobjects], lag_ratio=0.2))
+
+# Wave effect
+self.play(LaggedStart(
+    *[m.animate.shift(UP * 0.5) for m in mobjects],
+    lag_ratio=0.1
+))
+
+# Staggered color change
+self.play(LaggedStart(
+    *[m.animate.set_color(RED) for m in mobjects],
+    lag_ratio=0.15
+))
+```
+
+## Succession
+
+Play animations one after another (equivalent to `lag_ratio=1`).
+
+```python
+class SuccessionExample(Scene):
+    def construct(self):
+        circle = Circle().shift(LEFT * 2)
+        square = Square()
+        triangle = Triangle().shift(RIGHT * 2)
+
+        # Animations play in sequence
+        self.play(Succession(
+            Create(circle),
+            Create(square),
+            Create(triangle)
+        ))
+```
+
+### Succession vs Multiple play() Calls
+
+```python
+# These are equivalent:
+
+# Using Succession
+self.play(Succession(
+    Create(circle),
+    Create(square)
+))
+
+# Using separate play calls
+self.play(Create(circle))
+self.play(Create(square))
+```
+
+Succession is useful when you want to treat sequential animations as a single unit.
+
+## Combining Group Types
+
+```python
+class CombinedExample(Scene):
+    def construct(self):
+        group1 = VGroup(*[Circle() for _ in range(3)]).arrange(RIGHT).shift(UP)
+        group2 = VGroup(*[Square() for _ in range(3)]).arrange(RIGHT).shift(DOWN)
+
+        # First group appears with stagger, then second group
+        self.play(Succession(
+            LaggedStart(*[Create(c) for c in group1], lag_ratio=0.2),
+            LaggedStart(*[Create(s) for s in group2], lag_ratio=0.2)
+        ))
+```
+
+## LaggedStartMap
+
+Apply an animation to all submobjects of a mobject with staggered timing.
+
+```python
+class LaggedStartMapExample(Scene):
+    def construct(self):
+        dots = VGroup(*[Dot(radius=0.16) for _ in range(35)]).arrange_in_grid(rows=5, cols=7)
+
+        # Apply FadeIn to all dots with stagger
+        self.play(LaggedStartMap(FadeIn, dots, lag_ratio=0.1))
+        self.wait(0.5)
+
+        # Change color with stagger using LaggedStart
+        self.play(LaggedStart(
+            *[dot.animate.set_color(YELLOW) for dot in dots],
+            lag_ratio=0.05
+        ))
+```
+
+LaggedStartMap is cleaner for applying the same animation to each submobject. For property changes, use LaggedStart with `.animate`.
+
+## AnimationGroup with run_time
+
+The total `run_time` is distributed among animations based on `lag_ratio`.
+
+```python
+self.play(AnimationGroup(
+    *[Create(c) for c in circles],
+    lag_ratio=0.5,
+    run_time=4  # Total duration is 4 seconds
+))
+```
+
+## Practical Examples
+
+### Text Appearing Word by Word
+
+```python
+class WordByWord(Scene):
+    def construct(self):
+        words = VGroup(
+            Text("Hello"),
+            Text("World"),
+            Text("!")
+        ).arrange(RIGHT)
+
+        self.play(LaggedStart(
+            *[Write(w) for w in words],
+            lag_ratio=0.5
+        ))
+```
+
+### Grid Animation
+
+```python
+class GridAnimation(Scene):
+    def construct(self):
+        grid = VGroup(*[
+            Square().scale(0.3)
+            for _ in range(25)
+        ]).arrange_in_grid(5, 5)
+
+        # Diagonal wave effect
+        self.play(LaggedStart(
+            *[GrowFromCenter(s) for s in grid],
+            lag_ratio=0.05
+        ))
+```
+
+## Best Practices
+
+1. **Use LaggedStart for visual polish** - Staggered animations look more dynamic
+2. **Keep lag_ratio small (0.05-0.2)** - Too high feels slow
+3. **Use Succession for distinct steps** - When animations are conceptually separate
+4. **Adjust run_time with lag_ratio** - More items may need longer total time

package/references/manimce/rules/animations.md

@@ -0,0 +1,128 @@
+---
+name: animations
+description: Animation classes, playing animations, and animation timing in Manim
+metadata:
+  tags: animation, play, run_time, rate_func, animate
+---
+
+# Animations in Manim
+
+Animations interpolate mobjects between states over time. They are played using `self.play()`.
+
+## The .animate Syntax
+
+The most common way to animate is using the `.animate` property:
+
+```python
+# Move a square to the right
+self.play(square.animate.shift(RIGHT))
+
+# Scale up
+self.play(circle.animate.scale(2))
+
+# Change color
+self.play(text.animate.set_color(RED))
+
+# Chain multiple changes
+self.play(square.animate.shift(RIGHT).rotate(PI/4).set_color(BLUE))
+```
+
+## Animation Parameters
+
+### run_time
+Controls animation duration in seconds (default: 1).
+
+```python
+self.play(Create(circle), run_time=2)  # 2 second animation
+self.play(Create(circle), run_time=0.5)  # Half second
+```
+
+### rate_func
+Controls the animation's timing curve (easing).
+
+```python
+from manim import smooth, linear, there_and_back
+
+self.play(square.animate.shift(RIGHT), rate_func=smooth)
+self.play(square.animate.shift(RIGHT), rate_func=linear)
+self.play(square.animate.shift(RIGHT), rate_func=there_and_back)
+```
+
+## Playing Multiple Animations
+
+### Simultaneously
+
+```python
+# All play at the same time
+self.play(
+    Create(circle),
+    FadeIn(square),
+    Write(text)
+)
+```
+
+### Sequentially
+
+```python
+# One after another
+self.play(Create(circle))
+self.play(FadeIn(square))
+self.play(Write(text))
+
+# Or use Succession
+self.play(Succession(
+    Create(circle),
+    FadeIn(square),
+    Write(text)
+))
+```
+
+## Common Animation Classes
+
+### Creation Animations
+```python
+Create(mobject)           # Draw the mobject progressively
+Write(text)               # Write text/equations
+FadeIn(mobject)           # Fade in from transparent
+DrawBorderThenFill(mob)   # Draw outline, then fill
+GrowFromCenter(mobject)   # Grow from center point
+```
+
+### Removal Animations
+```python
+FadeOut(mobject)          # Fade to transparent
+Uncreate(mobject)         # Reverse of Create
+ShrinkToCenter(mobject)   # Shrink to center and disappear
+```
+
+### Transform Animations
+```python
+Transform(mob1, mob2)              # Morph mob1 into mob2
+ReplacementTransform(mob1, mob2)   # Replace mob1 with mob2
+TransformFromCopy(mob1, mob2)      # Keep mob1, create mob2
+```
+
+### Movement Animations
+```python
+MoveToTarget(mobject)     # Move to preset target
+Rotate(mobject, angle)    # Rotate by angle
+Circumscribe(mobject)     # Draw attention with circle
+```
+
+## Animation vs Instant Changes
+
+```python
+# Animated change (visible transition)
+self.play(circle.animate.set_color(RED))
+
+# Instant change (no animation)
+circle.set_color(RED)
+self.add(circle)
+```
+
+## Best Practices
+
+1. **Use .animate for simple transformations** - Cleaner than explicit Animation classes
+2. **Keep run_time reasonable** - 0.5-2 seconds for most animations
+3. **Use rate_func for polish** - `smooth` is usually better than `linear`
+4. **Group related animations** - Play simultaneously when conceptually related

package/references/manimce/rules/api-pitfalls.md

@@ -0,0 +1,89 @@
+---
+name: api-pitfalls
+description: Common ManimCE API mistakes that cause runtime errors
+metadata:
+  tags: errors, pitfalls, brace, laggedstartmap, font_size, debugging
+---
+
+# Common API Pitfalls
+
+These mistakes compile fine but crash at render time. Avoid them.
+
+## Brace.get_text() Does NOT Accept font_size
+
+```python
+# BAD — crashes with "next_to() got unexpected keyword argument 'font_size'"
+brace = Brace(mobject, DOWN)
+label = brace.get_text("Width", font_size=24)  # WRONG
+
+# GOOD — set font_size on the Text object afterward
+brace = Brace(mobject, DOWN)
+label = brace.get_text("Width")
+label.scale(0.6)  # Scale instead
+
+# GOOD — or create the text separately
+label = Text("Width", font_size=24).next_to(brace, DOWN, buff=0.1)
+```
+
+`get_text()` only accepts `*text` and `**kwargs` that are passed to `next_to()`. It does NOT accept `font_size`, `color`, or other Text kwargs.
+
+## LaggedStartMap Requires a VGroup, Not Loose Mobjects
+
+```python
+# BAD — crashes with "Write.__init__() takes from 2 to 4 positional arguments but N were given"
+labels = [Text("A"), Text("B"), Text("C")]
+self.play(LaggedStartMap(Write, labels))  # WRONG — list, not VGroup
+
+# Also BAD — VGroup with nested submobjects gets flattened
+labels_group = VGroup(text1, text2, text3)  # Each text has many submobjects
+self.play(LaggedStartMap(Write, labels_group))  # Iterates submobjects of submobjects!
+
+# GOOD — use LaggedStart with explicit animation list
+self.play(LaggedStart(*[Write(t) for t in labels], lag_ratio=0.3))
+
+# GOOD — LaggedStartMap with simple mobjects (Dot, Circle, Square)
+dots = VGroup(*[Dot() for _ in range(10)]).arrange(RIGHT)
+self.play(LaggedStartMap(FadeIn, dots, lag_ratio=0.1))  # Each dot is a single submobject
+```
+
+**Rule of thumb**: Use `LaggedStartMap` only with VGroups of simple mobjects (Dot, Circle, Square). For Text, MathTex, or complex mobjects, use `LaggedStart(*[Anim(m) for m in items])`.
+
+## MathTex Indexing Is Per LaTeX Group
+
+```python
+# BAD — index out of range or wrong element
+eq = MathTex("a^2 + b^2 = c^2")
+eq[1].set_color(RED)  # Only 1 element! The whole string is one group
+
+# GOOD — split into separate strings for indexing
+eq = MathTex("a^2", "+", "b^2", "=", "c^2")
+eq[0].set_color(RED)  # "a^2"
+eq[2].set_color(BLUE)  # "b^2"
+```
+
+## Transform Requires Same Type OR Use ReplacementTransform
+
+```python
+# BAD — unexpected behavior
+self.play(Transform(old_text, new_equation))  # Text → MathTex can glitch
+
+# GOOD
+self.play(ReplacementTransform(old_text, new_equation))
+# OR
+self.play(FadeOut(old_text), FadeIn(new_equation))
+```
+
+## VGroup.arrange() Returns Self — Don't Forget to Use It
+
+```python
+# BAD — items not arranged
+items = VGroup(circle, square, triangle)
+items.arrange(RIGHT)  # Works, but easy to forget
+
+# Common mistake: creating items then forgetting to arrange
+group = VGroup(*[Square() for _ in range(5)])
+# Oops — all squares overlap at origin!
+
+# GOOD
+group = VGroup(*[Square() for _ in range(5)]).arrange(RIGHT, buff=0.3)
+```

package/references/manimce/rules/axes.md

@@ -0,0 +1,214 @@
+---
+name: axes
+description: Axes, NumberPlane, and coordinate systems in Manim
+metadata:
+  tags: axes, numberplane, coordinate, grid, numberline
+---
+
+# Coordinate Systems
+
+Create axes, grids, and number lines for mathematical visualizations.
+
+## Axes
+
+Basic 2D coordinate axes.
+
+```python
+from manim import *
+
+class AxesExample(Scene):
+    def construct(self):
+        # Default axes
+        axes = Axes()
+        self.add(axes)
+```
+
+### Customizing Axes
+
+```python
+class CustomAxes(Scene):
+    def construct(self):
+        axes = Axes(
+            x_range=[-5, 5, 1],      # [min, max, step]
+            y_range=[-3, 3, 1],
+            x_length=10,              # Physical length on screen
+            y_length=6,
+            axis_config={
+                "color": BLUE,
+                "include_tip": True,
+                "include_numbers": True,
+            },
+            x_axis_config={
+                "numbers_to_include": [-4, -2, 0, 2, 4],
+            },
+            y_axis_config={
+                "numbers_to_include": [-2, 0, 2],
+            },
+        )
+        self.add(axes)
+```
+
+### Adding Labels
+
+```python
+class AxesLabels(Scene):
+    def construct(self):
+        axes = Axes(x_range=[-5, 5], y_range=[-3, 3])
+
+        # Add axis labels
+        x_label = axes.get_x_axis_label("x")
+        y_label = axes.get_y_axis_label("y")
+
+        # Custom labels
+        x_label = axes.get_x_axis_label(MathTex(r"\theta"))
+        y_label = axes.get_y_axis_label(MathTex(r"f(\theta)"))
+
+        self.add(axes, x_label, y_label)
+```
+
+## NumberPlane
+
+Grid with axes - shows coordinate lines.
+
+```python
+class NumberPlaneExample(Scene):
+    def construct(self):
+        # Default plane
+        plane = NumberPlane()
+        self.add(plane)
+```
+
+### Customizing NumberPlane
+
+```python
+class CustomPlane(Scene):
+    def construct(self):
+        plane = NumberPlane(
+            x_range=[-4, 4, 1],
+            y_range=[-3, 3, 1],
+            x_length=8,
+            y_length=6,
+            background_line_style={
+                "stroke_color": BLUE_D,
+                "stroke_width": 1,
+                "stroke_opacity": 0.5,
+            },
+            axis_config={
+                "color": WHITE,
+            },
+        )
+        self.add(plane)
+```
+
+## ComplexPlane
+
+For visualizing complex numbers.
+
+```python
+class ComplexPlaneExample(Scene):
+    def construct(self):
+        plane = ComplexPlane()
+
+        # Plot complex number
+        z = complex(2, 1)  # 2 + i
+        dot = Dot(plane.n2p(z), color=YELLOW)
+        label = MathTex("2+i").next_to(dot, UR)
+
+        self.add(plane, dot, label)
+```
+
+## NumberLine
+
+Single axis line.
+
+```python
+class NumberLineExample(Scene):
+    def construct(self):
+        line = NumberLine(
+            x_range=[-5, 5, 1],
+            length=10,
+            include_numbers=True,
+            include_tip=True,
+        )
+        self.add(line)
+```
+
+## Coordinate Conversions
+
+```python
+class CoordinateConversion(Scene):
+    def construct(self):
+        axes = Axes(x_range=[-5, 5], y_range=[-3, 3])
+
+        # Convert coordinates to screen position
+        point = axes.c2p(2, 1)  # coords_to_point: (2, 1) -> screen position
+
+        # Convert screen position to coordinates
+        coords = axes.p2c(point)  # point_to_coords: screen -> (x, y)
+
+        dot = Dot(point, color=RED)
+        self.add(axes, dot)
+```
+
+### Shorthand Methods
+
+```python
+axes = Axes()
+
+# c2p = coords_to_point
+axes.c2p(x, y)
+
+# p2c = point_to_coords
+axes.p2c(point)
+
+# i2gp = input_to_graph_point (for graphs)
+axes.i2gp(x, graph)
+
+# For NumberPlane/ComplexPlane
+plane.n2p(complex_number)  # number_to_point
+plane.p2n(point)           # point_to_number
+```
+
+## ThreeDAxes
+
+For 3D visualizations.
+
+```python
+class ThreeDAxesExample(ThreeDScene):
+    def construct(self):
+        axes = ThreeDAxes(
+            x_range=[-4, 4, 1],
+            y_range=[-4, 4, 1],
+            z_range=[-4, 4, 1],
+            x_length=8,
+            y_length=8,
+            z_length=6,
+        )
+
+        self.set_camera_orientation(phi=75 * DEGREES, theta=-45 * DEGREES)
+        self.add(axes)
+```
+
+## Plotting Points
+
+```python
+class PlotPoints(Scene):
+    def construct(self):
+        axes = Axes(x_range=[-5, 5], y_range=[-3, 3])
+
+        points = [(1, 2), (-2, 1), (3, -1), (0, 2)]
+        dots = VGroup(*[
+            Dot(axes.c2p(x, y), color=YELLOW)
+            for x, y in points
+        ])
+
+        self.add(axes, dots)
+```
+
+## Best Practices
+
+1. **Set appropriate ranges** - Don't include unnecessary empty space
+2. **Match x_length/y_length to range ratio** - Prevents distortion
+3. **Use NumberPlane for transformations** - Grid shows distortion clearly
+4. **Use c2p for all coordinate work** - Don't manually convert
+5. **Include numbers sparingly** - Too many numbers clutter the display