Visual Storyteller

Visual Storyteller Skill

The Visual Storyteller transforms explanations and processes into engaging visual narratives that build understanding progressively.

Storytelling Framework

The CLEAR Method

• Context: Establish what we're exploring
• Layers: Build complexity gradually
• Examples: Show concrete instances
• Analogies: Connect to familiar concepts
• Reinforce: Summarize key insights

Narrative Arc for Explanations

1. Hook (Why should I care?)
   ↓
2. Setup (What do I need to know?)
   ↓
3. Rising Action (Build understanding step by step)
   ↓
4. Climax (The "aha!" moment)
   ↓
5. Resolution (How does this connect to the bigger picture?)

Rules

rules/progressive-revelation.md

Show information piece by piece, never overwhelming the viewer.

rules/visual-metaphors.md

Use relatable visual metaphors to explain abstract concepts.

rules/pacing-for-understanding.md

Allow time for concepts to sink in before moving forward.

rules/emphasis-techniques.md

Highlight key elements using color, size, and animation.

Templates

Concept Explanation

from manim import *

class ConceptExplanation(Scene):
    def construct(self):
        # Hook: Pose an intriguing question
        question = Text("Why does this happen?", color=YELLOW)
        self.play(Write(question))
        self.wait(2)
        self.play(FadeOut(question))

        # Setup: Introduce the elements
        elements = self.introduce_elements()

        # Rising Action: Build step by step
        for i, step in enumerate(self.get_steps()):
            step_label = Text(f"Step {i+1}", font_size=24).to_corner(UL)
            self.play(FadeIn(step_label))
            self.demonstrate_step(step, elements)
            self.play(FadeOut(step_label))

        # Climax: The revelation
        self.play(Indicate(elements, scale_factor=1.2, color=GREEN))
        insight = Text("And that's why!", color=GREEN)
        self.play(Write(insight))

        # Resolution: Connect to bigger picture
        self.play(FadeOut(insight), FadeOut(elements))
        summary = self.create_summary()
        self.play(FadeIn(summary))

Process Walkthrough

from manim import *

class ProcessWalkthrough(Scene):
    def construct(self):
        # Title
        title = Text("How X Works").scale(1.2)
        self.play(Write(title))
        self.play(title.animate.to_edge(UP).scale(0.6))

        # Create process diagram
        steps = VGroup(*[
            self.create_step_box(f"Step {i+1}", desc)
            for i, desc in enumerate(self.step_descriptions)
        ]).arrange(RIGHT, buff=1)

        # Progressive revelation
        for i, step in enumerate(steps):
            self.play(FadeIn(step, shift=UP))
            self.wait(0.5)

            # Highlight current step
            self.play(step.animate.set_color(YELLOW))
            self.demonstrate_step_detail(i)
            self.play(step.animate.set_color(WHITE))

            # Draw arrow to next step
            if i < len(steps) - 1:
                arrow = Arrow(step.get_right(), steps[i+1].get_left())
                self.play(Create(arrow))

Comparison/Contrast

from manim import *

class ComparisonScene(Scene):
    def construct(self):
        # Split screen
        line = Line(UP * 3, DOWN * 3)
        self.play(Create(line))

        # Left side: Concept A
        left_title = Text("Without X").to_edge(UP).shift(LEFT * 3)
        left_demo = self.create_without_x().shift(LEFT * 3)

        # Right side: Concept B
        right_title = Text("With X").to_edge(UP).shift(RIGHT * 3)
        right_demo = self.create_with_x().shift(RIGHT * 3)

        # Show side by side
        self.play(Write(left_title), Write(right_title))
        self.play(Create(left_demo), Create(right_demo))

        # Animate differences
        self.highlight_differences(left_demo, right_demo)

        # Conclusion
        self.play(FadeOut(line), FadeOut(left_demo), FadeOut(left_title))
        self.play(right_demo.animate.move_to(ORIGIN))
        conclusion = Text("X makes the difference!", color=GREEN).next_to(right_demo, DOWN)
        self.play(Write(conclusion))

Emphasis Techniques

Color Highlighting

# Fade everything except the focus
self.play(
    other_elements.animate.set_opacity(0.3),
    focus_element.animate.set_color(YELLOW)
)

Scale Emphasis

# Grow important element
self.play(important.animate.scale(1.5))

Indicator Animation

# Pulse attention
self.play(Indicate(element, color=RED))

Surrounding Highlight

# Circle the important part
circle = Circle(color=YELLOW).surround(element)
self.play(Create(circle))

Pacing Guidelines

Best Practices

1. One idea at a time - Don't introduce multiple concepts simultaneously 2. Build on prior knowledge - Connect new ideas to what's already shown 3. Use consistent visual language - Same colors/shapes for same concepts 4. Allow breathing room - Silence and stillness aid comprehension 5. End with synthesis - Bring everything together at the conclusion

Community Edition Implementation Patterns

Best practices for implementing animations with the Manim Community Edition renderer.

Import Patterns

# Standard import (recommended)
from manim import *

# Selective imports for clarity
from manim import Scene, Circle, Square, Write, FadeIn, MathTex

Scene Types

Standard Scene

class MyAnimation(Scene):
    def construct(self):
        circle = Circle()
        self.play(Create(circle))
        self.wait()

3D Scene

class My3DAnimation(ThreeDScene):
    def construct(self):
        self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)
        sphere = Sphere()
        self.play(Create(sphere))

Moving Camera Scene

class CameraAnimation(MovingCameraScene):
    def construct(self):
        circle = Circle()
        self.play(Create(circle))
        self.play(self.camera.frame.animate.scale(0.5).move_to(circle))

Core Animations

Creation Animations

Transformation Animations

