Coverage for src/manimgx/cli/storyboard.py: 99%

162 statements  

« prev     ^ index     » next       coverage.py v7.16.1, created at 2026-10-26 05:52 +0000

1"""Play reports, annotated pictures and storyboard sheets.""" 

2 

3import math 

4from collections.abc import Callable 

5from concurrent.futures import Future, ThreadPoolExecutor 

6from dataclasses import dataclass, field 

7from fractions import Fraction 

8from pathlib import Path 

9 

10from PIL import Image, ImageDraw, ImageFont 

11 

12from manimgx.animation.timeline import Animation, AnimationGroup, Succession, Wait 

13from manimgx.animation.transform import Animate 

14from manimgx.audio import Speech 

15from manimgx.audio.sound import Sound 

16from manimgx.cli.diagnostics import ( 

17 Layout, 

18 Names, 

19 Problem, 

20 View, 

21 report, 

22 text_of, 

23 view, 

24) 

25from manimgx.rendering.film import Film, Play 

26from manimgx.scene import Scene, _written 

27from manimgx.settings import config 

28 

29# a tile's area: 1080p halved each way (reduced exactly: sharp text), two to a sheet's row — in 

30# the scene's shape, so a sheet costs the same image tokens whatever the shape 

31TILE = 960 * 540 

32# more to a sheet would shrink tiles past reading (probes: 330 px tiles miss defects) 

33PER_SHEET = 6 

34GAP, CAPTION = 8, 28 

35 

36 

37def tile(rgba: bytes, width: int, height: int) -> Image.Image: 

38 """A picture at tile size: reduced by a whole factor (exact and fast), resized only for the 

39 rest.""" 

40 image = Image.frombuffer( 

41 "RGBA", (width, height), rgba, "raw", "RGBA", 0, 1 

42 ).convert("RGB") 

43 scale = math.sqrt(TILE / (width * height)) 

44 size = (round(width * scale), round(height * scale)) 

45 if (factor := int(1 / scale + 1e-9)) >= 2: 

46 image = image.reduce(factor) 

47 if image.size != size: 

48 image = image.resize(size, Image.Resampling.BILINEAR) 

49 return image 

50 

51 

52@dataclass 

53class Sheets: 

54 """Captioned tiles, six to a sheet, each sheet written as it fills: `path`, `…-2`, …""" 

55 

56 path: Path 

57 written: list[Path] = field(default_factory=list[Path]) 

58 _tiles: list[tuple[str, Image.Image]] = field( 

59 default_factory=list[tuple[str, Image.Image]] 

60 ) 

61 # sheets are encoded beside the take (PNG encoding releases the GIL) 

62 _writer: ThreadPoolExecutor = field(default_factory=lambda: ThreadPoolExecutor(1)) 

63 _writes: list[Future[None]] = field(default_factory=list[Future[None]]) 

64 

65 def add(self, text: str, picture: Image.Image) -> None: 

66 self._tiles.append((text, picture)) 

67 if len(self._tiles) == PER_SHEET: 

68 self._flush() 

69 

70 def close(self) -> list[Path]: 

71 """The last sheet out; every sheet written.""" 

72 with self._writer: 

73 if self._tiles: 

74 self._flush() 

75 for write in self._writes: 

76 write.result() 

77 return self.written 

78 

79 def _flush(self) -> None: 

80 n = len(self.written) + 1 

81 out = self.path.with_name( 

82 self.path.name if n == 1 else f"{self.path.stem}-{n}{self.path.suffix}" 

83 ) 

84 out.parent.mkdir(parents=True, exist_ok=True) 

85 self._writes.append( 

86 self._writer.submit(_sheet(self._tiles).save, out, compress_level=3) 

87 ) 

88 self.written.append(out) 

89 self._tiles = [] 

90 

91 

92def _sheet(tiles: list[tuple[str, Image.Image]]) -> Image.Image: 

93 columns = 1 if len(tiles) == 1 else 2 

