manim-mcp 0.1.0

package/references/manimce/rules/color-conventions.md

@@ -0,0 +1,444 @@
+---
+name: color-conventions
+description: The comprehensive 3Blue1Brown color system for mathematical visualization in ManimCE
+metadata:
+  tags: colors, color-system, 3b1b, conventions, heatmap, gradient, backstroke, value-to-color
+---
+
+# 3Blue1Brown Color Conventions
+
+The 3b1b videos use a remarkably consistent color system across all 407+ files. Colors carry semantic meaning -- they tell the viewer what role each element plays.
+
+## Domain Color Conventions
+
+### Linear Algebra (from `_2016/eola/`)
+
+```python
+from manim import *
+
+# Basis vectors -- THE most iconic 3b1b color choice
+X_COLOR = GREEN       # i-hat, x-component, first basis vector
+Y_COLOR = RED         # j-hat, y-component, second basis vector
+Z_COLOR = BLUE        # k-hat, z-component, third basis vector
+
+# These are used in EVERY EoLA chapter
+i_hat = Vector([1, 0], color=X_COLOR)
+j_hat = Vector([0, 1], color=Y_COLOR)
+
+# Eigenvalues
+EIGEN_COLOR_1 = TEAL   # First eigenvalue/eigenvector
+EIGEN_COLOR_2 = YELLOW  # Second eigenvalue/eigenvector
+```
+
+### Calculus / Differential Equations (from `_2017/`, `_2019/diffyq/`)
+
+```python
+# Physical quantities
+DISTANCE_COLOR = BLUE
+TIME_COLOR = YELLOW
+VELOCITY_COLOR = GREEN
+ACCELERATION_COLOR = RED
+
+# Derivative visualization
+FUNCTION_COLOR = YELLOW    # f(x)
+DERIVATIVE_COLOR = GREEN   # f'(x)
+TANGENT_COLOR = BLUE       # tangent line
+
+# Area under curve
+AREA_COLOR = BLUE_D        # Riemann rectangles (with gradient to GREEN)
+```
+
+### Optics / Waves (from `_2023/optics_puzzles/`)
+
+```python
+# Wave colors
+WAVE_COLOR = YELLOW         # Default wave
+MEDIUM_COLOR = BLUE         # Glass/water medium
+MEDIUM_OPACITY = 0.35       # Standard medium opacity
+```
+
+### Physics / Differential Equations (from `_2019/diffyq/`)
+
+```python
+# Phase space
+THETA_COLOR = WHITE         # angle variable
+OMEGA_COLOR = RED           # angular velocity (also used for velocity vectors)
+```
+
+### Probability / Statistics (from `_2023/clt/`, `_2019/bayes/`)
+
+```python
+# Distribution colors
+BAR_COLORS = (BLUE_D, GREEN_D)   # Gradient for bar charts
+BAR_COLORS_ALT = (BLUE, TEAL)    # Alternative gradient
+SAMPLE_COLOR = YELLOW             # Sample markers / indicators
+GAUSSIAN_COLOR = YELLOW           # Normal curve overlay
+```
+
+### SIR Epidemic Model (from `_2020/sir.py`)
+
+```python
+# Epidemic states -- standard epidemiology convention
+SIR_COLORS = {
+    "S": BLUE,      # Susceptible
+    "I": RED,       # Infected
+    "R": GREY_D,    # Recovered
+}
+ASYMPTOMATIC_COLOR = YELLOW
+SOCIAL_DISTANCE_COLOR = YELLOW
+```
+
+### Transformers / Neural Networks (from `_2024/transformers/`)
+
+```python
+# Attention and embedding colors
+S_COLOR = YELLOW              # Used for variable 's' in Laplace/zeta
+T_COLOR = BLUE                # Used for time variable 't'
+
+# Matrix heatmap colors
+POSITIVE_LOW = BLUE_E         # Low positive values
+POSITIVE_HIGH = BLUE_B        # High positive values
+NEGATIVE_LOW = RED_E          # Low negative values (near zero)
+NEGATIVE_HIGH = RED_B         # High negative values
+
+# Pi creature conventional coloring
+PI_CREATURE_COLOR = BLUE      # Randolph (default pi creature)
+```
+
+### Complex Analysis (from `_2025/laplace/`, `_2025/zeta/`)
+
+```python
+S_COLOR = YELLOW              # Complex variable s
+T_COLOR = BLUE                # Time variable t
+PI_COLOR = RED                # Used for pi in e^(i*pi)
+```
+
+## The value_to_color() Pattern
+
+From `_2024/transformers/helpers.py` -- the key function for matrix heatmaps and data visualization.
+
+```python
+from manim import *
+
+def value_to_color(
+    value,
+    low_positive_color=BLUE_E,
+    high_positive_color=BLUE_B,
+    low_negative_color=RED_E,
+    high_negative_color=RED_B,
+    min_value=0.0,
+    max_value=10.0,
+):
+    """Map a numerical value to a color using HSL interpolation.
+
+    Positive values: blue gradient (BLUE_E to BLUE_B)
+    Negative values: red gradient (RED_E to RED_B)
+    """
+    alpha = min(max(abs(value) / max_value, 0), 1)
+    if value >= 0:
+        return interpolate_color(low_positive_color, high_positive_color, alpha)
+    else:
+        return interpolate_color(low_negative_color, high_negative_color, alpha)
+
+
+class MatrixHeatmap(Scene):
+    """Visualize a matrix with value_to_color encoding."""
+
+    def construct(self):
+        n_rows, n_cols = 5, 5
+        values = np.random.randn(n_rows, n_cols) * 3
+
+        cells = VGroup()
+        cell_size = 0.7
+        for i in range(n_rows):
+            for j in range(n_cols):
+                cell = Square(side_length=cell_size)
+                color = value_to_color(values[i, j], max_value=5)
+                cell.set_fill(color, opacity=0.9)
+                cell.set_stroke(WHITE, 0.5)
+                cell.move_to(np.array([
+                    j * cell_size - (n_cols - 1) * cell_size / 2,
+                    -i * cell_size + (n_rows - 1) * cell_size / 2,
+                    0
+                ]))
+                cells.add(cell)
+
+        self.play(FadeIn(cells, lag_ratio=0.01), run_time=2)
+        self.wait(2)
+```
+
+## Temperature-to-Color (Heat Equation)
+
+For heat equation and thermal simulations, map temperature to a blue-red gradient.
+
+```python
+def temperature_to_color(temp, t_min=-1, t_max=1):
+    """Map temperature to a blue (cold) to red (hot) gradient."""
+    alpha = (temp - t_min) / (t_max - t_min)
+    alpha = max(0, min(1, alpha))  # Clamp
+
+    if alpha < 0.5:
+        return interpolate_color(BLUE, WHITE, 2 * alpha)
+    else:
+        return interpolate_color(WHITE, RED, 2 * (alpha - 0.5))
+
+
+class HeatEquationViz(Scene):
+    """Heat distribution visualization."""
+
+    def construct(self):
+        n_bars = 50
+        bars = VGroup()
+        temps = np.sin(np.linspace(0, 2 * PI, n_bars))
+
+        for i, t in enumerate(temps):
+            bar = Rectangle(
+                width=FRAME_WIDTH / n_bars,
+                height=3,
+                fill_opacity=1,
+                stroke_width=0,
+            )
+            bar.set_fill(temperature_to_color(t))
+            bar.move_to([(i - n_bars / 2) * FRAME_WIDTH / n_bars, 0, 0])
+            bars.add(bar)
+
+        self.play(FadeIn(bars, lag_ratio=0.01))
+        self.wait(2)
+```
+
+## HSL Interpolation for Smooth Gradients
+
+ManimCE's `interpolate_color` works in RGB space. For smoother gradients (especially around the color wheel), HSL interpolation is preferred. 3b1b's ManimGL has `interpolate_color_by_hsl`.
+
+```python
+import colorsys
+
+def interpolate_color_hsl(color1, color2, alpha):
+    """Interpolate between two colors in HSL space for smoother results."""
+    rgb1 = color_to_rgb(color1)
+    rgb2 = color_to_rgb(color2)
+
+    h1, l1, s1 = colorsys.rgb_to_hls(*rgb1)
+    h2, l2, s2 = colorsys.rgb_to_hls(*rgb2)
+
+    # Handle hue wraparound
+    if abs(h2 - h1) > 0.5:
+        if h1 < h2:
+            h1 += 1
+        else:
+            h2 += 1
+
+    h = (1 - alpha) * h1 + alpha * h2
+    l = (1 - alpha) * l1 + alpha * l2
+    s = (1 - alpha) * s1 + alpha * s2
+
+    h = h % 1.0
+    r, g, b = colorsys.hls_to_rgb(h, l, s)
+    return rgb_to_color([r, g, b])
+
+
+class HSLGradient(Scene):
+    """Smooth HSL gradient compared to RGB."""
+
+    def construct(self):
+        n = 50
+        # RGB interpolation (can look muddy)
+        rgb_bars = VGroup()
+        for i in range(n):
+            alpha = i / (n - 1)
+            bar = Rectangle(width=FRAME_WIDTH / n, height=1)
+            bar.set_fill(interpolate_color(RED, BLUE, alpha), opacity=1)
+            bar.set_stroke(width=0)
+            bar.move_to([(i - n / 2) * FRAME_WIDTH / n, 1, 0])
+            rgb_bars.add(bar)
+
+        # HSL interpolation (stays vivid)
+        hsl_bars = VGroup()
+        for i in range(n):
+            alpha = i / (n - 1)
+            bar = Rectangle(width=FRAME_WIDTH / n, height=1)
+            bar.set_fill(interpolate_color_hsl(RED, BLUE, alpha), opacity=1)
+            bar.set_stroke(width=0)
+            bar.move_to([(i - n / 2) * FRAME_WIDTH / n, -1, 0])
+            hsl_bars.add(bar)
+
+        rgb_label = Text("RGB interpolation", font_size=24).next_to(rgb_bars, LEFT)
+        hsl_label = Text("HSL interpolation", font_size=24).next_to(hsl_bars, LEFT)
+
+        self.add(rgb_bars, hsl_bars, rgb_label, hsl_label)
+        self.wait(2)
+```
+
+## set_backstroke() for Readability
+
+3b1b frequently uses `set_backstroke()` to add a dark outline behind text/equations that overlap with colorful backgrounds. In ManimCE, this needs a manual approach since `set_backstroke` is a ManimGL feature.
+
+```python
+def set_backstroke(mob, color=BLACK, width=5):
+    """ManimCE equivalent of ManimGL's set_backstroke.
+    Adds a background stroke for readability over colored backgrounds."""
+    mob.set_stroke(color, width, background=True)
+    return mob
+
+
+class BackstrokeDemo(Scene):
+    """Text readability over colored backgrounds."""
+
+    def construct(self):
+        # Colorful background
+        gradient_rect = Rectangle(
+            width=FRAME_WIDTH, height=FRAME_HEIGHT,
+            fill_opacity=1,
+        )
+        gradient_rect.set_color_by_gradient(BLUE, GREEN, YELLOW)
+        self.add(gradient_rect)
+
+        # Text without backstroke (hard to read)
+        text_bad = MathTex(r"e^{i\pi} + 1 = 0", font_size=60)
+        text_bad.shift(UP)
+
+        # Text with backstroke (readable)
+        text_good = MathTex(r"e^{i\pi} + 1 = 0", font_size=60)
+        text_good.shift(DOWN)
+        set_backstroke(text_good, BLACK, 8)
+
+        label_bad = Text("Without backstroke", font_size=20).next_to(text_bad, UP)
+        label_good = Text("With backstroke", font_size=20).next_to(text_good, UP)
+        set_backstroke(label_bad, BLACK, 5)
+        set_backstroke(label_good, BLACK, 5)
+
+        self.add(text_bad, text_good, label_bad, label_good)
+        self.wait(2)
+```
+
+## Color-Coded Equation Pattern (tex_to_color_map / t2c)
+
+The most pervasive pattern in all 3b1b code: color individual LaTeX symbols by their semantic role.
+
+```python
+class ColorCodedEquation(Scene):
+    """Using tex_to_color_map for semantic coloring."""
+
+    def construct(self):
+        # Linear algebra style
+        eigen_eq = MathTex(
+            r"A \vec{v} = \lambda \vec{v}",
+            tex_to_color_map={
+                r"\vec{v}": YELLOW,
+                r"\lambda": TEAL,
+            },
+        )
+
+        # Calculus style
+        deriv_eq = MathTex(
+            r"\frac{d}{dt} f(t) = \lim_{\Delta t \to 0}"
+            r"\frac{f(t + \Delta t) - f(t)}{\Delta t}",
+            tex_to_color_map={
+                r"t": BLUE,
+                r"\Delta t": GREEN,
+            },
+        )
+
+        # Complex analysis style
+        euler = MathTex(
+            r"e^{i \theta} = \cos(\theta) + i \sin(\theta)",
+            tex_to_color_map={
+                r"\theta": YELLOW,
+                r"i": BLUE,
+            },
+        )
+
+        equations = VGroup(eigen_eq, deriv_eq, euler)
+        equations.arrange(DOWN, buff=0.8)
+
+        for eq in equations:
+            self.play(Write(eq), run_time=1.5)
+            self.wait(0.5)
+
+        self.wait(2)
+```
+
+## Submobject Color Gradients
+
+3b1b frequently colors groups of submobjects with a gradient using `set_submobject_colors_by_gradient` or `set_color_by_gradient`:
+
+```python
+class GradientPatterns(Scene):
+    """Color gradient patterns from the codebase."""
+
+    def construct(self):
+        # Bars with gradient
+        bars = VGroup(*[
+            Rectangle(width=0.5, height=h, fill_opacity=0.8, stroke_width=1)
+            for h in np.random.uniform(0.5, 3, 10)
+        ])
+        bars.arrange(RIGHT, buff=0.1, aligned_edge=DOWN)
+        bars.set_color_by_gradient(BLUE_D, GREEN_D)  # Standard 3b1b bar colors
+
+        # Dots along a path with gradient
+        dots = VGroup(*[
+            Dot(radius=0.08)
+            for _ in range(20)
+        ])
+        dots.arrange_in_grid(rows=1, buff=0.3)
+        dots.set_color_by_gradient(RED, YELLOW, GREEN, BLUE)
+
+        group = VGroup(bars, dots).arrange(DOWN, buff=1)
+        self.add(group)
+        self.wait(2)
+```
+
+## Opacity Conventions
+
+```python
+# Background planes/grids
+BACKGROUND_OPACITY = 0.3     # NumberPlane typically at 30-40% opacity
+
+# Faded elements (de-emphasized)
+FADED_OPACITY = 0.25         # Elements pushed to background
+
+# Fill opacity for shapes
+SHAPE_FILL_OPACITY = 0.5     # Standard fill for rectangles, polygons
+
+# Medium (glass, water) opacity
+MEDIUM_OPACITY = 0.35        # From optics videos
+```
+
+## Complete Color Reference Table
+
+| Domain | Element | Color | Source |
+|--------|---------|-------|--------|
+| Linear Algebra | i-hat / x-axis | `GREEN` | `_2016/eola/` |
+| Linear Algebra | j-hat / y-axis | `RED` | `_2016/eola/` |
+| Linear Algebra | k-hat / z-axis | `BLUE` | `_2016/eola/` |
+| Linear Algebra | Eigenvalue 1 | `TEAL` | `_2024/linalg/` |
+| Linear Algebra | Eigenvalue 2 | `YELLOW` | `_2024/linalg/` |
+| Calculus | Function graph | `YELLOW` | `_2017/` |
+| Calculus | Derivative | `GREEN` | `_2017/` |
+| Calculus | Area / integral | `BLUE_D` to `GREEN` | `_2017/` |
+| Physics | Time variable | `BLUE` / `YELLOW` | `_2019/diffyq/` |
+| Physics | Velocity | `RED` | `_2019/diffyq/` |
+| Probability | Bar chart | `BLUE_D` to `GREEN_D` | `_2023/clt/` |
+| Probability | Samples | `YELLOW` | `_2023/clt/` |
+| Probability | Gaussian curve | `YELLOW` | `_2023/clt/` |
+| SIR | Susceptible | `BLUE` | `_2020/sir.py` |
+| SIR | Infected | `RED` | `_2020/sir.py` |
+| SIR | Recovered | `GREY_D` | `_2020/sir.py` |
+| Complex | Variable s | `YELLOW` | `_2025/` |
+| Complex | Pi | `RED` | `_2025/laplace/` |
+| Neural Networks | Positive weights | `BLUE_E` to `BLUE_B` | `_2024/transformers/` |
+| Neural Networks | Negative weights | `RED_E` to `RED_B` | `_2024/transformers/` |
+| General | Highlighted text | `YELLOW` | everywhere |
+| General | Author name | `YELLOW` | `custom/opening_quote.py` |
+| General | Background | `BLACK` (default) | everywhere |
+| General | Backstroke | `BLACK`, width 3-8 | `_2025/` |
+
+## Best Practices
+
+1. **Maintain consistency** -- once a variable gets a color, keep it throughout the video
+2. **Use `tex_to_color_map`** for every equation with multiple meaningful symbols
+3. **Positive = blue, negative = red** for value-encoded colors (matrix heatmaps)
+4. **Use backstroke** (`background_stroke`) when text overlaps colored backgrounds
+5. **Gradients for bar charts** -- typically `BLUE_D` to `GREEN_D` or `BLUE` to `TEAL`
+6. **Dim to 25% opacity** to de-emphasize elements rather than removing them
+7. **HSL interpolation** for smooth gradients that stay vivid through the middle