Exit Animations

LaTeX Rendering

Basic Math

# Simple equation
eq = MathTex("E = mc^2")

# With color isolation
eq = MathTex("E", "=", "m", "c^2")
eq[0].set_color(YELLOW)  # E
eq[3].set_color(BLUE)    # c^2

Using substrings_to_isolate

eq = MathTex(
    "x^2 + 2x + 1 = 0",
    substrings_to_isolate=["x", "1", "0"]
)
eq.set_color_by_tex("x", BLUE)
eq.set_color_by_tex("1", GREEN)

Text with Math

text = Tex("The area is ", "$A = \\pi r^2$")

CLI Usage

# Preview with low quality (fast)
manim -pql script.py SceneName

# Preview with medium quality
manim -pqm script.py SceneName

# High quality render
manim -pqh script.py SceneName

# 4K render
manim -pqk script.py SceneName

# Save last frame as image
manim -pql -s script.py SceneName

# Transparent background
manim -pql -t script.py SceneName

Quality Presets

Debugging Techniques

Visual Debugging

# Add without animation (instant)
self.add(circle)

# Show bounding box
circle.add(SurroundingRectangle(circle))

# Add coordinate labels
self.add(NumberPlane())

Print Debugging

def construct(self):
    circle = Circle()
    print(f"Circle center: {circle.get_center()}")
    print(f"Circle radius: {circle.radius}")
    print(f"Circle color: {circle.get_color()}")

Interactive Mode

# Pause and inspect
self.wait()
self.interactive_embed()  # Opens interactive shell

Animation Timing

Run Time Control

self.play(Create(circle), run_time=2)  # 2 seconds
self.play(FadeIn(square), run_time=0.5)  # Fast

Simultaneous Animations

# All at once
self.play(Create(circle), Write(text), FadeIn(square))

# With AnimationGroup
self.play(AnimationGroup(
    Create(circle),
    Write(text),
    lag_ratio=0.5  # Stagger start times
))

Sequential with Succession

self.play(Succession(
    Create(circle),
    circle.animate.shift(RIGHT),
    FadeOut(circle)
))

Common Patterns

Animate Method

# Fluent animation syntax
self.play(circle.animate.shift(RIGHT).scale(2).set_color(RED))

Value Tracking

tracker = ValueTracker(0)
number = always_redraw(lambda: DecimalNumber(tracker.get_value()))
self.play(tracker.animate.set_value(100), run_time=3)

Updaters

dot = Dot()
label = always_redraw(lambda: Text(f"({dot.get_x():.1f}, {dot.get_y():.1f})").next_to(dot, UP))
self.add(dot, label)
self.play(dot.animate.shift(RIGHT * 3))

Anti-Patterns

Avoid

# Don't modify mobjects during play
self.play(Create(circle))
circle.shift(RIGHT)  # Wrong - not animated

# Don't forget to add mobjects
text = Text("Hello")
self.play(text.animate.shift(UP))  # Error - text not added

Prefer

# Animate changes
self.play(Create(circle))
self.play(circle.animate.shift(RIGHT))  # Correct

# Add before animating
text = Text("Hello")
self.add(text)
self.play(text.animate.shift(UP))  # Or use FadeIn

Emphasis Techniques

The Emphasis Hierarchy

From subtle to strong: 1. Position - Center stage = important 2. Size - Larger = more important 3. Color - Bright/contrast = attention 4. Animation - Movement catches eye 5. Isolation - Remove distractions

Position-Based Emphasis

Center Stage

# Most important element at center
key_element.move_to(ORIGIN)
supporting.to_edge(LEFT)
context.to_edge(RIGHT)

Golden Ratio Positioning

# Professional composition
# Place key elements at 1/3 and 2/3 points
left_focus = LEFT * 2.5  # ~1/3 from left
right_focus = RIGHT * 2.5  # ~2/3 from left

Foreground/Background

# Foreground = emphasized
important.set_z_index(10)
background.set_z_index(0)

Size-Based Emphasis

Scale Animation

# Draw attention by scaling
self.play(important.animate.scale(1.5))

# Pulse effect (scale up then back)
self.play(important.animate.scale(1.3))
self.play(important.animate.scale(1/1.3))

Relative Size

# Important elements larger from the start
main_point = Text("Key Concept", font_size=48)
sub_point = Text("Supporting detail", font_size=24)

Color-Based Emphasis

Highlight Colors

# Standard highlight palette
EMPHASIS_PRIMARY = YELLOW
EMPHASIS_SECONDARY = GOLD
EMPHASIS_ALERT = RED
EMPHASIS_SUCCESS = GREEN

Color Change Animation

# Draw attention with color
self.play(element.animate.set_color(YELLOW))

# Gradient emphasis
element.set_color_by_gradient(BLUE, YELLOW)

Dimming Others

# Emphasize by reducing others
all_elements = VGroup(elem1, elem2, elem3, focus_elem)
others = VGroup(elem1, elem2, elem3)

self.play(
    others.animate.set_opacity(0.3),
    focus_elem.animate.set_color(YELLOW)
)

Animation-Based Emphasis

Indicate Animation

# Built-in emphasis animation
self.play(Indicate(element, color=YELLOW, scale_factor=1.2))

Circumscribe (Circle Attention)

# Draw circle around important element
self.play(Circumscribe(element, color=RED, time_width=2))

Flash

# Quick bright flash
self.play(Flash(element.get_center(), color=WHITE))

Wiggle

# Attention-grabbing wiggle
self.play(Wiggle(element))

Focus Frame

# Box around important content
frame = SurroundingRectangle(element, color=YELLOW, buff=0.2)
self.play(Create(frame))

Underline

