ManimConfig#

Qualified name: manim.\_config.utils.ManimConfig

class ManimConfig[source]#

Bases: MutableMapping

Dict-like class storing all config options.

The global config object is an instance of this class, and acts as a single source of truth for all of the library’s customizable behavior.

The global config object is capable of digesting different types of sources and converting them into a uniform interface. These sources are (in ascending order of precedence): configuration files, command line arguments, and programmatic changes. Regardless of how the user chooses to set a config option, she can access its current value using ManimConfig’s attributes and properties.

Notes

Each config option is implemented as a property of this class.

Each config option can be set via a config file, using the full name of the property. If a config option has an associated CLI flag, then the flag is equal to the full name of the property. Those that admit an alternative flag or no flag at all are documented in the individual property’s docstring.

Examples

We use a copy of the global configuration object in the following examples for the sake of demonstration; you can skip these lines and just import config directly if you actually want to modify the configuration:

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

Each config option allows for dict syntax and attribute syntax. For example, the following two lines are equivalent,

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

The former is preferred; the latter is provided mostly for backwards compatibility.

The config options are designed to keep internal consistency. For example, setting frame_y_radius will affect frame_height:

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

There are many ways of interacting with config options. Take for example the config option background_color. There are three ways to change it: via a config file, via CLI flags, or programmatically.

To set the background color via a config file, save the following manim.cfg file with the following contents.

[CLI]
background_color = WHITE

In order to have this .cfg file apply to a manim scene, it needs to be placed in the same directory as the script,

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

Now, when the user executes

manim scene.py

the background of the scene will be set to WHITE. This applies regardless of where the manim command is invoked from.

Command line arguments override .cfg files. In the previous example, executing

manim scene.py -c BLUE

will set the background color to BLUE, regardless of the contents of manim.cfg.

Finally, any programmatic changes made within the scene script itself will override the command line arguments. For example, if scene.py contains the following

from manim import *

config.background_color = RED

class MyScene(Scene):
    ...

the background color will be set to RED, regardless of the contents of manim.cfg or the CLI arguments used when invoking manim.

Methods

`copy`	Deepcopy the contents of this ManimConfig.
`digest_args`	Process the config options present in CLI arguments.
`digest_file`	Process the config options present in a `.cfg` file.
`digest_parser`	Process the config options present in a `ConfigParser` object.
`get_dir`	Resolve a config option that stores a directory.
`resolve_movie_file_extension`
`update`	Digest the options found in another `ManimConfig` or in a dict.

Attributes

`aspect_ratio`	Aspect ratio (width / height) in pixels (--resolution, -r).
`assets_dir`	Directory to locate video assets (no flag).
`background_color`	Background color of the scene (-c).
`background_opacity`	A number between 0.0 (fully transparent) and 1.0 (fully opaque).
`bottom`	Coordinate at the center bottom of the frame.
`custom_folders`	Whether to use custom folder output.
`disable_caching`	Whether to use scene caching.
`disable_caching_warning`	Whether a warning is raised if there are too much submobjects to hash.
`dry_run`	Whether dry run is enabled.
`enable_gui`	Enable GUI interaction.
`enable_wireframe`	Enable wireframe debugging mode in opengl.
`ffmpeg_executable`	Manually specify the path to the ffmpeg executable
`ffmpeg_loglevel`	Verbosity level of ffmpeg (no flag).
`flush_cache`	Whether to delete all the cached partial movie files.
`force_window`	Set to force window when using the opengl renderer
`format`	File format; "png", "gif", "mp4", "webm" or "mov".
`frame_height`	Frame height in logical units (no flag).
`frame_rate`	Frame rate in frames per second.
`frame_size`	Tuple with (pixel width, pixel height) (no flag).
`frame_width`	Frame width in logical units (no flag).
`frame_x_radius`	Half the frame width (no flag).
`frame_y_radius`	Half the frame height (no flag).
`from_animation_number`	Start rendering animations at this number (-n).
`fullscreen`	Expand the window to its maximum possible size.
`gui_location`	Enable GUI interaction.
`images_dir`	Directory to place images (no flag).
`input_file`	Input file name.
`left_side`	Coordinate at the middle left of the frame.
`log_dir`	Directory to place logs.
`log_to_file`	Whether to save logs to a file.
`max_files_cached`	Maximum number of files cached.
`media_dir`	Main output directory.
`media_embed`	Embed videos in Jupyter notebook
`media_width`	Media width in Jupyter notebook
`movie_file_extension`	Either .mp4, .webm or .mov.
`notify_outdated_version`	Whether to notify if there is a version update available.
`output_file`	Output file name (-o).
`partial_movie_dir`	Directory to place partial movie files (no flag).
`pixel_height`	Frame height in pixels (--resolution, -r).
`pixel_width`	Frame width in pixels (--resolution, -r).
`plugins`	List of plugins to enable.
`preview`	Whether to play the rendered movie (-p).
`progress_bar`	Whether to show progress bars while rendering animations.
`quality`	Video quality (-q).
`renderer`	The currently active renderer.
`right_side`	Coordinate at the middle right of the frame.
`save_as_gif`	Whether to save the rendered scene in .gif format (-i).
`save_last_frame`	Whether to save the last frame of the scene as an image file (-s).
`save_pngs`	Whether to save all frames in the scene as images files (-g).
`save_sections`	Whether to save single videos for each section in addition to the movie file.
`scene_names`	Scenes to play from file.
`sections_dir`	Directory to place section videos (no flag).
`show_in_file_browser`	Whether to show the output file in the file browser (-f).
`tex_dir`	Directory to place tex (no flag).
`tex_template`	Template used when rendering Tex.
`tex_template_file`	File to read Tex template from (no flag).
`text_dir`	Directory to place text (no flag).
`top`	Coordinate at the center top of the frame.
`transparent`	Whether the background opacity is 0.0 (-t).
`upto_animation_number`	Stop rendering animations at this nmber.
`use_projection_fill_shaders`	Use shaders for OpenGLVMobject fill which are compatible with transformation matrices.
`use_projection_stroke_shaders`	Use shaders for OpenGLVMobject stroke which are compatible with transformation matrices.
`verbosity`	Logger verbosity; "DEBUG", "INFO", "WARNING", "ERROR", or "CRITICAL" (-v).
`video_dir`	Directory to place videos (no flag).
`window_monitor`	The monitor on which the scene will be rendered
`window_position`	Set the position of preview window.
`window_size`	The size of the opengl window.
`write_all`	Whether to render all scenes in the input file (-a).
`write_to_movie`	Whether to render the scene to a movie file (-w).
`zero_pad`	PNG zero padding.

