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参数如何。

方法

`copy`	深度复制此ManimConfig的内容。
`digest_args`	处理CLI参数中存在的配置选项。
`digest_file`	处理存在于`.cfg`文件中的配置选项。
`digest_parser`	处理存在于`ConfigParser`对象中的配置选项。
`get_dir`	解析存储目录的配置选项。
`resolve_movie_file_extension`
`update`	消化在另一个`ManimConfig`或字典中找到的选项。

属性

`aspect_ratio`	宽高比（宽度 / 高度）以像素为单位（--resolution, -r）。
`assets_dir`	用于定位视频资源的目录（无标志）。
`background_color`	场景的背景颜色 (-c)。
`background_opacity`	一个介于0.0（完全透明）和1.0（完全不透明）之间的数字。
`bottom`	框架底部中心的坐标。
`custom_folders`	是否使用自定义文件夹输出。
`disable_caching`	是否使用场景缓存。
`disable_caching_warning`	如果子对象过多导致哈希时是否发出警告。
`dry_run`	是否启用了试运行。
`enable_gui`	启用图形用户界面交互。
`enable_wireframe`	是否在opengl中启用线框调试模式。
`ffmpeg_executable`	自定义ffmpeg可执行文件的路径。
`ffmpeg_loglevel`	ffmpeg的详细程度（无标志）。
`flush_cache`	是否删除所有缓存的电影部分文件。
`force_window`	在使用opengl渲染器时是否强制窗口。
`format`	文件格式；"png"、"gif"、"mp4"、"webm" 或 "mov"。
`frame_height`	框架高度以逻辑单位表示（无标志）。
`frame_rate`	帧率，单位为每秒帧数。
`frame_size`	元组包含（像素宽度，像素高度）（无标志）。
`frame_width`	框架宽度以逻辑单位表示（无标志）。
`frame_x_radius`	帧宽度的一半（无标志）。
`frame_y_radius`	帧高度的一半（无标志）。
`from_animation_number`	从这个数字开始渲染动画 (-n)。
`fullscreen`	将窗口扩展到最大可能的大小。
`gui_location`	启用图形用户界面交互。
`images_dir`	放置图像的目录（无标志）。
`input_file`	输入文件名。
`left_side`	框架中左的坐标。
`log_dir`	放置日志的目录。
`log_to_file`	是否将日志保存到文件中。
`max_files_cached`	缓存文件的最大数量。
`media_dir`	主输出目录。
`media_embed`	是否在Jupyter笔记本中嵌入视频。
`media_width`	Jupyter笔记本中的媒体宽度。
`movie_file_extension`	可以是 .mp4、.webm 或 .mov。
`no_latex_cleanup`	防止删除由Tex和MathTex生成的.aux、.dvi和.log文件。
`notify_outdated_version`	是否在有版本更新可用时通知。
`output_file`	输出文件名 (-o)。
`partial_movie_dir`	放置部分电影文件的目录（无标志）。
`pixel_height`	帧高度以像素为单位（--resolution, -r）。
`pixel_width`	帧宽度以像素为单位 (--resolution, -r)。
`plugins`	启用的插件列表。
`preview`	是否播放渲染的电影 (-p)。
`preview_command`
`progress_bar`	是否在渲染动画时显示进度条。
`quality`	视频质量 (-q)。
`renderer`	当前活动的渲染器。
`right_side`	框架中右的坐标。
`save_as_gif`	是否将渲染的场景保存为.gif格式（-i）。
`save_last_frame`	是否将场景的最后一帧保存为图像文件 (-s)。
`save_pngs`	是否将场景中的所有帧保存为图像文件 (-g)。
`save_sections`	是否除了电影文件外，还要为每个部分保存单独的视频。
`scene_names`	从文件中播放的场景。
`sections_dir`	放置章节视频的目录（无标志）。
`show_in_file_browser`	是否在文件浏览器中显示输出文件 (-f)。
`tex_dir`	放置tex的目录（无标志）。
`tex_template`	渲染Tex时使用的模板。
`tex_template_file`	读取Tex模板的文件（无标志）。
`text_dir`	放置文本的目录（无标志）。
`top`	框架顶部中心的坐标。
`transparent`	背景透明度是否为0.0 (-t)。
`upto_animation_number`	在此数字处停止渲染动画。
`use_projection_fill_shaders`	使用与变换矩阵兼容的OpenGLVMobject填充着色器。
`use_projection_stroke_shaders`	使用与变换矩阵兼容的OpenGLVMobject描边着色器。
`verbosity`	日志详细程度；"DEBUG"（调试）、"INFO"（信息）、"WARNING"（警告）、"ERROR"（错误）或"CRITICAL"（严重）(-v)。
`video_dir`	放置视频的目录（无标志）。
`window_monitor`	场景将在其上渲染的监视器。
`window_position`	设置预览窗口的位置。
`window_size`	OpenGL窗口的大小。
`write_all`	是否渲染输入文件中的所有场景 (-a)。
`write_to_movie`	是否将场景渲染到电影文件 (-w)。
`zero_pad`	PNG 零填充。

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

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

