Manim v0.18.0 版本发布解析：颜色系统重构、checkhealth 诊断命令与 LaTeX 清理等核心变更
【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim
Manim v0.18.0 于 2023 年 11 月 11 日发布，是社区维护版 Manim 中一个承上启下的重要版本：它完成了颜色系统从colour第三方库到内置ManimColor类的整体迁移，新增了manim checkhealth安装诊断子命令，引入 LaTeX 辅助文件自动清理机制，并正式支持 Python 3.12。读完本文，你将完整了解该版本 59 个已合并 PR 的分类变更脉络（破坏性变更、新功能、增强、缺陷修复、文档与测试改进），并能结合仓库源码定位每项变更的实现位置，为从旧版本迁移代码、排查渲染问题提供依据。
版本概况：41 位贡献者，59 个合并的 PR
v0.18.0 共有 41 位贡献者参与（其中 22 位是首次提交补丁，即名字后带+的贡献者），22 位贡献者参与了补丁评审，共合并 59 个 pull request。变更记录原文见 0.18.0-changelog.rst，同一目录下还有从 0.17.3-changelog.rst 到 0.21.0-changelog.md 的完整历史版本记录可供追溯。
从当前仓库状态看，该版本确立的多项能力至今仍是 Manim 的组成部分：pyproject.toml 中声明了requires-python = ">=3.11"，说明当前主线已站在 0.18.0 引入的 Python 3.12 支持之上继续演进。
破坏性变更：颜色系统的整体重写
v0.18.0 唯一的破坏性变更是 PR #3020 —— 重写了 Manim 的颜色系统：
- 移除了
colour库这一第三方依赖； - 用新增的
ManimColor类取代了内部的颜色处理方式； - 一次性内置了数百种预定义颜色，详见
manim.utils.color模块。
只有此前直接操作过colour模块的用户才会遇到兼容问题，通用接口保持稳定。
从当前仓库源码可以印证这一设计的落地：
ManimColor类定义在 manim/utils/color/core.py（L108 起的class ManimColor）；- 预定义色板被组织为
manim/utils/color/目录下的多个数据文件，包括 X11.py、XKCD.py、SVGNAMES.py、DVIPSNAMES.py、AS2700.py 与 BS381.py，分别对应 X11/CSS 色名、XKCD 色名、SVG 标准色名、DVI 颜色名以及 AS2700 与 BS381 两套英国工业标准色号体系； - 颜色字段的类型定义也收敛到了
manim/typing.py中的类型别名（如ManimColorDType、FloatRGB、FloatHSV、FloatHSVA等），这与后文介绍的新manim.typing模块一脉相承。
对用户的实际意义是：现在可以用ManimColor("X11:Tomato")这类带色板前缀的字符串来引用内置色，而不再需要安装额外的colour包。相关用法测试可参考 tests/module/utils/test_color.py 与 tests/module/utils/test_manim_color.py。
亮点功能一：manim checkhealth安装诊断子命令
PR #3299 新增了manim checkhealth（或等价地python -m manim checkhealth）子命令，用于检查本地安装是否正确配置、必需与可选的依赖是否可用。
命令的输出与交互流程
实现位于 manim/cli/checkhealth/commands.py。从源码看，它的执行流程是：
- 打印当前 Python 解释器路径（
sys.executable），并提示开始健康检查； - 遍历注册的所有检查项（
HEALTH_CHECKS列表），逐项输出结果：PASSED（绿色）、FAILED（红色）或SKIPPED（蓝色，当它所依赖的前置检查失败时）； - 若存在失败项，逐条打印对应的修复建议（
recommendation），并在两条建议之间暂停确认； - 若全部通过，还会交互式询问是否渲染一个测试场景。测试场景会依次播放
ManimBanner的创建与展开动画、写入文本与公式，并关闭缓存、开启预览，最后用timeit报告渲染耗时——这本身就覆盖了 Cairo 渲染器、字体、LaTeX 与音频预览的端到端链路。
内置的四项检查
具体检查项定义在 manim/cli/checkhealth/checks.py，通过@healthcheck装饰器注册（装饰器会向函数附加description、recommendation、skip_on_failed、post_fail_fix_hook等元数据并追加到HEALTH_CHECKS列表）。当前内置四项：
| 检查项 | 验证内容 | 失败时的建议 |
|---|---|---|
is_manim_on_path | shutil.which("manim")能否找到命令 | 用python -m manim替代，或按 pip 安装警告修改 PATH |
is_manim_executable_associated_to_this_library | manim可执行文件内容是否指向manim.__main__（兼容 uv 工具的.__script__.py伴生脚本与 Windows batch 文件），排除 manimgl/manimlib 的同名命令 | 用python -m manim或pip install --upgrade --force-reinstall manim重装 |
is_latex_available | latex命令在 PATH 中且可执行 | 安装 LaTeX 发行版 |
is_dvisvgm_available | dvisvgm命令在 PATH 中且可执行（依赖is_latex_available，前置失败则跳过） | 确认 LaTeX 发行版包含 dvisvgm，必要时安装更大的发行版 |
这里的skip_on_failed机制值得注意：dvisvgm 检查在 latex 检查失败时会自动跳过，避免输出误导性错误。CLI 命令的注册入口在 manim/cli/default_group.py，将checkhealth挂到主命令组下。
亮点功能二：文档示例可直接在 Binder 中运行
PR #3427 让官方文档中的示例代码支持“Make interactive”按钮：点击后通过 Jupyter Binder 建立连接，可以在浏览器中直接修改示例代码并重新渲染。仓库的静态资源 docs/source/_static/manim-binder.min.js 即该功能的捆绑脚本，docs/source/_static/manim-binder.min.js.LICENSE.txt 记录其依赖许可。这个特性把“文档示例”从只读代码变成了可交互的实验环境。
亮点功能三：新增manim.typing类型提示模块
PR #3086 引入了专门的manim.typing模块，用于集中定义代码库使用的类型别名，并为大量核心代码补充类型标注。
当前仓库中的 manim/typing.py 有约 1000 行，其文件头注释说明了开发约定：源码中形如[CATEGORY]\n<category_name>的字符串块会被文档构建工具自动识别，其下的类型别名会被归类到相应类别中渲染到参考文档。从模块的__all__看，它系统性地组织了：
- 数值与颜色类型：
ManimFloat、ManimInt、ManimColorDType； - 各类颜色向量类型：
FloatRGB/IntRGB/FloatRGBA/FloatHSV/FloatHSL/FloatHSVA及其Like、_Array变体（区分“单个标量/序列”与“数组”两种形态）； - 点与向量类型：
Point2D、Point3D、PointND、Vector2D、Vector3D、VectorND及各自的Like/_Array变体； - 与颜色重写直接相关的
ManimColorInternal等内部类型。
这类模块让 IDE 与静态检查工具（配合 mypy.ini）能给出更精确的报错，例如把(float, float, float)误写为np.ndarray这类错误会在类型层面被暴露。
亮点功能四：LaTeX 辅助文件自动清理（默认开启）
PR #3322 实现了 LaTeX 编译产物（.aux、.dvi等辅助文件）的自动删除，默认启用，可通过两种方式关闭：
- 配置项：
no_latex_cleanup，默认值为False。该键在 manim/_config/utils.py 中注册，并带有类型检查的 property（L989 起的no_latex_cleanupgetter/setter，写入时会校验布尔类型）； - 命令行标志：
--no_latex_cleanup，定义在 manim/cli/render/global_options.py（L118 起）。
清理动作的实际执行点在 manim/utils/tex_file_writing.py：LaTeX 编译完成后，函数检查if not config["no_latex_cleanup"]（L71 附近），满足条件则删除本次编译产生的临时文件。这一机制的意义在于：渲染大量Tex/MathTex公式的场景不再会在工作目录留下成堆的.aux/.dvi垃圾文件，而需要保留中间产物用于调试时，加一个标志即可关闭。测试侧的用法可见 tests/module/mobject/text/test_texmobject.py（L354 处通过config.no_latex_cleanup = True临时禁用清理以便断言文件状态）。
Python 3.12 支持
PR #3395 添加了对 Python 3.12 的支持。结合 PR #3350（补齐typing-extensions依赖）与 pyproject.toml 中当前的requires-python = ">=3.11"，可以确认 0.18.0 之后 Manim 的 Python 支持窗口已整体上移——使用 3.12 解释器安装本版本时，typing-extensions会被自动随依赖安装，无需手动处理。
新功能：三个 SmoothStep 速率函数
PR #3361 基于 SmoothStep 函数族新增了三个速率函数：smoothstep、smootherstep、smoothererstep，实现位于 manim/utils/rate_functions.py（L164-L188）：
@unit_interval def smoothstep(t: float) -> float: """Implementation of the 1st order SmoothStep sigmoid function. The 1st derivative (speed) is zero at the endpoints. """ return 3 * t**2 - 2 * t**3 @unit_interval def smootherstep(t: float) -> float: """Implementation of the 2nd order SmoothStep sigmoid function. The 1st and 2nd derivatives (speed and acceleration) are zero at the endpoints. """ return 6 * t**5 - 15 * t**4 + 10 * t**3 @unit_interval def smoothererstep(t: float) -> float: """Implementation of the 3rd order SmoothStep sigmoid function. The 1st, 2nd and 3rd derivatives (speed, acceleration and jerk) are zero at the endpoints. """ return 35 * t**4 - 84 * t**5 + 70 * t**6 - 20 * t**7三者的区别体现在端点处的高阶导数：smoothstep仅保证端点速度为 0，smootherstep进一步保证端点加速度为 0，smoothererstep则连“加加速度”（jerk）都平滑归零。动画的观感差异在于起步与收尾的“柔顺程度”逐级递增。@unit_interval装饰器保证输入被约束在 [0, 1] 区间。这三个函数已被加入模块的__all__导出列表（L91-L93），可在任何Animation的rate_func参数中使用，例如self.play(Write(tex), rate_func=smoothstep)。速率函数的既有测试可参考 tests/module/utils/test_iterables.py 所在测试目录及图形化测试 tests/test_graphical_units/test_speed.py。
新功能：LabeledLine与LabeledArrow
PR #3264 新增了两个几何 mobject：LabeledLine和LabeledArrow，实现位于 manim/mobject/geometry/labeled.py。
从源码看，该模块实际还包含一个底层类Label和一个后续版本补充的LabeledPolygram。Label把标签文本渲染为MathTex（字符串输入）或直接接收MathTex/Text/Typst实例，并叠加BackgroundRectangle背景框与SurroundingRectangle边框，形成“带底色的标签块”。LabeledLine的关键参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
label | 必填 | 标签文本（字符串则按MathTex渲染）或标签 mobject |
label_position | 0.5 | 标签沿线段的位置比例，取值 [0, 1] |
label_config | None | 传给标签 mobject 的配置字典（仅字符串标签生效） |
box_config | None | 背景框配置，默认buff=0.05、fill_opacity=1、stroke_width=0.5 |
frame_config | None | 边框配置，默认buff=0.05、stroke_width=0.5 |
定位算法很直接：取label_position比例处的点(line_end - line_start) * label_position + line_start，将标签移动到该坐标后self.add(self.label)。LabeledArrow则通过多重继承LabeledLine, Arrow复用全部标签逻辑。文档字符串中给出的示例可以直接复制运行：
class LabeledLineExample(Scene): def construct(self): line = LabeledLine( label='0.5', label_position=0.8, label_config={"font_size": 20}, start=LEFT + DOWN, end=RIGHT + UP, ) line.set_length(line.get_length() * 2) self.add(line)典型用途是在数轴、线段比例图解上给线段本身打“长度标签”，标签会自动覆盖在线条上（带背景框保证可读性），无需手动next_to对齐。
增强：DecimalNumber的数值与单位间距
PR #3366 为DecimalNumber增加unit_buff_per_font_unit关键字参数（默认0，保持向后兼容），设为正数后会在数字与单位符号之间加入额外间距，且间距随字号缩放。实现见 manim/mobject/text/numbers.py：L44-L46 的文档说明“unit_buff_per_font_unit=0.003是一个不错的取值”，L179 处将其与digit_buff_per_font_unit相加作为单位符号的buff使用。
# 例如：让 “9.8 m/s²” 中数字和单位之间留出呼吸空间 DecimalNumber(9.8, num_decimal_places=1, unit=mtext("m/s$^2$"), unit_buff_per_font_unit=0.003)默认值0意味着旧代码渲染结果完全不变，仅在显式设置时才产生视觉差异——这是典型的非破坏性增强。
缺陷修复清单（14 项）
v0.18.0 修复的 bug 按 PR 编号完整列出如下，每条都值得在升级时逐一核对是否命中你踩过的坑：
| PR | 修复内容 | 影响面 |
|---|---|---|
| #3205 | 修正Arc的angle类型标注 | 静态检查 |
| #3210 | 修复DecimalNumber(show_ellipsis=True)在 OpenGL 渲染器下的表现 | OpenGL 渲染 |
| #3211 | 修复Axes自定义标签在 OpenGL 渲染器下的显示问题 | OpenGL 渲染 |
| #3298 | 修复ManimBanner的 expand 动画 | 动画正确性 |
| #3306 | 修复Scene.interactive_embed场景的 IPython 终端历史与内嵌 shell 实例化问题 | 交互开发 |
| #3315 | 修正Scene.add_subcaption的参数类型 | API 类型 |
| #3423 | 修复多部分Texmobject 的子 mobject 数量计算错误，解决了如MathTex("1", "^{", "0")这类公式显示不完整的系列问题 | 公式渲染 |
| #3284 | 修复 Jupyter 笔记本中LinearTransformationSceneExample的运行 | Jupyter 集成 |
| #3302 | 修复OpenGLVMobject.interpolate中比较运算的笔误 | OpenGL 渲染 |
| #3340 | 修复旋转后的ImageMobject边界框计算错误 | 图像 mobject |
| #3343 | 修正TexTemplate.add_to_preamble与add_to_document的返回值 | LaTeX 模板 |
| #3282 | 确保ArrowVectorField.get_vector不修改传入的输入参数 | 副作用消除 |
| #3392 | 修复NumberLine拉长刻度线（elongated tick lines）的行为 | 数轴 |
| #3430 | 修复文档构建时 CSV reader 在渲染汇总中加入空列表的问题 | 文档流水线 |
| #3404 | 空输入传给AddTextLetterByLetter时正确抛出异常 | 错误处理 |
其中 #3423 是典型的多部分Tex拼接缺陷：分段传入 LaTeX 片段时子 mobject 计数错误导致部分字符“丢失”，升级到 0.18.0 可解决。图形化回归测试可对照 tests/test_graphical_units/control_data 下的.npz基准数据。
文档相关变更（11 项）
- #3219：为指向文档的链接启用社交卡片（social cards）；
- #3274：将文档中错误提及的“最低支持 Python 3.7”更正；
- #3297：改进
ArrowTip的箭头样式展示示例； - #3312：为
always_redraw函数补充文档； - #3218：改进 deep dive 指南 的语法表述；
- #3251：新增 Fedora 系统的 LaTeX 安装说明（见 docs/source/installation 相关文档）；
- #3290：更新 macOS 安装所需的依赖清单；
- #3325：为
mobject_update_utils中的always_rotate、always_shift、turn_animation_into_updater补充 docstring 与类型标注（对应 manim/animation/updaters/mobject_update_utils.py）； - #3353：补充
Mobject.center方法文档； - #3355：在 ReadTheDocs 上临时启用
htmlzip构建； - #3377：修复 deep dive 指南中的错别字；
- #3389：移除某 LaTeX 表达式中多余的定界符；
- #3417：用“将可下载文档附加到 GitHub Release”的 workflow 取代 ReadTheDocs 的 htmlzip 构建。
测试系统与代码质量改进
测试系统（#3416、#3257、#3419）：修复测试在 Cairo 1.18.0 下的运行问题；修正 poetry 相关配置错误；修复 CI runner 上 Cairo 构建的缓存。这些保证 CI 在新旧系统库环境下行为一致。
代码质量与重构（14 项，择要说明）：
- #3229：使 docbuild（文档构建）错误更易调试，并修复异常类变更导致的报错（相关工具在 manim/utils/docbuild 目录）；
- #3231：修复
flake8报告的静态检查问题； - #3286：优化
Axes.coords_to_point——坐标到屏幕点的换算在绘制大量数据点时是热点路径，优化对性能敏感场景有益； - #3224：把剩余
os.path用法替换为pathlib.Path； - #3236：
AbstractImageMobject.set_resampling_algorithm返回self，支持链式调用； - #3350：补齐缺失依赖
typing-extensions（配合 Python 3.12 支持）； - #3253/#3272/#3287/#3431/#3433/#3399/#3397：一系列依赖与 GitHub Actions 的版本升级（tornado 6.3.1→6.3.2、docker/build-push-action 3→4、cryptography 41.0.1→41.0.2、setup-texlive-action 2→3 等）；
- #3405：升级 manimpango 版本以修复类型严格性相关的错误；
- #3421：改进树状图创建时的输入检查顺序（见 manim/mobject/graph.py 的
TreeGraph相关逻辑）。
版本小结与升级建议
v0.18.0 以一次有意的破坏性变更（颜色系统）为核心，辅以诊断工具（checkhealth）、开发体验（manim.typing、Binder 交互示例、Python 3.12）与工程质量（LaTeX 清理、依赖治理）三条线。升级时的关注点：
- 迁移检查：若代码中直接
import colour或调用其 API，需改用ManimColor（manim.utils.color），这是唯一可能破坏兼容的改动； - 环境诊断：升级后先跑
manim checkhealth，快速确认 PATH、LaTeX、dvisvgm 等系统依赖状态； - 工作目录：默认开启的 LaTeX 清理会让临时目录更干净；调试 LaTeX 编译过程时记得加
--no_latex_cleanup； - 视觉回归：
DecimalNumber单位间距、Axes换算等改动均为默认行为不变或修复类，正常场景无需调整。
完整的原始变更记录以 RST 格式保留在 docs/source/changelog/0.18.0-changelog.rst，可配合 docs/source/changelog.rst 索引查阅全部历史版本。
【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
