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
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1"""Play reports, annotated pictures and storyboard sheets."""
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
10from PIL import Image, ImageDraw, ImageFont
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
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
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
52@dataclass
53class Sheets:
54 """Captioned tiles, six to a sheet, each sheet written as it fills: `path`, `…-2`, …"""
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]])
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()
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
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 = []
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
111RED = (255, 64, 64)
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."""
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""
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)
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)
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])
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)
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] + "…")
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"
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})"
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)
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 )