manim-mcp 0.1.0

package/references/composer/references/visual-techniques.md

@@ -0,0 +1,480 @@
+# Visual Techniques for Math Animation
+
+Effective visualization patterns for explaining mathematical concepts, derived from 400+ 3b1b video source files (2015-2026).
+
+---
+
+## Core Principles
+
+### 1. Progressive Disclosure
+Never show everything at once. Build complexity gradually.
+
+**Bad:** Show complete equation immediately
+**Good:** Build equation term by term, explaining each part
+
+```
+Scene flow:
+1. Show simple case: f(x) = x^2
+2. Add complexity: f(x) = ax^2
+3. Full form: f(x) = ax^2 + bx + c
+```
+
+**Real example -- CLT `BuildUpGaussian`** (`_2023/clt/main.py`):
+1. Start with e^(-x^2)
+2. Add the 1/sqrt(2*pi) normalization
+3. Add the sigma parameter
+4. Full Gaussian formula
+
+### 2. Transform, Don't Replace
+When possible, morph objects into new forms rather than fading out/in.
+
+**Bad:** `FadeOut(equation1)`, `FadeIn(equation2)`
+**Good:** `TransformMatchingTex(equation1, equation2)`
+
+This maintains visual continuity and shows the relationship between forms.
+
+**From `_2023/clt_proof/main.py`:**
+```python
+self.play(TransformMatchingTex(eq1, eq2, matched_keys=[R"e^{tx}"]))
+```
+
+**The `matched_keys` parameter** explicitly tells which substrings to match, ensuring smooth morphing of the right terms.
+
+### 3. Color as Meaning
+Use color consistently to encode meaning throughout the video.
+
+**3b1b Default Palette:**
+- Background: #1C1C1C (dark grey) -- `GREY_E` or darker
+- Primary: #58C4DD (blue) -- `BLUE` or `BLUE_C`
+- Secondary: #83C167 (green) -- `GREEN`
+- Accent: #FFFF00 (yellow) -- `YELLOW`
+- Warning: #FF6666 (red) -- `RED`
+
+**Domain-specific color conventions:**
+
+| Domain | Convention | Source |
+|--------|-----------|--------|
+| Linear algebra | i-hat=GREEN, j-hat=RED, vector v=YELLOW | EoLA (2016) |
+| Calculus | Input=BLUE, output=GREEN, nudge dx=GREEN, df=YELLOW | EoC (2017) |
+| Probability | Favorable=GREEN, unfavorable=RED, Gaussian=YELLOW | CLT (2023) |
+| Laplace | Time t=BLUE, frequency s=YELLOW | Laplace (2025) |
+| Number theory | Primes=YELLOW | Zeta (2016, 2022) |
+| Epidemiology | Susceptible=BLUE, Infected=RED, Recovered=GREEN | SIR (2020) |
+| ML/Transformers | Positive weights=BLUE gradient, negative=RED gradient | Transformers (2024) |
+
+**Implementation via `t2c`:**
+```python
+formula = Tex(
+    R"f({t}) = \int e^{-{s}t} dt",
+    t2c={"{t}": BLUE, "{s}": YELLOW}
+)
+```
+
+### 4. Spatial Relationships
+Position encodes relationships:
+- Left-to-right: transformation, time, causation
+- Top-to-bottom: hierarchy, derivation
+- Center: focus of attention
+- Periphery: context, reference
+
+**Commutative diagram layout** (`_2025/laplace/derivatives.py`):
+```python
+terms.arrange_in_grid(h_buff=2.0, v_buff=3.0, fill_rows_first=False)
+# Top-left: f(t)      Top-right: F(s)
+# Bottom-left: f'(t)  Bottom-right: sF(s) - f(0)
+# Horizontal arrows: Laplace transform
+# Vertical arrows: differentiation / multiplication by s
+```
+
+---
+
+## Animation Techniques
+
+### Highlighting & Focus
+
+**`Indicate`** -- Brief flash to draw attention
+```python
+self.play(Indicate(term))
+```
+
+**`Circumscribe`** -- Circle around important element
+```python
+self.play(Circumscribe(equation, color=YELLOW))
+```
+
+**`FlashAround`** -- Dramatic attention on revelation (the "aha" animation)
+```python
+self.play(FlashAround(result))
+```
+
+**`SurroundingRectangle`** -- Box that stays (useful for quiz-style reveals)
+```python
+rect = SurroundingRectangle(term, color=YELLOW, buff=0.1)
+self.play(ShowCreation(rect))
+```
+
+**`Brace`** -- Point to a sub-expression with label
+```python
+brace = Brace(expression[3:7], DOWN)
+label = brace.get_text("this part")
+self.play(GrowFromCenter(brace), Write(label))
+```
+
+### Equation Manipulation
+
+**Isolate terms** -- Color or move specific parts
+```python
+equation.set_color_by_tex("x", BLUE)
+```
+
+**Step-by-step derivation** -- Show each algebraic step
+```python
+step1 = Tex(R"2x + 4 = 10")
+step2 = Tex(R"2x = 6")
+step3 = Tex(R"x = 3")
+self.play(TransformMatchingTex(step1, step2))
+self.wait(2)
+self.play(TransformMatchingTex(step2, step3))
+```
+
+**Substitution** -- Show value being plugged in
+```python
+# Animate the number moving into the variable's position
+value = Tex("3", color=BLUE)
+value.move_to(variable)
+self.play(FadeTransform(variable, value))
+```
+
+**Dynamic number 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()))
+```
+
+### Geometric Intuition
+
+**Coordinate systems** -- Always label axes
+```python
+axes = Axes(x_range=[-3, 3], y_range=[-2, 2])
+labels = axes.get_axis_labels(x_label="x", y_label="f(x)")
+```
+
+**Trace paths** -- Show how points move
+```python
+trace = TracedPath(dot.get_center, stroke_color=YELLOW)
+```
+
+**Area visualization** -- For integrals, sums
+```python
+area = axes.get_area(graph, x_range=[a, b], color=BLUE, opacity=0.5)
+```
+
+**Riemann rectangles with progressive refinement:**
+```python
+rects = axes.get_riemann_rectangles(graph, dx=0.1)
+for new_dx in [0.05, 0.01]:
+    new_rects = axes.get_riemann_rectangles(graph, dx=new_dx)
+    self.play(Transform(rects, new_rects))
+```
+
+**ValueTracker for interactive parameters:**
+```python
+tracker = ValueTracker(0.5)
+graph = always_redraw(lambda: axes.get_graph(
+    lambda x: func(x, tracker.get_value())
+))
+self.play(tracker.animate.set_value(2.0), run_time=3)
+```
+
+### 3D Techniques
+
+**Camera orbiting** -- Reveal 3D structure
+```python
+frame = self.frame
+frame.reorient(-40, 70, 0)  # theta, phi, gamma
+self.play(frame.animate.reorient(60, 50, 0), run_time=5)
+```
+
+**Field of view** for depth perception:
+```python
+frame.set_field_of_view(20 * DEGREES)
+```
+
+**Ambient rotation** for continuous motion:
+```python
+frame.add_updater(lambda m, dt: m.increment_theta(-0.1 * dt))
+```
+
+**Textured surfaces** for realistic objects:
+```python
+earth = TexturedSurface(Sphere(radius=r), "EarthTextureMap", "NightEarthTextureMap")
+```
+
+**Surface mesh** for mathematical surfaces:
+```python
+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, resolution=(21, 21))
+```
+
+**Clip planes** for cross-sections:
+```python
+surface.set_clip_plane(IN, 0)
+self.play(surface.animate.set_clip_plane(IN, radius))
+```
+
+**Depth sorting:**
+```python
+body.sort(lambda p: np.dot(p, [-1, 1, 1]))
+sphere.always_sort_to_camera(self.camera)
+```
+
+**Floor plane for grounding 3D scenes:**
+```python
+self.set_floor_plane("xz")
+self.camera.light_source.move_to([-5, 5, 10])
+```
+
+### Composite Animations
+
+**LaggedStartMap** -- Sequential group reveal (the workhorse):
+```python
+self.play(LaggedStartMap(FadeIn, group, lag_ratio=0.1))
+self.play(LaggedStartMap(ShowCreation, arrows, lag_ratio=0.5))
+```
+
+**LaggedStart** -- Staggered individual animations:
+```python
+self.play(LaggedStart(
+    stds[1].says("But why?", mode="sassy"),
+    stds[0].change('confused'),
+    morty.change("guilty"),
+    lag_ratio=0.3
+))
+```
+
+**AnimationGroup** -- Simultaneous with different timings:
+```python
+self.play(AnimationGroup(
+    ShowCreation(arrow),
+    MoveToTarget(dot, rate_func=rush_into),
+    numberline.numbers[n].animate.set_color(YELLOW),
+))
+```
+
+**`time_span` for staggered timing within one play() call:**
+```python
+# From _2022/zeta/part1.py
+anims.append(self.get_prime_animation(
+    numberline, n,
+    run_time=11,
+    time_span=(t, t + 1)  # Each prime appears at a different time
+))
+self.play(*anims)
+```
+
+**VShowPassingFlash** -- Flowing attention:
+```python
+self.play(VShowPassingFlash(arc, time_width=2))
+```
+
+**VFadeInThenOut** -- Temporary element:
+```python
+self.play(VFadeInThenOut(arrow))
+```
+
+---
+
+## Common Visual Metaphors
+
+### Vectors as Arrows
+- Position vectors: arrows from origin (GREEN for i-hat, RED for j-hat)
+- Addition: tip-to-tail
+- Scaling: stretching/shrinking
+
+### Functions as Machines
+- MachineWithDials from Transformers series
+- Input goes in one side, output comes out
+- Dials represent tunable parameters
+
+### Matrices as Transformations
+- Show grid being transformed (NumberPlane + apply_matrix)
+- Track where basis vectors go
+- Emphasize determinant as area scaling
+
+### Derivatives as Slopes / Nudges
+- Tangent line touching curve
+- Zoom in to show local linearity
+- "Nudge" dx creates resulting df
+
+### Integrals as Accumulation
+- Riemann sums with rectangles
+- Width -> 0 animation
+- Area filling under curve
+- Slider for moving upper bound
+
+### Probability as Population Frequency
+- Grid of dots/people
+- Color subsets by property
+- Count directly: no formulas needed
+
+### Attention as Arcs Between Tokens
+- From `_2024/transformers/`:
+- Curved arcs connecting token positions
+- Width/color encode attention weight
+- Flow animation with VShowPassingFlash
+
+### Optimization as Landscape
+- Function as 3D surface
+- Gradient descent as ball rolling downhill
+- Local minima as valleys
+
+---
+
+## Scene Composition Layouts
+
+### The Golden Layout (Default)
+```
++------------------------------------+
+|           TITLE/CONTEXT            |  (top edge, small)
++------------------------------------+
+|                                    |
+|      MAIN VISUALIZATION           |  (center, largest area)
+|                                    |
++------------------------------------+
+|    EQUATION / FORMULA              |  (bottom third)
++------------------------------------+
+```
+
+### Side-by-Side Comparison
+```
++----------------+----------------+
+|   CONCEPT A /  |   CONCEPT B /  |
+|   BEFORE /     |   AFTER /      |
+|   TIME DOMAIN  |   FREQ DOMAIN  |
++----------------+----------------+
+```
+Use `FullScreenRectangle().stretch(0.5, 0)` with tinted fill for domain coloring.
+
+### Phase Space Dual View
+```
++------------------------------------+
+|  PHYSICAL SYSTEM  |  PHASE SPACE  |
+|  (simulation)     |  (portrait)   |
++------------------------------------+
+```
+Linked via updaters.
+
+### Zoomed Detail
+```
++------------------------------------+
+|  +--------+                       |
+|  | ZOOM   | <-- magnified detail  |
+|  +--------+                       |
+|         Main context              |
++------------------------------------+
+```
+Use `frame.animate.set_height(smaller)` + `frame.animate.move_to(target)`.
+
+### Stacked Derivation
+```
++------------------------------------+
+|    Step 1: equation                |
+|         ||                         |
+|    Step 2: equation                |
+|         ||                         |
+|    Step 3: equation (highlight!)   |
++------------------------------------+
+```
+Use `TransformMatchingTex` between steps, `SurroundingRectangle` on final result.
+
+---
+
+## Timing Guidelines
+
+| Action | Typical Duration |
+|--------|------------------|
+| Simple shape creation (FadeIn) | 0.5-1s |
+| Text/equation writing (Write) | 1-2s |
+| Shape transformation (Transform) | 1-2s |
+| Equation morphing (TransformMatchingTex) | 1-2s |
+| Grid transformation (apply_matrix) | 2-3s |
+| Camera movement (3D reorient) | 3-5s |
+| Camera zoom (set_height) | 2-3s |
+| Pause for absorption | 1-3s |
+| Complex animation (LaggedStartMap) | 3-5s |
+| Opening quote author write | 4-5s |
+| FlashAround (aha moment) | 0.5-1s |
+
+### Rhythm Pattern
+Fast-fast-SLOW-fast-fast-SLOW
+
+Quick animations for setup, slow down for key insights. The longest waits come after the most significant reveals.
+
+---
+
+## Readability Techniques
+
+### Backstroke for Text Over Complex Backgrounds
+```python
+text.set_backstroke(BLACK, 5)
+```
+Essential when text overlays a colorful scene.
+
+### GlowDot for Points of Interest
+```python
+dot = GlowDot(point, color=YELLOW, radius=0.2)
+```
+Creates a soft glow around a point, drawing attention without harsh edges.
+
+### Gradient Coloring for Ordered Sets
+```python
+bars.set_submobject_colors_by_gradient(BLUE, GREEN)
+# or
+bars.set_submobject_colors_by_gradient(TEAL, YELLOW)
+```
+
+### HSL Interpolation for Smooth Color Transitions
+```python
+color = interpolate_color_by_hsl(TEAL, RED, alpha)
+```
+
+---
+
+## Color Palettes
+
+### Classic 3b1b
+- Background: #1C1C1C (dark grey)
+- Primary: #58C4DD (blue)
+- Secondary: #83C167 (green)
+- Accent: #FFFF00 (yellow)
+- Warning: #FF6666 (red)
+- Text: #FFFFFF (white)
+
+### Laplace Transform
+- Time domain: BLUE
+- Frequency domain: YELLOW
+- Background: standard dark
+
+### Transformers / ML
+- Positive values: BLUE gradient (BLUE_E to BLUE_B)
+- Negative values: RED gradient (RED_E to RED_B)
+- Highlighted/selected: TEAL or YELLOW
+- Token rectangles: pastel variants
+
+### Fourier / Signal Processing
+- Time domain: standard colors
+- Frequency domain ("Fourier Land"): TEAL-tinted background
+- Individual frequencies: spectral rainbow
+
+### Phase-Based (Complex Analysis)
+```python
+def z_to_color(z, sat=0.5, lum=0.5):
+    angle = math.atan2(z.imag, z.real)
+    return Color(hsl=(angle / TAU, sat, lum))
+```
+Maps complex phase angle to hue, creating rainbow-colored complex function plots.

package/references/composer/templates/scenes-template.md

@@ -0,0 +1,147 @@
+# [Video Title]
+
+## Overview
+- **Topic**: [Core mathematical/scientific concept]
+- **Hook**: [Opening question or mystery that draws viewers in]
+- **Target Audience**: [Prerequisites - what math/science background is assumed]
+- **Estimated Length**: [X minutes]
+- **Key Insight**: [The central "aha moment" - the one thing viewers should remember]
+
+## Narrative Arc
+[2-3 sentences describing the emotional and intellectual journey. Example: "We start with a puzzling observation, investigate why it's true, and discover a beautiful underlying principle that connects seemingly different ideas."]
+
+---
+
+## Scene 1: [Scene Name]
+**Duration**: ~X seconds
+**Purpose**: [What this scene accomplishes in the overall narrative]
+
+### Visual Elements
+- [Mobject 1: description, color, position]
+- [Mobject 2: description, color, position]
+- [Animation sequence]
+- [Camera movements if any]
+
+### Content
+[Detailed description of what happens visually and conceptually. Be specific enough that someone could implement this scene.]
+
+### Narration Notes
+[Key points to convey, suggested tone, pacing. Not a full script, but guidance.]
+
+### Technical Notes
+- [Specific Manim classes to use]
+- [Tricky implementations or gotchas]
+- [Dependencies on previous scenes]
+
+---
+
+## Scene 2: [Scene Name]
+**Duration**: ~X seconds
+**Purpose**: [Purpose]
+
+### Visual Elements
+- [List elements]
+
+### Content
+[Description]
+
+### Narration Notes
+[Notes]
+
+### Technical Notes
+- [Notes]
+
+---
+
+## Scene 3: [Scene Name]
+**Duration**: ~X seconds
+**Purpose**: [Purpose]
+
+### Visual Elements
+- [List elements]
+
+### Content
+[Description]
+
+### Narration Notes
+[Notes]
+
+### Technical Notes
+- [Notes]
+
+---
+
+[Add more scenes as needed]
+
+---
+
+## Transitions & Flow
+
+### Scene Connections
+- Scene 1 → Scene 2: [How they connect, what carries over visually]
+- Scene 2 → Scene 3: [Connection]
+- [Continue for all transitions]
+
+### Recurring Visual Motifs
+- [Element that appears throughout, providing continuity]
+- [Color or shape that reinforces key concept]
+
+---
+
+## Color Palette
+
+| Role | Color | Hex | Usage |
+|------|-------|-----|-------|
+| Primary | [e.g., Blue] | #58C4DD | [Main objects, key terms] |
+| Secondary | [e.g., Green] | #83C167 | [Results, outputs] |
+| Accent | [e.g., Yellow] | #FFFF00 | [Highlights, emphasis] |
+| Warning | [e.g., Red] | #FF6666 | [Errors, negatives] |
+| Background | [e.g., Dark grey] | #1C1C1C | [Scene background] |
+
+---
+
+## Mathematical Content
+
+### Equations to Render
+1. `[LaTeX equation 1]` - used in Scene X
+2. `[LaTeX equation 2]` - used in Scene Y
+3. [Continue...]
+
+### Graphs/Plots
+1. [Function 1]: domain, key features
+2. [Function 2]: domain, key features
+
+### Geometric Objects
+1. [Object]: properties, how it transforms
+2. [Continue...]
+
+---
+
+## Implementation Order
+
+Suggested order for building scenes (accounting for dependencies):
+
+1. **[Scene name]** - [Why first: standalone, establishes base objects]
+2. **[Scene name]** - [Dependency notes]
+3. **[Scene name]** - [Dependency notes]
+4. [Continue...]
+
+### Shared Components
+Objects or code that should be defined once and reused:
+- [Component 1]: used in Scenes X, Y, Z
+- [Component 2]: used in Scenes A, B
+
+---
+
+## Open Questions / Decisions Needed
+
+- [ ] [Question about scope, implementation, or creative direction]
+- [ ] [Another decision point]
+
+---
+
+## Reference Material
+
+- [Link or citation to source material]
+- [Inspiration videos or images]
+- [Academic papers if relevant]