manim-mcp 0.1.0

package/references/composer/references/scene-archetypes.md

@@ -0,0 +1,534 @@
+# 3Blue1Brown Scene Archetypes
+
+Reusable scene templates extracted from 400+ 3b1b video source files. Each archetype includes the base class, typical structure, and real implementation patterns.
+
+---
+
+## 1. TeacherStudentsScene (Classroom Dialogue)
+
+The most-used scene archetype across the entire codebase (134 files, 851 class instances). Features one teacher (Mortimer) and three students as Pi creatures.
+
+### Structure
+
+```python
+class MyDialogueScene(TeacherStudentsScene):
+    def construct(self):
+        # Teacher introduces concept
+        self.play(
+            self.teacher.says("Here's the key idea..."),
+            self.change_students("pondering", "happy", "erm")
+        )
+        self.wait(2)
+
+        # Student asks question
+        self.play(
+            self.students[1].says(
+                "But what about...?",
+                mode="sassy"
+            ),
+            self.teacher.change("guilty", self.students[1].eyes)
+        )
+        self.wait()
+
+        # Teacher responds
+        self.play(
+            self.teacher.says("Great question!", mode="raise_right_hand"),
+            self.change_students("thinking", "happy", "thinking")
+        )
+```
+
+### When to Use
+
+- Emotional resets between dense mathematical sections (15-30 seconds)
+- Acknowledging viewer confusion ("This might seem strange...")
+- Introducing controversial or non-obvious claims
+- Transitioning between major topics
+- Humor and personality breaks
+
+### Real Examples
+
+**Moser's Circle Problem** (`_2023/moser_reboot/main.py`):
+```python
+class AskAboutPosition(TeacherStudentsScene):
+    def construct(self):
+        self.play(LaggedStart(
+            stds[1].says("Doesn't it depend on\nwhere the points are?", mode="sassy"),
+            stds[0].change('confused', self.screen),
+            morty.change("guilty", stds[1].eyes)
+        ))
+```
+
+**FFT Revelation** (`_2022/convolutions/supplements.py`):
+```python
+class DumbIdea(TeacherStudentsScene):
+    # Student calls the polynomial approach "idiotic"
+    # Teacher reveals "But there's a trick" -> FFT
+    # Student asks "What...is that?"
+```
+
+---
+
+## 2. OpeningQuote Scene
+
+A formatted quote with author attribution. Standard opening for EoLA series.
+
+### Structure
+
+```python
+class OpeningQuote(Scene):
+    def construct(self):
+        words = OldTexText(R"``Quote text here.''")
+        words.set_width(2 * (FRAME_X_RADIUS - 1))
+        words.to_edge(UP)
+        words.set_color_by_tex("key phrase", GREEN)
+
+        author = OldTexText("-Author Name")
+        author.set_color(YELLOW)
+        author.next_to(words, DOWN, buff=0.5)
+
+        self.play(FadeIn(words))
+        self.wait(3)
+        self.play(Write(author, run_time=5))
+        self.wait()
+```
+
+### Timing
+
+- FadeIn quote: instant to 1 second
+- Wait for reading: 3-4 seconds
+- Write author: 4-5 seconds (slow, dramatic)
+- Final wait: 1-2 seconds
+- Total: ~8-12 seconds
+
+---
+
+## 3. Grid Transformation Scene
+
+THE signature 3b1b visual. A NumberPlane grid is deformed by a linear transformation.
+
+### Structure
+
+```python
+class TransformationScene(InteractiveScene):
+    def construct(self):
+        # Setup
+        plane = NumberPlane()
+        i_hat = Vector(RIGHT, color=GREEN)
+        j_hat = Vector(UP, color=RED)
+
+        self.add(plane, i_hat, j_hat)
+        self.wait()
+
+        # Apply transformation
+        matrix = [[2, 1], [0, 1]]  # Shear
+        self.play(
+            plane.animate.apply_matrix(matrix),
+            i_hat.animate.put_start_and_end_on(ORIGIN, matrix[0]),
+            j_hat.animate.put_start_and_end_on(ORIGIN, matrix[1]),
+            run_time=3
+        )
+        self.wait()
+```
+
+### Variations from the Codebase
+
+- **Single transformation**: Apply one matrix, observe result
+- **Composition**: Apply matrix A, then matrix B, show AB
+- **Determinant reveal**: Color the unit square, watch its area change
+- **Eigenvector highlight**: Some vectors stay on their line
+- **Non-square**: Map between dimensions (3D to 2D projection)
+
+### Color Convention
+
+- **i-hat (basis vector 1)**: GREEN
+- **j-hat (basis vector 2)**: RED
+- **Arbitrary vector v**: YELLOW
+- **Grid lines**: BLUE_D to BLUE_B
+
+---
+
+## 4. Equation Derivation Scene
+
+Step-by-step visual derivation of a formula, using `TransformMatchingTex` for smooth transitions.
+
+### Structure
+
+```python
+class DerivationScene(InteractiveScene):
+    def construct(self):
+        step1 = Tex(R"f(x) = \int_0^x g(t) \, dt")
+        step2 = Tex(R"\frac{d}{dx} f(x) = g(x)")
+        step3 = Tex(R"f'(x) = g(x)")
+
+        # Color code consistently
+        kw = {"t2c": {"{x}": BLUE, "{t}": YELLOW, "g": GREEN}}
+
+        self.play(Write(step1))
+        self.wait(2)
+
+        # Highlight the key part
+        self.play(Indicate(step1[...]))  # highlight derivative
+
+        # Transform to next step
+        self.play(TransformMatchingTex(step1, step2))
+        self.wait(2)
+
+        self.play(TransformMatchingTex(step2, step3))
+        self.wait()
+```
+
+### Key Techniques
+
+- **`TransformMatchingTex`**: Matches LaTeX substrings between equations for smooth morphing. Use `matched_keys` parameter for explicit matching.
+- **`t2c` (text-to-color)**: Color-code variables consistently across all steps.
+- **`Indicate()`**: Brief flash on the term being discussed.
+- **`SurroundingRectangle`**: Box around a sub-expression before explaining it.
+- **`Brace`**: Point to a piece with a descriptive label.
+
+### Real Example: CLT Proof (`_2023/clt_proof/main.py`)
+
+```python
+self.play(TransformMatchingTex(eq1, eq2, matched_keys=[R"e^{tx}"]))
+```
+
+### Real Example: Laplace Commutative Diagram (`_2025/laplace/derivatives.py`)
+
+```python
+ft, Fs, dft, sFs = terms = VGroup(
+    Tex(R"f({t})", **kw),
+    Tex(R"F({s})", **kw),
+    Tex(R"f'({t})", **kw),
+    Tex(R"{s}F({s}) - f(0)", **kw),
+)
+terms.arrange_in_grid(h_buff=2.0, v_buff=3.0, fill_rows_first=False)
+deriv_arrow = Arrow(ft, dft)
+laplace_arrow = Arrow(ft, Fs)
+```
+
+---
+
+## 5. Side-by-Side Comparison Scene
+
+Two representations of the same concept shown simultaneously.
+
+### Structure
+
+```python
+class ComparisonScene(InteractiveScene):
+    def construct(self):
+        # Split screen
+        left_group = VGroup(left_title, left_content)
+        right_group = VGroup(right_title, right_content)
+
+        left_group.to_edge(LEFT)
+        right_group.to_edge(RIGHT)
+
+        divider = Line(3 * UP, 3 * DOWN)
+
+        self.play(ShowCreation(divider))
+        self.play(FadeIn(left_group), FadeIn(right_group))
+```
+
+### Real Examples
+
+- **"Your coords vs Jennifer's coords"** (EoLA Ch 10): Two coordinate systems side by side
+- **"Fourier Land"** (`_2022/borwein/supplements.py`): Time domain on left, frequency domain on right, with teal-tinted right half
+- **Bertrand's Paradox** (`_2021/bertrands_paradox.py`): Three methods of choosing random chords compared
+
+### Fourier Land Split Screen Pattern
+
+```python
+right_rect = FullScreenRectangle()
+right_rect.set_fill(TEAL, 0.2)
+right_rect.stretch(0.5, 0, about_edge=RIGHT)
+ft_label = Text("Fourier Land", font_size=60)
+ft_label.set_fill(TEAL)
+```
+
+---
+
+## 6. Phase Space Scene
+
+Show a physical system alongside its phase portrait -- the signature technique from the Differential Equations series.
+
+### Structure
+
+```python
+class PhaseSpaceScene(InteractiveScene):
+    def construct(self):
+        # Left: physical system
+        pendulum = Pendulum(...)
+
+        # Right: phase portrait
+        phase_plane = NumberPlane(
+            x_range=[-PI, PI],  # theta
+            y_range=[-5, 5],    # omega
+        )
+        vector_field = VectorField(
+            lambda p: pendulum_vector_field_func(p),
+        )
+        stream_lines = StreamLines(
+            vector_field.func,
+            delta_x=0.5, delta_y=0.5,
+        )
+
+        # Link them: dot on phase space follows pendulum state
+        state_dot = Dot(color=YELLOW)
+        state_dot.add_updater(lambda m: m.move_to(
+            phase_plane.c2p(pendulum.theta, pendulum.omega)
+        ))
+```
+
+### Real Implementation (`_2019/diffyq/part1/`)
+
+The DiffEq series uses:
+- `Pendulum` custom mobject with physics simulation
+- `ThetaVsTAxes` for theta-vs-time graph
+- `IntroduceVectorField` for phase space
+- `PhaseSpaceOfPopulationModel` imported from `_2018/div_curl.py`
+
+---
+
+## 7. Progressive Build Scene
+
+Build a complex object incrementally, showing each component.
+
+### Structure
+
+```
+1. Show component A alone
+2. Add component B, explain
+3. Add component C, explain
+4. Show the combined result
+5. "Each piece is simple, but together..."
+```
+
+### Real Examples
+
+**Fourier Series** (DiffEq Part 4): Individual sine waves added one at a time, with running sum shown. 1 term, 3 terms, 5 terms, 50 terms...
+
+**CLT / Gaussian Build-Up** (`_2023/clt/main.py`): `BuildUpGaussian` constructs the Gaussian formula piece by piece: first the exponential, then the 1/sqrt(2*pi), then sigma.
+
+**Transformer Architecture** (`_2024/transformers/network_flow.py`): `HighLevelNetworkFlow` adds embedding -> attention -> MLP -> unembedding one block at a time.
+
+**Progressive Speed-Up Pattern**:
+```python
+for n in range(n_sums):
+    if n < 10:
+        self.run_one_sum(animated=True)
+    else:
+        self.run_one_sum(animated=False, still_frame=True)
+```
+
+---
+
+## 8. Proof/Demonstration Scene
+
+Visual proof with highlighted steps.
+
+### Structure
+
+```python
+class ProofScene(InteractiveScene):
+    def construct(self):
+        # State the claim
+        claim = Tex(R"\text{Claim: } ...")
+        self.play(Write(claim))
+
+        # Visual setup
+        # ... create geometric objects ...
+
+        # Step-by-step reasoning
+        step1_label = Text("Step 1: ...", font_size=36)
+        step1_label.to_corner(UL)
+        self.play(Write(step1_label))
+        # ... animate step 1 ...
+
+        # Highlight the key insight
+        self.play(FlashAround(key_element))
+
+        # QED / conclusion
+        qed = Tex(R"\blacksquare")
+        qed.to_corner(DR)
+        self.play(Write(qed))
+```
+
+### Real Examples
+
+- **Circle area via concentric rings** (EoC Ch 1): Each ring unfurled into a thin rectangle, stacked to form a triangle
+- **Surface area of a sphere** (`_2018/sphere_area.py`, `_2022/visual_proofs/lies.py`): Sphere sliced into bands, projected
+- **Moser's Circle Problem** (`_2023/moser_reboot/main.py`): Combinatorial counting with `choose()` function
+
+---
+
+## 9. Simulation Scene
+
+Real-time physics or mathematical simulation.
+
+### Examples from Codebase
+
+**SIR Epidemic** (`_2020/sir.py`):
+```python
+class SIRSimulation(VGroup):
+    # Physics-based particles with infection mechanics
+    # Susceptible=BLUE, Infected=RED, Recovered=GREEN
+```
+
+**Galton Board** (`_2023/clt/galton_board.py`):
+```python
+class GaltonBoard(InteractiveScene):
+    # Physical ball bouncing simulation
+    self.add_sound("clack")  # Sound effects for bounces
+```
+
+**Spring-Mass System** (`_2025/laplace/shm.py`):
+```python
+class SrpingMassSystem(VGroup):
+    def time_step(self, delta_t, dt_size=1e-3):
+        # Euler integration with substeps
+```
+
+**Sliding Blocks** (`_2019/clacks/question.py`):
+```python
+class SlidingBlocks(VGroup):
+    # Two blocks, elastic collisions, count clacks
+```
+
+**Ladybug Random Walk** (`_2026/monthly_mindbenders/ladybug.py`):
+```python
+# Random walk on clock face
+while len(covered_numbers) < 12:
+    step = random.choice([+1, -1])
+```
+
+---
+
+## 10. Data Visualization Scene
+
+Chart, graph, or distribution visualization.
+
+### Key Custom Mobjects
+
+**`ChartBars`** (`_2023/clt/main.py`):
+```python
+class ChartBars(VGroup):
+    # Bar chart aligned to axes
+    # Supports gradient coloring:
+    bars.set_submobject_colors_by_gradient(BLUE, GREEN)
+```
+
+**Dynamic Labels** (`make_number_changeable`):
+```python
+label = Tex(R"\mu = 0.00")
+decimal = label.make_number_changeable("0.00")
+decimal.add_updater(lambda m: m.set_value(get_mean()))
+```
+
+**`Histogram`** (`_2020/beta/helpers.py`):
+```python
+class Histogram(Group):
+    # Bar chart for probability distributions
+```
+
+---
+
+## 11. 3D Surface Scene
+
+Mathematical surface rendered in three dimensions with camera orbiting.
+
+### Structure
+
+```python
+class SurfaceScene(InteractiveScene):
+    def construct(self):
+        frame = self.frame
+        frame.reorient(-40, 70, 0)
+        frame.set_field_of_view(20 * DEGREES)
+
+        surface = ParametricSurface(
+            lambda u, v: [u, v, func(u, v)],
+            u_range=(-3, 3), v_range=(-3, 3),
+            resolution=(101, 101)
+        )
+        surface.set_shading(0.1, 0.1, 0.1)
+        mesh = SurfaceMesh(surface)
+
+        self.play(FadeIn(Group(surface, mesh)))
+        self.play(frame.animate.reorient(60, 50, 0), run_time=5)
+```
+
+### Variations
+
+- **Color by phase**: `surface.color_by_uv_function(lambda u, v: z_to_color(func(complex(u, v))))`
+- **Clip planes**: `surface.set_clip_plane(direction, value)` for cross-sections
+- **Textured surfaces**: `TexturedSurface(Sphere(), "EarthTextureMap")` for planets
+- **Ambient rotation**: `frame.add_updater(lambda m, dt: m.increment_theta(-0.1 * dt))`
+
+---
+
+## 12. End Screen / Patron Credits
+
+Standard ending with links and supporter acknowledgment.
+
+### Structure
+
+From `custom/end_screen.py`:
+- Channel logo/banner
+- Patron names scrolling or displayed
+- Links to related videos
+- Support call-to-action
+
+---
+
+## 13. Quiz / Interactive Reveal Scene
+
+Present a question, let the viewer think, then reveal the answer.
+
+### Real Example: Grover Quiz (`_2025/grover/runtime.py`)
+
+```python
+covers = VGroup(SurroundingRectangle(choice[2:]) for choice in choices)
+covers.set_fill(GREY_D, 1)
+for cover in covers:
+    cover.save_state()
+    cover.stretch(0, 0, about_edge=LEFT)
+self.play(LaggedStartMap(Restore, covers, lag_ratio=0.25))
+```
+
+---
+
+## 14. Taxonomy / Nested Box Scene
+
+Categorize concepts using nested or overlapping boxes.
+
+### Real Example: ML Taxonomy (`_2024/transformers/ml_basics.py`)
+
+```python
+class MLWithinDeepL(InteractiveScene):
+    def get_titled_box(self, text, color, ...):
+        title = Text(text)
+        box = Rectangle(...)
+        box.set_fill(interpolate_color(BLACK, color, opacity), 1)
+        box.set_stroke(color, 2)
+```
+
+Boxes nest: AI > Machine Learning > Deep Learning > Transformers
+
+---
+
+## Archetype Selection Guide
+
+| Situation | Recommended Archetype |
+|-----------|-----------------------|
+| Opening a series chapter | OpeningQuote + Question-Driven |
+| Introducing a linear algebra concept | Grid Transformation |
+| Deriving a formula | Equation Derivation |
+| Explaining a physics concept | Phase Space + Simulation |
+| Building something complex | Progressive Build |
+| Comparing two approaches | Side-by-Side Comparison |
+| Emotional reset / humor | TeacherStudentsScene |
+| Proving something visual | Proof/Demonstration |
+| Showing data or distributions | Data Visualization |
+| 3D mathematical object | 3D Surface |
+| Testing viewer understanding | Quiz / Interactive Reveal |
+| Categorizing concepts | Taxonomy / Nested Box |