94 rows = -(-len(tiles) // columns) 

95 width, height = tiles[0][1].size 

96 sheet = Image.new( 

97 "RGB", 

98 (columns * (width + GAP) - GAP, rows * (height + CAPTION + GAP) - GAP), 

99 (32, 32, 32), 

100 ) 

101 draw = ImageDraw.Draw(sheet) 

102 font = ImageFont.load_default(size=20) 

103 for i, (text, picture) in enumerate(tiles): 

104 row, column = divmod(i, columns) 

105 x, y = column * (width + GAP), row * (height + CAPTION + GAP) 

106 draw.text((x + 6, y + 4), text, fill=(235, 235, 235), font=font) 

107 sheet.paste(picture, (x, y + CAPTION)) 

108 return sheet 

109 

110 

111RED = (255, 64, 64) 

112 

113 

114@dataclass 

115class Watch: 

116 """A take's timeline, annotated pictures and layout report. As a `plays` hook it samples 

117 play endings; `see` inspects the live scene at any moment.""" 

118 

119 storyboard: Sheets 

120 layout: Layout = field(default_factory=Layout) 

121 lines: list[str] = field(default_factory=list[str]) 

122 checked: int = 0 

123 three_d: bool = False 

124 _last: bytes = b"" 

125 

126 def __call__( 

127 self, made: Scene, play: Play, animations: tuple[Animation, ...] 

128 ) -> None: 

129 self.lines.append(line(play, animations)) 

130 self.see(made, play.end, play=play, distinct=True) 

131 

132 def see( 

133 self, 

134 made: Scene, 

135 time: Fraction, 

136 *, 

137 play: Play | None = None, 

138 distinct: bool = False, 

139 known: Names | None = None, 

140 ) -> None: 

141 """Check and draw the scene now; optionally omit a consecutive identical picture.""" 

142 play = play or (made.film.plays[-1] if made.film.plays else None) 

143 index = None if play is None else play.index 

144 where = None if play is None else play.where 

145 # Inside a play that has not ended yet, its source is still on the stack. 

146 if made.num_plays > len(made.film.plays): 

147 index, where = made.num_plays - 1, _written() 

148 self.three_d = made.three_d 

149 seen = None if made.three_d else view(made, known) 

150 marked = [] if seen is None else self.layout.see((time, where), seen) 

151 self.checked += seen is not None 

152 rgba = made.film.picture(made.camera, made.display_list()) 

153 picture = tile(rgba, config.pixel_width, config.pixel_height) 

154 pixels = picture.tobytes() 

155 if distinct and pixels == self._last: 

156 return 

157 self._last = pixels 

158 if seen is not None and marked: 

159 _mark(picture, seen, marked) 

160 caption = f"t={float(time):g}s" 

161 if index is not None: 

162 caption = f"#{index} {caption}" 

163 if where is not None: 

164 caption += f" {Path(where[0]).name}:{where[1]}" 

165 self.storyboard.add(caption, picture) 

166 

167 def report(self, *, timeline: bool = True, film: "Film | None" = None) -> str: 

168 """The timeline (if asked), then the layout, then the sounds the film's end cuts 

169 short (given the film).""" 

170 layout = ( 

171 "layout: not checked (a 3D scene)" 

172 if self.three_d 

173 else report(self.layout, self.checked) 

174 ) 

175 cut = [] if film is None else film.cut() 

176 sounds = [ 

177 f"sound: {describe(clip.sound)} at {float(clip.start):.2f}s is cut" 

178 f" {lost:.2f}s short: the film ends first" 

179 for clip, lost in cut 

180 ] 

181 return "\n".join([*(self.lines if timeline else []), layout, *sounds]) 

182 

183 

184def _mark(picture: Image.Image, seen: View, marked: list[tuple[int, Problem]]) -> None: 

185 """The problems seen now, outlined in red with their numbers.""" 

186 draw = ImageDraw.Draw(picture) 

187 x0, y0, x1, y1 = seen.frame 

188 sx, sy = picture.width / (x1 - x0), picture.height / (y1 - y0) 

189 px = 18 

190 font = ImageFont.load_default(size=px) 

191 for number, problem in marked: 

192 if not number: 

193 continue # a note 

194 for thing in (problem.subject, problem.other): 

195 if thing is None: 

196 continue 

197 a, b, c, d = thing.box 

198 box = ( 

199 (a - x0) * sx - 3, 

200 (y1 - d) * sy - 3, 

201 (c - x0) * sx + 3, 

202 (y1 - b) * sy + 3, 

203 ) 

204 draw.rectangle(box, outline=RED, width=2) 

205 tag = str(number) 

206 tx, ty = max(0.0, box[0]), max(0.0, box[1] - px - 4) 

207 draw.rectangle((tx, ty, tx + 8 + 10 * len(tag), ty + px + 4), fill=RED) 

208 draw.text((tx + 4, ty + 1), tag, fill="white", font=font) 

209 

210 

211def said(text: str, limit: int = 28) -> str: 

212 text = " ".join(text.split()) 

213 return repr(text if len(text) <= limit else text[: limit - 1] + "…") 

214 

215 

216def _named(function: Callable[..., object]) -> str: 

217 """A recorded method's name (an edit, `mob.animate(lambda m: …)`, has none).""" 

218 name = getattr(function, "__name__", None) 

219 return name if isinstance(name, str) else "edit" 

220 

221 

222def describe(animation: Animation) -> str: 

223 """An animation as the code wrote it: `Create(Circle)`, `title.animate.shift(…)`, 

224 `LaggedStart(4× FadeIn)`; a speech as what it says, `say 'Here is…'`, and a sound as 

225 `sound 0.8 s`.""" 

226 if isinstance(animation, Speech): 

227 return f"say {said(animation.text)}" 

228 if isinstance(animation, Sound): 

229 return f"sound {animation.duration:.1f} s" 

230 if ( # a line said with its animations (`Scene.say`) 

231 type(animation) is AnimationGroup 

232 and animation.animations 

233 and isinstance(animation.animations[0], Speech) 

234 ): 

235 speech, *rest = animation.animations 

236 return " with ".join([describe(speech), *(_waited(part) for part in rest)]) 

237 kind = type(animation).__name__ 

238 target = type(animation.mobject).__name__ 

239 words = text_of(animation.mobject) 

240 if words: 

241 target += f" {said(words)}" 

242 if isinstance(animation, Animate) and animation.methods: 

243 calls = ".".join(f"{_named(call.function)}(…)" for call in animation.methods) 

244 return f"{target}.animate.{calls}" 

245 if isinstance(animation, AnimationGroup) and animation.animations: 

246 inner = [describe(part) for part in animation.animations] 

247 kinds = {i.split("(")[0] for i in inner} 

248 if len(inner) > 3 and len(kinds) == 1: 

249 return f"{kind}({len(inner)}× {inner[0].split('(')[0]})" 

250 more = ", …" if len(inner) > 4 else "" 

251 return f"{kind}({', '.join(inner[:4])}{more})" 

252 return f"{kind}({target})" 

253 

254 

255def _waited(animation: Animation) -> str: 

256 """A part of a said line: one that waits for its words, as what it plays.""" 

257 parts = animation.animations if isinstance(animation, Succession) else [] 

258 if len(parts) == 2 and isinstance(parts[0], Wait): 

259 return describe(parts[1]) 

260 return describe(animation) 

261 

262 

263def line(play: Play, animations: tuple[Animation, ...]) -> str: 

264 where = ( 

265 "" if play.where is None else f"{Path(play.where[0]).name}:{play.where[1]} " 

266 ) 

267 what = ( 

268 "wait" 

269 if len(animations) == 1 and isinstance(animations[0], Wait) 

270 else ", ".join(describe(a) for a in animations) 

271 ) 

272 return ( 

273 f" #{play.index:<2d} {float(play.start):5.2f}–{float(play.end):5.2f}s " 

274 f" {where}{what}" 

275 )