# Underline key text
underline = Underline(text_element, color=RED)
self.play(Create(underline))

Isolation Emphasis

Clear Everything Else

# Remove distractions
other_elements = [e for e in self.mobjects if e != focus_element]
self.play(*[FadeOut(e) for e in other_elements])
self.wait(2)  # Focus time
self.play(*[FadeIn(e) for e in other_elements])  # Restore

Spotlight Effect

# Dim surroundings, spotlight on focus
def spotlight(scene, focus, others):
    scene.play(
        focus.animate.set_opacity(1),
        *[o.animate.set_opacity(0.2) for o in others]
    )

Zoom Isolation

# Zoom camera to focus element
self.play(
    self.camera.frame.animate.scale(0.5).move_to(focus_element)
)

Combining Techniques

Weak Emphasis (Subtle)

# Just position or small color change
self.play(element.animate.move_to(UP * 0.5))

Medium Emphasis (Notice)

# Position + color
self.play(
    element.animate.move_to(UP * 0.5).set_color(YELLOW)
)

Strong Emphasis (Critical)

# Position + color + size + frame
frame = SurroundingRectangle(element, color=YELLOW)
self.play(
    element.animate.move_to(ORIGIN).scale(1.5).set_color(YELLOW),
    Create(frame)
)

Maximum Emphasis (Climax)

# Everything: isolation + position + color + size + animation
self.play(*[FadeOut(m) for m in self.mobjects if m != element])
self.play(
    element.animate.move_to(ORIGIN).scale(2).set_color(GOLD)
)
self.play(Flash(element.get_center(), color=WHITE, num_lines=12))
self.play(Indicate(element))

When to Use Each Level

Anti-Patterns

DON'T: Emphasize everything

# BAD - Nothing stands out
for elem in all_elements:
    self.play(Indicate(elem))  # Everything is "important"

DON'T: Inconsistent emphasis

# BAD - Confusing signals
self.play(important.animate.scale(0.5))  # Shrinking = less important??
self.play(minor.animate.scale(2))  # Growing = important??

DO: Reserve strong emphasis for key moments

# GOOD - Clear hierarchy
for elem in supporting_elements:
    self.play(FadeIn(elem))  # Normal

self.play(Indicate(key_element, scale_factor=1.5, color=GOLD))  # Emphasis

CLEAR Explanation Framework

A structured approach to creating educational animations that ensure understanding and retention.

The CLEAR Method

Context → Layers → Examples → Analogies → Reinforce

Each component builds upon the previous, creating a complete learning experience.

┌─────────────────────────────────────────────────────────┐
│                     CLEAR Framework                      │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│ Context  │  Layers  │ Examples │ Analogies │  Reinforce │
│   10%    │   40%    │   25%    │    15%    │    10%     │
├──────────┼──────────┼──────────┼──────────┼─────────────┤
│  Setup   │  Build   │  Apply   │  Connect  │  Solidify  │
│  ground  │  step by │  to real │  to known │  the       │
│          │  step    │  cases   │  concepts │  learning  │
└──────────┴──────────┴──────────┴──────────┴─────────────┘

---

C - Context (10% of content)

Purpose

Establish why this matters and what the viewer already knows.

Elements

Implementation Pattern

class ContextScene(Scene):
    def construct(self):
        # Hook - Start with a compelling question
        hook = Text("Why do things fall?", font_size=48)
        self.play(Write(hook))
        self.wait(2)
        
        # Relevance - Connect to their world
        relevance = Text(
            "Understanding gravity explains everything\n"
            "from raindrops to rocket launches",
            font_size=32
        )
        self.play(
            FadeOut(hook),
            FadeIn(relevance)
        )
        self.wait(3)
        
        # Overview - Set expectations
        overview = BulletedList(
            "What gravity is",
            "How Newton discovered it",
            "The universal law",
            font_size=28
        )
        self.play(
            FadeOut(relevance),
            Write(overview)
        )
        self.wait(2)

Context Anti-Patterns

---

L - Layers (40% of content)

Purpose

Build understanding progressively, from simple to complex.

Layering Strategies

1. Additive Layering

Simple concept
    + First detail
        + Second detail
            + Full complexity

2. Zoom-In Layering

Big picture overview
    → Focus on component A
        → Detail of component A
    → Return to big picture
        → Focus on component B

3. Scaffold Layering

Foundation concept
    ↑ builds on
Supporting concept
    ↑ builds on
Target concept

Implementation Pattern

class LayeredExplanation(Scene):
    def construct(self):
        # Layer 1: Simplest form
        simple = MathTex("F = ma")
        self.play(Write(simple))
        self.wait(2)
        
        # Layer 2: Add meaning
        labels = VGroup(
            Text("Force", font_size=24).next_to(simple[0][0], DOWN),
            Text("Mass", font_size=24).next_to(simple[0][2], DOWN),
            Text("Acceleration", font_size=24).next_to(simple[0][4], DOWN),
        )
        self.play(FadeIn(labels))
        self.wait(2)
        
        # Layer 3: Add context
        context = Text(
            "The more massive an object,\n"
            "the more force needed to accelerate it",
            font_size=28
        ).to_edge(DOWN)
        self.play(FadeIn(context))
        self.wait(3)
        
        # Layer 4: Show implications
        self.play(FadeOut(labels), FadeOut(context))
        rearranged = MathTex("a = \\frac{F}{m}")
        self.play(TransformMatchingTex(simple, rearranged))
        self.wait(2)

Pacing Guidelines

---

E - Examples (25% of content)

Purpose

Make abstract concepts concrete through specific instances.

Example Types

Implementation Pattern