property aspect_ratio#: Aspect ratio (width / height) in pixels (–resolution, -r).

property assets_dir#: Directory to locate video assets (no flag).

property background_color#: Background color of the scene (-c).

property background_opacity#: A number between 0.0 (fully transparent) and 1.0 (fully opaque).

property bottom#: Coordinate at the center bottom of the frame.

copy()[source]#

Deepcopy the contents of this ManimConfig.

Returns: A copy of this object containing no shared references.
Return type: ManimConfig

See also

tempconfig()

Notes

This is the main mechanism behind tempconfig().

property custom_folders#: Whether to use custom folder output.

digest_args(args)[source]#

Process the config options present in CLI arguments.

Parameters: args (Namespace) – An object returned by main_utils.parse_args().
Returns: self – This object, after processing the contents of parser.
Return type: ManimConfig

See also

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

Notes

If args.config_file is a non-empty string, ManimConfig tries to digest the contents of said file with digest_file() before digesting any other CLI arguments.

digest_file(filename)[source]#

Process the config options present in a .cfg file.

This method processes a single .cfg file, whereas digest_parser() can process arbitrary parsers, built perhaps from multiple .cfg files.

Parameters: filename (str | os.PathLike) – Path to the .cfg file.
Returns: self – This object, after processing the contents of filename.
Return type: ManimConfig

Notes

If there are multiple .cfg files to process, it is always more efficient to parse them into a single ConfigParser object first and digesting them with one call to digest_parser(), instead of calling this method multiple times.

digest_parser(parser)[source]#

Process the config options present in a ConfigParser object.

This method processes arbitrary parsers, not only those read from a single file, whereas digest_file() can only process one file at a time.

Parameters: parser (ConfigParser) – An object reflecting the contents of one or many .cfg files. In particular, it may reflect the contents of multiple files that have been parsed in a cascading fashion.
Returns: self – This object, after processing the contents of parser.
Return type: ManimConfig

Notes

If there are multiple .cfg files to process, it is always more efficient to parse them into a single ConfigParser object first, and then call this function once (instead of calling digest_file() multiple times).

Examples

To digest the config options set in two files, first create a ConfigParser and parse both files and then digest the parser:

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

In fact, the global config object is initialized like so:

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

property disable_caching#: Whether to use scene caching.

property disable_caching_warning#: Whether a warning is raised if there are too much submobjects to hash.

property dry_run#: Whether dry run is enabled.

property enable_gui#: Enable GUI interaction.

property enable_wireframe#: Enable wireframe debugging mode in opengl.

property ffmpeg_executable#: Manually specify the path to the ffmpeg executable

property ffmpeg_loglevel#: Verbosity level of ffmpeg (no flag).

property flush_cache#: Whether to delete all the cached partial movie files.

property force_window#: Set to force window when using the opengl renderer

property format#: File format; “png”, “gif”, “mp4”, “webm” or “mov”.

property frame_height#: Frame height in logical units (no flag).

property frame_rate#: Frame rate in frames per second.

property frame_size#: Tuple with (pixel width, pixel height) (no flag).

property frame_width#: Frame width in logical units (no flag).

property frame_x_radius#: Half the frame width (no flag).

property frame_y_radius#: Half the frame height (no flag).

property from_animation_number#: Start rendering animations at this number (-n).

property fullscreen#: Expand the window to its maximum possible size.

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

Resolve a config option that stores a directory.

Config options that store directories may depend on one another. This method is used to provide the actual directory to the end user.

Parameters

