MSP — Manim 风格与协议 是做什么的?
一份用于 AI 生成 Manim 动画的生产级技能规范
版本: 1.0
目标环境: Manim 社区版 (ManimCE) ≥ v0.18
目的: 使任何 AI 系统能够默认生成清晰、组织良好、过渡平滑、达到工作室/电影级质量的 Manim 动画——而不是例外情况。
0. 首要指令
你编写的每一个场景,都必须看起来出自专业动画工作室,而非学生脚本。当选择模棱两可时,选择更平滑、更简洁、更有意图的那个——永远不要选择最懒的默认选项。
在编写任何代码之前,心中快速检查以下清单:
- 这个场景要传达的一个核心思想是什么?
- 视觉层次是什么(观众应该先看到什么,再看到什么,最后看到什么)?
- 我使用了何种调色板和字体,并且在整个项目中保持一致吗?
- 每个对象将如何进入、变换和退出——没有任何对象应该不经过动画就直接“出现”或“消失”。
- 这个场景的节奏(总 run_time 预算)是怎样的?
1. 环境与版本锁定
默认始终使用 Manim 社区版,而非 ManimGL,除非用户明确要求 3b1b 风格的 ManimGL。
from manim import *
- CLI 二进制文件:
manim(而非manimgl) - 创建动词:
Create()(而非ShowCreation()) - 数学渲染:
MathTex(r"...")(而非Tex(R"..."))
绝不要混用 API。 如果某个代码片段在没有 MovingCameraScene/ThreeDScene 的情况下使用了 self.camera.frame,请标记出来——这是渗入的 ManimGL 语法。
2. 项目文件结构
对于任何超出单个简单场景的项目,强制使用以下结构——绝不要将所有内容都塞进一个庞大的文件中:
project/
├── manim.cfg # 锁定的渲染配置(见 §9)
├── theme.py # 颜色、字体、常量(单一事实来源)
├── helpers.py # 可复用的 mobject 构建器 / 布局函数
├── scenes/
│ ├── 01_intro.py
│ ├── 02_derivation.py
│ └── 03_outro.py
└── assets/ # svgs, images, audio
theme.py 示例(对于多场景项目务必创建一个):
from manim import *
# ---- 调色板 ----
BG_COLOR = "#0E0E12"
PRIMARY = "#58C4DD" # manim 默认蓝色,或品牌色
SECONDARY = "#FFD166"
ACCENT = "#EF476F"
TEXT_MAIN = "#F5F5F5"
TEXT_MUTED = "#8A8A8F"
SUCCESS = "#06D6A0"
# ---- 排版 ----
FONT_MAIN = "Helvetica" # 或项目特定字体
FONT_MONO = "JetBrains Mono"
# ---- 时间常量 ----
T_FAST = 0.5
T_NORMAL = 1.0
T_SLOW = 1.8
LAG = 0.08 # 分组揭示的默认 lag_ratio
config.background_color = BG_COLOR
每个场景文件都从 theme.py 导入。一旦创建了主题文件,就绝不要在代码中硬编码十六进制颜色或 magic run_time 数字——这是不专业、不一致输出的第一标志。
3. 视觉设计标准
3.1 颜色规则
- 每个项目最多使用 4–5 种颜色(1 背景色,1–2 主色,1–2 强调色)。更多颜色会显得杂乱/业余。
- 语义化使用颜色:在整个视频中,相同的颜色代表相同的含义(例如,蓝色始终代表“已知”,红色始终代表“未知”)。
- 背景几乎从不使用纯黑(
#000000)或纯白——使用柔和的近黑(#0E0E12)或柔和的近白,以减少视觉疲劳并获得“工作室”感。
3.2 排版规则
- 使用
Text()处理 UI 标签、标题、说明文字——速度快,无需 LaTeX 依赖。 - 使用
MathTex()处理所有数学符号——绝不使用Text()伪造数学公式。 - 仅当需要混合散文+数学的 LaTeX 块时使用
Tex()。 - 通过主题常量全局设置
font=;绝不让字体选择在不同场景间变化。 - 标题规范:使用
.to_edge(UP),粗体,在所有场景中保持一致的字体大小(例如 40pt)。
3.3 布局规则
- 尊重三分法——避免默认将所有内容居中;有意识地使用
.to_edge()、.shift()、.next_to()。 - 保持一致的边距(buff 值)——定义一个
MARGIN = 0.75常量,并在每个.to_edge(..., buff=MARGIN)调用中复用。 - 将相关对象分组到一个
VGroup中,并对组进行定位和动画处理,而不是处理松散独立的 mobject——这确保了在后续任何变换中对齐保持不变。 - 始终在组上调用
.arrange()或.arrange_in_grid(),而不是手动计算坐标——手动坐标计算很脆弱,是后续编辑中布局出错的首要原因。
4. 变形与变换协议
这是“平滑、变形”动画的核心——高端解说视频的标志性外观。
4.1 规则:绝不剪切,始终变换
如果一个对象概念上变成了另一个对象(方程重排,形状变成另一个形状,标签更新),绝不要对独立的 mobject 使用 FadeOut + FadeIn——这样看起来像跳切。始终使用变换族:
| 情况 | 正确的工具 |
|---|---|
| 方程重排,项保持不变 | TransformMatchingTex(old, new) |
| 形状变形为不同的形状 | Transform(old, new) 或 ReplacementTransform(old, new) |
| mobject 组重构(例如,要点列表 → 图表) | TransformMatchingShapes(old_group, new_group) |
| 一个对象明确替换场景图中的另一个对象 | ReplacementTransform(在 self.mobjects 中用新对象替换旧对象) |
| 淡出同时暗示连续性(例如,幽灵/叠加) | FadeTransform(old, new) |
TransformMatchingTex 的协议细节: 始终构建两个具有一致子串分组的 MathTex mobject(相同的 LaTeX 片段作为单独的 {} 组),以便 Manim 能够匹配相同的符号——这使得各项能够视觉上“滑动”到新位置,而不是交叉淡入淡出。
eq1 = MathTex("a", "+", "b", "=", "c")
eq2 = MathTex("c", "=", "a", "+", "b")
self.play(TransformMatchingTex(eq1, eq2), run_time=1.2)
4.2 规则:对简单属性变形使用 .animate
对于一个 mobject 上的单个连续属性更改(位置、缩放、颜色、旋转),优先使用 .animate 语法——它更简洁,Manim 会自动插值净变换:
self.play(square.animate.shift(RIGHT * 2).scale(1.5).set_color(ACCENT), run_time=1.0)
注意事项(关键,防止 AI 幻觉错误): 链式 .animate 调用插值的是最终净状态,而不是按顺序的每个中间步骤。绝不要链式调用那些依赖于中间结果的 .animate 调用(例如,.animate.move_to(X).rotate(angle_depending_on_position))——应将其拆分为单独的 self.play() 调用。
4.3 规则:对连续/从属运动使用更新器
每当一个对象的状态必须持续跟踪另一个对象时(标签跟随点,值显示跟踪 ValueTracker),使用 add_updater,绝不要手动为每一帧重新 play:
tracker = ValueTracker(0)
label = DecimalNumber(0).add_updater(lambda d: d.set_value(tracker.get_value()))
dot = Dot().add_updater(lambda m: m.move_to(axes.c2p(tracker.get_value(), f(tracker.get_value()))))
self.add(label, dot)
self.play(tracker.animate.set_value(5), run_time=3, rate_func=linear)
一旦一个对象的依赖阶段结束,始终 remove_updater(或使用 always_redraw 进行更干净的从头重新计算逻辑),以避免在较长的场景中出现过期更新器错误。
5. 时间、节奏与缓动协议
5.1 默认速率函数策略
- 默认(不覆盖):
smooth—— S 曲线缓入/缓出。用于 90% 的动画——方程揭示、形状创建、标准移动。 linear:对于描绘任何字面意义上的恒定速率物理运动是强制性的——轨道上的点、均匀速度矢量、旋转的时钟指针、与真实经过时间绑定的进度条。rush_into/rush_from:用于强调进入/退出,当某些东西应该感觉像是“咔哒”一声到位或弹射出去时。there_and_back/there_and_back_with_pause:用于Indicate风格的注意力脉冲,绝不用于永久状态更改。ease_out_bounce/ease_out_elastic:仅限于有趣、非正式的内容——绝不要在正式的数理科推导中使用,否则会显得不专业。
5.2 时间预算规则
- 保持单个
run_time在 0.4s 到 3s 之间。低于 0.4s 会显得刺眼;高于 3s(无叙述理由)会显得拖沓。 - 标题/章节标头进入:
0.8–1.2s。 - 方程/图表变换:
1.0–1.5s。 - 强调脉冲(
Indicate、Flash、Circumscribe):0.5–0.8s。 - 相机移动(
move_camera、self.camera.frame.animate):1.5–3s—— 快于此速度的相机移动会让人感到恶心。 - 在每次重要揭示之后,有意插入
self.wait(0.3–1.0)的停顿——绝不要将self.play()调用无间隙地连续执行;这会淹没观众。
5.3 组合协议
- 同时但独立的事件 → 单个
self.play(AnimA, AnimB, ...)调用。 - 同时但交错开始(例如,6 个要点依次出现但时间重叠)→
LaggedStart(*anims, lag_ratio=0.15)。 - 严格顺序、依赖的事件 →
Succession(*anims)或单独的self.play()调用。 - 列表/网格揭示(要点、形状网格)→ 始终使用
LaggedStartMap(FadeIn, group, lag_ratio=0.08, shift=UP*0.3),而不是单次同时的FadeIn(group)—— 交错让群组进入感觉更有机而非机械。
6. 场景与代码组织协议
6.1 Construct 方法形态
始终通过注释或辅助方法将 construct() 分解为清晰界定、命名的阶段——绝不要写成一个不间断的 100 行代码块:
class DerivationScene(Scene):
def construct(self):
self.setup_title()
self.show_initial_equation()
self.derive_steps()
self.highlight_result()
self.cleanup()
def setup_title(self):
self.title = Text("Deriving the Quadratic Formula", font=FONT_MAIN).to_edge(UP)
self.play(Write(self.title), run_time=T_NORMAL)
self.wait(T_FAST)
def show_initial_equation(self):
...
对于长视频,拆分成多个场景类(每个逻辑部分一个),而不是一个巨大的 construct()——这使得可以通过 -n 进行目标性重新渲染和并行迭代。
6.2 Mobject 构建协议
- 将复杂的自定义视觉元素(图表、图形、图标)构建为
helpers.py中的独立函数,返回VGroup,而不是内联在construct()中:
# helpers.py
def make_neuron(radius=0.3, color=PRIMARY) -> VGroup:
circle = Circle(radius=radius, color=color, fill_opacity=0.8)
label = Text("n", font_size=20).move_to(circle)
return VGroup(circle, label)
- 始终有意义地命名 mobject(
title、eq_initial、graph_group)——绝不要留下你稍后需要修改或变换的未引用匿名字面量。 - 对于任何存在重叠图层的场景,显式使用
z_index(一旦图层超过 2 层,不要依赖添加顺序)。
6.3 样式/代码检查规则
- 变量/方法使用 snake_case,Scene 子类使用 PascalCase。
- 在代码中,动画“节拍”之间留一个空行以提高可读性——代码结构应在视觉上反映视频的节奏。
- 对于颜色/位置/时间,没有裸写的魔法数字——始终引用
theme.py常量。 - 为辅助函数添加类型提示(
def make_axes() -> Axes:)以在较大项目中保持可维护性。
7. 合成与相机协议(2D 和 3D)
2D
- 当视频需要在 2D 中平移/缩放时(例如,聚焦于图表的子区域),使用
MovingCameraScene—— 通过self.camera.frame.animate.move_to(...).set(width=...)进行动画,始终配合显式的run_time。
3D
- 继承
ThreeDScene。 - 在专门的设置步骤中,使用
self.set_camera_orientation(phi=70*DEGREES, theta=-45*DEGREES, zoom=1)设置初始方向——除非有意的,否则绝不留默认方向。 - 对于观众应该感知为运动的任何相机重新定位,使用
self.move_camera(phi=..., theta=..., run_time=2.5)—— 绝不要 在场景中间通过set_camera_orientation进行跳切。 - 在旁白下进行缓慢的闲置旋转时,使用
self.begin_ambient_camera_rotation(rate=0.15);在后续故意的move_camera之前,始终配对使用self.stop_ambient_camera_rotation()。 - 无论相机角度如何都必须保持清晰可读的 HUD/标签/标题 →
self.add_fixed_in_frame_mobjects(label)。 - 应跟踪 3D 对象但保持可读的标签 →
self.add_fixed_orientation_mobjects(label)。 - 在迭代期间保持 3D 表面的
resolution元组较低(例如(24,24));仅在对最终产出版本进行渲染时再提高——这纯粹是一个性能/工作流规则,而非视觉效果规则。
8. 强调与注意力协议
绝不要让一个关键结果在视觉上看起来与支持内容相同。在揭示一个场景的“回报”(最终方程、关键见解、结果)之后,仅应用一种强调技术——不要叠加超过一种,否则会显得狂乱:
Circumscribe(mobject, color=ACCENT, run_time=1.2)—— 在其周围绘制一个形状。Indicate(mobject, scale_factor=1.15)—— 短暂的脉冲缩放 + 颜色闪烁。Flash(point, color=ACCENT)—— 径向爆发,适用于特定坐标/交点。mobject.animate.set_color(ACCENT)结合轻微缩放——用于永久重新着色,表示“这就是答案”。
9. 渲染与导出协议
9.1 锁定配置文件(提交此文件——绝不要依赖临时标志来交付最终版本)
manim.cfg:
[CLI]
quality = production_quality
preview = False
background_color = "#0E0E12"
output_file = {scene_name}
frame_rate = 60
pixel_height = 1080
pixel_width = 1920
9.2 工作流阶段(始终遵循此顺序,绝不要首先渲染最终质量)
- 草稿阶段:
manim -pql scenes/02_derivation.py DerivationScene—— 快速迭代,检查逻辑/时机。 - 点检阶段:
manim -pqh -s scenes/02_derivation.py DerivationScene—— 对构图/颜色进行单帧高质量检查。 - 回顾阶段:
manim -pqh scenes/02_derivation.py DerivationScene—— 全质量、全时长的最终审查。 - 交付:从
media/videos/scenes/1080p60/收集.mp4文件。(默认输出目录;如果更改了,请相应调整。)
9.3 工作流提示
- 添加
-n start_frame,end_frame以仅渲染一系列帧,而不是整个场景——在长场景中对迭代至关重要。 - 对于精确的音频/旁白同步匹配,使用
manim-slides,而不是手动时间调整逐帧渲染。
附录 A:常见 AI 生成代码的幻觉与陷阱
以下错误在 AI 生成的 Manim 代码中反复出现。已知它们,并加以防范:
| 问题 | 错误写法 | 正确写法 |
|---|---|---|
| 过期 API | ShowCreation(circle) | Create(circle) |
| 混用 ManimGL 语法 | self.frame 在 Scene 中 | self.camera.frame(且仅在 MovingCameraScene/ThreeDScene 中安全使用) |
| 颜色字符串而非常量 | set_color("#FF1493") | set_color(ACCENT)(从 theme.py) |
| 硬编码缓冲区 | .to_edge(UP, buff=0.5) | .to_edge(UP, buff=MARGIN) |
| 未使用的孤立 mobject | Circle() 未赋值 | circle = Circle() |
| 在非 Unity 警告下省略 VGroup | 独立定位 20 个圆圈 | 使用 VGroup(*circles) 并 .arrange_in_grid() |
| 每秒 2 帧的更新器泄漏 | 添加更新器但不移除 | remove_updater 或 always_redraw |
| 无意义的 run_time | run_time=0.15 导致锯齿 | run_time=0.5(最小值) |
| 在 MathTex 中错误使用 Text() | Text("E=mc^2") | MathTex("E=mc^2") |
| 混乱的分组导致 TransformMatchingTex 失效 | MathTex("a+b=c") 作为一个字符串 | MathTex("a", "+", "b", "=", "c") 进行子串匹配 |
附录 B:风格经验法则
- 5 秒法则:如果超过 5 秒没有新的 mobject 进入、变换或高亮,场景就显得无精打采。
- 1 种颜色规则:如果一个 mobject 在场景中出现超过 3 秒,它应至少通过颜色或动画强调一次其用途。
- 少于 30 秒规则:对于独立短视频,如果没有分量或场景变化,很少有场景需要超过 30 秒。精确。
- 过渡规则:如果切换主题或更改上下文,总是通过
self.next_section()引入一个新部分,或者至少通过一次self.wait(0.5)并改变相机位置。
附录 C:快速参考卡
查询的不同类型动画及其用法:
| 动画类型 | 何时使用 | 示例 |
|---|---|---|
Create | 路径/形状首次出现时 | Create(Axes()) |
DrawBorderThenFill | 填充形状:外围线条出现,然后填充 | DrawBorderThenFill(Square()) |
Write | 文本逐字符出现 | Write(title) |
FadeIn / FadeOut | 简单的透明度进出;谨慎用于变换 | FadeIn(circle) |
Transform | 一个 mobject 变成另一个 | Transform(circle, square) |
ReplacementTransform | 在场景图中用新 mobject 替换旧 mobject | ReplacementTransform(circle, square) |
TransformMatchingTex | 方程重排,匹配的 LaTeX 子串滑动到位 | TransformMatchingTex(eq1, eq2) |
TransformMatchingShapes | 一般的群组重构 | TransformMatchingShapes(old_vg, new_vg) |
Uncreate / Unwrite | 反向创建/书写 | Uncreate(axes) |
Indicate | 短暂引起注意 | Indicate(answer, scale_factor=1.15) |
Circumscribe | 围绕 mobject 绘制几何高亮 | Circumscribe(formula, color=ACCENT) |
Flash | 点上的径向爆发 | Flash(dot.get_center(), color=ACCENT) |
LaggedStart | 交错开始的动画组 | LaggedStart(*anims, lag_ratio=0.15) |
LaggedStartMap | 对群组的每个元素应用相同的动画并有偏移 | LaggedStartMap(FadeIn, group) |
Succession | 严格顺序的动画 | Succession(anim1, anim2, anim3) |
AnimationGroup | 同时或顺序的组 | AnimationGroup(anim1, anim2, lag_ratio=0.1) |
mobject.animate | 快速链式属性更改 | square.animate.shift(RIGHT).scale(2) |