Coverage for src/manimgx/settings.py: 91%
89 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1# SPDX-FileCopyrightText: 2026 Academa, Inc.
2# SPDX-FileCopyrightText: 2024 the Manim Community Developers
3# SPDX-FileCopyrightText: 2018 3Blue1Brown LLC
4# SPDX-License-Identifier: MIT
6"""Global scene configuration (a small, typed subset of CE's `config`)."""
8from dataclasses import dataclass, field
9from typing import Literal, overload
10from warnings import deprecated
12import numpy as np
14from manimgx import constants
15from manimgx.drawing.paint import BLACK, ManimColor, ParsableManimColor
16from manimgx.typing import Point3D, Vector3D
18__all__ = ["Degrees", "Munits", "Percent", "Pixels", "config"]
21@dataclass
22class Config:
23 """The configuration scenes are made and rendered with: the video's size, frame rate
24 and background, and the frame's size in scene units.
26 There is one, [`config`][manimgx.config]. Set its fields before making a
27 scene: a scene's camera, and the mobjects that fill the frame, take their sizes and
28 the background from it when they are made, and [`render`][manimgx.Scene.render]
29 takes the video's size and frame rate when it starts. It can be read and set as a
30 dictionary too, as Manim code does: `config["frame_width"]`,
31 `config["pixel_height"] = 720`.
33 The frame has the video's proportions, and its short side is 8 units: a wide video
34 (16:9) shows about 14.2 × 8 units, a tall one (9:16) 8 × 14.2. So what fits in the
35 8 × 8 square at the center fits both, at the same size.
36 """
38 pixel_width: int = 1920
39 """The width of the video, in pixels (default 1920)."""
40 pixel_height: int = 1080
41 """The height of the video, in pixels (default 1080). For a tall video (9:16), make
42 it the larger: `config.pixel_width, config.pixel_height = 1080, 1920`."""
43 frame_rate: float = 60
44 """How many frames a second the film has (default 60): frame k shows the scene at
45 exactly k / `frame_rate` seconds. A video needs a whole number."""
46 simulation_rate: int = 60 # the simulation clock of `manimgx.animation.clock`
47 """How many times a second the simulation clock ticks (default 60).
49 A time-based updater that is not a [flow][manimgx.mobject.flow] is simulated:
50 it steps at each tick of this clock and at the end of each play and wait, never at
51 frames, so it takes the same steps at any frame rate, and a frame shows it as its
52 last step left it. While one is in the scene, the scene computes every tick. At 60
53 frames a second each frame is a tick, so the ticks cost nothing more; at a frame
54 rate that divides it (10, 12, 15, 20, 30), every frame falls on a tick too.
55 """
56 background_color: ParsableManimColor = BLACK
57 """The color of the background (default black)."""
58 background_opacity: float = 1.0
59 """The opacity of the background, from 0 to 1 (default 1)."""
60 _frame_height: float | None = field(default=None, repr=False)
61 """The frame's height as set, if it was (`frame_height`)."""
63 @property
64 def frame_height(self) -> float:
65 """The height of the frame, in scene units. Unless set, the frame's short side is
66 8 units: a wide video's frame is 8 high, a tall one's as high as its proportions
67 make it when it is 8 wide (about 14.2 at 9:16). Its width follows from the
68 video's proportions."""
69 if self._frame_height is not None:
70 return self._frame_height
71 return 8.0 * max(1.0, self.pixel_height / self.pixel_width)
73 @frame_height.setter
74 def frame_height(self, value: float) -> None:
75 self._frame_height = value
77 @property
78 def frame_width(self) -> float:
79 """The width of the frame, in scene units: `frame_height` times the video's
80 aspect ratio (about 14.2 at 16:9, 8 at 9:16)."""
81 return self.frame_height * self.pixel_width / self.pixel_height
83 @property
84 def frame_x_radius(self) -> float:
85 """Half the frame's width, in scene units: the x of its right edge."""
86 return self.frame_width / 2
88 @property
89 def frame_y_radius(self) -> float:
90 """Half the frame's height, in scene units (4 for a wide video): the y of its top
91 edge."""
92 return self.frame_height / 2
94 @property
95 def top(self) -> "Point3D":
96 """The middle of the frame's top edge: `frame_y_radius` up from the origin."""
97 return self.frame_y_radius * np.array([0.0, 1.0, 0.0])
99 @property
100 def bottom(self) -> "Point3D":
101 """The middle of the frame's bottom edge: `frame_y_radius` down from the
102 origin."""
103 return -self.top
105 @property
106 def right_side(self) -> "Point3D":
107 """The middle of the frame's right edge: `frame_x_radius` right of the
108 origin."""
109 return self.frame_x_radius * np.array([1.0, 0.0, 0.0])
111 @property
112 def left_side(self) -> "Point3D":
113 """The middle of the frame's left edge: `frame_x_radius` left of the origin."""
114 return -self.right_side
116 @property
117 def aspect_ratio(self) -> float:
118 """The video's width over its height: `pixel_width / pixel_height` (16:9 by
119 default)."""
120 return self.pixel_width / self.pixel_height
122 @property
123 def background(self) -> ManimColor:
124 """The color of the background, as a [`ManimColor`][manimgx.ManimColor]."""
125 return ManimColor(self.background_color)
127 # CE's dict-style access (`config["frame_width"]`), typed by key
128 @overload
129 def __getitem__(
130 self, key: Literal["pixel_width", "pixel_height", "simulation_rate"]
131 ) -> int: ...
132 @overload
133 def __getitem__(
134 self,
135 key: Literal[
136 "frame_rate",
137 "frame_height",
138 "frame_width",
139 "frame_x_radius",
140 "frame_y_radius",
141 "aspect_ratio",
142 "background_opacity",
143 ],
144 ) -> float: ...
145 @overload
146 def __getitem__(
147 self, key: Literal["top", "bottom", "left_side", "right_side"]
148 ) -> "Point3D": ...
149 @overload
150 def __getitem__(self, key: Literal["background_color"]) -> ParsableManimColor: ...
151 @overload
152 def __getitem__(self, key: Literal["background"]) -> ManimColor: ...
153 def __getitem__(self, key: str) -> object:
154 return getattr(self, key)
156 @overload
157 def __setitem__(
158 self,
159 key: Literal["pixel_width", "pixel_height", "simulation_rate"],
160 value: int,
161 ) -> None: ...
162 @overload
163 def __setitem__(
164 self,
165 key: Literal["frame_rate", "frame_height", "background_opacity"],
166 value: float,
167 ) -> None: ...
168 @overload
169 def __setitem__(
170 self, key: Literal["background_color"], value: ParsableManimColor
171 ) -> None: ...
172 def __setitem__(self, key: str, value: object) -> None:
173 setattr(self, key, value)
176config = Config()
177"""The configuration every scene is made and rendered with, as `m.config`: a
178[`Config`][manimgx.settings.Config]. Set its fields before making a scene:
179`m.config.pixel_width, m.config.pixel_height = 1280, 720`."""
182class _PixelUnits:
183 def __mul__(self, val: float) -> float:
184 return val * config.frame_width / config.pixel_width
186 def __rmul__(self, val: float) -> float:
187 return val * config.frame_width / config.pixel_width
190@deprecated(
191 "use a fraction of config.frame_width or config.frame_height", category=None
192)
193class Percent:
194 """A length as a percentage of the frame's width or height: `25 * Percent(X_AXIS)`
195 is a quarter of the frame's width, in scene units.
197 The frame's size is read when the unit is made.
199 Args:
200 axis: [X_AXIS][manimgx.X_AXIS] for the frame's width, [Y_AXIS][manimgx.Y_AXIS]
201 for its height; [Z_AXIS][manimgx.Z_AXIS], which has no length, raises an
202 exception.
203 """
205 def __init__(self, axis: Vector3D) -> None:
206 if np.array_equal(axis, constants.X_AXIS):
207 self.length = config.frame_width
208 if np.array_equal(axis, constants.Y_AXIS):
209 self.length = config.frame_height
210 if np.array_equal(axis, constants.Z_AXIS):
211 raise NotImplementedError("length of Z axis is undefined")
213 def __mul__(self, val: float) -> float:
214 return val / 100 * self.length
216 def __rmul__(self, val: float) -> float:
217 return val / 100 * self.length
220Pixels = _PixelUnits()
221"""Pixels as a unit of length: `100 * Pixels` is the width of 100 of the rendered
222frame's pixels, in scene units, as the configuration sets them when multiplied."""
223Degrees = constants.PI / 180
224"""One degree, in radians: `30 * Degrees` is 30°, as [DEGREES][manimgx.DEGREES] is."""
225Munits = 1
226"""One scene unit: `2 * Munits` is 2, a length written in scene units."""