Coverage for src/manimgx/cli/diagnostics.py: 91%
312 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"""Visible scene content and its layout diagnostics."""
3import inspect
4from dataclasses import dataclass, field, replace
5from fractions import Fraction
6from pathlib import Path
7from types import FrameType
9import numpy as np
11import manimgx
12from manimgx.constants import DL, UR
13from manimgx.drawing.geometry import subpath_ranges
14from manimgx.mobject import Mobject
15from manimgx.scene import Scene
16from manimgx.settings import config
18PACKAGE = str(Path(manimgx.__file__).parent)
20TEXTS: tuple[type[Mobject], ...] = (
21 manimgx.Typst,
22 manimgx.DecimalNumber,
23 manimgx.Code,
24)
25# what the player draws (a plain Mobject with points — a ValueTracker's value — is not drawn)
26DRAWN: tuple[type[Mobject], ...] = (
27 manimgx.VMobject,
28 manimgx.PMobject,
29 manimgx.MeshMobject,
30 manimgx.ImageMobject,
31)
32SCENE_OWN = {"mobjects", "foreground_mobjects", "camera", "film", "compositor"}
33# an extent this small is none (a shape scaled to 0, where a GrowFromCenter starts): a fill needs
34# area to be seen, a stroke length
35EMPTY = 1e-9
37type Box = tuple[float, float, float, float] # x0, y0, x1, y1 in scene units
40@dataclass(frozen=True, slots=True)
41class Thing:
42 """A text, or another drawn part, as it is on screen."""
44 name: str # the code's name for it, or its kind
45 kind: str
46 text: str | None # what a text says (None: not a text)
47 box: Box
48 outline: np.ndarray | None # a shape's curves as polylines: (curves, samples, 2)
49 fill: float # fill opacity
50 stroked: bool # a visible outline
51 closed: bool # every subpath closes (not a line or a graph)
52 order: int # draw order
53 root: str # the outermost group the code names that holds it (else its top object's kind)
54 root_kind: str
55 backdrop: int | None # a text's own opaque background: its draw order
56 ink: int # a text's glyphs, fingerprinted: equal ink in one place is one text
59def written_frame() -> FrameType | None:
60 """The innermost frame of the scene's own code on the stack (outside ManimGX)."""
61 here = inspect.currentframe()
62 frame = None if here is None else here.f_back
63 while frame is not None and frame.f_code.co_filename.startswith(PACKAGE):
64 frame = frame.f_back
65 return frame
68type Names = tuple[dict[int, str], dict[str, Mobject]]
71def names(scene: Scene, frame: FrameType | None) -> Names:
72 """The code's names for the scene's objects — its running variables, then the scene's
73 attributes, and indices into the groups they name, a few levels deep — and the groups by
74 their bare names."""
75 named: dict[int, str] = {}
76 bare: dict[str, Mobject] = {}
78 def visit(mob: Mobject, name: str, depth: int) -> None:
79 if id(mob) in named:
80 return
81 named[id(mob)] = name
82 if "[" not in name:
83 bare.setdefault(name, mob)
84 if depth < 3:
85 for i, sub in enumerate(mob.submobjects[:64]):
86 visit(sub, f"{name}[{i}]", depth + 1)
88 scopes: list[tuple[str, dict[str, object]]] = []
89 while frame is not None:
90 if not frame.f_code.co_filename.startswith(PACKAGE):
91 scopes.append(("", dict(frame.f_locals)))
92 frame = frame.f_back
93 own = {k: v for k, v in vars(scene).items() if k not in SCENE_OWN}
94 scopes.append(("self.", own))
95 for prefix, scope in scopes:
96 for key, value in scope.items():
97 if key.startswith("_") or key == "self":
98 continue
99 if isinstance(value, Mobject):
100 visit(value, prefix + key, 0)
101 elif isinstance(value, list | tuple) and 0 < len(value) <= 64:
102 for i, item in enumerate(value):
103 if isinstance(item, Mobject):
104 visit(item, f"{prefix}{key}[{i}]", 1)
105 return named, bare
108def text_of(mob: Mobject) -> str:
109 """What a text says (empty if it keeps no source)."""
110 if isinstance(mob, manimgx.DecimalNumber):
111 return f"{mob.get_value():g}"
112 for attr in ("text", "tex_string", "original_text", "source"):
113 value = getattr(mob, attr, None)
114 if isinstance(value, str) and value:
115 return value
116 return ""
119def _paint(mob: Mobject) -> tuple[float, bool]:
120 """How much it fills (opacity), and whether its outline shows (a hairline of opacity ×
121 width below 0.02 does not)."""
122 fill = float(np.max(np.atleast_1d(mob.get_fill_opacity())))
123 stroke = float(np.max(np.atleast_1d(mob.get_stroke_opacity())))
124 width = float(np.max(np.atleast_1d(mob.get_stroke_width())))
125 return fill, stroke * width > 0.02
128def _visible(mob: Mobject) -> bool:
129 fill, stroked = _paint(mob)
130 return fill > 0.02 or stroked
133def outline(mob: Mobject) -> np.ndarray | None:
134 """A path's cubic curves as polylines (17 samples each): (curves, 17, 2)."""
135 points = mob.points
136 if len(points) < 4:
137 return points[None, :, :2] if len(points) >= 2 else None
138 curves = points[: len(points) // 4 * 4].reshape(-1, 4, points.shape[1])[:, :, :2]
139 t = np.linspace(0, 1, 17)
140 basis = np.stack(
141 [(1 - t) ** 3, 3 * (1 - t) ** 2 * t, 3 * (1 - t) * t**2, t**3], axis=1
142 )
143 return np.einsum("tk,ckd->ctd", basis, curves)
146@dataclass(frozen=True, slots=True)
147class View:
148 """What the viewer sees at a moment: the camera's frame (scene units) and the things in
149 it, in draw order."""
151 frame: Box
152 things: list[Thing]
153 framed: bool # the camera has moved or zoomed: it frames part of a larger world
156def view(scene: Scene, known: Names | None = None) -> View:
157 """What the viewer sees now. Names from the running code take precedence over `known`,
158 which preserves local names after `construct` returns."""
159 (x0, y0), (x1, y1) = (scene.camera.frame.get_corner(c)[:2] for c in (DL, UR))
160 frame = (float(x0), float(y0), float(x1), float(y1))
161 w, h = config.frame_width / 2, config.frame_height / 2
162 framed = max(abs(a - b) for a, b in zip(frame, (-w, -h, w, h), strict=True)) > 1e-3
163 current = names(scene, written_frame())
164 if known is not None:
165 current = (known[0] | current[0], known[1] | current[1])
166 return View(frame, seen(scene, current), framed)
169def seen(scene: Scene, scope: Names) -> list[Thing]:
170 """What the viewer sees now, in draw order."""
171 named, bare = scope
172 order = {id(leaf): i for i, leaf in enumerate(scene.display_list())}
173 out: list[Thing] = []
175 def name_of(mob: Mobject, chain: list[Mobject]) -> str:
176 for m in reversed(chain):
177 if id(m) in named:
178 return named[id(m)] + ("" if m is mob else "…")
179 return type(mob).__name__
181 def root_of(name: str, chain: list[Mobject]) -> tuple[str, str]:
182 group = bare.get(name.split("[")[0].rstrip("…"))
183 if group is not None:
184 return name.split("[")[0].rstrip("…"), type(group).__name__
185 top = chain[0]
186 return named.get(id(top), type(top).__name__), type(top).__name__
188 def visit(mob: Mobject, chain: list[Mobject]) -> None:
189 chain = [*chain, mob]
190 if isinstance(mob, TEXTS):
191 leaves = [m for m in mob.family_members_with_points() if _visible(m)]
192 if not leaves:
193 return
194 points = np.concatenate([m.points for m in leaves])[:, :2]
195 (x0, y0), (x1, y1) = points.min(axis=0), points.max(axis=0)
196 if min(x1 - x0, y1 - y0) <= EMPTY:
197 return # glyphs without area
198 backs = [
199 order.get(id(m), 0)
200 for m in leaves
201 if isinstance(m, manimgx.BackgroundRectangle) and _paint(m)[0] >= 0.9
202 ]
203 name = name_of(mob, chain)
204 root, root_kind = root_of(name, chain)
205 out.append(
206 Thing(
207 name=name,
208 kind=type(mob).__name__,
209 text=text_of(mob),
210 box=(x0, y0, x1, y1),
211 outline=None,
212 fill=1.0,
213 stroked=False,
214 closed=True,
215 order=min(order.get(id(m), 0) for m in leaves),
216 root=root,
217 root_kind=root_kind,
218 backdrop=min(backs) if backs else None,
219 ink=hash(np.round(points, 3).tobytes()),
220 )
221 )
222 return
223 if (
224 mob.has_points()
225 and id(mob) in order
226 and isinstance(mob, DRAWN)
227 and _visible(mob)
228 and (thing := shape(mob, chain)) is not None
229 ):
230 out.append(thing)
231 for sub in mob.submobjects:
232 visit(sub, chain)
234 def shape(mob: Mobject, chain: list[Mobject]) -> Thing | None:
235 curves = outline(mob) if isinstance(mob, manimgx.VMobject) else None
236 extent = curves.reshape(-1, 2) if curves is not None else mob.points[:, :2]
237 (x0, y0), (x1, y1) = extent.min(axis=0), extent.max(axis=0)
238 fill, stroked = _paint(mob)
239 if min(x1 - x0, y1 - y0) <= EMPTY and not (
240 stroked and max(x1 - x0, y1 - y0) > EMPTY
241 ):
242 return None # no area to fill, no length to stroke
243 closed = isinstance(mob, manimgx.VMobject) and all(
244 c for _, _, c in subpath_ranges(mob.points, 1e-6)
245 )
246 name = name_of(mob, chain)
247 root, root_kind = root_of(name, chain)
248 return Thing(
249 name=name,
250 kind=type(mob).__name__,
251 text=None,
252 box=(x0, y0, x1, y1),
253 outline=curves,
254 fill=fill,
255 stroked=stroked,
256 closed=closed,
257 order=order[id(mob)],
258 root=root,
259 root_kind=root_kind,
260 backdrop=None,
261 ink=0,
262 )
264 for mob in scene.mobjects:
265 visit(mob, [])
266 for mob in scene.foreground_mobjects:
267 if mob not in scene.mobjects:
268 visit(mob, [])
269 return out
272GRIDS = {
273 "NumberPlane",
274 "ComplexPlane",
275 "PolarPlane",
276 "ArrowVectorField",
277 "StreamLines",
278 "VectorField",
279}
280# sized to sit behind text: their edges are no collision
281BACKDROPS = {"BackgroundRectangle"}
282# scene units (4 px at 1080p): a line this close to a glyph's box touches it
283TOUCH = 0.03
284# pixels tall at 1080p, a video whose short side is 1080 px: text below this is hard to read
285SMALL = 20
288type Moment = tuple[Fraction, tuple[str, int] | None] # time and source location
291@dataclass
292class Problem:
293 kind: str # cut, runs off (a note), overlap, crossing, covered, small
294 subject: Thing
295 other: Thing | None
296 detail: str
297 moments: list[Moment] = field(default_factory=list[Moment])
299 @property
300 def note(self) -> bool:
301 return self.kind == "runs off"
303 def key(self) -> tuple[str, str, str | None, str | None]:
304 other = None if self.other is None else self.other.name
305 return (self.kind, self.subject.name, self.subject.text, other)
308def _area(b: Box) -> float:
309 return max(0.0, b[2] - b[0]) * max(0.0, b[3] - b[1])
312def _common(a: Box, b: Box) -> Box:
313 return (max(a[0], b[0]), max(a[1], b[1]), min(a[2], b[2]), min(a[3], b[3]))
316def _meet(a: Box, b: Box) -> bool:
317 """Do two boxes share a point? (A line's box has no height; it still meets a text's.)"""
318 x0, y0, x1, y1 = _common(a, b)
319 return x0 <= x1 and y0 <= y1
322def _grow(b: Box, by: float) -> Box:
323 return (b[0] - by, b[1] - by, b[2] + by, b[3] + by)
326def crosses(curves: np.ndarray, box: Box) -> bool:
327 """Does any segment of these polylines pass through the box (Liang–Barsky, all at once)?"""
328 a = curves[:, :-1].reshape(-1, 2)
329 d = curves[:, 1:].reshape(-1, 2) - a
330 x0, y0, x1, y1 = box
331 enter, leave = np.zeros(len(a)), np.ones(len(a))
332 inside = np.ones(len(a), bool)
333 for p, q in (
334 (-d[:, 0], a[:, 0] - x0),
335 (d[:, 0], x1 - a[:, 0]),
336 (-d[:, 1], a[:, 1] - y0),
337 (d[:, 1], y1 - a[:, 1]),
338 ):
339 parallel = p == 0
340 inside &= ~(parallel & (q < 0))
341 r = np.divide(q, p, out=np.zeros_like(q), where=~parallel)
342 enter = np.where(~parallel & (p < 0), np.maximum(enter, r), enter)
343 leave = np.where(~parallel & (p > 0), np.minimum(leave, r), leave)
344 return bool(np.any(inside & (enter <= leave)))
347def covers(curves: np.ndarray, points: np.ndarray) -> np.ndarray:
348 """Which points the region these closed polylines bound covers (even-odd rule)."""
349 a = curves[:, :-1].reshape(-1, 2)
350 b = curves[:, 1:].reshape(-1, 2)
351 px, py = points[:, 0:1], points[:, 1:2]
352 straddle = (a[:, 1] > py) != (b[:, 1] > py)
353 with np.errstate(divide="ignore", invalid="ignore"):
354 x = a[:, 0] + (py - a[:, 1]) * (b[:, 0] - a[:, 0]) / (b[:, 1] - a[:, 1])
355 return np.sum(straddle & (px < x), axis=1) % 2 == 1
358def _grid(box: Box, n: int) -> np.ndarray:
359 xs, ys = np.linspace(box[0], box[2], n), np.linspace(box[1], box[3], n)
360 return np.array([(x, y) for x in xs for y in ys])
363def _cut(box: Box, frame: Box) -> str | None:
364 x0, y0, x1, y1 = box
365 f0, g0, f1, g1 = frame
366 past = [
367 (f0 - x0, "left"),
368 (x1 - f1, "right"),
369 (y1 - g1, "top"),
370 (g0 - y0, "bottom"),
371 ]
372 sides = [f"{d:.2f} past the {side} edge" for d, side in past if d > 0.02]
373 if not sides:
374 return None
375 if x1 < f0 or x0 > f1 or y1 < g0 or y0 > g1:
376 return "outside the frame (not visible)"
377 return ", ".join(sides)
380def at(seen: View) -> list[Problem]:
381 """The problems a viewer sees in this view."""
382 frame, things = seen.frame, seen.things
383 # the camera maps the frame's height onto the video's, whatever the frame's shape
384 short = min(config.pixel_width, config.pixel_height)
385 px_per_unit = 1080 * config.pixel_height / short / (frame[3] - frame[1])
386 now: list[Problem] = []
387 texts = [t for t in things if t.text is not None]
388 shapes = [t for t in things if t.outline is not None]
389 groups: dict[str, list[Thing]] = {}
390 for t in things:
391 groups.setdefault(t.root, []).append(t)
392 for root, parts in groups.items():
393 if parts[0].root_kind in GRIDS:
394 continue
395 box = (
396 min(p.box[0] for p in parts),
397 min(p.box[1] for p in parts),
398 max(p.box[2] for p in parts),
399 max(p.box[3] for p in parts),
400 )
401 detail = _cut(box, frame)
402 if detail is None:
403 continue
404 whole = replace(
405 parts[0],
406 name=root,
407 kind=parts[0].root_kind,
408 box=box,
409 text=parts[0].text if len(parts) == 1 else None,
410 )
411 # meant often enough to be notes: a line or a graph leaving the frame, what is out of
412 # sight altogether, and what a moved or zoomed camera shows only part of
413 lines = all(p.outline is not None and not p.closed for p in parts)
414 gone = detail.startswith("outside")
415 partial = seen.framed and not (len(parts) == 1 and parts[0].text is not None)
416 note = lines or gone or partial
417 now.append(Problem("runs off" if note else "cut", whole, None, detail))
418 for i, a in enumerate(texts):
419 for b in texts[i + 1 :]:
420 if a.ink == b.ink or max(abs(u - v) for u, v in zip(a.box, b.box)) < 0.01:
421 continue # the same glyphs in one place (a transform's copy): one text
422 common = _area(_common(a.box, b.box))
423 if common > 1e-4 and common > 0.05 * min(_area(a.box), _area(b.box)):
424 now.append(Problem("overlap", a, b, "texts overlap"))
425 for a in texts:
426 tall = (a.box[3] - a.box[1]) * px_per_unit
427 if tall < SMALL:
428 now.append(
429 Problem("small", a, None, f"text is {tall:.0f} px tall at 1080p")
430 )
431 near = _grow(a.box, TOUCH)
432 samples = _grid(a.box, 7)
433 corners = _grid(near, 2)
434 # opaque fills under the text that cover it: lines drawn before them are hidden
435 backs = [
436 s.order
437 for s in shapes
438 if s.outline is not None
439 and s.fill >= 0.9
440 and s.order < a.order
441 and covers(s.outline, corners).all()
442 ]
443 if a.backdrop is not None:
444 backs.append(a.backdrop)
445 for s in shapes:
446 if s.outline is None or not _meet(near, s.box):
447 continue
448 under = s.order < a.order
449 edged = s.stroked or (s.fill >= 0.2 and s.kind not in BACKDROPS)
450 if edged and crosses(s.outline, near):
451 if under and (s.root_kind in GRIDS or any(s.order < b for b in backs)):
452 continue # a grid line, or one behind the text's backdrop
453 what = "runs through" if s.stroked else "has its edge through"
454 now.append(Problem("crossing", a, s, f"{s.kind} {what} the text"))
455 elif s.fill >= 0.5 and not under:
456 share = float(np.mean(covers(s.outline, samples)))
457 if share > 0.3:
458 detail = f"{s.kind} is drawn over {share:.0%} of it"
459 now.append(Problem("covered", a, s, detail))
460 return now
463class Layout:
464 """A take's problems at sampled moments: each once, with the moments it appears in; the
465 problems (not the notes) numbered from 1 in the order they first appear — as the report
466 and the storyboard number them."""
468 def __init__(self) -> None:
469 self.found: dict[tuple[str, str, str | None, str | None], Problem] = {}
470 self.numbers: dict[tuple[str, str, str | None, str | None], int] = {}
472 def see(self, moment: Moment, seen: View) -> list[tuple[int, Problem]]:
473 """The problems at this moment, and their numbers (0: a note)."""
474 out = []
475 for problem in at(seen):
476 key = problem.key()
477 self.found.setdefault(key, problem).moments.append(moment)
478 if not problem.note and key not in self.numbers:
479 self.numbers[key] = len(self.numbers) + 1
480 out.append((self.numbers.get(key, 0), problem))
481 return out
484def _label(t: Thing) -> str:
485 said = " ".join((t.text or "").split())
486 said = said if len(said) <= 30 else said[:29] + "…"
487 what = f"{t.kind} {said!r}" if t.text else t.kind
488 return f"{t.name} ({what})" if t.name != t.kind else what
491def _when(moments: list[Moment]) -> str:
492 """When a problem is seen, and the line that played its first sample."""
493 first, last = f"{float(moments[0][0]):g}", f"{float(moments[-1][0]):g}"
494 span = f"t={first}s" if first == last else f"t={first}–{last}s"
495 where = moments[0][1]
496 return span if where is None else f"{span} ({Path(where[0]).name}:{where[1]})"
499def report(layout: Layout, checked: int, similar: int = 3) -> str:
500 """A line per problem, by number; more than `similar` alike in a row (a label on each of
501 four planets) show the first and fold the rest; then the notes."""
502 found = layout.found
503 if not checked:
504 return "layout: not checked (no samples)"
505 if not found:
506 return f"layout: no problems in {checked} sample{'' if checked == 1 else 's'}"
507 real = sorted((n, found[k]) for k, n in layout.numbers.items())
508 notes = [p for p in found.values() if p.note]
509 head = f"layout: {len(real)} problem{'' if len(real) == 1 else 's'}"
510 if notes:
511 head += f", {len(notes)} note{'' if len(notes) == 1 else 's'} (likely meant)"
512 lines = [head]
513 runs: list[list[tuple[int, Problem]]] = []
514 for n, p in real:
515 if runs and _alike(runs[-1][-1][1], p):
516 runs[-1].append((n, p))
517 else:
518 runs.append([(n, p)])
519 for run in runs:
520 for n, p in run if len(run) <= similar else run[:1]:
521 lines.append(f" [{n}] {_line(p)}")
522 if len(run) > similar:
523 names = ", ".join(p.subject.name for _, p in run[1:])
524 lines.append(f" [{run[1][0]}–{run[-1][0]}] the same for {names}")
525 lines += [f" note: {_line(p)}" for p in notes]
526 return "\n".join(lines)
529def _alike(a: Problem, b: Problem) -> bool:
530 """Problems of one kind between the same two named groups."""
532 def shape(p: Problem) -> tuple[object, ...]:
533 other = None if p.other is None else (p.other.root, p.other.kind)
534 return (p.kind, p.subject.root, p.subject.kind, other)
536 return shape(a) == shape(b)
539def _line(p: Problem) -> str:
540 other = "" if p.other is None else f" and {_label(p.other)}"
541 return f"{_when(p.moments)} {_label(p.subject)}{other}: {p.detail}"