回到顶部

Manim配置¶

完整名称: manim.\_config.utils.ManimConfig

class ManimConfig[source]¶

基类: MutableMapping

类似字典的类，用于存储所有配置选项。

全局 config 对象是此类的实例，是库所有可定制行为的单一真实来源。

全局 config 对象能够消化不同类型的来源并将其转换为统一的接口。这些来源（按优先级升序）包括：配置文件、命令行参数和程序化更改。无论用户选择如何设置配置选项，她都可以使用 ManimConfig 的属性和特性来访问其当前值。

注意

每个配置选项都作为此类的特性实现。

每个配置选项都可以通过配置文件设置，使用属性的全名。如果配置选项有相关的 CLI 标志，则该标志等于属性的全名。那些支持替代标志或根本没有标志的选项在单独的属性文档字符串中进行了说明。

示例

为了演示目的，我们在以下示例中使用了全局配置对象的副本；如果您确实想修改配置，可以跳过这些行并直接导入 config。

>>> from manim import config as global_config
>>> config = global_config.copy()

每个配置选项都允许使用字典语法和属性语法。例如，以下两行是等效的：

>>> from manim import WHITE
>>> config.background_color = WHITE
>>> config["background_color"] = WHITE

推荐使用前者；后者主要是为了向后兼容而提供。

配置选项旨在保持内部一致性。例如，设置 frame_y_radius 将影响 frame_height。

>>> config.frame_height
8.0
>>> config.frame_y_radius = 5.0
>>> config.frame_height
10.0

有多种与配置选项交互的方式。以配置选项 background_color 为例。有三种方法可以更改它：通过配置文件、通过 CLI 标志或通过程序。

要通过配置文件设置背景颜色，请保存以下包含以下内容的 manim.cfg 文件。

[CLI]
background_color = WHITE

为了使此 .cfg 文件应用于 Manim 场景，它需要与脚本放置在同一目录中，

project/
├─scene.py
└─manim.cfg

现在，当用户执行

manim scene.py

场景的背景将设置为 WHITE。无论从何处调用 Manim 命令，这都适用。

命令行参数会覆盖 .cfg 文件。在前面的示例中，执行

manim scene.py -c BLUE

将把背景颜色设置为蓝色，而不管 manim.cfg 的内容如何。

最后，场景脚本本身中进行的任何程序化更改都将覆盖命令行参数。例如，如果 scene.py 包含以下内容：

from manim import *

config.background_color = RED

class MyScene(Scene): ...

背景颜色将设置为红色，而不管 manim.cfg 的内容或调用 Manim 时使用的 CLI 参数如何。

方法

`复制`	深度复制此 ManimConfig 的内容。
`处理参数`	处理 CLI 参数中存在的配置选项。
`处理文件`	处理 `.cfg` 文件中存在的配置选项。
`处理解析器`	处理 `ConfigParser` 对象中存在的配置选项。
`获取目录`	解析存储目录的配置选项。
`解析电影文件扩展名`
`更新`	处理在另一个 `ManimConfig` 或字典中找到的选项。

属性

