Manim 社区版 v0.1.0 版本解析：从 3b1b/manim 分支到独立生态的技术起点

导读

v0.1.0 是 Manim 社区版（manimce）从 3b1b/manim 分支后的首个正式发布版本（2020 年 10 月 21 日），它确立了社区维护路线的基本技术骨架：统一的 manim.cfg 配置系统、基于 rich 的日志体系、-q/--quality 五档渲染质量、--tex_template 自定义 TeX 模板，以及 Tex/MathTex 对 TextMobject/TexMobject 的命名替换。本文基于 0.1.0-changelog.rst 的原始条目，逐项结合当前仓库源码进行验证与展开，帮助你理解这些设计决策的来龙去脉，以及它们在今天的 manim 中如何落地。

版本背景：一次以「清理与重构」为目标的社区分支

v0.1.0 发布于 2020 年 10 月 21 日，这是 manimce 从 3b1b/manim 分叉后的首个版本。原始 changelog 明确写道：开发者把工作重心放在清理和重构代码库上，同时尽可能保持向后兼容。这一基调贯穿了版本中的所有改动——大量新增功能并非全新发明，而是把 3b1b 版本中分散、脆弱的机制（打印输出、全局常量、硬编码路径）收敛为统一、可配置、可测试的基础设施。

具体到工程层面，v0.1.0 还完成了三件影响深远的事：

• 包名从 manimlib 重命名为 manim，所有导入收敛到包的 __init__.py，从此 from manim import * 取代了 from manimlib.imports import *（见 manim/init.py）；
• 移除了全局目录变量处理，目录初始化改为在运行时由 initialize_directories 依据 cfg 文件动态覆盖；
• 清理了 3b1b 专属文件（如 tex_template.tex、ctex_template.tex 等旧模板文件随 TexTemplate 类的引入而被移除）。

命令行：从「打印」到「日志 + 结构化选项」

v0.1.0 对命令行体验做了系统性升级，多数改动在今天的源码中依然可见。

更友好的 --help 与日志体系

manim --help 的输出被重构为分组结构。当前实现中，渲染相关选项被划分为 Render Options（见 manim/cli/render/render_options.py）、Output options（见 manim/cli/render/output_options.py）与 Global options（见 manim/cli/render/global_options.py）三组，选项分组格式化参数（如对齐、缩进、主题色）由 manim/_config/default.cfg 中的 [CLI_CTX] 段控制。

