manim-mcp 0.1.0

package/references/manimce/rules/3b1b-translation.md

@@ -0,0 +1,594 @@
+---
+name: 3b1b-translation
+description: Comprehensive guide for translating ManimGL (3b1b video code) to ManimCE, with examples from all 407 video files
+metadata:
+  tags: manimgl, manimce, translation, migration, porting, conversion, 3b1b, ShowCreation, CONFIG, InteractiveScene
+---
+
+# Translating ManimGL to ManimCE
+
+This guide covers every major difference between the ManimGL code used in 3Blue1Brown's video repository and ManimCE (Manim Community Edition). The patterns come from analyzing 407 Python files across the `_2015/` through `_2026/` directories.
+
+## Animation Name Changes
+
+### ShowCreation to Create
+
+The single most common translation. Every 3b1b file uses `ShowCreation`.
+
+```python
+# ManimGL (3b1b)
+self.play(ShowCreation(circle))
+self.play(ShowCreation(plane, lag_ratio=0.01, run_time=3))
+self.play(ShowCreation(rect))
+
+# ManimCE
+self.play(Create(circle))
+self.play(Create(plane, lag_ratio=0.01, run_time=3))
+self.play(Create(rect))
+```
+
+### Other Renamed Animations
+
+```python
+# ManimGL                          # ManimCE
+ShowCreation(mob)                   Create(mob)
+ShowCreation(mob, lag_ratio=0.5)    Create(mob, lag_ratio=0.5)
+# Note: Write() works the same in both for text/equations
+
+# These are the same in both:
+# FadeIn, FadeOut, Write, GrowArrow, GrowFromCenter, Transform,
+# ReplacementTransform, DrawBorderThenFill, Rotate, MoveToTarget,
+# LaggedStartMap, LaggedStart, Succession, AnimationGroup
+```
+
+## Scene Classes
+
+### InteractiveScene to Scene
+
+3b1b's base class for most scenes is `InteractiveScene`. ManimCE uses `Scene`.
+
+```python
+# ManimGL (3b1b)
+class MyScene(InteractiveScene):
+    def construct(self):
+        ...
+
+# ManimCE
+class MyScene(Scene):
+    def construct(self):
+        ...
+```
+
+### PiCreatureScene / TeacherStudentsScene
+
+These exist in 3b1b's custom directory (`custom/characters/`) and are not part of ManimCE. You can create similar patterns manually or use community plugins.
+
+```python
+# ManimGL (3b1b)
+class AskAboutPosition(TeacherStudentsScene):
+    def construct(self):
+        self.teacher_says("Think about this...")
+        self.student_says("Oh, I see!")
+
+# ManimCE: No direct equivalent. Use plain Scene with custom mobjects.
+class AskAboutPosition(Scene):
+    def construct(self):
+        # Create speech bubbles manually
+        teacher_text = Text("Think about this...", font_size=28)
+        bubble = SurroundingRectangle(teacher_text, buff=0.3, corner_radius=0.2)
+        self.play(Create(bubble), Write(teacher_text))
+        self.wait()
+```
+
+## CONFIG Dict to Class Attributes / __init__ Parameters
+
+This is pervasive -- nearly every 3b1b class uses the CONFIG pattern.
+
+```python
+# ManimGL (3b1b) -- CONFIG dict pattern
+class Pendulum(VGroup):
+    CONFIG = {
+        "length": 3,
+        "gravity": 9.8,
+        "weight_diameter": 0.5,
+        "initial_theta": 0.3,
+        "omega": 0,
+        "damping": 0.1,
+        "top_point": 2 * UP,
+        "n_steps_per_frame": 100,
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        # self.length, self.gravity etc. are auto-set from CONFIG
+
+# ManimCE -- use __init__ parameters
+class Pendulum(VGroup):
+    def __init__(
+        self,
+        length=3,
+        gravity=9.8,
+        weight_diameter=0.5,
+        initial_theta=0.3,
+        omega=0,
+        damping=0.1,
+        top_point=2 * UP,
+        n_steps_per_frame=100,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.length = length
+        self.gravity = gravity
+        self.weight_diameter = weight_diameter
+        self.initial_theta = initial_theta
+        self.omega = omega
+        self.damping = damping
+        self.top_point = top_point
+        self.n_steps_per_frame = n_steps_per_frame
+```
+
+For Scene subclasses used as "configuration":
+
+```python
+# ManimGL (3b1b)
+class GaltonBoard(InteractiveScene):
+    random_seed = 1
+    pegs_per_row = 15
+    n_rows = 5
+    spacing = 1.0
+    bucket_style = dict(fill_color=GREY_D, fill_opacity=1.0)
+
+# ManimCE -- exactly the same! Class attributes work fine.
+class GaltonBoard(Scene):
+    random_seed = 1
+    pegs_per_row = 15
+    n_rows = 5
+    spacing = 1.0
+    bucket_style = dict(fill_color=GREY_D, fill_opacity=1.0)
+```
+
+## Camera and Frame Access
+
+### self.frame to self.camera.frame
+
+```python
+# ManimGL (3b1b)
+frame = self.frame
+frame.set_height(10)
+self.play(frame.animate.move_to(LEFT))
+self.play(frame.animate.scale(0.5))
+frame.add_updater(lambda m, dt: m.increment_theta(-0.1 * dt))
+
+# ManimCE (MovingCameraScene)
+class MyScene(MovingCameraScene):
+    def construct(self):
+        frame = self.camera.frame
+        self.play(frame.animate.set(width=10))
+        self.play(frame.animate.move_to(LEFT))
+        self.play(frame.animate.scale(0.5))
+        frame.add_updater(lambda m, dt: m.rotate(-0.1 * dt))
+```
+
+### frame.reorient() to set_camera_orientation()
+
+```python
+# ManimGL (3b1b) -- 3D camera
+frame.reorient(20, 70)
+self.play(frame.animate.reorient(-30, 60))
+
+# ManimCE (ThreeDScene)
+class MyScene(ThreeDScene):
+    def construct(self):
+        self.set_camera_orientation(phi=70 * DEGREES, theta=20 * DEGREES)
+        self.move_camera(phi=60 * DEGREES, theta=-30 * DEGREES, run_time=2)
+        # Or for continuous rotation:
+        self.begin_ambient_camera_rotation(rate=0.2)
+```
+
+### fix_in_frame() to add_fixed_in_frame_mobjects()
+
+```python
+# ManimGL (3b1b)
+equation.fix_in_frame()
+# Or:
+mob.always.fix_in_frame()
+
+# ManimCE (ThreeDScene)
+class MyScene(ThreeDScene):
+    def construct(self):
+        equation = MathTex(r"E = mc^2")
+        self.add_fixed_in_frame_mobjects(equation)
+        # Now equation stays fixed while 3D camera moves
+```
+
+## LaTeX / Text Classes
+
+### Tex / OldTex / OldTexText to MathTex / Tex
+
+```python
+# ManimGL (3b1b) -- RECENT code
+formula = Tex(R"\frac{d}{dx} e^x = e^x", t2c={R"e^x": YELLOW})
+label = TexText("Hello World")
+
+# ManimGL (3b1b) -- OLDER code (pre-2020)
+formula = OldTex(R"\frac{d}{dx} e^x = e^x")
+label = OldTexText("Hello World")
+
+# ManimCE
+formula = MathTex(r"\frac{d}{dx} e^x = e^x", tex_to_color_map={r"e^x": YELLOW})
+label = Tex(r"Hello World")
+# Or for plain text:
+label = Text("Hello World")
+```
+
+### Key LaTeX Differences
+
+```python
+# ManimGL: Uses R"..." raw strings (capital R)
+Tex(R"\pi r^2")
+Tex(R"...", t2c={R"\pi": RED})
+
+# ManimCE: Uses r"..." raw strings (lowercase r), different kwarg name
+MathTex(r"\pi r^2")
+MathTex(r"...", tex_to_color_map={r"\pi": RED})
+# Shorthand also works in ManimCE:
+MathTex(r"...", t2c={r"\pi": RED})
+```
+
+### TexText (styled text in LaTeX) to Tex
+
+```python
+# ManimGL (3b1b)
+title = TexText(R"Moser's Circle Problem", font_size=72)
+
+# ManimCE
+title = Tex(r"Moser's Circle Problem", font_size=72)
+# Or often better:
+title = Text("Moser's Circle Problem", font_size=72)
+```
+
+## Updater Patterns
+
+### f_always to add_updater
+
+```python
+# ManimGL (3b1b)
+dot.f_always.move_to(lambda: axes.i2gp(x_tracker.get_value(), graph))
+f_always(counter.set_value, lambda: len(items))
+frac_label.f_always.move_to(rect.get_center)
+
+# ManimCE
+dot.add_updater(lambda m: m.move_to(axes.i2gp(x_tracker.get_value(), graph)))
+counter.add_updater(lambda m: m.set_value(len(items)))
+frac_label.add_updater(lambda m: m.move_to(rect.get_center()))
+```
+
+### mob.always.method() to add_updater
+
+```python
+# ManimGL (3b1b)
+randy.always.fix_in_frame()
+label.always.next_to(dot, UR, SMALL_BUFF)
+
+# ManimCE
+# fix_in_frame doesn't have a direct always equivalent
+# For ThreeDScene: self.add_fixed_in_frame_mobjects(randy)
+label.add_updater(lambda m: m.next_to(dot, UR, SMALL_BUFF))
+```
+
+### always_redraw (Same in Both!)
+
+```python
+# ManimGL (3b1b)
+h_line = always_redraw(lambda: axes.get_h_line(dot.get_left()))
+brace = always_redraw(Brace, square, UP)
+
+# ManimCE -- identical!
+h_line = always_redraw(lambda: axes.get_horizontal_line(dot.get_left()))
+# Note: get_h_line -> get_horizontal_line in ManimCE
+brace = always_redraw(lambda: Brace(square, UP))
+```
+
+## Coordinate Systems
+
+### Axes Methods
+
+```python
+# ManimGL (3b1b)
+axes.get_h_line(point)
+axes.get_v_line(point)
+axes.get_graph(func)
+
+# ManimCE
+axes.get_horizontal_line(point)
+axes.get_vertical_line(point)
+axes.plot(func)
+# Or for compatibility: axes.get_graph(func) also works in ManimCE
+```
+
+## Specific Mobject Translations
+
+### GlowDot
+
+```python
+# ManimGL (3b1b) -- used in zeta/play.py
+s_dot = Group(TrueDot(), GlowDot())
+s_dot.set_color(YELLOW)
+
+# ManimCE -- no GlowDot, approximate with glow effect
+dot = Dot(color=YELLOW, radius=0.08)
+glow = Dot(color=YELLOW, radius=0.3).set_opacity(0.2)
+s_dot = VGroup(glow, dot)
+```
+
+### set_backstroke()
+
+```python
+# ManimGL (3b1b)
+equations.set_backstroke()
+label.set_backstroke(BLACK, 3)
+
+# ManimCE
+equations.set_stroke(BLACK, 5, background=True)
+label.set_stroke(BLACK, 3, background=True)
+
+# Or create a helper:
+def set_backstroke(mob, color=BLACK, width=5):
+    mob.set_stroke(color, width, background=True)
+    return mob
+```
+
+### make_number_changeable()
+
+```python
+# ManimGL (3b1b) -- from _2025/zeta/play.py
+exp_const_label = Tex(R"c = 0.0000", t2c={"c": RED})
+c_dec = exp_const_label.make_number_changeable("0.0000")
+c_dec.add_updater(lambda m: m.set_value(get_exp_const()))
+
+# ManimCE -- use DecimalNumber explicitly
+prefix = MathTex(r"c = ", color=WHITE)
+c_dec = DecimalNumber(0, num_decimal_places=4, color=RED)
+c_dec.add_updater(lambda m: m.set_value(get_exp_const()))
+c_dec.add_updater(lambda m: m.next_to(prefix, RIGHT, buff=0.1))
+label = VGroup(prefix, c_dec)
+```
+
+### ComplexValueTracker
+
+```python
+# ManimGL (3b1b)
+s_tracker = ComplexValueTracker(1)
+get_s = s_tracker.get_value
+
+# ManimCE -- no ComplexValueTracker, use two ValueTrackers
+s_real = ValueTracker(1)
+s_imag = ValueTracker(0)
+get_s = lambda: complex(s_real.get_value(), s_imag.get_value())
+```
+
+### NumericEmbedding and Custom Mobjects
+
+The transformers series uses custom mobjects (`NumericEmbedding`, `WeightMatrix`, `ContextAnimation`, etc.) that don't exist in ManimCE. These need to be reimplemented.
+
+```python
+# ManimGL (3b1b) -- custom helper from transformers/helpers.py
+embedding = NumericEmbedding(length=10).set_width(0.5)
+
+# ManimCE -- build from primitives
+def make_embedding(values, width=0.5, font_size=18):
+    entries = VGroup()
+    for val in values:
+        dec = DecimalNumber(val, num_decimal_places=2, font_size=font_size)
+        alpha = min(abs(val) / 3, 1)
+        color = interpolate_color(BLUE_E, BLUE_B, alpha) if val >= 0 else \
+                interpolate_color(RED_E, RED_B, alpha)
+        dec.set_color(color)
+        entries.add(dec)
+    entries.arrange(DOWN, buff=0.1)
+    brackets = MathTex(r"\left[ \right]", font_size=36)
+    left = brackets[0][:1]
+    right = brackets[0][1:]
+    left.stretch_to_fit_height(entries.height + 0.3).next_to(entries, LEFT, buff=0.1)
+    right.stretch_to_fit_height(entries.height + 0.3).next_to(entries, RIGHT, buff=0.1)
+    return VGroup(left, entries, right).set_width(width)
+```
+
+## 3D-Specific Translations
+
+### Camera Euler Angles
+
+```python
+# ManimGL (3b1b)
+self.camera.frame.set_euler_angles(
+    theta=-30 * DEGREES,
+    phi=70 * DEGREES,
+)
+self.camera.frame.increment_phi(-10 * DEGREES)
+self.camera.frame.increment_theta(-20 * DEGREES)
+
+# ManimCE (ThreeDScene)
+self.set_camera_orientation(phi=70 * DEGREES, theta=-30 * DEGREES)
+self.move_camera(phi=60 * DEGREES, theta=-50 * DEGREES)
+```
+
+### Surface and TexturedSurface
+
+```python
+# ManimGL (3b1b)
+torus = Torus(r1=1, r2=1)
+sphere = Sphere(radius=3, resolution=torus.resolution)
+earth = TexturedSurface(sphere, "EarthTextureMap", "NightEarthTextureMap")
+mesh = SurfaceMesh(earth)
+
+# ManimCE
+torus = Torus(major_radius=1, minor_radius=1)
+sphere = Sphere(radius=3)
+# TexturedSurface not directly available; use Surface with custom func
+# SurfaceMesh: not available, approximate with wireframe
+```
+
+### Light Source
+
+```python
+# ManimGL (3b1b)
+light = self.camera.light_source
+self.play(light.move_to(3 * IN))
+
+# ManimCE -- lighting is handled differently
+# ManimCE uses ThreeDScene lighting config, not a movable light object
+```
+
+## Syntax Differences
+
+### set_anim_args (ManimGL Only)
+
+```python
+# ManimGL (3b1b)
+rect.animate.next_to(tale, RIGHT, buff=LARGE_BUFF).set_anim_args(rate_func=linear)
+
+# ManimCE
+# Pass rate_func to self.play() instead
+self.play(
+    rect.animate.next_to(tale, RIGHT, buff=LARGE_BUFF),
+    rate_func=linear,
+)
+```
+
+### VGroup Generator Syntax
+
+```python
+# ManimGL (3b1b) -- generator inside VGroup (recent ManimGL feature)
+embeddings = VGroup(
+    NumericEmbedding(length=10).set_width(0.5).next_to(rect, DOWN, buff=1.5)
+    for rect in all_rects
+)
+
+# ManimCE -- must use * unpacking or explicit list
+embeddings = VGroup(*[
+    make_embedding([0]*10).next_to(rect, DOWN, buff=1.5)
+    for rect in all_rects
+])
+```
+
+### time_span in Animations
+
+```python
+# ManimGL (3b1b)
+self.play(
+    FadeIn(elements, time_span=(1, 2)),
+    Write(text),
+    run_time=3,
+)
+
+# ManimCE -- no time_span, use AnimationGroup or separate plays
+self.play(Write(text), run_time=1)
+self.play(FadeIn(elements), run_time=1)
+```
+
+## Import Translations
+
+```python
+# ManimGL (3b1b)
+from manim_imports_ext import *           # Their universal import
+from manimlib import *                     # Direct manimlib import
+from manimlib.animation.creation import ShowCreation
+from manimlib.scene.interactive_scene import InteractiveScene
+
+# ManimCE
+from manim import *                        # Everything you need
+```
+
+## Complete Translation Example
+
+### ManimGL Original (from codebase)
+
+```python
+from manim_imports_ext import *
+
+class CircumferenceToArea(InteractiveScene):
+    def construct(self):
+        t2c = {"{r}": BLUE}
+        circum_formula = Tex(R"\text{Circumference} = 2 \pi {r}", t2c=t2c)
+        radius = 3
+        circle = Circle(radius=radius)
+        circle.set_stroke(YELLOW, 5)
+        r_group = VGroup(
+            Line(ORIGIN, radius * RIGHT).set_stroke(WHITE, 3),
+            Tex(R"r", font_size=72).set_color(BLUE),
+        )
+        self.add(circle, r_group)
+        self.play(
+            ShowCreation(circle),
+            Rotate(r_group, TAU, about_point=ORIGIN),
+            run_time=3,
+        )
+```
+
+### ManimCE Translation
+
+```python
+from manim import *
+
+class CircumferenceToArea(Scene):
+    def construct(self):
+        t2c = {"{r}": BLUE}
+        circum_formula = MathTex(
+            r"\text{Circumference} = 2 \pi {r}",
+            tex_to_color_map=t2c,
+        )
+        radius = 3
+        circle = Circle(radius=radius)
+        circle.set_stroke(YELLOW, 5)
+        r_group = VGroup(
+            Line(ORIGIN, radius * RIGHT).set_stroke(WHITE, 3),
+            MathTex(r"r", font_size=72).set_color(BLUE),
+        )
+        self.add(circle, r_group)
+        self.play(
+            Create(circle),
+            Rotate(r_group, TAU, about_point=ORIGIN),
+            run_time=3,
+        )
+```
+
+## Quick Reference Table
+
+| ManimGL (3b1b) | ManimCE | Frequency |
+|-----------------|---------|-----------|
+| `ShowCreation(mob)` | `Create(mob)` | Very high |
+| `InteractiveScene` | `Scene` | Very high |
+| `Tex(R"...", t2c={})` | `MathTex(r"...", tex_to_color_map={})` | Very high |
+| `OldTex(R"...")` | `MathTex(r"...")` | High (older files) |
+| `OldTexText("...")` | `Tex("...")` or `Text("...")` | High (older files) |
+| `TexText("...")` | `Tex("...")` or `Text("...")` | High |
+| `CONFIG = {...}` | `__init__` parameters | Very high |
+| `self.frame` | `self.camera.frame` (MovingCameraScene) | High |
+| `frame.reorient(th, ph)` | `self.set_camera_orientation(phi, theta)` | Medium |
+| `mob.fix_in_frame()` | `self.add_fixed_in_frame_mobjects(mob)` | Medium |
+| `mob.f_always.method(func)` | `mob.add_updater(lambda m: m.method(func()))` | Medium |
+| `f_always(mob.set_value, func)` | `mob.add_updater(lambda m: m.set_value(func()))` | Medium |
+| `mob.always.fix_in_frame()` | `self.add_fixed_in_frame_mobjects(mob)` | Low |
+| `set_backstroke(color, w)` | `set_stroke(color, w, background=True)` | Medium |
+| `make_number_changeable()` | Use `DecimalNumber` with updater | Low |
+| `GlowDot` | `Dot` with transparent larger `Dot` behind | Low |
+| `ComplexValueTracker` | Two `ValueTracker`s (real, imag) | Low |
+| `axes.get_h_line()` | `axes.get_horizontal_line()` | Medium |
+| `axes.get_v_line()` | `axes.get_vertical_line()` | Medium |
+| `axes.get_graph()` | `axes.plot()` | Medium |
+| `.set_anim_args(rate_func=...)` | Pass `rate_func` to `self.play()` | Low |
+| `VGroup(x for x in items)` | `VGroup(*[x for x in items])` | Medium |
+| `time_span=(0, 1)` in anim | Not available; restructure animations | Low |
+
+## Best Practices for Translation
+
+1. **Start with imports**: Replace `from manim_imports_ext import *` with `from manim import *`
+2. **Find-replace animations**: `ShowCreation` to `Create` globally
+3. **Find-replace scene classes**: `InteractiveScene` to `Scene`
+4. **Convert CONFIG dicts**: Move to `__init__` parameters
+5. **Fix LaTeX classes**: `Tex(R"...")` to `MathTex(r"...")`, `OldTex` to `MathTex`
+6. **Fix camera access**: `self.frame` to `self.camera.frame` and use proper scene type
+7. **Fix updater patterns**: `f_always` to `add_updater`
+8. **Test incrementally**: Translate one scene at a time, render to verify
+9. **Skip custom mobjects**: Reimplement 3b1b-specific helpers from scratch
+10. **Check coordinate system methods**: Many method names differ slightly