class ExampleScene(Scene):
    def construct(self):
        # Set up the example context
        title = Text("Example: Dropping a ball", font_size=36)
        title.to_edge(UP)
        self.play(Write(title))
        
        # Visual setup
        ball = Circle(radius=0.3, fill_opacity=1, color=RED)
        ball.move_to(UP * 2)
        ground = Line(LEFT * 5, RIGHT * 5, color=WHITE)
        ground.move_to(DOWN * 2)
        
        self.play(Create(ball), Create(ground))
        
        # Show the physics
        formula = MathTex("h = \\frac{1}{2}gt^2")
        formula.to_edge(RIGHT)
        self.play(Write(formula))
        
        # Animate the example
        self.play(
            ball.animate.move_to(DOWN * 2 + UP * 0.3),
            run_time=2,
            rate_func=rate_functions.ease_in_quad
        )
        
        # Highlight the connection
        result = Text("t ≈ 0.64 seconds", font_size=28)
        result.next_to(formula, DOWN)
        self.play(Write(result))

Example Selection Criteria

Good examples are:

• Familiar: Use everyday objects/situations
• Simple: Minimal distracting details
• Representative: Capture the core concept
• Memorable: Easy to recall later

---

A - Analogies (15% of content)

Purpose

Connect new concepts to existing mental models.

Analogy Types

Implementation Pattern

class AnalogyScene(Scene):
    def construct(self):
        # Show the unfamiliar concept
        concept = Text("Electric Current", font_size=36)
        concept.to_edge(UP)
        self.play(Write(concept))
        
        # Show the familiar analogy
        analogy = Text("is like", font_size=28)
        familiar = Text("Water Flow", font_size=36)
        
        VGroup(concept, analogy, familiar).arrange(DOWN)
        self.play(Write(analogy), Write(familiar))
        self.wait(1)
        
        # Visual comparison
        self.play(FadeOut(VGroup(concept, analogy, familiar)))
        
        # Left: Water
        pipe = Rectangle(width=4, height=1, color=BLUE)
        pipe.shift(LEFT * 3)
        water = Arrow(LEFT * 1.5, RIGHT * 1.5, color=BLUE)
        water.move_to(pipe)
        water_label = Text("Water", font_size=24).next_to(pipe, DOWN)
        
        # Right: Electricity
        wire = Rectangle(width=4, height=0.3, color=YELLOW)
        wire.shift(RIGHT * 3)
        current = Arrow(LEFT * 1.5, RIGHT * 1.5, color=YELLOW)
        current.move_to(wire)
        current_label = Text("Current", font_size=24).next_to(wire, DOWN)
        
        self.play(
            Create(pipe), Create(wire),
            Create(water), Create(current),
            Write(water_label), Write(current_label)
        )
        self.wait(2)
        
        # Show the mapping
        mapping = VGroup(
            Text("Pressure → Voltage", font_size=24),
            Text("Flow Rate → Current", font_size=24),
            Text("Pipe Width → Resistance", font_size=24),
        ).arrange(DOWN, aligned_edge=LEFT)
        mapping.to_edge(DOWN)
        
        for item in mapping:
            self.play(FadeIn(item, shift=RIGHT * 0.3))
            self.wait(0.5)

Analogy Guidelines

---

R - Reinforce (10% of content)

Purpose

Solidify learning through summary, repetition, and forward connection.

Reinforcement Techniques

Implementation Pattern

class ReinforcementScene(Scene):
    def construct(self):
        # Summary title
        title = Text("Key Takeaways", font_size=48)
        title.to_edge(UP)
        self.play(Write(title))
        
        # Key points
        points = VGroup(
            Text("✓ Gravity pulls objects toward Earth", font_size=28),
            Text("✓ F = mg gives the gravitational force", font_size=28),
            Text("✓ All objects fall at the same rate (in vacuum)", font_size=28),
        ).arrange(DOWN, aligned_edge=LEFT, buff=0.4)
        points.move_to(ORIGIN)
        
        for point in points:
            self.play(FadeIn(point, shift=RIGHT * 0.3))
            self.wait(0.5)
        
        self.wait(2)
        
        # Application teaser
        application = Text(
            "Now you can calculate the fall time\n"
            "of any object from any height!",
            font_size=32,
            color=YELLOW
        ).to_edge(DOWN)
        
        self.play(FadeIn(application))
        self.wait(2)
        
        # Next topic preview
        self.play(FadeOut(VGroup(title, points, application)))
        preview = Text(
            "Next: How does this apply to orbits?",
            font_size=36
        )
        self.play(Write(preview))
        self.wait(2)

Memory Techniques

# The Rule of Three
key_points = [
    "Point one",
    "Point two", 
    "Point three"
]  # Three is optimal for memory

# Repetition with Variation
self.play(Write(concept))  # First exposure
# ... explanation ...
self.play(Indicate(concept))  # Second exposure (different form)
# ... examples ...
self.play(Transform(concept, summary_version))  # Third exposure (summarized)

---

Complete CLEAR Scene Template

class CLEARExplanation(Scene):
    """Complete template following CLEAR framework."""
    
    def construct(self):
        self.context_phase()
        self.layers_phase()
        self.examples_phase()
        self.analogies_phase()
        self.reinforce_phase()
    
    def context_phase(self):
        """10% - Set up the learning."""
        pass  # Implement hook, relevance, prerequisites
    
    def layers_phase(self):
        """40% - Build understanding."""
        pass  # Implement progressive complexity
    
    def examples_phase(self):
        """25% - Concrete instances."""
        pass  # Implement worked examples
    
    def analogies_phase(self):
        """15% - Connect to known."""
        pass  # Implement visual analogies
    
    def reinforce_phase(self):
        """10% - Solidify learning."""
        pass  # Implement summary and callbacks

---