`宽高比`	像素宽高比（宽度 / 高度）（--resolution, -r）。
`资产目录`	定位视频资产的目录（无标志）。
`背景颜色`	场景的背景颜色（-c）。
`背景不透明度`	一个介于 0.0（完全透明）和 1.0（完全不透明）之间的数字。
`底部`	帧中心底部的坐标。
`自定义文件夹`	是否使用自定义文件夹输出。
`禁用缓存`	是否使用场景缓存。
`禁用缓存警告`	如果子对象太多而无法哈希，是否发出警告。
`空运行`	是否启用空运行。
`启用GUI`	启用图形用户界面交互。
`启用线框模式`	是否在 OpenGL 中启用线框调试模式。
`ffmpeg日志级别`	ffmpeg 的详细程度级别（无标志）。
`刷新缓存`	是否删除所有缓存的部分电影文件。
`强制窗口`	使用 OpenGL 渲染器时是否强制显示窗口。
`格式`	文件格式；“png”、“gif”、“mp4”、“webm”或“mov”。
`帧高度`	逻辑单位中的帧高度（无标志）。
`帧率`	每秒帧数。
`帧大小`	（像素宽度，像素高度）元组（无标志）。
`帧宽度`	逻辑单位中的帧宽度（无标志）。
`帧X半径`	帧宽度的一半（无标志）。
`帧Y半径`	帧高度的一半（无标志）。
`从动画编号开始`	从该编号开始渲染动画（-n）。
`全屏`	将窗口扩展到最大可能尺寸。
`GUI位置`	启用图形用户界面交互。
`图像目录`	放置图像的目录（无标志）。
`输入文件`	输入文件名。
`左侧`	帧中左侧的坐标。
`日志目录`	放置日志的目录。
`日志写入文件`	是否将日志保存到文件。
`最大缓存文件数`	最大缓存文件数。
`媒体目录`	主要输出目录。
`媒体嵌入`	是否在 Jupyter Notebook 中嵌入视频。
`媒体宽度`	Jupyter Notebook 中的媒体宽度。
`电影文件扩展名`	可以是 .mp4、.webm 或 .mov。
`不清理LaTeX`	防止删除由 Tex 和 MathTex 生成的 .aux、.dvi 和 .log 文件。
`通知过时版本`	是否有可用版本更新时通知。
`输出文件`	输出文件名（-o）。
`部分电影目录`	放置部分电影文件的目录（无标志）。
`像素高度`	像素高度（--resolution, -r）。
`像素宽度`	像素宽度（--resolution, -r）。
`插件`	要启用的插件列表。
`预览`	是否播放渲染的电影（-p）。
`预览命令`
`进度条`	渲染动画时是否显示进度条。
`质量`	视频质量（-q）。
`渲染器`	当前活动的渲染器。
`右侧`	帧中右侧的坐标。
`保存为GIF`	是否将渲染的场景保存为 .gif 格式（-i）。
`保存最后一帧`	是否将场景的最后一帧保存为图像文件（-s）。
`保存PNG`	是否将场景中的所有帧保存为图像文件（-g）。
`保存章节`	除了电影文件外，是否为每个章节保存单独的视频。
`场景名称`	要从文件中播放的场景。
`章节目录`	放置章节视频的目录（无标志）。
`在文件浏览器中显示`	是否在文件浏览器中显示输出文件（-f）。
`Tex目录`	放置 Tex 文件的目录（无标志）。
`Tex模板`	渲染 Tex 时使用的模板。
`Tex模板文件`	从中读取 Tex 模板的文件（无标志）。
`文本目录`	放置文本的目录（无标志）。
`顶部`	帧中心顶部的坐标。
`透明`	背景不透明度是否小于 1.0（-t）。
`直到动画编号`	在此编号停止渲染动画。
`使用投影填充着色器`	为 OpenGLVMobject 填充使用与变换矩阵兼容的着色器。
`使用投影描边着色器`	为 OpenGLVMobject 描边使用与变换矩阵兼容的着色器。
`详细程度`	日志记录器详细程度；“DEBUG”、“INFO”、“WARNING”、“ERROR”或“CRITICAL”（-v）。
`视频目录`	放置视频的目录（无标志）。
`窗口显示器`	场景将在其上渲染的显示器。
`窗口位置`	设置预览窗口的位置。您可以使用方向，例如 UL/DR/ORIGIN/LEFT…或者窗口左上角的像素位置，例如“960,540”。
`窗口大小`	OpenGL 窗口的大小。“default”表示根据显示器自动缩放窗口。
`写入全部`	是否渲染输入文件中的所有场景（-a）。
`写入电影`	是否将场景渲染为电影文件（-w）。
`零填充`	PNG 零填充。一个介于 0（无零填充）和 9（至少 9 列）之间的数字。

_set_between(key, val, lo, hi)[source]¶

如果 lo <= val <= hi，则将 key 设置为 val。

参数:

key (str)
val (float)
lo (float)
hi (float)

返回类型:

无

_set_boolean(key, val)[source]¶

如果 val 是布尔值，则将 key 设置为 val。

参数:

key (str)
val (Any)

返回类型:

无

_set_from_enum(key, enum_value, enum_class)[source]¶

将 key 设置为在给定 enum_class 中具有值 enum_value 的枚举对象。

测试

>>> from enum import Enum
>>> class Fruit(Enum):
...     APPLE = 1
...     BANANA = 2
...     CANTALOUPE = 3
>>> test_config = ManimConfig()
>>> test_config._set_from_enum("fruit", 1, Fruit)
>>> test_config._d['fruit']
<Fruit.APPLE: 1>
>>> test_config._set_from_enum("fruit", Fruit.BANANA, Fruit)
>>> test_config._d['fruit']
<Fruit.BANANA: 2>
>>> test_config._set_from_enum("fruit", 42, Fruit)
Traceback (most recent call last):
...
ValueError: 42 is not a valid Fruit

参数:

key (str)
enum_value (Any)
enum_class (EnumMeta)

返回类型:

无

_set_from_list(key, val, values)[source]¶

如果 val 包含在 values 中，则将 key 设置为 val。