key (str) – The config option to be resolved. Must be an option ending in '_dir', for example 'media_dir' or 'video_dir'.
kwargs (str) – Any strings to be used when resolving the directory.

Returns

Path to the requested directory. If the path resolves to the empty string, return None instead.

Return type

pathlib.Path

Raises

KeyError – When key is not a config option that stores a directory and thus get_dir() is not appropriate; or when key is appropriate but there is not enough information to resolve the directory.

Notes

Standard str.format() syntax is used to resolve the paths so the paths may contain arbitrary placeholders using f-string notation. However, these will require kwargs to contain the required values.

Examples

The value of config.tex_dir is '{media_dir}/Tex' by default, i.e. it is a subfolder of wherever config.media_dir is located. In order to get the actual directory, use 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'

Resolving directories is done in a lazy way, at the last possible moment, to reflect any changes in other config options:

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

Some directories depend on information that is not available to ManimConfig. For example, the default value of video_dir includes the name of the input file and the video quality (e.g. 480p15). This informamtion has to be supplied via 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'

Note the quality does not need to be passed as keyword argument since ManimConfig does store information about quality.

Directories may be recursively defined. For example, the config option partial_movie_dir depends on video_dir, which in turn depends on 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'

Standard f-string syntax is used. Arbitrary names can be used when defining directories, as long as the corresponding values are passed to ManimConfig.get_dir() via kwargs.

>>> 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#: Enable GUI interaction.

property images_dir#: Directory to place images (no flag). See ManimConfig.get_dir().

property input_file#: Input file name.

property left_side#: Coordinate at the middle left of the frame.

property log_dir#: Directory to place logs. See ManimConfig.get_dir().

property log_to_file#: Whether to save logs to a file.

property max_files_cached#: Maximum number of files cached. Use -1 for infinity (no flag).

property media_dir#: Main output directory. See ManimConfig.get_dir().

property media_embed#: Embed videos in Jupyter notebook

property media_width#: Media width in Jupyter notebook

property movie_file_extension#: Either .mp4, .webm or .mov.

property notify_outdated_version#: Whether to notify if there is a version update available.

property output_file#: Output file name (-o).

property partial_movie_dir#: Directory to place partial movie files (no flag). See ManimConfig.get_dir().

property pixel_height#: Frame height in pixels (–resolution, -r).

property pixel_width#: Frame width in pixels (–resolution, -r).

property plugins#: List of plugins to enable.

property preview#: Whether to play the rendered movie (-p).

property progress_bar#: Whether to show progress bars while rendering animations.

property quality#: Video quality (-q).

property renderer#

The currently active renderer.

Populated with one of the available renderers in RendererType.

Tests:

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

Check that capitalization of renderer types is irrelevant:

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

property right_side#: Coordinate at the middle right of the frame.

property save_as_gif#: Whether to save the rendered scene in .gif format (-i).

property save_last_frame#: Whether to save the last frame of the scene as an image file (-s).

property save_pngs#: Whether to save all frames in the scene as images files (-g).

property save_sections#: Whether to save single videos for each section in addition to the movie file.

property scene_names#: Scenes to play from file.

property sections_dir#: Directory to place section videos (no flag). See ManimConfig.get_dir().

property show_in_file_browser#: Whether to show the output file in the file browser (-f).

property tex_dir#: Directory to place tex (no flag). See ManimConfig.get_dir().

property tex_template#: Template used when rendering Tex. See TexTemplate.

property tex_template_file#: File to read Tex template from (no flag). See TexTemplateFromFile.

property text_dir#: Directory to place text (no flag). See ManimConfig.get_dir().

property top#: Coordinate at the center top of the frame.

property transparent#: Whether the background opacity is 0.0 (-t).

update(obj)[source]#

Digest the options found in another ManimConfig or in a dict.

Similar to dict.update(), replaces the values of this object with those of obj.

Parameters: obj (ManimConfig | dict) – The object to copy values from.
Return type: None
Raises: AttributeError – If obj is a dict but contains keys that do not belong to any config options.

property upto_animation_number#: Stop rendering animations at this nmber. Use -1 to avoid skipping (-n).

property use_projection_fill_shaders#: Use shaders for OpenGLVMobject fill which are compatible with transformation matrices.

property use_projection_stroke_shaders#: Use shaders for OpenGLVMobject stroke which are compatible with transformation matrices.

property verbosity#: Logger verbosity; “DEBUG”, “INFO”, “WARNING”, “ERROR”, or “CRITICAL” (-v).

property video_dir#: Directory to place videos (no flag). See ManimConfig.get_dir().

property window_monitor#: The monitor on which the scene will be rendered

property window_position#: Set the position of preview window. You can use directions, e.g. UL/DR/ORIGIN/LEFT…or the position(pixel) of the upper left corner of the window, e.g. ‘960,540’

property window_size#: The size of the opengl window. ‘default’ to automatically scale the window based on the display monitor.

property write_all#: Whether to render all scenes in the input file (-a).

property write_to_movie#: Whether to render the scene to a movie file (-w).

property zero_pad#: PNG zero padding. A number between 0 (no zero padding) and 9 (9 columns minimum).