Measuring Effectiveness

Self-Check Questions

After creating a CLEAR explanation:

1. Context: Could someone skip the intro and still follow? 2. Layers: Is there a logical progression? 3. Examples: Are examples relatable? 4. Analogies: Is the analogy simpler than the concept? 5. Reinforce: Will they remember the key points?

Explanation Patterns for Visual Stories

The "What, Why, How" Pattern

Structure

1. What: Define the concept (5-10 seconds) 2. Why: Explain importance/relevance (10-15 seconds) 3. How: Demonstrate mechanics (20-40 seconds)

Example Implementation

def construct(self):
    # WHAT
    title = Text("Recursion")
    definition = Text("A function that calls itself", font_size=24)
    self.play(Write(title))
    self.play(FadeIn(definition))
    self.wait(2)

    # WHY
    self.clear()
    use_cases = BulletedList(
        "Solve complex problems simply",
        "Tree traversal",
        "Mathematical sequences"
    )
    self.play(Write(use_cases))
    self.wait(3)

    # HOW
    self.clear()
    # ... demonstration animation

The "Problem → Solution" Pattern

Structure

1. Present the problem visually 2. Show failed/naive approaches (optional) 3. Introduce the solution 4. Demonstrate why it works

Visual Cues

• Problem: Red highlights, question marks
• Struggle: Shaking, confusion animations
• Solution: Green highlights, checkmarks
• Success: Celebration effects

The "Build-Up" Pattern

Layer-by-Layer Construction

# Start simple
base = Square()
self.play(Create(base))

# Add complexity
addition1 = Circle().next_to(base, UP)
self.play(Create(addition1))

# Show relationship
connection = Arrow(base, addition1)
self.play(Create(connection))

# Reveal full picture
label = Text("Complete System")
self.play(Write(label))

The "Comparison" Pattern

Side-by-Side Analysis

• Show two approaches simultaneously
• Highlight differences with color
• Animate parallel processes
• Conclude with clear winner/summary

The "Zoom" Pattern

Macro to Micro

# Start with big picture
overview = ImageMobject("full_system.png")
self.play(FadeIn(overview))

# Zoom to detail
self.play(
    overview.animate.scale(3).shift(LEFT * 2 + UP),
    run_time=2
)

# Highlight specific part
highlight = Circle(color=YELLOW).move_to(...)
self.play(Create(highlight))

Micro to Macro

• Start with detail
• Pull back to show context
• Connect to larger system

Transition Phrases (Visual)

Visual Storytelling Principles

Narrative Structure

Three-Act Structure

1. Setup - Introduce the problem or question 2. Confrontation - Explore the concept, show challenges 3. Resolution - Reveal the answer, demonstrate understanding

Story Arc Elements

• Hook: Grab attention in first 3 seconds
• Build: Gradually increase complexity
• Climax: The "aha moment"
• Denouement: Reinforce the lesson

Visual Metaphors

Abstract → Concrete

Transform abstract concepts into tangible visuals:

• Numbers → Objects (5 apples, not "5")
• Growth → Expanding shapes
• Connection → Lines/arrows between elements
• Time → Left-to-right progression

Color as Emotion

Pacing for Storytelling

Emotional Beats

# Tension building
self.play(obj.animate.scale(1.2), run_time=2)
self.wait(0.5)  # Pause for effect

# Release/resolution
self.play(
    obj.animate.set_color(GREEN),
    Flash(obj),
    run_time=0.5
)

Rhythm Patterns

• Quick-quick-slow for emphasis
• Consistent rhythm for procedural content
• Irregular rhythm for dramatic effect

Character/Object Consistency

Visual Identity

• Keep consistent colors for recurring elements
• Use similar animation styles for related objects
• Establish visual "characters" early

Transformation Rules

• Show intermediate states during morphs
• Maintain recognizable features when transforming
• Use anticipation before major changes

Techniques

Reveal Strategies

# Progressive reveal
for part in parts:
    self.play(FadeIn(part))
    self.wait(0.3)

# Dramatic reveal
self.play(
    FadeOut(cover),
    GrowFromCenter(hidden_element)
)

# Focus reveal (blur surroundings)
self.play(
    element.animate.set_opacity(1),
    *[other.animate.set_opacity(0.2) for other in others]
)

Emphasis Techniques

• Scale up important elements
• Add glow or highlight
• Isolate from other elements
• Use contrasting colors

Avoid

• Information overload
• Inconsistent visual language
• Abrupt topic changes
• Missing context or setup

OpenGL Renderer Implementation Patterns

Best practices for implementing animations with the OpenGL-based renderer (alternative to Cairo).

Key Differences from Community Edition

Import Patterns

# Standard import for OpenGL renderer
from manimlib import *

# Note: Different package name

Interactive Development

Starting Interactive Mode

# Run with interactive embed
manimgl script.py SceneName -se

# The -se flag enables:
# - Pausing at self.embed() calls
# - Live code execution
# - Real-time mobject inspection

Using embed()

class InteractiveScene(Scene):
    def construct(self):
        circle = Circle()
        self.play(ShowCreation(circle))
        
        # Pause here for interactive exploration
        self.embed()
        
        # Continue after exiting embed
        self.play(circle.animate.shift(RIGHT))

Checkpoint Workflow

def construct(self):
    # Create initial state
    circle = Circle()
    self.play(ShowCreation(circle))
    
    # Save checkpoint
    self.checkpoint_paste()  # Copy current state
    
    # Experiment from here
    self.play(circle.animate.scale(2))

LaTeX with Color Coding

Using t2c Parameter

# t2c = "tex to color" dictionary
equation = Tex(
    "E = mc^2",
    t2c={
        "E": YELLOW,
        "m": GREEN,
        "c": BLUE
    }
)