package/references/manimce/rules/colors.md

@@ -0,0 +1,199 @@
+---
+name: colors
+description: Color constants, gradients, and color manipulation in Manim
+metadata:
+  tags: color, colors, gradient, rgb, hex, palette
+---
+
+# Colors in Manim
+
+Manim provides predefined color constants and supports custom colors.
+
+## IMPORTANT: Only Use Named Color Constants
+
+**NEVER use hex color strings like `"#FF5733"` or `"#2ECC71"`.** Hex strings frequently cause `ManimColor._internal_from_hex_string` errors and crash the render. Always use the named constants below.
+
+**NEVER use `CYAN`** — it does not exist in ManimCE. Use `TEAL` instead.
+
+### Complete List of Valid Color Constants
+
+```python
+# Primary colors
+RED, GREEN, BLUE, YELLOW, ORANGE, PINK, PURPLE, WHITE, BLACK
+
+# Grey/Gray (both spellings work)
+GREY, GRAY
+GREY_A, GREY_B, GREY_C, GREY_D, GREY_E
+GRAY_A, GRAY_B, GRAY_C, GRAY_D, GRAY_E
+LIGHT_GREY, LIGHT_GRAY, DARK_GREY, DARK_GRAY
+LIGHTER_GREY, LIGHTER_GRAY, DARKER_GREY, DARKER_GRAY
+
+# Color variants (_A = lightest, _E = darkest)
+BLUE_A, BLUE_B, BLUE_C, BLUE_D, BLUE_E
+RED_A, RED_B, RED_C, RED_D, RED_E
+GREEN_A, GREEN_B, GREEN_C, GREEN_D, GREEN_E
+TEAL, TEAL_A, TEAL_B, TEAL_C, TEAL_D, TEAL_E
+GOLD, GOLD_A, GOLD_B, GOLD_C, GOLD_D, GOLD_E
+YELLOW_A, YELLOW_B, YELLOW_C, YELLOW_D, YELLOW_E
+MAROON, MAROON_A, MAROON_B, MAROON_C, MAROON_D, MAROON_E
+PURPLE_A, PURPLE_B, PURPLE_C, PURPLE_D, PURPLE_E
+ORANGE_A, ORANGE_B, ORANGE_C, ORANGE_D, ORANGE_E
+PINK_A, PINK_B, PINK_C, PINK_D, PINK_E
+
+# Pure RGB primaries
+PURE_RED, PURE_GREEN, PURE_BLUE
+
+# Browns
+LIGHT_BROWN, DARK_BROWN
+```
+
+These 80+ named colors provide more than enough variety. If you need a specific shade, use `interpolate_color(COLOR1, COLOR2, alpha)` with named colors — never raw hex strings.
+
+## Using Colors
+
+### Setting Color on Creation
+```python
+circle = Circle(color=RED)
+square = Square(color=BLUE, fill_color=GREEN, fill_opacity=0.5)
+text = Text("Hello", color=YELLOW)
+```
+
+### Setting Color After Creation
+```python
+circle = Circle()
+circle.set_color(RED)
+```
+
+## Custom Colors (Advanced — Prefer Named Constants)
+
+If you absolutely need a custom color, use `ManimColor` or `interpolate_color` with named constants:
+```python
+# Blend two named colors — PREFERRED approach
+custom = interpolate_color(BLUE, GREEN, 0.5)
+
+# RGB values (0-1 range) — use only when no named color works
+from manim import rgb_to_color
+custom = rgb_to_color([0.5, 0.2, 0.8])
+```
+
+## Fill vs Stroke Color
+
+```python
+square = Square()
+square.set_fill(RED, opacity=0.8)      # Interior color
+square.set_stroke(BLUE, width=4)       # Border color
+```
+
+### Combined Styling
+```python
+square = Square(
+    color=BLUE,            # Sets both fill and stroke
+    fill_opacity=0.5,      # Fill transparency
+    stroke_width=4         # Border thickness
+)
+```
+
+## Gradients
+
+### Color Gradient on Mobject
+```python
+text = Text("GRADIENT")
+text.set_color_by_gradient(RED, YELLOW, GREEN)
+```
+
+### Gradient Along Path
+```python
+line = Line(LEFT * 3, RIGHT * 3)
+line.set_color_by_gradient(BLUE, GREEN, YELLOW)
+```
+
+## Color Interpolation
+
+Create colors between two colors:
+
+```python
+from manim import interpolate_color
+
+# Get color halfway between RED and BLUE
+mid_color = interpolate_color(RED, BLUE, 0.5)
+
+# Create a range of colors
+colors = [interpolate_color(RED, BLUE, alpha) for alpha in np.linspace(0, 1, 10)]
+```
+
+## ManimColor Class
+
+For advanced color manipulation:
+
+```python
+from manim import ManimColor
+
+# Start from named constants — NOT hex strings
+color1 = ManimColor(RED)
+color2 = ManimColor(BLUE)
+
+# Color manipulation methods
+lighter = color1.lighter()               # Lighter version
+darker = color1.darker()                 # Darker version
+
+# Interpolation
+mixed = color1.interpolate(color2, 0.5)  # Blend two colors
+```
+
+## Opacity
+
+```python
+# Set opacity (0 = transparent, 1 = opaque)
+circle = Circle(fill_opacity=0.5, stroke_opacity=0.8)
+
+# Modify opacity
+circle.set_opacity(0.5)         # Both fill and stroke
+circle.set_fill_opacity(0.7)    # Fill only
+circle.set_stroke_opacity(0.3)  # Stroke only
+```
+
+## Color by Value
+
+Color mobjects based on a value (useful for data visualization):
+
+```python
+class ColorByValue(Scene):
+    def construct(self):
+        dots = VGroup(*[Dot() for _ in range(10)]).arrange(RIGHT)
+
+        for i, dot in enumerate(dots):
+            # Color from blue (cold) to red (hot)
+            dot.set_color(interpolate_color(BLUE, RED, i / 9))
+
+        self.add(dots)
+```
+
+## Random Colors
+
+```python
+from manim import random_color, random_bright_color
+
+circle = Circle(color=random_color())
+square = Square(color=random_bright_color())
+```
+
+## Color Lists for Animations
+
+```python
+class ColorCycle(Scene):
+    def construct(self):
+        circle = Circle()
+        self.add(circle)
+
+        colors = [RED, ORANGE, YELLOW, GREEN, BLUE, PURPLE]
+        for color in colors:
+            self.play(circle.animate.set_color(color), run_time=0.5)
+```
+
+## Best Practices
+
+1. **Use color variants for depth** - `BLUE_E` for shadows, `BLUE_A` for highlights
+2. **Maintain color consistency** - Use the same colors for related concepts
+3. **Use opacity for layering** - Semi-transparent fills show overlapping
+4. **Consider colorblind accessibility** - Avoid red-green only distinctions
+5. **Use gradients sparingly** - They can be distracting