参数:

key (str)
val (Any)
values (list[Any])

返回类型:

无

_set_int_between(key, val, lo, hi)[source]¶

如果 lo <= val <= hi，则将 key 设置为 val。

参数:

key (str)
val (int)
lo (int)
hi (int)

返回类型:

无

_set_pos_number(key, val, allow_inf)[source]¶

如果 val 是正整数，则将 key 设置为 val。

参数:

key (str)
val (int)
allow_inf (bool)

返回类型:

无

_set_str(key, val)[source]¶

如果 val 是字符串，则将 key 设置为 val。

参数:

key (str)
val (Any)

返回类型:

无

property aspect_ratio: int¶: 像素宽高比（宽度/高度）（--resolution, -r）。

property assets_dir: str¶: 定位视频资产的目录（无标志）。

property background_color: ManimColor¶: 场景的背景颜色（-c）。

property background_opacity: float¶: 一个介于 0.0（完全透明）和 1.0（完全不透明）之间的数字。

property bottom: Vector3D¶: 帧中心底部的坐标。

copy()[source]¶

深度复制此 ManimConfig 的内容。

返回:: 此对象的一个不包含共享引用的副本。
返回类型:: ManimConfig

另请参阅

tempconfig()

注意

这是 tempconfig() 背后的主要机制。

property custom_folders: str¶: 是否使用自定义文件夹输出。

digest_args(args)[source]¶

处理 CLI 参数中存在的配置选项。

参数:: args (argparse.Namespace) – main_utils.parse_args() 返回的对象。
返回:: self – 处理 parser 内容后的此对象。
返回类型:: ManimConfig

另请参阅

main_utils.parse_args(), digest_parser(), digest_file()

注意

如果 args.config_file 是一个非空字符串，则 ManimConfig 会在处理任何其他 CLI 参数之前尝试使用 digest_file() 处理该文件的内容。

digest_file(filename)[source]¶

处理 .cfg 文件中存在的配置选项。

此方法处理单个 .cfg 文件，而 digest_parser() 可以处理任意解析器，这些解析器可能由多个 .cfg 文件构建而成。

参数:: filename (StrPath) – .cfg 文件的路径。
返回:: self – 处理 filename 内容后的此对象。
返回类型:: ManimConfig

另请参阅

digest_file(), digest_args(), make_config_parser()

注意

如果存在多个 .cfg 文件要处理，那么总是更高效的做法是先将它们解析到一个单个的 ConfigParser 对象中，然后通过一次调用 digest_parser() 来处理它们，而不是多次调用此方法。

digest_parser(parser)[source]¶

处理 ConfigParser 对象中存在的配置选项。

此方法处理任意解析器，而不仅仅是从单个文件读取的解析器，而 digest_file() 每次只能处理一个文件。

参数:: parser (configparser.ConfigParser) – 一个反映一个或多个 .cfg 文件内容的对象。特别是，它可能反映了以级联方式解析的多个文件的内容。
返回:: self – 处理 parser 内容后的此对象。
返回类型:: ManimConfig

另请参阅

make_config_parser(), digest_file(), digest_args()

注意

如果存在多个 .cfg 文件要处理，那么总是更高效的做法是先将它们解析到一个单个的 ConfigParser 对象中，然后调用此函数一次（而不是多次调用 digest_file()）。

示例

要处理两个文件中设置的配置选项，首先创建一个 ConfigParser 并解析这两个文件，然后处理该解析器。

parser = configparser.ConfigParser()
parser.read([file1, file2])
config = ManimConfig().digest_parser(parser)

实际上，全局 config 对象是这样初始化的：

parser = make_config_parser()
config = ManimConfig().digest_parser(parser)

property disable_caching: bool¶: 是否使用场景缓存。

property disable_caching_warning: bool¶: 如果子对象太多而无法哈希，是否发出警告。

property dry_run: bool¶: 是否启用空运行。

property enable_gui: bool¶: 启用图形用户界面交互。

property enable_wireframe: bool¶: 是否在 OpenGL 中启用线框调试模式。

property ffmpeg_loglevel: str¶: ffmpeg 的详细程度级别（无标志）。

property flush_cache: bool¶: 是否删除所有缓存的部分电影文件。

property force_window: bool¶: 使用 OpenGL 渲染器时是否强制显示窗口。

property format: str¶: 文件格式；“png”、“gif”、“mp4”、“webm”或“mov”。

property frame_height: float¶: 逻辑单位中的帧高度（无标志）。

property frame_rate: float¶: 每秒帧数。