Complex Color Mapping

# Multiple characters with same color
formula = Tex(
    "\\frac{d}{dx}[x^n] = nx^{n-1}",
    t2c={
        "x": BLUE,
        "n": RED,
        "d": GREEN,
        "dx": GREEN
    }
)

Isolating Substrings

# For transformation matching
eq1 = Tex("x^2", " + ", "2x", " + ", "1")
eq2 = Tex("(x + 1)^2")

# Color individual parts
eq1[0].set_color(BLUE)   # x^2
eq1[2].set_color(GREEN)  # 2x

Camera Control

Frame-Based Control

class CameraScene(Scene):
    def construct(self):
        circle = Circle()
        self.play(ShowCreation(circle))
        
        # Access frame directly (not self.camera.frame)
        self.play(self.frame.animate.scale(0.5))
        self.play(self.frame.animate.move_to(circle))

3D Camera Orientation

class My3DScene(Scene):
    def construct(self):
        # No special 3D scene class needed
        surface = Surface(lambda u, v: [u, v, u*v])
        self.play(ShowCreation(surface))
        
        # Reorient camera
        self.play(self.frame.animate.reorient(45, 60))
        
        # Camera parameters: theta (rotation), phi (elevation)

Camera Movements

# Pan
self.play(self.frame.animate.shift(RIGHT * 2))

# Zoom
self.play(self.frame.animate.scale(0.5))  # Zoom in
self.play(self.frame.animate.scale(2))    # Zoom out

# Combined
self.play(
    self.frame.animate
        .move_to(target)
        .scale(0.3)
        .reorient(30, 45)
)

Animation Syntax

ShowCreation (not Create)

# Correct for OpenGL renderer
self.play(ShowCreation(circle))

# NOT Create(circle) - that's Community Edition

Other Animation Differences

# These work the same
self.play(Write(text))
self.play(FadeIn(mobject))
self.play(Transform(a, b))

# Animate method works the same
self.play(circle.animate.shift(RIGHT).scale(2))

3D Without Special Classes

class Simple3D(Scene):
    def construct(self):
        # 3D objects work in regular Scene
        axes = ThreeDAxes()
        sphere = Sphere(radius=1)
        
        self.play(ShowCreation(axes))
        self.play(ShowCreation(sphere))
        
        # Camera reorientation
        self.play(self.frame.animate.reorient(60, 70))
        
        # Continuous rotation
        self.frame.add_updater(lambda m, dt: m.increment_theta(0.1 * dt))
        self.wait(5)

Debugging in Interactive Mode

Inspecting Mobjects

def construct(self):
    circle = Circle()
    self.add(circle)
    self.embed()
    
    # In interactive mode, you can:
    # >>> circle.get_center()
    # >>> circle.set_color(RED)
    # >>> self.play(circle.animate.scale(2))

Real-Time Modifications

# While in embed(), you can:
# - Create new mobjects
# - Run animations
# - Test transformations
# - Adjust colors and positions

Performance Optimizations

GPU Acceleration

# OpenGL renderer leverages GPU for:
# - Shader-based rendering
# - Real-time preview
# - Smooth 3D rotations

Efficient Updates

# Use always_redraw for dynamic content
graph = always_redraw(lambda: FunctionGraph(
    lambda x: np.sin(x + tracker.get_value()),
    x_range=[-PI, PI]
))

Common Patterns

Interactive Workflow

# 1. Start with interactive flag
manimgl script.py MyScene -se

# 2. Scene runs until embed()
# 3. Test changes in Python shell
# 4. Type 'exit()' to continue
# 5. Iterate on code

Rapid Prototyping

class Prototype(Scene):
    def construct(self):
        # Quick setup
        self.play(ShowCreation(Circle()))
        
        # Pause to experiment
        self.embed()
        
        # Continue with refined version

Anti-Patterns

Avoid

# Don't use Create() - use ShowCreation()
self.play(Create(circle))  # Wrong for OpenGL

# Don't use self.camera.frame
self.play(self.camera.frame.animate.scale(0.5))  # Wrong

Prefer

# Use ShowCreation()
self.play(ShowCreation(circle))  # Correct

# Use self.frame directly
self.play(self.frame.animate.scale(0.5))  # Correct

Pacing for Understanding

The Learning Curve Principle

Viewers need time to: 1. See the visual (0.5s minimum) 2. Read any text (varies) 3. Process the meaning (1-3s) 4. Connect to prior knowledge (0.5-1s)

Pacing by Content Type

New Concepts (Slow)

# Introducing something unfamiliar
new_concept = Text("Recursion: A function calling itself")
self.play(Write(new_concept), run_time=2)
self.wait(3)  # Long pause for processing

# Support with example
example = Code("def f(): return f()")
self.play(FadeIn(example))
self.wait(2)

Familiar Concepts (Medium)

# Building on known knowledge
familiar = Text("Like the factorial function...")
self.play(Write(familiar), run_time=1)
self.wait(1.5)

Reinforcement (Fast)

# Repeating what viewer already saw
reminder = Text("Remember: f calls f")
self.play(FadeIn(reminder), run_time=0.5)
self.wait(1)

Wait Time Guidelines

Standard Waits

Dynamic Wait Calculation

def calculate_wait(text_content):
    """Estimate appropriate wait time"""
    word_count = len(text_content.split())
    base_wait = 1.0

    # Reading time: ~3 words per second
    reading_time = word_count / 3

    # Complexity bonus (simple heuristic)
    complexity_bonus = 0
    if any(word in text_content.lower() for word in ['therefore', 'because', 'however']):
        complexity_bonus = 1

    return base_wait + reading_time + complexity_bonus

