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

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 

5 

6"""Global scene configuration (a small, typed subset of CE's `config`).""" 

7 

8from dataclasses import dataclass, field 

9from typing import Literal, overload 

10from warnings import deprecated 

11 

12import numpy as np 

13 

14from manimgx import constants 

15from manimgx.drawing.paint import BLACK, ManimColor, ParsableManimColor 

16from manimgx.typing import Point3D, Vector3D 

17 

18__all__ = ["Degrees", "Munits", "Percent", "Pixels", "config"] 

19 

20 

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. 

25 

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

32 

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

37 

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

48 

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

62 

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) 

72 

73 @frame_height.setter 

74 def frame_height(self, value: float) -> None: 

75 self._frame_height = value 

76 

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 

82 

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 

87 

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 

93 

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

98 

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 

104 

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

110 

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 

115 

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 

121 

122 @property 

123 def background(self) -> ManimColor: 

124 """The color of the background, as a [`ManimColor`][manimgx.ManimColor].""" 

125 return ManimColor(self.background_color) 

126 

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) 

155 

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) 

174 

175 

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

180 

181 

182class _PixelUnits: 

183 def __mul__(self, val: float) -> float: 

184 return val * config.frame_width / config.pixel_width 

185 

186 def __rmul__(self, val: float) -> float: 

187 return val * config.frame_width / config.pixel_width 

188 

189 

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. 

196 

197 The frame's size is read when the unit is made. 

198 

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

204 

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

212 

213 def __mul__(self, val: float) -> float: 

214 return val / 100 * self.length 

215 

216 def __rmul__(self, val: float) -> float: 

217 return val / 100 * self.length 

218 

219 

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