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

Keep scene execution and camera state consistent

Sina Atalay5f41102373c7
diff --git a/src/manimgx/scene.py b/src/manimgx/scene.py
index 4960f69b..505ac6f9 100644
--- a/src/manimgx/scene.py
+++ b/src/manimgx/scene.py
@@ -10,6 +10,8 @@ from __future__ import annotations
from collections.abc import Iterable
from typing import TYPE_CHECKING, Literal, overload
+from typing_extensions import TypedDict
+
from manimgx.config import config
from manimgx.constants import DEGREES, DOWN, LEFT, OUT, RIGHT, UP
from manimgx.drawing.paint import ManimColor, ParsableManimColor
@@ -22,7 +24,7 @@ import os
import pathlib
from collections.abc import Callable, Sequence
from fractions import Fraction
-from typing import TYPE_CHECKING, NamedTuple, Self, TypedDict, Unpack, cast
+from typing import TYPE_CHECKING, NamedTuple, Self, Unpack, cast
from warnings import deprecated
import numpy as np
@@ -608,7 +610,7 @@ class Scene:
@staticmethod
def _fps() -> Fraction:
- return Fraction(config.frame_rate).limit_denominator(1000)
+ return clock.rational(config.frame_rate)
def render(
self,
@@ -627,8 +629,8 @@ class Scene:
`frames`, if given; each play or wait, as it ends, is handed to `plays`, if given.
A frame is drawn only for the video, or when `frames` asks for its pixels: with
neither, the frames are counted, not drawn, which checks a scene quickly. Frames
- `k = 0, 1, …` show the world at `k / fps` seconds, before the scene's end; the
- closing frame then shows it at its own instant: the scene's end if a frame falls
+ `k = 0, 1, …` sample `k / fps` seconds, after events at the same float instant;
+ the closing frame then shows it at its own instant: the scene's end if a frame falls
there, or else the first frame time after it. So the scene's last animation is
seen landing.
@@ -668,8 +670,8 @@ class Scene:
self.construct()
self.tear_down()
closing = Fraction(self.frame) / self._fps()
- if (
- closing > clock.now
+ if float(closing) > float(
+ clock.now
): # the scene ended between frames: the world at frame N
self._records = self._recording()
self._frame(closing, self._simulation_rate())
@@ -715,15 +717,17 @@ class Scene:
act: Act | None = None,
stop: Callable[[], bool] | None = None,
frozen: bool = False,
+ boundaries: dict[float, Fraction] | None = None,
) -> None:
- """Run the clock to `end`: each frame in [clock, end) shows the world at its instant (`act` is
+ """Run to `end`: frames in the observed [clock, end) show the world at their instants (`act` is
the play's step, before the updaters); then the world is brought to `end`. `stop` ends the run
at the frame it holds after. A frozen run, or one where nothing can change, is one held frame;
while anything is simulated, the world also steps at the simulation clock's ticks.
"""
fps, stopped = self._fps(), False
+ limit = clock.frame_at(end, fps)
if frozen or (act is None and stop is None and not self._anything_runs()):
- self._emit(int(-(-end * fps // 1)) - self.frame)
+ self._emit(limit - self.frame)
if frozen:
for mob in self.mobjects:
mob._stamp(end)
@@ -732,7 +736,8 @@ class Scene:
else:
rate = self._simulation_rate()
self._records = self._recording()
- while (t := Fraction(self.frame) / fps) < end:
+ while self.frame < limit:
+ t = self._sample(Fraction(self.frame) / fps, boundaries)
self._frame(t, rate, act)
self._emit()
if stop is not None and stop():
@@ -747,6 +752,13 @@ class Scene:
self._instant(end, act, framing=False)
self.clock = end
+ def _sample(
+ self, t: Fraction, boundaries: dict[float, Fraction] | None = None
+ ) -> Fraction:
+ # A frame observes all events at the same binary64 instant, in exact order.
+ # It must not rewind an event just beyond its mathematical grid time.
+ return max(t, self.clock, boundaries.get(float(t), t) if boundaries else t)
+
def _simulation_rate(self) -> int | None:
"""The simulation clock's rate, if anything in the scene is simulated (a time-based
updater that is not a flow — an integrator, a traced path), or in what the play
@@ -1230,7 +1242,7 @@ class Scene:
wait = anims[0] if len(anims) == 1 and isinstance(anims[0], Wait) else None
self.num_plays += 1
if wait is not None:
- end = start + _exact(wait.run_time)
+ end = start + wait._duration
self._run(end, stop=wait.stop_condition, frozen=bool(wait.is_static_wait))
else:
anim = (
@@ -1240,7 +1252,7 @@ class Scene:
*anims, group=Group(), suspend_mobject_updating=False
)
)
- end = start + _exact(anim.run_time)
+ end = start + anim._duration
self.compositor, self._animation = Compositor(), anim
try:
self._play(anim, start, end)
@@ -1295,10 +1307,20 @@ class Scene:
return None
fps = self._fps()
- frames = range(
- self.frame, int(-(-end * fps // 1))
- ) # their times fall in [start, end)
- alpha = [float((Fraction(k) / fps - start) / (end - start)) for k in frames]
+ parts = windows(anim)
+ boundaries: dict[float, Fraction] = {}
+ for part in parts:
+ for at in (part.opens, part.closes):
+ if at is not None:
+ time = start + at * (end - start)
+ boundaries[float(time)] = max(
+ boundaries.get(float(time), time), time
+ )
+ frames = range(self.frame, clock.frame_at(end, fps))
+ alpha = [
+ float((self._sample(Fraction(k) / fps, boundaries) - start) / (end - start))
+ for k in frames
+ ]
pure = self._pure_tweens(anim, alpha)
if pure is None:
# its parts begin and finish at their windows, whatever the frame rate: at
@@ -1306,12 +1328,12 @@ class Scene:
self._playing = _acted_on(anim)
self._events = {
start + x * (end - start): concern
- for x, concern in self._exact(windows(anim)).items()
+ for x, concern in self._exact(parts).items()
}
try:
if self._events and Fraction(self.frame) / fps != start:
self._instant(start, act, framing=False)
- self._run(end, act)
+ self._run(end, act, boundaries=boundaries)
finally:
self._events, self._playing = {}, []
else:
@@ -1692,7 +1714,7 @@ class Scene:
sound = sound.gain(gain)
# decoded now: a file it cannot read fails here, not at the end of the render
_ = sound.samples
- clip = Clip(sound, clock.now + _exact(time_offset))
+ clip = Clip(sound, clock.now + clock.rational(time_offset))
self.film.clips.append(clip)
return clip
@@ -2241,11 +2263,6 @@ def _written() -> tuple[str, int] | None:
return None if frame is None else (frame.f_code.co_filename, frame.f_lineno)
-def _exact(seconds: float) -> Fraction:
- """A duration given in float seconds, as the rational number it stands for."""
- return Fraction(seconds).limit_denominator(10**6)
-
-
def _restructure(
mobjects: Sequence[Mobject], to_remove: Iterable[Mobject], extract: bool = True
) -> list[Mobject]:
@@ -2285,8 +2302,8 @@ Y_COLOR = RED_C
Z_COLOR = BLUE_D
-class LabelPlacement(TypedDict, total=False):
- """Where a vector's label sits (for the methods that pass it on)."""
+class _LabelPlacement(TypedDict, total=False):
+ """LabelPlacement's keys, open, for the keywords that add to them."""
at_tip: bool
"""Whether the label goes beyond the vector's tip, rather than beside its middle
@@ -2299,7 +2316,11 @@ class LabelPlacement(TypedDict, total=False):
False)."""
-class VectorLabelOptions(LabelPlacement, total=False):
+class LabelPlacement(_LabelPlacement, total=False, closed=True):
+ """Where a vector's label sits (for the methods that pass it on)."""
+
+
+class VectorLabelOptions(_LabelPlacement, total=False, closed=True):
"""Where a vector's label sits, its color and its size (for the methods that pass
them on)."""
@@ -2309,7 +2330,7 @@ class VectorLabelOptions(LabelPlacement, total=False):
"""How much the label is scaled (default 0.8)."""
-class UnitSquareOptions(TypedDict, total=False):
+class UnitSquareOptions(TypedDict, total=False, closed=True):
"""The unit square's look (for the methods that pass it on)."""
color: Colors
diff --git a/tests/unit/test_scene.py b/tests/unit/test_scene.py
index 66a0e98e..7662f832 100644
--- a/tests/unit/test_scene.py
+++ b/tests/unit/test_scene.py
@@ -23,6 +23,7 @@ as they stand when their turns come.
to it, last ran or was added; a recorder runs after everything else, if it is still there.
"""
+import math
import sys
from collections.abc import Callable
from dataclasses import dataclass
@@ -39,10 +40,12 @@ from tests.scenes import (
Node,
Recorder,
Story,
+ assert_same_frames,
assert_same_instants,
assert_same_outcome,
outcome,
record,
+ scene,
stories,
)
@@ -110,6 +113,102 @@ def test_a_group_of_no_animations_is_an_error() -> None:
record(story)
[email protected](frame_rate=30)
+ ("duration", "count"),
+ [
+ (math.nextafter(5 / 6, 0), 26),
+ (5 / 6, 26),
+ (math.nextafter(5 / 6, math.inf), 27),
+ ],
+)
+def test_frame_boundaries_distinguish_adjacent_durations(
+ duration: float, count: int
+) -> None:
+ made = scene(lambda s: s.wait(duration))
+ film = made.render()
+ assert film.frame_count == count
+ assert float(made.clock) == duration
+
+
[email protected]("duration", [1e-8, math.ulp(0.0)])
+def test_a_positive_wait_never_becomes_zero(duration: float) -> None:
+ made = scene(lambda s: s.wait(duration))
+ film = made.render()
+ assert float(made.clock) == duration
+ assert made.clock > 0
+ assert film.frame_count == 2
+
+
[email protected](frame_rate=10)
+def test_an_absolute_target_subtraction_does_not_add_a_frame() -> None:
+ def story(s: m.Scene) -> None:
+ s.wait(14.6)
+ s.wait(20.8 - s.time)
+ s.wait(3)
+ s.wait(26.4 - s.time)
+ s.wait(1.2)
+ s.wait(30.5 - s.time)
+
+ made = scene(story)
+ film = made.render()
+ assert float(made.clock) == 30.5
+ assert film.frame_count == 306
+
+
[email protected]("fast", [False, True])
[email protected]("introduced", [False, True])
+def test_observed_event_boundaries_compose_without_rewinding(
+ fast: bool, introduced: bool
+) -> None:
+ def story(s: Recorder, nested: bool) -> None:
+ dot = m.Dot()
+ first, tiny = m.Wait(0.1), m.Wait(1e-18)
+ move = m.Transform(
+ dot, dot.copy().shift(m.RIGHT), run_time=0.1, introducer=introduced
+ )
+ if not introduced:
+ s.add(dot)
+ if nested:
+ s.play(m.Succession(first, tiny, move))
+ else:
+ s.play(first)
+ s.play(tiny)
+ s.play(move)
+
+ nested = record(lambda s: story(s, True), fps=10, fast=fast)
+ separate = record(lambda s: story(s, False), fps=10, fast=fast)
+ assert nested.clock == separate.clock > Fraction(1, 5)
+ assert float(nested.clock) == 0.2
+ assert nested.frame == separate.frame == 3
+ assert_same_frames(nested.frames, separate.frames)
+
+
+def test_a_sub_ulp_event_never_rewinds_a_simulated_updater() -> None:
+ steps: list[float] = []
+
+ def story(s: m.Scene) -> None:
+ s.add_updater(steps.append)
+ s.wait(0.1)
+ s.wait(1e-18)
+ s.wait(0.1)
+
+ made = scene(story)
+ made.render()
+ assert min(steps) >= 0
+ assert made.clock > Fraction(1, 5)
+ assert float(made.clock) == 0.2
+
+
[email protected](frame_rate=30000 / 1001)
+def test_the_scene_and_film_keep_the_same_fractional_frame_rate() -> None:
+ made = scene(lambda s: s.wait(1001 / 30000))
+ film = made.render()
+ assert film.fps == made._fps() == Fraction(30000, 1001)
+ assert made.clock == Fraction(1001, 30000)
+ assert film.frame_count == 2
+
+
@pytest.mark.parametrize("fps", [7, 10, 24])
def test_a_wait_that_stops_ends_at_its_instant(fps: int) -> None:
ends: list[tuple[float, float]] = []