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

1"""Visible scene content and its layout diagnostics.""" 

2 

3import inspect 

4from dataclasses import dataclass, field, replace 

5from fractions import Fraction 

6from pathlib import Path 

7from types import FrameType 

8 

9import numpy as np 

10 

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 

17 

18PACKAGE = str(Path(manimgx.__file__).parent) 

19 

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 

36 

37type Box = tuple[float, float, float, float] # x0, y0, x1, y1 in scene units 

38 

39 

40@dataclass(frozen=True, slots=True) 

41class Thing: 

42 """A text, or another drawn part, as it is on screen.""" 

43 

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 

57 

58 

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 

66 

67 

68type Names = tuple[dict[int, str], dict[str, Mobject]] 

69 

70 

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] = {} 

77 

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) 

87 

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 

106 

107 

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

117 

118 

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 

126 

127 

128def _visible(mob: Mobject) -> bool: 

129 fill, stroked = _paint(mob) 

130 return fill > 0.02 or stroked 

131 

132 

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) 

144 

145 

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

150 

151 frame: Box 

152 things: list[Thing] 

153 framed: bool # the camera has moved or zoomed: it frames part of a larger world 

154 

155 

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) 

167 

168 

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] = [] 

174 

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__ 

180 

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__ 

187 

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) 

233 

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 ) 

263 

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 

270 

271 

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 

286 

287 

288type Moment = tuple[Fraction, tuple[str, int] | None] # time and source location 

289 

290 

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

298 

299 @property 

300 def note(self) -> bool: 

301 return self.kind == "runs off" 

302 

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) 

306 

307 

308def _area(b: Box) -> float: 

309 return max(0.0, b[2] - b[0]) * max(0.0, b[3] - b[1]) 

310 

311 

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

314 

315 

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 

320 

321 

322def _grow(b: Box, by: float) -> Box: 

323 return (b[0] - by, b[1] - by, b[2] + by, b[3] + by) 

324 

325 

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

345 

346 

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 

356 

357 

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

361 

362 

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) 

378 

379 

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 

461 

462 

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

467 

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] = {} 

471 

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 

482 

483 

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 

489 

490 

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

497 

498 

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) 

527 

528 

529def _alike(a: Problem, b: Problem) -> bool: 

530 """Problems of one kind between the same two named groups.""" 

531 

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) 

535 

536 return shape(a) == shape(b) 

537 

538 

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