property frame_size: tuple[int, int]¶: （像素宽度，像素高度）元组（无标志）。

property frame_width: float¶: 逻辑单位中的帧宽度（无标志）。

property frame_x_radius: float¶: 帧宽度的一半（无标志）。

property frame_y_radius: float¶: 帧高度的一半（无标志）。

property from_animation_number: int¶: 从该编号开始渲染动画（-n）。

property fullscreen: bool¶: 将窗口扩展到最大可能尺寸。

get_dir(key, **kwargs)[source]¶

解析存储目录的配置选项。

存储目录的配置选项可能相互依赖。此方法用于向最终用户提供实际目录。

参数:

key (str) – 要解析的配置选项。必须是以 '_dir' 结尾的选项，例如 'media_dir' 或 'video_dir'。
kwargs (Any) – 解析目录时要使用的任何字符串。

返回:

请求目录的路径。如果路径解析为空字符串，则返回 None。

返回类型:

pathlib.Path

抛出:

KeyError – 当 key 不是存储目录的配置选项，因此 get_dir() 不适用时；或者当 key 适用但没有足够信息来解析目录时。

注意

使用标准 str.format() 语法解析路径，因此路径可能包含使用 f-string 符号的任意占位符。然而，这需要 kwargs 包含所需的值。

示例

默认情况下，config.tex_dir 的值为 '{media_dir}/Tex'，即它是 config.media_dir 所在位置的子文件夹。要获取实际目录，请使用 get_dir()。

>>> from manim import config as globalconfig
>>> config = globalconfig.copy()
>>> config.tex_dir
'{media_dir}/Tex'
>>> config.media_dir
'./media'
>>> config.get_dir("tex_dir").as_posix()
'media/Tex'

目录解析以惰性方式完成，在最后一个可能的时刻进行，以反映其他配置选项中的任何更改。

>>> config.media_dir = "my_media_dir"
>>> config.get_dir("tex_dir").as_posix()
'my_media_dir/Tex'

某些目录依赖于 ManimConfig 无法获得的信息。例如，video_dir 的默认值包括输入文件名和视频质量（例如 480p15）。此信息必须通过 kwargs 提供。

>>> config.video_dir
'{media_dir}/videos/{module_name}/{quality}'
>>> config.get_dir("video_dir")
Traceback (most recent call last):
KeyError: 'video_dir {media_dir}/videos/{module_name}/{quality} requires the following keyword arguments: module_name'
>>> config.get_dir("video_dir", module_name="myfile").as_posix()
'my_media_dir/videos/myfile/1080p60'

请注意，质量不需要作为关键字参数传递，因为 ManimConfig 确实存储了有关质量的信息。

目录可以递归定义。例如，配置选项 partial_movie_dir 依赖于 video_dir，而 video_dir 又依赖于 media_dir。

>>> config.partial_movie_dir
'{video_dir}/partial_movie_files/{scene_name}'
>>> config.get_dir("partial_movie_dir")
Traceback (most recent call last):
KeyError: 'partial_movie_dir {video_dir}/partial_movie_files/{scene_name} requires the following keyword arguments: scene_name'
>>> config.get_dir(
...     "partial_movie_dir", module_name="myfile", scene_name="myscene"
... ).as_posix()
'my_media_dir/videos/myfile/1080p60/partial_movie_files/myscene'

使用标准的 f-string 语法。定义目录时可以使用任意名称，只要将相应的值通过 kwargs 传递给 ManimConfig.get_dir() 即可。

>>> config.media_dir = "{dir1}/{dir2}"
>>> config.get_dir("media_dir")
Traceback (most recent call last):
KeyError: 'media_dir {dir1}/{dir2} requires the following keyword arguments: dir1'
>>> config.get_dir("media_dir", dir1="foo", dir2="bar").as_posix()
'foo/bar'
>>> config.media_dir = "./media"
>>> config.get_dir("media_dir").as_posix()
'media'

property gui_location: tuple[Any]¶: 启用图形用户界面交互。

property images_dir: str¶: 放置图像的目录（无标志）。请参阅 ManimConfig.get_dir()。

property input_file: str¶: 输入文件名。

property left_side: Vector3D¶: 帧中左侧的坐标。

property log_dir: str¶: 放置日志的目录。请参阅 ManimConfig.get_dir()。

property log_to_file: bool¶: 是否将日志保存到文件。

property max_files_cached: int¶: 最大缓存文件数。使用 -1 表示无限（无标志）。

property media_dir: str¶: 主要输出目录。请参阅 ManimConfig.get_dir()。

property media_embed: bool¶: 是否在 Jupyter Notebook 中嵌入视频。