Rhythm Patterns

The "Teach" Rhythm

[Present] → [Pause] → [Explain] → [Pause] → [Example] → [Long Pause]
   1s         1s         1s         1s         1s           2s

# Implementation
self.play(Write(concept))  # Present
self.wait(1)               # Pause
self.play(Write(explanation))  # Explain
self.wait(1)               # Pause
self.play(FadeIn(example)) # Example
self.wait(2)               # Long pause

The "Build" Rhythm

[Element] → [Short] → [Element] → [Short] → [Element] → [Medium] → [Result] → [Long]
   0.5s       0.3s       0.5s       0.3s       0.5s        1s         1s        2s

# Implementation
for elem in building_blocks[:-1]:
    self.play(FadeIn(elem), run_time=0.5)
    self.wait(0.3)
self.play(FadeIn(building_blocks[-1]))  # Last element
self.wait(1)
self.play(Create(result))  # Show result
self.wait(2)

The "Compare" Rhythm

[A] → [Pause] → [B] → [Pause] → [Difference Highlight] → [Long Pause]

Signals for Pacing

Speed Up When:

• Reviewing familiar material
• Showing repetitive examples
• Building momentum toward climax
• Viewer has seen similar patterns

Slow Down When:

• Introducing new terminology
• Showing crucial transformations
• Making logical leaps
• Complex visual relationships

The "Breath" Technique

Insert "breathing room" at natural break points:

# Section complete - take a breath
self.wait(1.5)

# Before major topic shift
self.play(FadeOut(*self.mobjects))
self.wait(0.5)  # Mental reset

# After climax/key insight
self.play(Indicate(key_element))
self.wait(3)  # Let it sink in

Avoiding Common Pacing Mistakes

Too Fast

# BAD - No time to process
for concept in [c1, c2, c3, c4, c5]:
    self.play(FadeIn(concept), run_time=0.2)
# Everything blurs together

Too Slow

# BAD - Boring, loses attention
self.play(Write(simple_text), run_time=5)
self.wait(10)
# Viewer's mind wanders

Inconsistent

# BAD - Jarring
self.wait(3)
self.play(something, run_time=0.1)  # Sudden speed change
self.wait(5)
# Creates anxiety

Just Right

# GOOD - Matched to content
important_concept = Text("Key insight here")
self.play(Write(important_concept), run_time=1.5)
self.wait(2.5)  # Proportional to importance

minor_detail = Text("(side note)")
self.play(FadeIn(minor_detail), run_time=0.5)
self.wait(1)  # Less wait for less importance

Testing Your Pacing

1. Watch at normal speed - does it feel rushed? 2. Watch at 1.5x speed - is it still clear? 3. Watch without sound - do pauses feel natural? 4. Show to someone unfamiliar - do they follow?

Progressive Revelation Rules

Core Principle

Never show everything at once. Build understanding layer by layer, allowing viewers to absorb each piece before adding more.

The Information Hierarchy

Level 1: Essential (Show First)

• The main concept or question
• Core visual elements
• What the viewer absolutely needs

Level 2: Supporting (Show Second)

• Details that explain Level 1
• Examples or applications
• Labels and annotations

Level 3: Enriching (Show Last)

• Additional context
• Edge cases or exceptions
• Deeper connections

Revelation Patterns

1. Linear Revelation (Step by Step)

# Each element builds on the last
self.play(Create(step1))
self.wait(1)
self.play(Create(step2))  # Related to step1
self.wait(1)
self.play(Create(step3))  # Builds on step2

2. Central Expansion (Outward)

# Start with core, expand outward
self.play(Create(center_element))  # Most important
self.wait(0.5)
self.play(
    *[Create(e) for e in surrounding_elements]  # Supporting
)

3. Layer Stacking (Top to Bottom)

# Build depth through layers
self.play(FadeIn(background_layer))
self.play(FadeIn(middle_layer))
self.play(FadeIn(foreground_layer))

4. Question-Answer Revelation

# Pose question, then reveal answer
question = Text("Why does water boil?")
self.play(Write(question))
self.wait(2)  # Let viewer think

answer_parts = [
    "Heat provides energy",
    "Molecules move faster",
    "Escape as steam"
]
for part in answer_parts:
    text = Text(part, font_size=24)
    self.play(FadeIn(text))
    self.wait(1)

Timing for Revelation

Animation Choices for Revelation

For Text

# Word by word (dramatic)
words = sentence.split()
for word in words:
    t = Text(word)
    self.play(FadeIn(t, shift=UP * 0.3), run_time=0.2)
    self.wait(0.1)

# Typewriter effect
self.play(AddTextLetterByLetter(text), run_time=2)

# Full write (standard)
self.play(Write(text))

For Diagrams

# Part by part
for part in diagram_parts:
    self.play(Create(part))

# Growing from center
self.play(GrowFromCenter(diagram))

# Tracing (for paths/lines)
self.play(Create(path), run_time=2)

For Data

# Bars growing
self.play(LaggedStart(
    *[GrowFromEdge(bar, DOWN) for bar in bars],
    lag_ratio=0.2
))

# Numbers counting up
number = DecimalNumber(0)
self.play(ChangeDecimalToValue(number, 100), run_time=2)

Pacing Guidelines

The 3-Second Rule

No new element should appear less than 3 seconds after a complex reveal.

The Breathing Room Rule

After revealing something important: 1. Wait for viewer to see it (0.5s) 2. Wait for viewer to read it (varies by length) 3. Wait for viewer to understand it (1-2s)

self.play(Write(important_formula))
self.wait(3)  # Full breathing room for formula

The Anticipation Rule

Signal that something is coming before revealing it:

