manim-mcp 0.1.0

package/references/manimce/rules/pedagogy.md

@@ -0,0 +1,532 @@
+---
+name: pedagogy
+description: Pedagogical patterns from 3Blue1Brown for creating effective mathematical explanations in ManimCE
+metadata:
+  tags: pedagogy, teaching, 3b1b, pi-creature, intuition, visualization, revelation
+---
+
+# Pedagogical Patterns from 3Blue1Brown
+
+These patterns are distilled from the full 3Blue1Brown video corpus (2015-2026). They represent the core teaching philosophy that makes 3b1b videos effective.
+
+## "Never Forget What This Represents"
+
+The central 3b1b principle: every algebraic manipulation must be tied back to its geometric or visual meaning. Never let the viewer lose sight of the connection between symbols and pictures.
+
+```python
+from manim import *
+
+class TieComputationToGeometry(Scene):
+    """Always show both the formula AND what it means visually."""
+
+    def construct(self):
+        # Show the equation
+        equation = MathTex(
+            r"|\vec{v}|^2 = x^2 + y^2",
+            tex_to_color_map={"x": GREEN, "y": RED},
+        )
+        equation.to_edge(UP)
+
+        # Show the geometry simultaneously
+        plane = NumberPlane().set_opacity(0.3)
+        vec = Vector([3, 2], color=YELLOW)
+        x_comp = Line(ORIGIN, [3, 0, 0], color=GREEN, stroke_width=4)
+        y_comp = Line([3, 0, 0], [3, 2, 0], color=RED, stroke_width=4)
+
+        x_label = MathTex("x", color=GREEN).next_to(x_comp, DOWN)
+        y_label = MathTex("y", color=RED).next_to(y_comp, RIGHT)
+
+        # Introduce both together
+        self.add(plane)
+        self.play(
+            GrowArrow(vec),
+            Write(equation),
+        )
+        self.wait()
+
+        # Show the components connecting to the formula
+        self.play(Create(x_comp), Write(x_label))
+        self.play(Create(y_comp), Write(y_label))
+        self.wait()
+
+        # Highlight the connection: square each component visually
+        x_square = Square(side_length=1.5, color=GREEN, fill_opacity=0.3)
+        x_square.next_to(x_comp, DOWN, buff=0.5, aligned_edge=LEFT)
+        x_sq_label = MathTex("x^2", color=GREEN).move_to(x_square)
+
+        y_square = Square(side_length=1.0, color=RED, fill_opacity=0.3)
+        y_square.next_to(y_comp, RIGHT, buff=0.5, aligned_edge=DOWN)
+        y_sq_label = MathTex("y^2", color=RED).move_to(y_square)
+
+        self.play(
+            DrawBorderThenFill(x_square), Write(x_sq_label),
+            DrawBorderThenFill(y_square), Write(y_sq_label),
+        )
+        self.wait(2)
+```
+
+## Physical Intuition First, Formalization Second
+
+Always start with a physical, tangible example before introducing abstract notation. The viewer should already "feel" the answer before seeing the formula.
+
+```python
+class IntuitionFirst(Scene):
+    """Show the physical behavior, THEN the equation."""
+
+    def construct(self):
+        # Phase 1: Show the physical behavior (no formulas yet)
+        title = Text("What happens when you spin a wheel?", font_size=36)
+        title.to_edge(UP)
+        self.play(Write(title))
+
+        wheel = Circle(radius=1.5, color=WHITE)
+        dot = Dot(point=wheel.point_from_proportion(0), color=YELLOW)
+        dot.add_updater(
+            lambda m, dt: m.move_to(
+                wheel.point_from_proportion(
+                    (m.get_center()[0] / (2 * PI * 1.5)) % 1
+                )
+            )
+        )
+        self.play(Create(wheel), FadeIn(dot))
+
+        # Trace the path as the wheel rolls
+        traced_path = TracedPath(dot.get_center, stroke_color=YELLOW, stroke_width=2)
+        self.add(traced_path)
+        self.play(Rotate(wheel, 2 * TAU, about_point=ORIGIN), run_time=4)
+        self.wait()
+
+        # Phase 2: NOW introduce the formula
+        self.play(FadeOut(title))
+        formula_title = Text("The math behind this:", font_size=36)
+        formula_title.to_edge(UP)
+        formula = MathTex(
+            r"\vec{r}(t) = \begin{bmatrix} t - \sin(t) \\ 1 - \cos(t) \end{bmatrix}"
+        )
+        formula.next_to(formula_title, DOWN, buff=0.5)
+
+        self.play(Write(formula_title), Write(formula))
+        self.wait(2)
+```
+
+## Multiple Perspectives on the Same Concept
+
+3b1b regularly shows 2-3 different ways to think about the same idea (algebraic, geometric, physical). This is central to the Essence of Linear Algebra series.
+
+```python
+class MultiplePerspectives(Scene):
+    """Show the same concept from different angles."""
+
+    def construct(self):
+        # Perspective 1: Geometric (visual)
+        p1_title = Text("Geometric View", font_size=30, color=BLUE)
+        p1_title.to_corner(UL)
+        det_visual = VGroup(
+            Vector([2, 0], color=GREEN),
+            Vector([1, 1.5], color=RED),
+        )
+        parallelogram = Polygon(
+            ORIGIN, [2, 0, 0], [3, 1.5, 0], [1, 1.5, 0],
+            fill_color=YELLOW, fill_opacity=0.3, stroke_color=YELLOW,
+        )
+        area_label = MathTex(r"\text{Area}", color=YELLOW)
+        area_label.move_to(parallelogram)
+
+        geo_group = VGroup(det_visual, parallelogram, area_label, p1_title)
+        geo_group.shift(3 * LEFT)
+
+        # Perspective 2: Algebraic (formula)
+        p2_title = Text("Algebraic View", font_size=30, color=GREEN)
+        p2_title.to_edge(UP).shift(3 * RIGHT)
+        formula = MathTex(
+            r"\det \begin{bmatrix} a & b \\ c & d \end{bmatrix} = ad - bc"
+        )
+        formula.next_to(p2_title, DOWN, buff=0.5)
+
+        alg_group = VGroup(p2_title, formula)
+
+        # Show them side by side
+        self.play(
+            Write(p1_title),
+            GrowArrow(det_visual[0]), GrowArrow(det_visual[1]),
+        )
+        self.play(DrawBorderThenFill(parallelogram), Write(area_label))
+        self.wait()
+
+        self.play(Write(p2_title), Write(formula))
+        self.wait()
+
+        # Draw the connection
+        arrow = Arrow(
+            parallelogram.get_right(), formula.get_left(),
+            color=WHITE, buff=0.5,
+        )
+        same_thing = Text("Same thing!", font_size=24, color=YELLOW)
+        same_thing.next_to(arrow, UP)
+        self.play(GrowArrow(arrow), Write(same_thing))
+        self.wait(2)
+```
+
+## Pi Creature Reactions for Emotional Engagement
+
+In ManimGL, 3b1b uses `PiCreatureScene` and `TeacherStudentsScene` for character reactions. In ManimCE, you can create similar emotional signposting with simpler means, or use the community pi creature plugin.
+
+### Emotional Markers Without Pi Creatures
+
+```python
+class EmotionalMarkers(Scene):
+    """Use visual cues to signal emotional beats."""
+
+    def construct(self):
+        # Confusion marker
+        equation = MathTex(r"e^{i\pi} + 1 = 0")
+        equation.scale(1.5)
+        self.play(Write(equation))
+
+        # "Wait, what?" moment
+        question_marks = VGroup(
+            *[Text("?", font_size=48, color=YELLOW) for _ in range(3)]
+        )
+        question_marks.arrange(RIGHT, buff=0.3)
+        question_marks.next_to(equation, DOWN, buff=0.5)
+        self.play(
+            LaggedStartMap(FadeIn, question_marks, scale=2, lag_ratio=0.2)
+        )
+        self.wait()
+
+        # "Aha!" moment
+        self.play(FadeOut(question_marks))
+        checkmark = Text("Ah, that makes sense!", color=GREEN, font_size=36)
+        checkmark.next_to(equation, DOWN, buff=0.5)
+        self.play(Write(checkmark))
+        self.wait()
+
+        # Surprise/delight
+        highlight = SurroundingRectangle(equation, color=YELLOW, buff=0.3)
+        self.play(Create(highlight))
+        self.play(
+            highlight.animate.set_stroke(width=6),
+            rate_func=there_and_back,
+            run_time=0.8,
+        )
+        self.wait()
+```
+
+### Teacher-Student Pattern (from 3b1b's TeacherStudentsScene)
+
+```python
+class TeacherStudentMoment(Scene):
+    """Recreate the teacher-student dynamic without pi creatures."""
+
+    def construct(self):
+        # Teacher's statement
+        teacher_bubble = RoundedRectangle(
+            corner_radius=0.3, width=5, height=1.5,
+            color=BLUE, fill_opacity=0.15,
+        ).to_edge(LEFT).shift(UP)
+        teacher_text = Text(
+            "Think about what the\ndeterminant represents",
+            font_size=28,
+        ).move_to(teacher_bubble)
+
+        # Student's response
+        student_bubble = RoundedRectangle(
+            corner_radius=0.3, width=4, height=1.2,
+            color=GREEN, fill_opacity=0.15,
+        ).to_edge(RIGHT).shift(DOWN)
+        student_text = Text(
+            "Scaling factor\nfor areas!",
+            font_size=28,
+        ).move_to(student_bubble)
+
+        self.play(FadeIn(teacher_bubble), Write(teacher_text))
+        self.wait(2)
+        self.play(FadeIn(student_bubble), Write(student_text))
+        self.wait(2)
+```
+
+## Building on Prior Knowledge (Explicit Recap Scenes)
+
+Many 3b1b series videos open by briefly recapping the previous video's key idea.
+
+```python
+class RecapPreviousVideo(Scene):
+    """Brief recap before diving into new content."""
+
+    def construct(self):
+        # Mini header
+        recap_label = Text("Quick recap from last time:", font_size=28, color=GREY_A)
+        recap_label.to_corner(UL)
+        self.play(Write(recap_label))
+
+        # Show the key takeaway from previous video (dimmed)
+        prev_result = MathTex(
+            r"A\vec{v} = \lambda \vec{v}",
+            font_size=48,
+        )
+        prev_result.set_opacity(0.7)
+        prev_context = Text(
+            "An eigenvector stays on its own span",
+            font_size=24, color=GREY_B,
+        )
+        prev_context.next_to(prev_result, DOWN)
+
+        self.play(FadeIn(VGroup(prev_result, prev_context), shift=0.5 * UP))
+        self.wait(2)
+
+        # Transition to new content
+        new_title = Text("Today: How to compute eigenvalues", font_size=40)
+        new_title.to_edge(UP)
+        self.play(
+            FadeOut(VGroup(recap_label, prev_result, prev_context), shift=UP),
+            Write(new_title),
+        )
+        self.wait()
+```
+
+## Controlled Revelation Pattern
+
+Information is revealed progressively. Question marks become answers. Blank spaces get filled in. This creates a sense of discovery.
+
+```python
+class ControlledRevelation(Scene):
+    """Reveal information progressively -- question marks become answers."""
+
+    def construct(self):
+        # Start with unknowns
+        equation = MathTex(
+            r"\det(A - ", r"\lambda", r"I) = ", r"?"
+        )
+        equation.set_color_by_tex(r"\lambda", TEAL)
+        equation[-1].set_color(RED)
+        equation.scale(1.3)
+        self.play(Write(equation))
+        self.wait(2)
+
+        # Replace the question mark with the actual answer
+        answer = MathTex(r"0", color=GREEN)
+        answer.scale(1.3)
+        answer.move_to(equation[-1])
+        self.play(
+            FadeOut(equation[-1], shift=UP),
+            FadeIn(answer, shift=UP),
+        )
+        self.wait()
+
+        # Expand progressively
+        expanded = MathTex(
+            r"(3-\lambda)(1-\lambda) - 2 = 0",
+            tex_to_color_map={r"\lambda": TEAL},
+        )
+        expanded.next_to(equation, DOWN, buff=0.8)
+        self.play(Write(expanded, run_time=2))
+        self.wait()
+
+        # Factor
+        factored = MathTex(
+            r"\lambda^2 - 4\lambda + 1 = 0",
+            tex_to_color_map={r"\lambda": TEAL},
+        )
+        factored.next_to(expanded, DOWN, buff=0.5)
+        self.play(Write(factored))
+        self.wait(2)
+```
+
+### Progressive Detail on Diagrams
+
+```python
+class ProgressiveDetail(Scene):
+    """Add detail to a diagram in stages."""
+
+    def construct(self):
+        # Stage 1: Simple shape
+        circle = Circle(radius=2, color=WHITE)
+        self.play(Create(circle))
+        self.wait()
+
+        # Stage 2: Add points
+        points = VGroup(*[
+            Dot(circle.point_from_proportion(i / 5), color=YELLOW)
+            for i in range(5)
+        ])
+        self.play(LaggedStartMap(FadeIn, points, scale=2, lag_ratio=0.15))
+        self.wait()
+
+        # Stage 3: Add chords
+        lines = VGroup()
+        for i in range(5):
+            for j in range(i + 1, 5):
+                line = Line(
+                    points[i].get_center(), points[j].get_center(),
+                    stroke_width=1, color=BLUE,
+                )
+                lines.add(line)
+        self.play(LaggedStartMap(Create, lines, lag_ratio=0.05))
+        self.wait()
+
+        # Stage 4: Add intersection dots
+        intersections = VGroup(*[
+            Dot(radius=0.05, color=RED)
+            for _ in range(3)  # Simplified
+        ])
+        # ... position at actual intersections
+        self.play(LaggedStartMap(FadeIn, intersections, scale=3, lag_ratio=0.1))
+        self.wait()
+
+        # Stage 5: Count regions with labels
+        counts = VGroup(*[
+            Integer(n, font_size=24, color=GREEN)
+            for n in [1, 2, 4, 8, 16]
+        ])
+        # ... position in each configuration
+```
+
+## The "Build False Confidence, Then Reveal Truth" Pattern
+
+From Moser's Circle Problem: present a pattern that looks obvious, then show it breaks. This is a powerful teaching tool for mathematical rigor.
+
+```python
+class FalseConfidence(Scene):
+    """Moser pattern: build expectation, then subvert it."""
+
+    def construct(self):
+        # Phase 1: Accumulate evidence for the "obvious" pattern
+        title = Text("Powers of 2?", font_size=48)
+        title.to_edge(UP)
+        self.play(Write(title))
+
+        values = [1, 2, 4, 8, 16]
+        value_mobs = VGroup()
+        for v in values:
+            mob = Integer(v, font_size=42)
+            value_mobs.add(mob)
+        value_mobs.arrange(RIGHT, buff=1.0)
+        value_mobs.next_to(title, DOWN, buff=1.0)
+
+        for mob in value_mobs:
+            self.play(FadeIn(mob, shift=0.25 * UP), run_time=0.5)
+            self.wait(0.5)
+
+        # Viewer expects 32 next
+        dots = MathTex(r"\ldots")
+        dots.next_to(value_mobs, RIGHT)
+        next_val = Integer(32, font_size=42, color=GREEN)
+        next_val.next_to(dots, RIGHT)
+        question = Text("32?", font_size=42, color=GREEN)
+        question.next_to(dots, RIGHT)
+        self.play(Write(dots), FadeIn(question))
+        self.wait(2)
+
+        # Phase 2: The REVEAL -- it's actually 31!
+        actual = Integer(31, font_size=42, color=RED)
+        actual.move_to(question)
+        cross = Cross(question, stroke_color=RED, stroke_width=6)
+
+        self.play(Create(cross))
+        self.wait()
+        self.play(
+            FadeOut(question), FadeOut(cross),
+            FadeIn(actual, scale=1.5),
+        )
+
+        # Update title
+        new_title = Text("NOT powers of 2!", font_size=48, color=RED)
+        new_title.to_edge(UP)
+        self.play(
+            FadeOut(title),
+            FadeIn(new_title),
+        )
+        self.wait(2)
+```
+
+## Signposting and Navigation
+
+3b1b frequently tells the viewer where they are in the explanation:
+
+```python
+class Signposting(Scene):
+    """Visual navigation through a multi-step argument."""
+
+    def construct(self):
+        # Step tracker
+        steps = VGroup(
+            Text("1. Setup", font_size=24),
+            Text("2. Key insight", font_size=24),
+            Text("3. Proof", font_size=24),
+            Text("4. Implications", font_size=24),
+        )
+        steps.arrange(DOWN, aligned_edge=LEFT, buff=0.3)
+        steps.to_corner(UL)
+        steps.set_opacity(0.3)
+
+        self.add(steps)
+
+        # Highlight current step
+        for i, step in enumerate(steps):
+            if i > 0:
+                steps[i - 1].animate.set_opacity(0.3)
+            self.play(step.animate.set_opacity(1.0).set_color(YELLOW))
+            self.wait()
+            # ... do the content for this step ...
+            self.wait(2)
+```
+
+## Analogy Pattern
+
+3b1b often introduces a concept through analogy to a familiar domain:
+
+```python
+class AnalogyPattern(Scene):
+    """Introduce abstract concept through familiar analogy."""
+
+    def construct(self):
+        # The familiar thing
+        familiar_title = Text("A recipe", font_size=36)
+        familiar_title.to_edge(UP).shift(3 * LEFT)
+        recipe_items = VGroup(
+            Text("Ingredients:", font_size=24),
+            Text("  2 cups flour", font_size=20),
+            Text("  1 cup sugar", font_size=20),
+            Text("  3 eggs", font_size=20),
+        ).arrange(DOWN, aligned_edge=LEFT)
+        recipe_items.next_to(familiar_title, DOWN)
+
+        # The abstract thing
+        abstract_title = Text("A linear combination", font_size=36)
+        abstract_title.to_edge(UP).shift(3 * RIGHT)
+        math_items = VGroup(
+            MathTex(r"\text{Components:}", font_size=24),
+            MathTex(r"2\hat{\imath}", font_size=24, color=GREEN),
+            MathTex(r"1\hat{\jmath}", font_size=24, color=RED),
+            MathTex(r"3\hat{k}", font_size=24, color=BLUE),
+        ).arrange(DOWN, aligned_edge=LEFT)
+        math_items.next_to(abstract_title, DOWN)
+
+        # Show familiar first
+        self.play(Write(familiar_title), FadeIn(recipe_items, lag_ratio=0.2))
+        self.wait(2)
+
+        # Then the abstract, drawing parallels
+        self.play(Write(abstract_title), FadeIn(math_items, lag_ratio=0.2))
+
+        # Draw arrows showing the analogy
+        arrows = VGroup(*[
+            Arrow(recipe_items[i + 1].get_right(), math_items[i + 1].get_left(), buff=0.3)
+            for i in range(3)
+        ])
+        self.play(LaggedStartMap(GrowArrow, arrows, lag_ratio=0.2))
+        self.wait(2)
+```
+
+## Best Practices Summary
+
+1. **Always tie algebra to geometry** -- if you write a formula, show what it means visually
+2. **Physical intuition first** -- let the viewer "feel" the concept before formalizing
+3. **Show multiple perspectives** -- algebraic, geometric, and physical views of the same idea
+4. **Progressive revelation** -- question marks become answers, details accumulate
+5. **Build false confidence** (when appropriate) -- show a pattern, then break it
+6. **Signpost your progress** -- tell the viewer where they are in the argument
+7. **Use emotional markers** -- surprise, confusion, and satisfaction moments
+8. **Recap before extending** -- briefly review before building on prior concepts
+9. **Analogy first** -- connect new concepts to familiar ones
+10. **Never let notation become opaque** -- if a symbol appears, the viewer should know what it means