ManimConfig

Qualified name: manim.\_config.utils.ManimConfig

class ManimConfig[source]

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

ffmpeg_loglevel

Verbosity level of ffmpeg (no flag).

flush_cache

Whether to delete all the cached partial movie files.

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

“cairo”, “opengl”, “webgl

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

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_opengl_renderer

Whether or not to use the OpenGL renderer.

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.

use_webgl_renderer

Whether or not to use WebGL renderer.

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.

window_monitor

The monitor on which the scene will be rendered

window_position

Set the position of preview 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).

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()[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 (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)[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) – 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 ffmpeg_loglevel

Verbosity level of ffmpeg (no flag).

property flush_cache

Whether to delete all the cached partial movie files.

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
>>> 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.0'

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.0/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_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

“cairo”, “opengl”, “webgl

Type

Renderer

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

property upto_animation_number

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

property use_opengl_renderer

Whether or not to use the OpenGL renderer.

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 use_webgl_renderer

Whether or not to use WebGL renderer.

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