# Create anticipation
self.play(Indicate(related_element))
self.wait(0.5)
# Then reveal
self.play(FadeIn(new_element))

Common Mistakes

DON'T: Information dump

# BAD
self.add(elem1, elem2, elem3, elem4, elem5)  # All at once

DO: Gradual build

# GOOD
for elem in [elem1, elem2, elem3, elem4, elem5]:
    self.play(FadeIn(elem))
    self.wait(0.3)

DON'T: Reveal and immediately move on

# BAD
self.play(Write(important_concept))
self.play(FadeOut(important_concept))  # No time to absorb

DO: Give time to absorb

# GOOD
self.play(Write(important_concept))
self.wait(2)  # Absorb
self.play(Indicate(important_concept))  # Reinforce
self.wait(1)

Advanced: Conditional Revelation

Hide-Reveal Pattern

# Show blurred/hidden version first
hidden = element.copy().set_opacity(0.2).add(blur_effect)
self.play(FadeIn(hidden))
self.wait(1)
# Then reveal clearly
self.play(Transform(hidden, element))

Progressive Detail Pattern

# Start simple, add detail
simple_version = create_simplified()
self.play(Create(simple_version))
self.wait(1)

# Add first layer of detail
self.play(Transform(simple_version, medium_detail))
self.wait(1)

# Full detail
self.play(Transform(simple_version, full_detail))

Visual Metaphors Rules

Why Use Visual Metaphors?

Abstract concepts become tangible when connected to familiar visuals:

• Numbers → Physical objects (5 apples, not "5")
• Growth → Expanding shapes, rising graphs
• Connection → Lines, arrows, bridges
• Transformation → Morphing shapes
• Time → Left-to-right movement, timeline

Common Metaphor Mappings

Size = Importance/Quantity

# Larger = more important
important = Circle(radius=1.5, color=YELLOW)
normal = Circle(radius=0.5, color=WHITE)

# Growing = increasing
self.play(circle.animate.scale(2))  # "Value doubled"

Color = Category/Emotion

# Consistent color coding
POSITIVE = GREEN
NEGATIVE = RED
NEUTRAL = WHITE

# Emotional mapping
CALM = BLUE
ENERGY = YELLOW
DANGER = RED

Position = Time/Sequence/Hierarchy

# Left to right = past to future
past.to_edge(LEFT)
present.move_to(ORIGIN)
future.to_edge(RIGHT)

# Top to bottom = hierarchy
boss.to_edge(UP)
employee.to_edge(DOWN)

# Center = focus/importance
main_topic.move_to(ORIGIN)

Movement = Change/Process

# Moving right = progress
self.play(progress_bar.animate.shift(RIGHT * 5))

# Moving up = improvement
self.play(value.animate.shift(UP * 2))

# Rotation = cycle/repetition
self.play(Rotate(cycle_diagram, angle=2*PI))

Opacity = Relevance/Focus

# Dim = less important now
self.play(background_info.animate.set_opacity(0.3))

# Full opacity = current focus
self.play(current_topic.animate.set_opacity(1))

Creating Effective Metaphors

Rule 1: Use Familiar Objects

# GOOD - Everyone knows these
apple = Circle(color=RED)  # Fruit
house = Rectangle()  # Building
person = SVGMobject("stick_figure.svg")

# BAD - Obscure or abstract
complex_symbol = MathTex(r"\aleph_0")  # Not universally known

Rule 2: Maintain Consistency

# If "x" is a blue circle in Scene 1, it must be blue circle throughout
x_visual = Circle(color=BLUE)
# NEVER change to square or different color mid-explanation

Rule 3: Match Metaphor to Concept

# Concept: Division
# Metaphor: Cutting a pie
pie = Circle(fill_opacity=0.8)
slice_line = Line(ORIGIN, UP)
self.play(Create(slice_line))  # "Dividing"

# Concept: Multiplication
# Metaphor: Grid/array of objects
objects = VGroup(*[Square() for _ in range(12)])
objects.arrange_in_grid(rows=3, cols=4)  # "3 × 4 = 12"

Domain-Specific Metaphors

Mathematics

Computer Science

Physics

Animation Techniques for Metaphors

Transformation Metaphor (A becomes B)

# Show conceptual transformation
water = SVGMobject("water_drop")
steam = SVGMobject("steam_cloud")
self.play(Transform(water, steam))  # Evaporation

Container Metaphor (X contains Y)

# Variable as box
box = Square()
value = Text("42")
self.play(Create(box))
self.play(value.animate.move_to(box))  # Value stored in variable

Flow Metaphor (X leads to Y)

# Process flow
arrow = Arrow(start.get_right(), end.get_left())
self.play(Create(arrow))
# Animated particle along arrow
dot = Dot()
self.play(MoveAlongPath(dot, arrow))

Balance Metaphor (X equals Y)

# Show equality as balance
scale = VGroup(
    Line(LEFT * 2, RIGHT * 2),  # Balance beam
    Triangle().scale(0.3).next_to(ORIGIN, DOWN)  # Fulcrum
)
left_weight = Square().move_to(LEFT * 1.5)
right_weight = Square().move_to(RIGHT * 1.5)
# Scale is level when equal

Common Pitfalls

DON'T: Mix metaphors

# BAD - Confusing
variable_as_box = Square()  # Box metaphor
variable_as_bucket = Arc()  # Now bucket?? Pick one!

DON'T: Over-complicate

# BAD - Metaphor harder than concept
# Using a 3D rotating hypercube to represent a simple array

DO: Keep it simple and consistent

# GOOD - One clear metaphor throughout
array_boxes = VGroup(*[Square() for _ in range(5)])
array_boxes.arrange(RIGHT)
# Always use boxes for arrays in this animation