manim._config.utils.ManimConfig

class ManimConfig

Bases: collections.abc.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

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

>>> from manim import config, 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 conents 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.
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.
dry_run	Whether dry run is enabled.
ffmpeg_loglevel	Verbosity level of ffmpeg (no flag).
flush_cache	Whether to delete all the cached partial movie files.
frame_height	Frame height in logical units (no flag).
frame_rate	Frame rate in frames per second (-q).
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).
images_dir	Directory to place images (no flag).
input_file	Input file name.
leave_progress_bars	Whether to leave the progress bar for each animation.
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.
movie_file_extension	Either .mp4 or .mov (no flag).
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.
png_mode	Either RGA (no transparency) or RGBA (with transparency) (no flag).
preview	Whether to play the rendered movie (-p).
progress_bar	Whether to show progress bars while rendering animations.
quality	Video quality (-q).
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).
scene_names	Scenes to play from file.
show_in_file_browser	Whether to show the output file in the file browser (-f).
sound	Whether to play a sound to notify when a scene is rendered (no flag).
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_webgl_renderer	Whether to use WebGL renderer or not (default).
verbosity	Logger verbosity; “DEBUG”, “INFO”, “WARNING”, “ERROR”, or “CRITICAL” (-v).
video_dir	Directory to place videos (no flag).
webgl_renderer_path	Path to WebGL renderer.
webgl_updater_fps	Frame rate to use when generating keyframe data for animations that use updaters while using the WebGL frontend.
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).

Return type

None

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

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)

Process the config options present in CLI arguments.

Parameters

args (argparse.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)

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) – Path to the .cfg file.

Returns

self – This object, after processing the contents of filename.

Return type

ManimConfig

See also

digest_file(), digest_args(), make_config_parser()

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)

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

See also

make_config_parser(), digest_file(), digest_args()

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 dry_run

Whether dry run is enabled.

property ffmpeg_loglevel

Verbosity level of ffmpeg (no flag).

property flush_cache

Whether to delete all the cached partial movie files.

property frame_height

Frame height in logical units (no flag).

property frame_rate

Frame rate in frames per second (-q).

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

get_dir(key, **kwargs)

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

Directory to place images (no flag). See ManimConfig.get_dir().

property input_file

Input file name.

property leave_progress_bars

Whether to leave the progress bar for each animation.

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 movie_file_extension

Either .mp4 or .mov (no flag).

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 png_mode

Either RGA (no transparency) or RGBA (with transparency) (no flag).

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

Scenes to play from file.

property show_in_file_browser

Whether to show the output file in the file browser (-f).

property sound

Whether to play a sound to notify when a scene is rendered (no flag).

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)

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 (Union[ManimConfig, dict]) – The object to copy values from.

Returns

Return type

None

Raises

AttributeError – If obj is a dict but contains keys that do not belong to any config options.

See also

digest_file(), digest_args(), digest_parser()

property upto_animation_number

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

property use_webgl_renderer

Whether to use WebGL renderer or not (default).

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 webgl_renderer_path

Path to WebGL renderer.

property webgl_updater_fps

Frame rate to use when generating keyframe data for animations that use updaters while using the WebGL frontend.

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