property media_width: str¶: Jupyter Notebook 中的媒体宽度。

property movie_file_extension: str¶: 可以是 .mp4、.webm 或 .mov。

property no_latex_cleanup: bool¶: 防止删除由 Tex 和 MathTex 生成的 .aux、.dvi 和 .log 文件。

property notify_outdated_version: bool¶: 是否有可用版本更新时通知。

property output_file: str¶: 输出文件名（-o）。

property partial_movie_dir: str¶: 放置部分电影文件的目录（无标志）。请参阅 ManimConfig.get_dir()。

property pixel_height: int¶: 像素高度（--resolution, -r）。

property pixel_width: int¶: 像素宽度（--resolution, -r）。

property plugins: list[str]¶: 要启用的插件列表。

property preview: bool¶: 是否播放渲染的电影（-p）。

property progress_bar: str¶: 渲染动画时是否显示进度条。

property quality: str | None¶: 视频质量（-q）。

property renderer: RendererType¶

当前活动的渲染器。

填充 RendererType 中可用的渲染器之一。

测试

>>> test_config = ManimConfig()
>>> test_config.renderer is None  # a new ManimConfig is unpopulated
True
>>> test_config.renderer = 'opengl'
>>> test_config.renderer
<RendererType.OPENGL: 'opengl'>
>>> test_config.renderer = 42
Traceback (most recent call last):
...
ValueError: 42 is not a valid RendererType

检查渲染器类型的首字母大写是否无关紧要

>>> test_config.renderer = 'OpenGL'
>>> test_config.renderer = 'cAirO'

property right_side: Vector3D¶: 帧中右侧的坐标。

property save_as_gif: bool¶: 是否将渲染的场景保存为 .gif 格式（-i）。

property save_last_frame: bool¶: 是否将场景的最后一帧保存为图像文件（-s）。

property save_pngs: bool¶: 是否将场景中的所有帧保存为图像文件（-g）。

property save_sections: bool¶: 除了电影文件外，是否为每个章节保存单独的视频。

property scene_names: list[str]¶: 要从文件中播放的场景。

property sections_dir: str¶: 放置章节视频的目录（无标志）。请参阅 ManimConfig.get_dir()。

property show_in_file_browser: bool¶: 是否在文件浏览器中显示输出文件（-f）。

property tex_dir: str¶: 放置 Tex 文件的目录（无标志）。请参阅 ManimConfig.get_dir()。

property tex_template: TexTemplate¶: 渲染 Tex 时使用的模板。请参阅 TexTemplate。

property tex_template_file: Path¶: 从中读取 Tex 模板的文件（无标志）。请参阅 TexTemplate。

property text_dir: str¶: 放置文本的目录（无标志）。请参阅 ManimConfig.get_dir()。

property top: Vector3D¶: 帧中心顶部的坐标。

property transparent: bool¶: 背景不透明度是否小于 1.0（-t）。

update(obj)[source]¶

处理在另一个 ManimConfig 或字典中找到的选项。

类似于 dict.update()，用 obj 的值替换此对象的值。

参数:: obj (ManimConfig | dict[str, Any]) – 要复制值的对象。
返回类型:: 无
抛出:: AttributeError – 如果 obj 是一个字典，但包含不属于任何配置选项的键。

另请参阅

digest_file(), digest_args(), digest_parser()

property upto_animation_number: int¶: 在此编号停止渲染动画。使用 -1 避免跳过（-n）。

property use_projection_fill_shaders: bool¶: 为 OpenGLVMobject 填充使用与变换矩阵兼容的着色器。

property use_projection_stroke_shaders: bool¶: 为 OpenGLVMobject 描边使用与变换矩阵兼容的着色器。

property verbosity: str¶: 日志记录器详细程度；“DEBUG”、“INFO”、“WARNING”、“ERROR”或“CRITICAL”（-v）。

property video_dir: str¶: 放置视频的目录（无标志）。请参阅 ManimConfig.get_dir()。

property window_monitor: int¶: 场景将在其上渲染的显示器。

property window_position: str¶: 设置预览窗口的位置。您可以使用方向，例如 UL/DR/ORIGIN/LEFT…或者窗口左上角的像素位置，例如“960,540”。

property window_size: str¶: OpenGL 窗口的大小。“default”表示根据显示器自动缩放窗口。

property write_all: bool¶: 是否渲染输入文件中的所有场景（-a）。

property write_to_movie: bool¶: 是否将场景渲染为电影文件（-w）。

property zero_pad: int¶: PNG 零填充。一个介于 0（无零填充）和 9（至少 9 列）之间的数字。