Parameters:

key (str)
val (浮点数)
lo (浮点数)
你好 (浮点数)

Return type:

无

_set_boolean(key, val)[source]¶

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

Parameters:

key (str)
val (任意)

Return type:

无

_set_from_enum(key, enum_value, enum_class)[来源]¶

将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

Parameters:

key (str)
enum_value (任意)
enum_class (EnumMeta)

Return type:

无

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

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

Parameters:

key (str)
val (任意)
值 (列表[任意类型])

Return type:

无

_set_int_between(key, val, lo, hi)[来源]¶

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

Parameters:

key (str)
val (整数)
lo (int)
你好 (int)

Return type:

无

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

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

Parameters:

key (str)
val (整数)
allow_inf (bool)

Return type:

无

_set_str(key, val)[source]¶

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

Parameters:

key (str)
val (任意)

Return type:

无

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()[来源]¶

深度复制此ManimConfig的内容。

Returns:: 此对象的副本，不包含任何共享引用。
Return type:: ManimConfig

另请参阅

tempconfig()

注释

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

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

digest_args(args)[来源]¶

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

Parameters:: args (argparse.Namespace) – 由 main_utils.parse_args() 返回的对象。
Returns:: self – 处理完parser内容后的此对象。
Return type:: 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文件构建。

Parameters:: 文件名 (StrPath) – 指向 .cfg 文件的路径。
Returns:: self – 处理完filename内容后的此对象。
Return type:: ManimConfig

另请参阅

digest_file(), digest_args(), make_config_parser()

注释

如果有多个.cfg文件需要处理，通常更高效的做法是先将它们解析为一个单一的ConfigParser对象，然后通过一次调用digest_parser()来消化它们，而不是多次调用此方法。

digest_parser(parser)[来源]¶

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

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

Parameters:: parser (configparser.ConfigParser) – 一个反映一个或多个.cfg文件内容的对象。特别是，它可能反映以级联方式解析的多个文件的内容。
Returns:: self – 处理完parser内容后的此对象。
Return type:: 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_executable: str¶: 自定义ffmpeg可执行文件的路径。

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]¶

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

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

Parameters:

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

Returns:

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

Return type:

pathlib.Path

Raises:

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，而后者又依赖于 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笔记本中嵌入视频。

property media_width: str¶: Jupyter笔记本中的媒体宽度。

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¶: 背景透明度是否为0.0 (-t)。

update(obj)[来源]¶

消化在另一个ManimConfig或字典中找到的选项。

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

Parameters:: obj (ManimConfig | dict[str, Any]) – 从中复制值的对象。
Return type:: 无
Raises:: 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 列）之间的数字。