The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.
Python
"""A 3D view composites what can be seen through in depth order, whatever order it is drawn
in: a pixel shows every surface, shape and point on its ray, the nearer over the farther — in a
picture and in a video alike, however many a ray meets. Where things meet edge to edge, each
covers its own part of a pixel."""
from pathlib import Path
import numpy as np
import pytest
from tests import scenes
from tests.integration.corpus.frames import decode
import manimgx as m
SIZE = (320, 180)
OPACITY = 0.4
COLORS = (m.RED, m.GREEN, m.BLUE, m.YELLOW, m.TEAL, m.PURPLE)
pytestmark = pytest.mark.config(pixel_width=SIZE[0], pixel_height=SIZE[1])
def stack(
order: list[int],
points: frozenset[int] = frozenset(),
colors: tuple[m.ManimColor, ...] = COLORS,
meshes: frozenset[int] = frozenset(),
*,
mesh_resolution: int = 1,
mesh_shift: float = 0.0,
) -> m.Scene:
"""Layers one behind another, layer k nearer than layer k - 1, in `colors[k]`, each
see-through; added in `order`. Each is a plane filling the view (a shape, or, if in
`meshes`, a surface), or, if in `points`, a point's disk over its center."""
def layer(k: int, color: m.ManimColor) -> m.Mobject:
if k in points:
shape = m.PMobject(stroke_width=270).add_points(
[m.ORIGIN], color=color, alpha=OPACITY
)
elif k in meshes:
shape = m.Surface(
lambda u, v: np.array([u, v, 0.0]),
u_range=[-20, 20],
v_range=[-20, 20],
resolution=mesh_resolution,
checkerboard_colors=False,
stroke_width=0,
shade_in_3d=False, # (its color as given, as a shape's)
).set_fill(color, OPACITY)
shape.shift(mesh_shift * (m.RIGHT - m.UP))
else:
shape = m.Square(side_length=40.0).set_fill(color, OPACITY)
shape.set_stroke(width=0)
return shape.shift(0.5 * k * m.OUT)
def construct(scene: m.ThreeDScene) -> None:
scene.set_camera_orientation(phi=0.0, theta=-90 * m.DEGREES)
layers = [layer(k, color) for k, color in enumerate(colors)]
scene.add(*(layers[k] for k in order))
scene.wait(0.1)
return scenes.scene_3d(construct)
def picture(scene: m.Scene) -> np.ndarray:
"""The first frame the scene shows (RGB rows)."""
return scenes.frames(scene)[0][..., :3]
def composite(colors: tuple[m.ManimColor, ...] = COLORS) -> np.ndarray:
"""The layers over black, nearest first: each seen through all nearer ones."""
rgb = np.zeros(3)
seen = 1.0 # how much of what is behind the nearer layers shows
for color in reversed(colors):
rgb += seen * OPACITY * m.ManimColor(color).to_rgb()
seen *= 1.0 - OPACITY
return rgb * 255
@pytest.mark.parametrize("colors", [COLORS, COLORS * 2], ids=["six", "twelve"])
def test_see_through_layers_composite_in_depth_order_in_any_order(
colors: tuple[m.ManimColor, ...],
) -> None:
# twelve: more than a pixel sorts at once (`FEW`), so it takes them a batch at a time
n = len(colors)
forward = picture(stack(list(range(n)), colors=colors))
backward = picture(stack(list(reversed(range(n))), colors=colors))
assert np.array_equal(forward, backward)
center = forward[SIZE[1] // 2, SIZE[0] // 2].astype(float)
assert np.abs(center - composite(colors)).max() <= 2.0
ALL, ODD = frozenset(range(len(COLORS))), frozenset(range(1, len(COLORS), 2))
@pytest.mark.parametrize(
("points", "colors", "meshes"),
[
(ALL, COLORS, frozenset()),
(ODD, COLORS, frozenset()),
(ALL, (m.TEAL,) * len(COLORS), frozenset()),
(ODD, COLORS, frozenset({2, 4})),
],
ids=[
"points",
"points-between-planes",
"points-of-one-color",
"points-between-surfaces",
],
)
def test_see_through_points_composite_in_depth_order_in_any_order(
points: frozenset[int],
colors: tuple[m.ManimColor, ...],
meshes: frozenset[int],
) -> None:
# points alone blend far to near (of one color, in any order); between planes, shapes or
# surfaces, each blends among the points between the same two planes
n = len(colors)
forward = picture(stack(list(range(n)), points, colors, meshes))
backward = picture(stack(list(reversed(range(n))), points, colors, meshes))
assert np.array_equal(forward, backward)
center = forward[SIZE[1] // 2, SIZE[0] // 2].astype(float)
assert np.abs(center - composite(colors)).max() <= 2.0
@pytest.mark.parametrize("resolution", [1, 2, 4])
@pytest.mark.parametrize("offset", [0.0, 0.02, 0.04])
def test_surface_tessellation_preserves_points_depth_order(
resolution: int, offset: float
) -> None:
# More triangles may meet a pixel, or a backend may append one node per sample.
# Neither creates more depth boundaries: each point stays between the same planes.
# Moving the grid by half a pixel makes its triangles share the center's samples.
for order in (list(range(len(COLORS))), list(reversed(range(len(COLORS))))):
shown = picture(
stack(
order,
ODD,
meshes=frozenset({2, 4}),
mesh_resolution=resolution,
mesh_shift=offset,
)
)
center = shown[SIZE[1] // 2, SIZE[0] // 2].astype(float)
assert np.abs(center - composite()).max() <= 2.0
def test_a_title_fixed_in_the_frame_changes_no_pixel_but_its_own() -> None:
# a deep pile of see-through points and a line beside it: a title fixed in the frame, over
# everything, takes no place among the scene's depths, so the pile is drawn as without it
def scene(title: bool) -> m.Scene:
def construct(s: m.ThreeDScene) -> None:
s.set_camera_orientation(phi=0.0, theta=-90 * m.DEGREES)
rng = np.random.default_rng(5)
pile = m.PMobject(stroke_width=20).add_points(
rng.normal(scale=0.02, size=(400, 3)) + [-1.0, -1.5, 0.0],
color=m.YELLOW,
alpha=0.55,
)
s.add(pile, m.Line([4.0, -3.5, 0.0], [4.0, -0.5, 0.0], stroke_width=4))
if title:
s.add_fixed_in_frame_mobjects(m.Text("A title").to_corner(m.UL))
s.wait(0.1)
return scenes.scene_3d(construct)
# the title is in the top left; the pile and the line below
bottom = slice(SIZE[1] // 2, None)
assert np.array_equal(picture(scene(True))[bottom], picture(scene(False))[bottom])
def test_a_mobject_unpinned_from_the_frame_is_drawn_as_one_never_pinned() -> None:
# a square and a title, pinned and then unpinned from a turned camera's frame: the square
# is drawn where the camera puts it, as if it had never been pinned; the title stays pinned
def scene(pin: bool) -> m.Scene:
def construct(s: m.ThreeDScene) -> None:
s.set_camera_orientation(phi=60 * m.DEGREES, theta=-30 * m.DEGREES)
square = m.Square(side_length=2.0, fill_opacity=1.0).shift(m.RIGHT)
title = m.Text("A title").to_corner(m.UL)
if pin:
s.add_fixed_in_frame_mobjects(square, title)
s.remove_fixed_in_frame_mobjects(square)
assert square in s.mobjects
assert square not in s.camera.fixed_in_frame_mobjects
assert title in s.camera.fixed_in_frame_mobjects
else:
s.add(square)
s.add_fixed_in_frame_mobjects(title)
s.wait(0.1)
return scenes.scene_3d(construct)
assert np.array_equal(picture(scene(True)), picture(scene(False)))
def test_points_show_where_an_earlier_frame_had_see_through_surfaces() -> None:
# a see-through surface over the whole view, then over its top only: the points below it
# show in the last frame as if it had always been at the top
def surface(v_range: list[float]) -> m.Surface:
return m.Surface(
lambda u, v: np.array([u, v, 1.0]),
u_range=[-8, 8],
v_range=v_range,
resolution=1,
checkerboard_colors=False,
stroke_width=0,
).set_fill(m.BLUE, 0.5)
def scene(first: list[float]) -> m.Scene:
def construct(s: m.ThreeDScene) -> None:
s.set_camera_orientation(phi=0.0, theta=-90 * m.DEGREES)
grid = [[x, y, 0.0] for x in np.linspace(-6, 6, 13) for y in (-3, -2, -1)]
s.add(
m.PMobject(stroke_width=40).add_points(grid, color=m.YELLOW, alpha=0.6)
)
sheet = surface(first)
s.add(sheet)
s.wait(0.1)
s.remove(sheet)
s.add(surface([3.0, 5.0]))
s.wait(0.1)
return scenes.scene_3d(construct)
bottom = slice(SIZE[1] // 2, None)
moved = scenes.frames(scene([-5.0, 5.0]))[-1][..., :3]
still = scenes.frames(scene([3.0, 5.0]))[-1][..., :3]
assert np.array_equal(moved[bottom], still[bottom])
def test_a_video_frame_that_outgrows_the_lists_is_drawn_whole(tmp_path: Path) -> None:
# every pixel meets six planes, more than the lists first hold: the frame is drawn again
stack(list(range(len(COLORS)))).render(tmp_path / "stack.mp4")
frame = next(decode(tmp_path / "stack.mp4", SIZE)).astype(float)
expected = picture(stack(list(range(len(COLORS))))).astype(float)
assert np.abs(frame - expected).mean() <= 1.0
@pytest.mark.parametrize("three_d", [False, True], ids=["2d", "3d"])
def test_a_mesh_and_a_shape_meeting_edge_to_edge_show_no_seam(three_d: bool) -> None:
# a mesh and a shape side by side on black, their common edge through the middle of a pixel:
# the pixel is half of each (were their coverages mixed as if independent, a quarter of the
# black would show through it: a dark seam)
boundary = 0.5 * 8 / SIZE[1] # half a pixel right of the view's centre, in units
def seam(scene: m.Scene) -> None:
if isinstance(scene, m.ThreeDScene):
scene.set_camera_orientation(phi=0.0, theta=-90 * m.DEGREES)
mesh = m.Surface(
lambda u, v: np.array([u, v, 0]),
u_range=[-5, boundary],
v_range=[-3, 3],
resolution=(1, 1),
stroke_width=0,
)
corners = [[boundary, -3, 0], [5, -3, 0], [5, 3, 0], [boundary, 3, 0]]
shape = m.Polygon(*corners, stroke_width=0, fill_opacity=1)
scene.add(mesh.set_color(m.WHITE), shape.set_fill(m.WHITE))
scene.wait(0.1)
told = scenes.scene_3d(seam) if three_d else scenes.scene(seam)
shown = picture(told).astype(float)
row, middle = SIZE[1] // 2, SIZE[0] // 2
left, here, right = (shown[row, middle + k] for k in (-3, 0, 3))
assert np.abs(here - 0.5 * (left + right)).max() <= 2.0