Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Add runtime diagnostics

Sina Atalay004825edf0b1
diff --git a/src/manimgx/cli/diagnostics.py b/src/manimgx/cli/diagnostics.py
new file mode 100644
index 00000000..be1de12e
--- /dev/null
+++ b/src/manimgx/cli/diagnostics.py
@@ -0,0 +1,530 @@
+"""Visible scene content and its layout diagnostics."""
+
+import inspect
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from types import FrameType
+
+import numpy as np
+
+import manimgx
+from manimgx.config import config
+from manimgx.constants import DL, UR
+from manimgx.drawing.geometry import subpath_ranges
+from manimgx.mobject import Mobject
+from manimgx.rendering.film import Play
+from manimgx.scene import Scene
+
+PACKAGE = str(Path(manimgx.__file__).parent)
+
+TEXTS: tuple[type[Mobject], ...] = (
+ manimgx.Typst,
+ manimgx.DecimalNumber,
+ manimgx.Code,
+)
+# what the player draws (a plain Mobject with points — a ValueTracker's value — is not drawn)
+DRAWN: tuple[type[Mobject], ...] = (
+ manimgx.VMobject,
+ manimgx.PMobject,
+ manimgx.MeshMobject,
+ manimgx.ImageMobject,
+)
+SCENE_OWN = {"mobjects", "foreground_mobjects", "camera", "film", "compositor"}
+# an extent this small is none (a shape scaled to 0, where a GrowFromCenter starts): a fill needs
+# area to be seen, a stroke length
+EMPTY = 1e-9
+
+type Box = tuple[float, float, float, float] # x0, y0, x1, y1 in scene units
+
+
+@dataclass(frozen=True, slots=True)
+class Thing:
+ """A text, or another drawn part, as it is on screen."""
+
+ name: str # the code's name for it, or its kind
+ kind: str
+ text: str | None # what a text says (None: not a text)
+ box: Box
+ outline: np.ndarray | None # a shape's curves as polylines: (curves, samples, 2)
+ fill: float # fill opacity
+ stroked: bool # a visible outline
+ closed: bool # every subpath closes (not a line or a graph)
+ order: int # draw order
+ root: str # the outermost group the code names that holds it (else its top object's kind)
+ root_kind: str
+ backdrop: int | None # a text's own opaque background: its draw order
+ ink: int # a text's glyphs, fingerprinted: equal ink in one place is one text
+
+
+def written_frame() -> FrameType | None:
+ """The innermost frame of the scene's own code on the stack (outside manimgx)."""
+ here = inspect.currentframe()
+ frame = None if here is None else here.f_back
+ while frame is not None and frame.f_code.co_filename.startswith(PACKAGE):
+ frame = frame.f_back
+ return frame
+
+
+def names(
+ scene: Scene, frame: FrameType | None
+) -> tuple[dict[int, str], dict[str, Mobject]]:
+ """The code's names for the scene's objects — its running variables, then the scene's
+ attributes, and indices into the groups they name, a few levels deep — and the groups by
+ their bare names."""
+ named: dict[int, str] = {}
+ bare: dict[str, Mobject] = {}
+
+ def visit(mob: Mobject, name: str, depth: int) -> None:
+ if id(mob) in named:
+ return
+ named[id(mob)] = name
+ if "[" not in name:
+ bare.setdefault(name, mob)
+ if depth < 3:
+ for i, sub in enumerate(mob.submobjects[:64]):
+ visit(sub, f"{name}[{i}]", depth + 1)
+
+ scopes: list[tuple[str, dict[str, object]]] = []
+ while frame is not None:
+ if not frame.f_code.co_filename.startswith(PACKAGE):
+ scopes.append(("", dict(frame.f_locals)))
+ frame = frame.f_back
+ own = {k: v for k, v in vars(scene).items() if k not in SCENE_OWN}
+ scopes.append(("self.", own))
+ for prefix, scope in scopes:
+ for key, value in scope.items():
+ if key.startswith("_") or key == "self":
+ continue
+ if isinstance(value, Mobject):
+ visit(value, prefix + key, 0)
+ elif isinstance(value, list | tuple) and 0 < len(value) <= 64:
+ for i, item in enumerate(value):
+ if isinstance(item, Mobject):
+ visit(item, f"{prefix}{key}[{i}]", 1)
+ return named, bare
+
+
+def text_of(mob: Mobject) -> str:
+ """What a text says (empty if it keeps no source)."""
+ if isinstance(mob, manimgx.DecimalNumber):
+ return f"{mob.get_value():g}"
+ for attr in ("text", "tex_string", "original_text", "source"):
+ value = getattr(mob, attr, None)
+ if isinstance(value, str) and value:
+ return value
+ return ""
+
+
+def _paint(mob: Mobject) -> tuple[float, bool]:
+ """How much it fills (opacity), and whether its outline shows (a hairline of opacity ×
+ width below 0.02 does not)."""
+ fill = float(np.max(np.atleast_1d(mob.get_fill_opacity())))
+ stroke = float(np.max(np.atleast_1d(mob.get_stroke_opacity())))
+ width = float(np.max(np.atleast_1d(mob.get_stroke_width())))
+ return fill, stroke * width > 0.02
+
+
+def _visible(mob: Mobject) -> bool:
+ fill, stroked = _paint(mob)
+ return fill > 0.02 or stroked
+
+
+def outline(mob: Mobject) -> np.ndarray | None:
+ """A path's cubic curves as polylines (17 samples each): (curves, 17, 2)."""
+ points = mob.points
+ if len(points) < 4:
+ return points[None, :, :2] if len(points) >= 2 else None
+ curves = points[: len(points) // 4 * 4].reshape(-1, 4, points.shape[1])[:, :, :2]
+ t = np.linspace(0, 1, 17)
+ basis = np.stack(
+ [(1 - t) ** 3, 3 * (1 - t) ** 2 * t, 3 * (1 - t) * t**2, t**3], axis=1
+ )
+ return np.einsum("tk,ckd->ctd", basis, curves)
+
+
+@dataclass(frozen=True, slots=True)
+class View:
+ """What the viewer sees at a moment: the camera's frame (scene units) and the things in
+ it, in draw order."""
+
+ frame: Box
+ things: list[Thing]
+ framed: bool # the camera has moved or zoomed: it frames part of a larger world
+
+
+def view(scene: Scene) -> View:
+ """What the viewer sees now — called from inside a play hook: the scene's code (whose
+ variables name things) is up the stack."""
+ (x0, y0), (x1, y1) = (scene.camera.frame.get_corner(c)[:2] for c in (DL, UR))
+ frame = (float(x0), float(y0), float(x1), float(y1))
+ w, h = config.frame_width / 2, config.frame_height / 2
+ framed = max(abs(a - b) for a, b in zip(frame, (-w, -h, w, h), strict=True)) > 1e-3
+ return View(frame, seen(scene, written_frame()), framed)
+
+
+def seen(scene: Scene, frame: FrameType | None) -> list[Thing]:
+ """What the viewer sees now, in draw order."""
+ named, bare = names(scene, frame)
+ order = {id(leaf): i for i, leaf in enumerate(scene.display_list())}
+ out: list[Thing] = []
+
+ def name_of(mob: Mobject, chain: list[Mobject]) -> str:
+ for m in reversed(chain):
+ if id(m) in named:
+ return named[id(m)] + ("" if m is mob else "…")
+ return type(mob).__name__
+
+ def root_of(name: str, chain: list[Mobject]) -> tuple[str, str]:
+ group = bare.get(name.split("[")[0].rstrip("…"))
+ if group is not None:
+ return name.split("[")[0].rstrip("…"), type(group).__name__
+ top = chain[0]
+ return named.get(id(top), type(top).__name__), type(top).__name__
+
+ def visit(mob: Mobject, chain: list[Mobject]) -> None:
+ chain = [*chain, mob]
+ if isinstance(mob, TEXTS):
+ leaves = [m for m in mob.family_members_with_points() if _visible(m)]
+ if not leaves:
+ return
+ points = np.concatenate([m.points for m in leaves])[:, :2]
+ (x0, y0), (x1, y1) = points.min(axis=0), points.max(axis=0)
+ if min(x1 - x0, y1 - y0) <= EMPTY:
+ return # glyphs without area
+ backs = [
+ order.get(id(m), 0)
+ for m in leaves
+ if isinstance(m, manimgx.BackgroundRectangle) and _paint(m)[0] >= 0.9
+ ]
+ name = name_of(mob, chain)
+ root, root_kind = root_of(name, chain)
+ out.append(
+ Thing(
+ name=name,
+ kind=type(mob).__name__,
+ text=text_of(mob),
+ box=(x0, y0, x1, y1),
+ outline=None,
+ fill=1.0,
+ stroked=False,
+ closed=True,
+ order=min(order.get(id(m), 0) for m in leaves),
+ root=root,
+ root_kind=root_kind,
+ backdrop=min(backs) if backs else None,
+ ink=hash(np.round(points, 3).tobytes()),
+ )
+ )
+ return
+ if (
+ mob.has_points()
+ and id(mob) in order
+ and isinstance(mob, DRAWN)
+ and _visible(mob)
+ and (thing := shape(mob, chain)) is not None
+ ):
+ out.append(thing)
+ for sub in mob.submobjects:
+ visit(sub, chain)
+
+ def shape(mob: Mobject, chain: list[Mobject]) -> Thing | None:
+ curves = outline(mob) if isinstance(mob, manimgx.VMobject) else None
+ extent = curves.reshape(-1, 2) if curves is not None else mob.points[:, :2]
+ (x0, y0), (x1, y1) = extent.min(axis=0), extent.max(axis=0)
+ fill, stroked = _paint(mob)
+ if min(x1 - x0, y1 - y0) <= EMPTY and not (
+ stroked and max(x1 - x0, y1 - y0) > EMPTY
+ ):
+ return None # no area to fill, no length to stroke
+ closed = isinstance(mob, manimgx.VMobject) and all(
+ c for _, _, c in subpath_ranges(mob.points, 1e-6)
+ )
+ name = name_of(mob, chain)
+ root, root_kind = root_of(name, chain)
+ return Thing(
+ name=name,
+ kind=type(mob).__name__,
+ text=None,
+ box=(x0, y0, x1, y1),
+ outline=curves,
+ fill=fill,
+ stroked=stroked,
+ closed=closed,
+ order=order[id(mob)],
+ root=root,
+ root_kind=root_kind,
+ backdrop=None,
+ ink=0,
+ )
+
+ for mob in scene.mobjects:
+ visit(mob, [])
+ for mob in scene.foreground_mobjects:
+ if mob not in scene.mobjects:
+ visit(mob, [])
+ return out
+
+
+GRIDS = {
+ "NumberPlane",
+ "ComplexPlane",
+ "PolarPlane",
+ "ArrowVectorField",
+ "StreamLines",
+ "VectorField",
+}
+# sized to sit behind text: their edges are no collision
+BACKDROPS = {"BackgroundRectangle"}
+# scene units (4 px at 1080p): a line this close to a glyph's box touches it
+TOUCH = 0.03
+# pixels tall at 1080p: text below this is hard to read
+SMALL = 20
+
+
+@dataclass
+class Problem:
+ kind: str # cut, runs off (a note), overlap, crossing, covered, small
+ subject: Thing
+ other: Thing | None
+ detail: str
+ ends: list[Play] = field(default_factory=list[Play]) # the plays it is seen after
+
+ @property
+ def note(self) -> bool:
+ return self.kind == "runs off"
+
+ def key(self) -> tuple[str, str, str | None, str | None]:
+ other = None if self.other is None else self.other.name
+ return (self.kind, self.subject.name, self.subject.text, other)
+
+
+def _area(b: Box) -> float:
+ return max(0.0, b[2] - b[0]) * max(0.0, b[3] - b[1])
+
+
+def _common(a: Box, b: Box) -> Box:
+ return (max(a[0], b[0]), max(a[1], b[1]), min(a[2], b[2]), min(a[3], b[3]))
+
+
+def _meet(a: Box, b: Box) -> bool:
+ """Do two boxes share a point? (A line's box has no height; it still meets a text's.)"""
+ x0, y0, x1, y1 = _common(a, b)
+ return x0 <= x1 and y0 <= y1
+
+
+def _grow(b: Box, by: float) -> Box:
+ return (b[0] - by, b[1] - by, b[2] + by, b[3] + by)
+
+
+def crosses(curves: np.ndarray, box: Box) -> bool:
+ """Does any segment of these polylines pass through the box (Liang–Barsky, all at once)?"""
+ a = curves[:, :-1].reshape(-1, 2)
+ d = curves[:, 1:].reshape(-1, 2) - a
+ x0, y0, x1, y1 = box
+ enter, leave = np.zeros(len(a)), np.ones(len(a))
+ inside = np.ones(len(a), bool)
+ for p, q in (
+ (-d[:, 0], a[:, 0] - x0),
+ (d[:, 0], x1 - a[:, 0]),
+ (-d[:, 1], a[:, 1] - y0),
+ (d[:, 1], y1 - a[:, 1]),
+ ):
+ parallel = p == 0
+ inside &= ~(parallel & (q < 0))
+ r = np.divide(q, p, out=np.zeros_like(q), where=~parallel)
+ enter = np.where(~parallel & (p < 0), np.maximum(enter, r), enter)
+ leave = np.where(~parallel & (p > 0), np.minimum(leave, r), leave)
+ return bool(np.any(inside & (enter <= leave)))
+
+
+def covers(curves: np.ndarray, points: np.ndarray) -> np.ndarray:
+ """Which points the region these closed polylines bound covers (even-odd rule)."""
+ a = curves[:, :-1].reshape(-1, 2)
+ b = curves[:, 1:].reshape(-1, 2)
+ px, py = points[:, 0:1], points[:, 1:2]
+ straddle = (a[:, 1] > py) != (b[:, 1] > py)
+ with np.errstate(divide="ignore", invalid="ignore"):
+ x = a[:, 0] + (py - a[:, 1]) * (b[:, 0] - a[:, 0]) / (b[:, 1] - a[:, 1])
+ return np.sum(straddle & (px < x), axis=1) % 2 == 1
+
+
+def _grid(box: Box, n: int) -> np.ndarray:
+ xs, ys = np.linspace(box[0], box[2], n), np.linspace(box[1], box[3], n)
+ return np.array([(x, y) for x in xs for y in ys])
+
+
+def _cut(box: Box, frame: Box) -> str | None:
+ x0, y0, x1, y1 = box
+ f0, g0, f1, g1 = frame
+ past = [
+ (f0 - x0, "left"),
+ (x1 - f1, "right"),
+ (y1 - g1, "top"),
+ (g0 - y0, "bottom"),
+ ]
+ sides = [f"{d:.2f} past the {side} edge" for d, side in past if d > 0.02]
+ if not sides:
+ return None
+ if x1 < f0 or x0 > f1 or y1 < g0 or y0 > g1:
+ return "outside the frame (not visible)"
+ return ", ".join(sides)
+
+
+def at(seen: View) -> list[Problem]:
+ """The problems a viewer sees in this view."""
+ frame, things = seen.frame, seen.things
+ px_per_unit = 1080 / (frame[3] - frame[1])
+ now: list[Problem] = []
+ texts = [t for t in things if t.text is not None]
+ shapes = [t for t in things if t.outline is not None]
+ groups: dict[str, list[Thing]] = {}
+ for t in things:
+ groups.setdefault(t.root, []).append(t)
+ for root, parts in groups.items():
+ if parts[0].root_kind in GRIDS:
+ continue
+ box = (
+ min(p.box[0] for p in parts),
+ min(p.box[1] for p in parts),
+ max(p.box[2] for p in parts),
+ max(p.box[3] for p in parts),
+ )
+ detail = _cut(box, frame)
+ if detail is None:
+ continue
+ whole = replace(
+ parts[0],
+ name=root,
+ kind=parts[0].root_kind,
+ box=box,
+ text=parts[0].text if len(parts) == 1 else None,
+ )
+ # meant often enough to be notes: a line or a graph leaving the frame, what is out of
+ # sight altogether, and what a moved or zoomed camera shows only part of
+ lines = all(p.outline is not None and not p.closed for p in parts)
+ gone = detail.startswith("outside")
+ partial = seen.framed and not (len(parts) == 1 and parts[0].text is not None)
+ note = lines or gone or partial
+ now.append(Problem("runs off" if note else "cut", whole, None, detail))
+ for i, a in enumerate(texts):
+ for b in texts[i + 1 :]:
+ if a.ink == b.ink or max(abs(u - v) for u, v in zip(a.box, b.box)) < 0.01:
+ continue # the same glyphs in one place (a transform's copy): one text
+ common = _area(_common(a.box, b.box))
+ if common > 1e-4 and common > 0.05 * min(_area(a.box), _area(b.box)):
+ now.append(Problem("overlap", a, b, "texts overlap"))
+ for a in texts:
+ tall = (a.box[3] - a.box[1]) * px_per_unit
+ if tall < SMALL:
+ now.append(
+ Problem("small", a, None, f"text is {tall:.0f} px tall at 1080p")
+ )
+ near = _grow(a.box, TOUCH)
+ samples = _grid(a.box, 7)
+ corners = _grid(near, 2)
+ # opaque fills under the text that cover it: lines drawn before them are hidden
+ backs = [
+ s.order
+ for s in shapes
+ if s.outline is not None
+ and s.fill >= 0.9
+ and s.order < a.order
+ and covers(s.outline, corners).all()
+ ]
+ if a.backdrop is not None:
+ backs.append(a.backdrop)
+ for s in shapes:
+ if s.outline is None or not _meet(near, s.box):
+ continue
+ under = s.order < a.order
+ edged = s.stroked or (s.fill >= 0.2 and s.kind not in BACKDROPS)
+ if edged and crosses(s.outline, near):
+ if under and (s.root_kind in GRIDS or any(s.order < b for b in backs)):
+ continue # a grid line, or one behind the text's backdrop
+ what = "runs through" if s.stroked else "has its edge through"
+ now.append(Problem("crossing", a, s, f"{s.kind} {what} the text"))
+ elif s.fill >= 0.5 and not under:
+ share = float(np.mean(covers(s.outline, samples)))
+ if share > 0.3:
+ detail = f"{s.kind} is drawn over {share:.0%} of it"
+ now.append(Problem("covered", a, s, detail))
+ return now
+
+
+class Layout:
+ """A take's problems as its plays end: each once, with the plays it lasts through; the
+ problems (not the notes) numbered from 1 in the order they first appear — as the report
+ and the storyboard number them."""
+
+ def __init__(self) -> None:
+ self.found: dict[tuple[str, str, str | None, str | None], Problem] = {}
+ self.numbers: dict[tuple[str, str, str | None, str | None], int] = {}
+
+ def see(self, play: Play, seen: View) -> list[tuple[int, Problem]]:
+ """The problems at this play's end (as they are now), and their numbers (0: a note)."""
+ out = []
+ for problem in at(seen):
+ key = problem.key()
+ self.found.setdefault(key, problem).ends.append(play)
+ if not problem.note and key not in self.numbers:
+ self.numbers[key] = len(self.numbers) + 1
+ out.append((self.numbers.get(key, 0), problem))
+ return out
+
+
+def _label(t: Thing) -> str:
+ said = " ".join((t.text or "").split())
+ said = said if len(said) <= 30 else said[:29] + "…"
+ what = f"{t.kind} {said!r}" if t.text else t.kind
+ return f"{t.name} ({what})" if t.name != t.kind else what
+
+
+def _when(ends: list[Play]) -> str:
+ """When a problem is seen: from the end of the play that brought it (and that play's line)."""
+ first, last = f"{float(ends[0].end):.1f}", f"{float(ends[-1].end):.1f}"
+ span = f"t={first}s" if first == last else f"t={first}–{last}s"
+ where = ends[0].where
+ return span if where is None else f"{span} (after {Path(where[0]).name}:{where[1]})"
+
+
+def report(layout: Layout, checked: int, similar: int = 3) -> str:
+ """A line per problem, by number; more than `similar` alike in a row (a label on each of
+ four planets) show the first and fold the rest; then the notes."""
+ found = layout.found
+ if not found:
+ return f"layout: no problems at the end of any of the {checked} plays"
+ real = sorted((n, found[k]) for k, n in layout.numbers.items())
+ notes = [p for p in found.values() if p.note]
+ head = f"layout: {len(real)} problem{'' if len(real) == 1 else 's'}"
+ if notes:
+ head += f", {len(notes)} note{'' if len(notes) == 1 else 's'} (likely meant)"
+ lines = [head]
+ runs: list[list[tuple[int, Problem]]] = []
+ for n, p in real:
+ if runs and _alike(runs[-1][-1][1], p):
+ runs[-1].append((n, p))
+ else:
+ runs.append([(n, p)])
+ for run in runs:
+ for n, p in run if len(run) <= similar else run[:1]:
+ lines.append(f" [{n}] {_line(p)}")
+ if len(run) > similar:
+ names = ", ".join(p.subject.name for _, p in run[1:])
+ lines.append(f" [{run[1][0]}–{run[-1][0]}] the same for {names}")
+ lines += [f" note: {_line(p)}" for p in notes]
+ return "\n".join(lines)
+
+
+def _alike(a: Problem, b: Problem) -> bool:
+ """Problems of one kind between the same two named groups."""
+
+ def shape(p: Problem) -> tuple[object, ...]:
+ other = None if p.other is None else (p.other.root, p.other.kind)
+ return (p.kind, p.subject.root, p.subject.kind, other)
+
+ return shape(a) == shape(b)
+
+
+def _line(p: Problem) -> str:
+ other = "" if p.other is None else f" and {_label(p.other)}"
+ return f"{_when(p.ends)} {_label(p.subject)}{other}: {p.detail}"