同时，plain print 被彻底替换为基于 rich 库 + logger 对象的日志输出。manim.logger（即 logging.getLogger("manim")）通过 RichHandler 输出富文本，其中 Played、Rendering、Reading 等关键词会被特殊高亮（见 manim/_config/logger_utils.py 中的 HIGHLIGHTED_KEYWORDS）。日志配色可在配置文件的 <a href="https://link.gitcode.com/i/3f6417fa63bf01ea540422926168325b" target="_blank">logger] 段自定义——仓库自带的示例场景配置 [example_scenes/manim.cfg 就演示了如何把关键字改成 magenta、把信息日志改成 dim green 等自定义配色。

关键新增/变更的 CLI 标志

标志	功能	当前源码对应
--dry_run	渲染但不写出任何媒体文件	global_options.py 中的 --dry_run，帮助文案为 "Renders animations without outputting image or video files"
python3 -m manim	以模块方式运行 manim	manim/main.py 提供入口
--tex_template	指定自定义 TeX 模板文件	global_options.py 中的 --tex_template；Tex/MathTex 也支持用 template 关键字参数指定模板
--save_frames（后演变为 -s/--save_last_frame）	保存每一帧为 PNG	现行为 -s 快进动画并保存最后一帧，等价于 --format=png
-（stdin 文件名）	从标准输入读取 manim 代码	见 cli/render/commands.py 的输入解析逻辑
--custom_folders（后并入 --media_dir 体系）	更简单的输出目录结构	目录布局由 manim/_config/default.cfg 的 media_dir、video_dir、partial_movie_dir 等键统一管理
-i（GIF 导出）	只输出 .gif、不输出 .mp4	现在由 --format gif 承担，选项见 render_options.py
--verbose / -v/--verbosity	控制输出详细程度	现支持 DEBUG/INFO/WARNING/ERROR/CRITICAL 五档（见 global_options.py）
--log_to_file	把日志写入文件	见 output_options.py；文件日志使用 JSONFormatter 输出 JSON 格式记录（见 logger_utils.py）
--use_js_renderer	实验性 JavaScript 渲染	属于实验功能，未进入当前稳定选项集
-q/--quality [k|p|h|m|l]	五档渲染质量，取代旧 -m/-l	见下文「质量档位」

五档渲染质量：-q/--quality

v0.1.0 用一个统一的 -q/--quality 标志替代了原先零散的 -m/-l 标志，可选值为 k|p|h|m|l（4K / 生产 / 高清 / 中 / 低）。这五个档位的分辨率与帧率定义至今仍完整保留在 manim/constants.py 的 QUALITIES 字典中：

标志	档位键	分辨率	帧率
k	fourk_quality	3840×2160	60
p	production_quality	2560×1440	60
h	high_quality	1920×1080	60
m	medium_quality	1280×720	30
l	low_quality	854×480	15

-q 选项的类型检查直接从 QUALITIES 生成（见 render_options.py），_determine_quality 会把单字母标志映射回完整档位键（见 manim/_config/utils.py）。注意：v0.1.0 中 --sound 标志被移除，而 frame_rate、pixel_height、pixel_width 在现在版本中已可独立覆盖质量档位（默认值在 manim/_config/default.cfg 中为 60 / 1080 / 1920）。

配置系统：manim.cfg 的诞生

v0.1.0 最重要的架构决策是实现了 manim.cfg 配置文件系统，把全局配置、命令行参数解析以及原先散落在 constants.py 中的常量统一收敛。

三级配置文件查找顺序

当前实现中，config_file_paths()（见 manim/_config/utils.py）按优先级从低到高返回三个位置：

1. 库级配置：manim/_config/default.cfg（必须存在，定义全部默认值）；
2. 用户级配置：Linux/macOS 下为 ~/.config/manim/manim.cfg，Windows 下为 AppData\Roaming\Manim\manim.cfg（可选）；
3. 目录级配置：当前工作目录下的 manim.cfg（可选，优先级最高，可覆盖前两者）。

make_config_parser() 先读取库级文件，再叠加用户级与目录级文件；--config_file 可以指定自定义文件并忽略目录级配置。示例场景目录中的 example_scenes/manim.cfg 就是目录级配置的真实用法——它只覆盖 [logger] 段的配色，其余全部继承默认值。

从常量到配置的迁移对照表

原始 changelog 列出了以下从 constants.py 迁移到配置系统的变量，这正是「配置即真相」设计的第一批落地：

旧常量	新配置项
FRAME_HEIGHT	config["frame_width"]
TOP	config["frame_height"] / 2 * UP
BOTTOM	config["frame_height"] / 2 * DOWN
LEFT_SIDE	config["frame_width"] / 2 * LEFT
RIGHT_SIDE	config["frame_width"] / 2 * RIGHT
self.camera.frame_rate	config["frame_rate"]

当前仓库中，config 是一个 ManimConfig 实例（MutableMapping 子类），作为全部可配置行为的单一数据源（见 manim/_config/utils.py），而 constants.py（manim/constants.py）仍保留方向向量、缓冲、默认时长等纯粹的常量定义，以及为 -q 服务的 QUALITIES 表。

配置管理的子命令结构

v0.1.0 引入了操作 .cfg 文件的子命令结构。如今这演变为 manim/cli/cfg/ 下的 manim cfg 命令组（如 manim cfg write、manim cfg show 等），配合 manim init（manim/cli/init/）可以生成并检查配置文件。命令本身基于 DefaultGroup 实现（见 manim/cli/default_group.py），它允许 manim 直接充当 manim render，这也是 manim render 文件.py 与 manim 文件.py 两种调用形式等价的原因。

Mobjects、Scene 与动画层级的增强

z_index：场景内对象深度控制

新增的 z_index 属性让用户可以直接控制对象在场景中的层级叠放，而不必依赖 add/remove 的顺序。该机制现内置于 manim/mobject/mobject.py 的对象排序逻辑中，配合 set_z_index 等链式方法使用，是组织复杂构图的基本工具。

VDict：像操作字典一样操作 Mobject 组

VDict 之于 VGroup，正如 dict 之于 list——它允许用键名访问、插入、删除子对象。类定义位于 manim/mobject/types/vectorized_mobject.py（class VDict(VMobject, ...)），并支持打印内部对象字典；VGroup 则在同文件中支持打印所包含对象的类名。

Matrix 的可定制括号与行着色

Matrix 新增了可定制的左右括号以及 set_row_colors 行着色方法。当前实现中，括号通过 left_bracket / right_bracket 参数指定，支持 (、)、\{、\}、\langle、\rangle 等 TeX 形式（见 manim/mobject/matrix.py），set_row_colors 则为矩阵各行批量着色，极大简化了线性代数讲解类动画的排版。

新增动画与对象类

• AddTexLetterByLetter：逐字母显现 TeX 文本的动画，现名 AddTextLetterByLetter，定义于 manim/animation/creation.py，继承自 ShowIncreasingSubsets；
• Variable：显示一个随 Python 变量值实时更新的文本对象，定义于 manim/mobject/text/numbers.py，配合 ValueTracker 使用可制作数值变化可视化；
• PangoText：基于 Pango 的文本渲染（对应今日的 PangoText 系，见 manim/mobject/text/text_mobject.py）；
• 标准缓动函数：rate_functions 模块（manim/utils/rate_functions.py）补齐了 smooth、ease_in_out 等全部标准缓动曲线。

API 风格转变

v0.1.0 删除了大量 get_/set_ 方法，改用实例属性与 property；Container 类变为抽象基类（不可直接实例化，需使用其子类）；Scene.render() 取代「实例化即渲染」的行为；ValueTracker 支持 += 运算符。这些改动奠定了后来 manim 链式调用与属性式 API 的基调。

命名重构：Tex 与 MathTex 取代旧对象

由于 TextMobject 与 TexMobject 的命名容易混淆（前者管文本、后者管 TeX，名字却长得很像），v0.1.0 将其弃用并引入 Tex 与 MathTex。弃用不是移除：旧对象仍可使用，但每次使用都会弹出 DeprecationWarning 提醒迁移。新的 Tex/MathTex 支持通过 template 关键字参数指定自定义 TexTemplate。

在 manim/mobject/text/tex_mobject.py 中，Tex 与 MathTex 目前实现为同一核心类 _Tex 的别名构造：MathTex 默认使用 \begin{align*} 数学环境，Tex 默认使用普通文本排版。模板机制由 manim/utils/tex_templates.py 中的 TexTemplate 类承载，包括预置的 tex_template、ctex_template（中文）等。示例场景 example_scenes/advanced_tex_fonts.py 展示了自定义模板的实际用法。

GraphScene 与 ThreeDScene 增强

v0.1.0 对 GraphScene 做了四项强化（这些能力在今天已并入 Axes/NumberPlane 体系，见 manim/mobject/graphing/coordinate_systems.py）：

• 坐标轴可添加箭头尖端；
• 坐标轴可在起始/结束处略微延长；
• 支持隐藏坐标轴；
• 支持高亮两条曲线之间的区域（对应 get_area 类功能）。

ThreeDScene 则新增了 3dillusion_camera_rotation，即「3D 视错觉旋转」——一种不改变投影方式、仅旋转相机营造 3D 感的技法，对应 manim/scene/three_d_scene.py 中 ThreeDScene 的相机控制能力。

场景缓存：partial_movie_file 增量渲染

v0.1.0 引入了场景缓存特性：如果某个 partial_movie_file（分段动画文件）对应的代码没有变化，则不会重复渲染。原始 changelog 坦率标注了该功能当时「高度不稳定，正在完善中」。

如今这一机制已成为核心性能设施：默认配置中 max_files_cached = 100、disable_caching = False（见 manim/_config/default.cfg），缓存基于场景/动画的 hash 比对（见 manim/utils/hashing.py），缓存目录由 partial_movie_dir = {video_dir}/partial_movie_files/{scene_name} 模板决定。测试端，tests/test_scene_rendering/test_caching_related.py 与 OpenGL 侧的 tests/test_scene_rendering/opengl/test_caching_related_opengl.py 持续守护该行为。

修复与工程化：v0.1.0 的「质量底稿」

主要修复

• 目录初始化逻辑移入 config.py，修复了一批与文件结构生成相关的 bug；
• 删除了失效的 media_dir.txt 文件，以及 scene_file_writer.py 中无用的 if 语句；
• 修复了「不指定场景时渲染示例场景会列出库中全部场景对象」的问题；
• 大量通用 Exception 替换为更具体的异常子类；
• 修复 ArcBetweenPoints 中的若干细微 bug（相关实现见 manim/mobject/geometry/arc.py）。

开发者侧约定

面向贡献者的变更同样塑造了今日项目形态：

• 使用 black 强制统一 Python 代码格式（配置见 pyproject.toml）；
• PR 合并前需获得两位社区开发者的 approving review；
• 引入基于 GitHub CI + pytest 的自动化测试，确保提交间不破坏既有功能——这正是 tests/ 目录庞大测试集的开端；
• 引入 sphinx + autodoc/autosummary 自动生成 API 文档（见 docs/source/conf.py），并新增贡献指南 CONTRIBUTING.md；
• 库内部改用相对导入；
• 提供日志测试工具，并支持以 JSON 格式保存日志（JSONFormatter，见 manim/_config/logger_utils.py）；
• 包管理迁移到 Poetry（今日项目已进一步使用 uv，见 uv.lock）；
• 颜色从字符串常量迁移为 Enum（当前为 ManimColor 体系，见 manim/utils/color/core.py）。

结语：从 changelog 看 manim 的成长脉络

回看 v0.1.0 的 changelog，可以清晰辨认出 manim 社区版今日架构的几乎所有雏形：manim.cfg 三级配置、rich 日志、-q 质量档、Tex/MathTex 命名体系、场景缓存、pytest 测试矩阵。这份发布说明不仅是版本历史的一页，更是一份「如何把一个个人项目工程化、社区化」的范本。理解这些条目在源码中的落点，能帮你更准确地使用配置系统、排查 CLI 行为差异，并在编写扩展时遵循社区确立的 API 约定。