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

Explain the benchmark in benchmarks/ and simplify the user guide

Sina Atalaydccac8ef8bf4
diff --git a/AGENTS.md b/AGENTS.md
index d7c79db0..eb6f09f9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,8 +85,8 @@ is published apart from it has a folder of its own, with its own tests.
`tests/docs/`: `llms.txt`'s hand-written primer for agents, checked against the API, and
the narrated examples, which say what `docs/voice/` keeps (the site is built with no key).
- `tests/benchmarks/`: laws of what work costs (with the suite) and timed benchmarks against
- another commit (`just bench`): `manimgx render` of the README's scenes (`scenes/`) and of
- example films, from launch to exit.
+ another commit (`just bench`): `manimgx render` of three scenes (`scenes/`) and of example
+ films, from launch to exit.
- `docs/`: the Zensical site and what its build loads. Pages are in `docs/content/`, the
first, Welcome, being the README, included; `docs/examples.py` renders the examples in
them and in the docstrings, and shows each above its code; `docs/links.py` makes the
@@ -99,14 +99,17 @@ is published apart from it has a folder of its own, with its own tests.
whole. `docs/zensical.toml` sets the site; its llmstxt plugin
writes each page's Markdown beside it, and `llms.txt`, whose primer for agents it holds.
- `examples/`: example films.
+- `benchmarks/`: the README's benchmark, ManimGX against Manim CE, ManimGL and Blender on
+ five scenes (`scenes/`). Its `README.md` is the method and the results, the source of the
+ README's numbers; `run.py` times the engines into `results.json`, `chart.py` draws the
+ README's chart from it into `docs/content/images/`, and `quality.py` renders the README's
+ comparison images (`docs/content/images/benchmark-quality/`).
- `scripts/`: what writes and builds, a folder for each thing it makes. `release/`: lavapipe
for the Linux wheels, the wheels' third-party notice, the executables, and the smoke test a
wheel or an executable passes. `docs/`: the pages the docs build generates (not committed),
the command line's reference (`reference.py`) and the Gallery from `examples/`
(`gallery.py`). `showcase/`: the README's pictures (committed), the logo (`logo.py`: the
banner, the header's, the favicon) and the wall of films (`wall.py`). `engine/`: the DFG
- table the engine is compiled with (`dfg_table.py`). `benchmark/` times ManimGX against
- Manim CE, ManimGL and Blender on the README's scenes (`run.py` writes `results.json`;
- `chart.py` draws the README's chart from it into `docs/content/images/`).
+ table the engine is compiled with (`dfg_table.py`).
- `skills/manimgx/`: the agent skill, which `npx skills add academa-labs/manimgx` installs;
`tests/docs/test_skill.py` checks its front matter.
diff --git a/README.md b/README.md
index 8705dc59..16497ccc 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@
<a href="https://github.com/academa-labs/manimgx/blob/main/examples/catenoid_helicoid.py"><img alt="A rainbow helicoid bends into a catenoid while preserving its intrinsic curvature" src="https://raw.githubusercontent.com/academa-labs/manimgx/main/docs/content/showcase/catenoid_helicoid.gif" width="32%"></a>
</p>
-**36.2 seconds of video, rendered in 3.08 seconds.** Across five scenes at 1080p60 on an Apple M4 Pro, ManimGX is **90.6× faster than ManimCE**, **11.5× faster than ManimGL**, and **18.7× faster than Blender Workbench**, from launch to finished MP4.
+**36.2 seconds of video, rendered in 3.08 seconds.** Across five scenes at 1080p60 on an Apple M4 Pro, ManimGX is **90.6× faster than ManimCE**, **11.5× faster than ManimGL**, and **18.7× faster than Blender Workbench**, from launch to finished MP4. [How it was measured](https://github.com/academa-labs/manimgx/tree/main/benchmarks): the scenes, the settings and every run.
<figure class="mx-benchmark">
<picture>
@@ -122,7 +122,7 @@ ManimGX's Rust + wgpu engine renders the MP4, blazingly fast.
and plots.
- **Runs in the browser.** `npm install manimgx`. [Pyodide](https://pyodide.org) runs
Python in a Web Worker; WebGPU renders the scene.
- [Embed a scene](https://manimgx.academa.ai/user-guide/rendering/#in-the-browser) with no render server.
+ [Embed a scene](https://manimgx.academa.ai/user-guide/rendering/#embed-in-a-web-page) with no render server.
- **Agent feedback.** [`manimgx inspect`](https://manimgx.academa.ai/user-guide/rendering/#inspect): storyboards and 2D layout checks, at play endings or times you choose.
- **Text and math.** Write LaTeX or Typst. No LaTeX installation needed.
- **Speech in sync.** [Match animations to spoken words](https://manimgx.academa.ai/user-guide/sound-and-voice/)
diff --git a/benchmarks/README.md b/benchmarks/README.md
new file mode 100644
index 00000000..f54c8364
--- /dev/null
+++ b/benchmarks/README.md
@@ -0,0 +1,150 @@
+# Benchmarks
+
+How long ManimGX, ManimGL, Manim Community Edition (ManimCE) and Blender take to make the
+same five scenes into 1080p60 MP4 videos, each with its own renderer. The
+[README](../README.md)'s numbers, chart and comparison images all come from this folder: the
+scenes, the runner, its recorded results, and the scripts that draw the chart and the images.
+
+## Results
+
+Times are in seconds, from launching the engine to its finished MP4. Lower is better.
+
+| Scene | Video | ManimGX | ManimGL | ManimCE | Blender Workbench | Blender EEVEE |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Surface and orbiting camera (`orbit`) | 10 s | 1.184 | 6.463 | 211.809 | 16.563 | 220.242 |
+| Matrix-vector multiplication (`matrix`) | 7.2 s | 0.360 | 8.287 | 7.140 | 11.045 | 90.798 |
+| Twelve pendulums (`pendulums`) | 13 s | 0.756 | 16.812 | 4.745 | 19.860 | 165.890 |
+| Planets and moons (`hierarchy`) | 3 s | 0.334 | 1.789 | 16.169 | 4.979 | 62.265 |
+| Linked rings (`linked_rings`) | 3 s | 0.443 | 1.933 | 38.962 | 5.163 | 62.200 |
+| Total | 36.2 s | 3.078 | 35.284 | 278.826 | 57.611 | 601.395 |
+| Relative to ManimGX | | 1× | 11.5× | 90.6× | 18.7× | 195.4× |
+
+A scene's time is the mean of three runs for ManimGX and ManimGL, and a single run for
+ManimCE and each Blender renderer. A total adds an engine's five scene times.
+[`results.json`](results.json) holds all 45 runs: the command of each, its wall and CPU
+times, and the checks of its video.
+
+Measured on October 7, 2026, on an Apple M4 Pro (12 CPU cores, 24 GB of memory) with macOS
+15.7.9: ManimGX 0.1.0, ManimGL 1.7.2, ManimCE 0.21.0 and Blender 5.2.2 LTS.
+
+## Scenes
+
+| Scene | What it shows |
+| --- | --- |
+| `orbit` | A 48 × 48 surface on three axes, a curve drawn across it with a ball riding its tip, and an orbiting camera. |
+| `matrix` | A matrix-vector product, its arithmetic written out, and the resulting vector. |
+| `pendulums` | Twelve pendulums of different lengths, their rods and bobs swinging, under a title. |
+| `hierarchy` | Five planets and five moons moving around a central sphere, seen by an orbiting camera. |
+| `linked_rings` | Eight linked rings (tori of 32 × 8 faces) moving under one key light, seen by an orbiting camera. |
+
+Each engine makes the scenes with its own API: geometry, animation, text and shading. In
+[`scenes/`](scenes), `orbit`, `matrix` and `pendulums` have a file for each Manim engine
+(`orbit_manimgx.py`, `orbit_manimgl.py`, `orbit_manim_ce.py`, …); `hierarchy` and
+`linked_rings` share one for the three (`suite_manim.py`). Blender's scenes are scripts for
+its Python API (`*_blender.py`). `suite_data.py` holds what the engines share: the
+scenes' lengths, the output's size and frame rate, and the shapes' positions over time.
+
+## Method
+
+- **The same videos.** Every engine makes each scene at 1920 × 1080 and 60 frames a second,
+ as H.264 video (`yuv420p`) in an MP4, with its own renderer and exporter: `manimgx
+ render`, ManimCE's `manim render`, `manimgl -w`, and Blender in the background
+ (`blender -b`), with Workbench or EEVEE. EEVEE takes 64 samples a pixel; Workbench draws
+ with its rasterizer.
+- **The fastest encoding.** ManimGX, ManimGL and ManimCE encode with x264's `ultrafast`
+ preset at CRF 23: ManimGX through its command's options, ManimCE and ManimGL through
+ `scenes/ce_cli.py` and `scenes/ffmpeg.py`, which hand those options to their encoders.
+ Blender's fastest preset is `REALTIME`, also at CRF 23; the options it encodes with
+ correspond to x264's `superfast`.
+- **From launch to finished MP4.** A run's time starts when its process launches and ends
+ when the process exits: starting up, building the scene, rendering, encoding and
+ finishing the MP4. ManimGX's time includes the storyboard and the layout checks that
+ `manimgx render` always makes.
+- **Fresh processes.** Each run starts a new process, with an output folder and a cache of
+ its own (ManimCE's cache is off). The runs go one after another. The operating system's
+ and the GPU driver's caches are not cleared between them.
+- **Checked videos.** After the timer stops, the runner decodes every frame of the video and
+ checks its size, pixel format, frame rate, timestamps and length, and the x264 options
+ the file records. ManimGX's MP4 doesn't record them; its command sets them
+ (`--preset ultrafast --crf 23`).
+- **The same length.** A video must last as long as its scene, to within one frame.
+ ManimGX's ends with one more frame, the scene's last moment. Where the picture holds
+ still, ManimGX encodes it once, as a longer frame: its `matrix` and `pendulums` videos
+ have 243 and 721 frames over 433 and 781 frames of time. The other engines encode every
+ frame.
+
+## Run it
+
+The runner works on macOS and Linux. It needs this repository's environment (`just sync`),
+whose ManimGX it measures; FFmpeg, with `ffprobe`; a LaTeX distribution, for ManimCE and
+ManimGL; Blender 5.2.2 LTS; and an OpenGL context, for ManimGL.
+
+Make an environment each for ManimCE and ManimGL, from the repository's root:
+
+```sh
+uv venv --python 3.13 .cache/benchmark-envs/ce
+uv pip install --python .cache/benchmark-envs/ce/bin/python 'manim==0.21.0'
+uv venv --python 3.12 .cache/benchmark-envs/gl
+uv pip install --python .cache/benchmark-envs/gl/bin/python 'manimgl==1.7.2' 'setuptools==80.9.0'
+```
+
+Then run every scene on every engine, with the path to Blender:
+
+```sh
+uv run --frozen python -m benchmarks.run \
+ --out .cache/comparison/five-scenes \
+ --ce-python .cache/benchmark-envs/ce/bin/python \
+ --manimgl .cache/benchmark-envs/gl/bin/manimgl \
+ --blender /path/to/blender
+```
+
+The output folder must not exist yet. It receives each run's MP4 and log, and
+`results.json`, with each run's command, times and checks, written again after every run. A
+run that fails, makes an invalid video or runs out of time stops the command, and stays
+recorded. An engine has a total only once all its runs are complete.
+
+`--scenes orbit linked_rings` chooses the scenes, and `--tools manimgx manimgl` the engines.
+`--rounds 1` sets the number of runs for every engine. `--timeout 900` sets the seconds a
+render may take. `--gx` measures another `manimgx`, such as one installed with pip.
+`--dry-run` writes the plan of commands without starting a renderer.
+
+## The chart
+
+Draw the README's chart, dark and light, from the recorded results:
+
+```sh
+uv run --frozen python -m benchmarks.chart
+```
+
+It writes `docs/content/images/benchmark-dark.svg` and `benchmark-light.svg`: each engine's
+total time in seconds, on one linear scale. To chart a new complete run into a folder of its
+own:
+
+```sh
+uv run --frozen python -m benchmarks.chart \
+ --results .cache/comparison/five-scenes/results.json \
+ --out .cache/comparison/five-scenes/charts
+```
+
+## The comparison images
+
+The README compares the engines on one frame: the linked rings at 2.5 seconds. Render it
+with each engine:
+
+```sh
+uv run --frozen python -m benchmarks.quality \
+ --out .cache/comparison/linked-rings-images \
+ --ce-python .cache/benchmark-envs/ce/bin/python \
+ --gl-python .cache/benchmark-envs/gl/bin/python \
+ --blender /path/to/blender
+```
+
+`scenes/quality_manim.py` makes the frame with the three Manim engines, and
+`scenes/linked_rings_blender.py` with Blender's two renderers. Each engine keeps its own
+shading. ManimGX and Blender color the rings with the scenes' colors; ManimCE's and
+ManimGL's are darker, by 0.24 and 0.18 of each RGB channel.
+
+`native/` receives each engine's frame, 1920 × 1080 and transparent, with its log and
+command. `images/` receives the README's ten images, the files of
+`docs/content/images/benchmark-quality/`: the same 302 × 524 part of each frame, the part
+that holds the rings, on the site's dark (`#0B0C0F`) and light (`#FFFFFF`) backgrounds.
diff --git a/scripts/benchmark/chart.py b/benchmarks/chart.py
similarity index 97%
rename from scripts/benchmark/chart.py
rename to benchmarks/chart.py
index f73e8a79..e7ab0327 100644
--- a/scripts/benchmark/chart.py
+++ b/benchmarks/chart.py
@@ -1,6 +1,6 @@
"""The README's static chart: total render times for the five-scene suite.
- uv run --frozen python scripts/benchmark/chart.py
+ uv run --frozen python -m benchmarks.chart
Reads `results.json` and writes `docs/content/images/benchmark-light.svg`
and `benchmark-dark.svg`. Every label and bar uses the recorded total in seconds,
@@ -13,7 +13,7 @@ import math
from pathlib import Path
HERE = Path(__file__).parent
-IMAGES = HERE.parents[1] / "docs" / "content" / "images"
+IMAGES = HERE.parent / "docs" / "content" / "images"
LABELS = {
"manimgx": "ManimGX",
"manim_ce": "ManimCE",
diff --git a/scripts/benchmark/quality.py b/benchmarks/quality.py
similarity index 69%
rename from scripts/benchmark/quality.py
rename to benchmarks/quality.py
index 74fece5e..68e9f37d 100644
--- a/scripts/benchmark/quality.py
+++ b/benchmarks/quality.py
@@ -1,4 +1,5 @@
-"""Render the linked-rings frame at 2.5 seconds on dark and light backgrounds."""
+"""Render the linked-rings frame at 2.5 seconds, and the part of it the README shows on
+dark and light backgrounds."""
import argparse
import json
@@ -7,11 +8,32 @@ import subprocess
import sys
from pathlib import Path
+from benchmarks.run import executable
from PIL import Image
-from scripts.benchmark.run import executable
HERE = Path(__file__).resolve().parent
SOURCES = HERE / "scenes"
+# what the README shows of each frame: the 302 × 524 pixels from (810, 326), which hold
+# the rings
+CROP = (810, 326, 1112, 850)
+
+
+def website_images(frame: Path) -> dict[str, Image.Image]:
+ """What the README shows of a transparent 1080p frame, on the site's dark (`""`) and
+ light (`"-light"`) backgrounds."""
+ with Image.open(frame) as source:
+ foreground = source.convert("RGBA")
+ if (
+ foreground.size != (1920, 1080)
+ or foreground.getchannel("A").getextrema()[0] != 0
+ ):
+ raise ValueError(f"Expected a transparent 1080p frame: {frame}")
+ pictures = {}
+ for suffix, color in (("", "#0B0C0F"), ("-light", "#FFFFFF")):
+ background = Image.new("RGBA", foreground.size, color)
+ background.alpha_composite(foreground)
+ pictures[suffix] = background.convert("RGB").crop(CROP)
+ return pictures
def main() -> None:
@@ -82,17 +104,8 @@ def main() -> None:
check=True,
timeout=120,
)
- with Image.open(target) as source:
- foreground = source.convert("RGBA")
- if (
- foreground.size != (1920, 1080)
- or foreground.getchannel("A").getextrema()[0] != 0
- ):
- raise ValueError(f"Expected a transparent 1080p frame: {target}")
- for suffix, color in (("", "#0B0C0F"), ("-light", "#FFFFFF")):
- background = Image.new("RGBA", foreground.size, color)
- background.alpha_composite(foreground)
- background.convert("RGB").save(images / f"{engine}{suffix}.png")
+ for suffix, image in website_images(target).items():
+ image.save(images / f"{engine}{suffix}.png")
print(images)
diff --git a/scripts/benchmark/results.json b/benchmarks/results.json
similarity index 100%
rename from scripts/benchmark/results.json
rename to benchmarks/results.json
diff --git a/scripts/benchmark/run.py b/benchmarks/run.py
similarity index 99%
rename from scripts/benchmark/run.py
rename to benchmarks/run.py
index 8bd61f09..70e38ab6 100644
--- a/scripts/benchmark/run.py
+++ b/benchmarks/run.py
@@ -18,7 +18,7 @@ from fractions import Fraction
from pathlib import Path
from threading import Timer
-from scripts.benchmark.scenes.suite_data import DURATIONS, FPS, HEIGHT, WIDTH
+from benchmarks.scenes.suite_data import DURATIONS, FPS, HEIGHT, WIDTH
HERE = Path(__file__).resolve().parent
SOURCES = HERE / "scenes"
diff --git a/scripts/benchmark/scenes/ce_cli.py b/benchmarks/scenes/ce_cli.py
similarity index 100%
rename from scripts/benchmark/scenes/ce_cli.py
rename to benchmarks/scenes/ce_cli.py
diff --git a/scripts/benchmark/scenes/ffmpeg.py b/benchmarks/scenes/ffmpeg.py
similarity index 100%
rename from scripts/benchmark/scenes/ffmpeg.py
rename to benchmarks/scenes/ffmpeg.py
diff --git a/scripts/benchmark/scenes/lighting.py b/benchmarks/scenes/lighting.py
similarity index 100%
rename from scripts/benchmark/scenes/lighting.py
rename to benchmarks/scenes/lighting.py
diff --git a/scripts/benchmark/scenes/linked_rings_blender.py b/benchmarks/scenes/linked_rings_blender.py
similarity index 100%
rename from scripts/benchmark/scenes/linked_rings_blender.py
rename to benchmarks/scenes/linked_rings_blender.py
diff --git a/scripts/benchmark/scenes/matrix_manim_ce.py b/benchmarks/scenes/matrix_manim_ce.py
similarity index 100%
rename from scripts/benchmark/scenes/matrix_manim_ce.py
rename to benchmarks/scenes/matrix_manim_ce.py
diff --git a/scripts/benchmark/scenes/matrix_manimgl.py b/benchmarks/scenes/matrix_manimgl.py
similarity index 100%
rename from scripts/benchmark/scenes/matrix_manimgl.py
rename to benchmarks/scenes/matrix_manimgl.py
diff --git a/scripts/benchmark/scenes/matrix_manimgx.py b/benchmarks/scenes/matrix_manimgx.py
similarity index 100%
rename from scripts/benchmark/scenes/matrix_manimgx.py
rename to benchmarks/scenes/matrix_manimgx.py
diff --git a/scripts/benchmark/scenes/orbit_blender.py b/benchmarks/scenes/orbit_blender.py
similarity index 100%
rename from scripts/benchmark/scenes/orbit_blender.py
rename to benchmarks/scenes/orbit_blender.py
diff --git a/scripts/benchmark/scenes/orbit_manim_ce.py b/benchmarks/scenes/orbit_manim_ce.py
similarity index 100%
rename from scripts/benchmark/scenes/orbit_manim_ce.py
rename to benchmarks/scenes/orbit_manim_ce.py
diff --git a/scripts/benchmark/scenes/orbit_manimgl.py b/benchmarks/scenes/orbit_manimgl.py
similarity index 100%
rename from scripts/benchmark/scenes/orbit_manimgl.py
rename to benchmarks/scenes/orbit_manimgl.py
diff --git a/scripts/benchmark/scenes/orbit_manimgx.py b/benchmarks/scenes/orbit_manimgx.py
similarity index 100%
rename from scripts/benchmark/scenes/orbit_manimgx.py
rename to benchmarks/scenes/orbit_manimgx.py
diff --git a/scripts/benchmark/scenes/pendulums_manim_ce.py b/benchmarks/scenes/pendulums_manim_ce.py
similarity index 100%
rename from scripts/benchmark/scenes/pendulums_manim_ce.py
rename to benchmarks/scenes/pendulums_manim_ce.py
diff --git a/scripts/benchmark/scenes/pendulums_manimgl.py b/benchmarks/scenes/pendulums_manimgl.py
similarity index 100%
rename from scripts/benchmark/scenes/pendulums_manimgl.py
rename to benchmarks/scenes/pendulums_manimgl.py
diff --git a/scripts/benchmark/scenes/pendulums_manimgx.py b/benchmarks/scenes/pendulums_manimgx.py
similarity index 100%
rename from scripts/benchmark/scenes/pendulums_manimgx.py
rename to benchmarks/scenes/pendulums_manimgx.py
diff --git a/scripts/benchmark/scenes/quality_manim.py b/benchmarks/scenes/quality_manim.py
similarity index 100%
rename from scripts/benchmark/scenes/quality_manim.py
rename to benchmarks/scenes/quality_manim.py
diff --git a/scripts/benchmark/scenes/suite_blender.py b/benchmarks/scenes/suite_blender.py
similarity index 100%
rename from scripts/benchmark/scenes/suite_blender.py
rename to benchmarks/scenes/suite_blender.py
diff --git a/scripts/benchmark/scenes/suite_data.py b/benchmarks/scenes/suite_data.py
similarity index 100%
rename from scripts/benchmark/scenes/suite_data.py
rename to benchmarks/scenes/suite_data.py
diff --git a/scripts/benchmark/scenes/suite_manim.py b/benchmarks/scenes/suite_manim.py
similarity index 100%
rename from scripts/benchmark/scenes/suite_manim.py
rename to benchmarks/scenes/suite_manim.py
diff --git a/scripts/benchmark/scenes/two_d_blender.py b/benchmarks/scenes/two_d_blender.py
similarity index 100%
rename from scripts/benchmark/scenes/two_d_blender.py
rename to benchmarks/scenes/two_d_blender.py
diff --git a/docs/content/changelog.md b/docs/content/changelog.md
index 0ae367d5..9aa3cc03 100644
--- a/docs/content/changelog.md
+++ b/docs/content/changelog.md
@@ -22,6 +22,9 @@ The notable changes to ManimGX, release by release. The format follows
- Show measured render times in a static benchmark chart.
- Use a Markdown table for the benchmark comparison images.
+- Install ManimGX in the Quickstart with one command, `pip install manimgx`, and run `manimgx` directly throughout the docs.
+- Move the benchmark to `benchmarks/`, whose README explains its scenes, method and results; the README's numbers link to it.
+- Arrange the Rendering and sharing page by command, with settings, tall videos and rendering from Python under Render.
### Fixed
diff --git a/docs/content/developer-guide/documentation.md b/docs/content/developer-guide/documentation.md
index 8dbf8d1a..2f885cf6 100644
--- a/docs/content/developer-guide/documentation.md
+++ b/docs/content/developer-guide/documentation.md
@@ -178,8 +178,15 @@ the README.
per film and one shared wall, in both places and on both color schemes. The GIFs are
committed; `uv run --frozen python -m scripts.showcase.wall` makes them again with
Gifski installed and `gifski` on PATH.
-- **The chart** (`images/benchmark-light.svg` and `benchmark-dark.svg`): the benchmark, as
- a race; `scripts/benchmark/chart.py` draws it from `scripts/benchmark/results.json`.
+- **The chart** (`images/benchmark-light.svg` and `benchmark-dark.svg`): the
+ [benchmark](https://github.com/academa-labs/manimgx/tree/main/benchmarks)'s total times,
+ as static bars on one linear scale;
+ [`benchmarks/chart.py`](https://github.com/academa-labs/manimgx/blob/main/benchmarks/chart.py)
+ draws it from `benchmarks/results.json`.
+- **The comparison** (`images/benchmark-quality/<engine>.png` and `<engine>-light.png`):
+ the benchmark's linked rings at 2.5 seconds, as each engine draws them;
+ [`benchmarks/quality.py`](https://github.com/academa-labs/manimgx/blob/main/benchmarks/quality.py)
+ renders them.
- **The scene's film** (`films/readme-<scene>.svg`): `docs/examples.py` records the README's
scene frame by frame with
[`docs/svg.py`](https://github.com/academa-labs/manimgx/blob/main/docs/svg.py), which
diff --git a/docs/content/developer-guide/project-management.md b/docs/content/developer-guide/project-management.md
index a965d369..9cdc83ac 100644
--- a/docs/content/developer-guide/project-management.md
+++ b/docs/content/developer-guide/project-management.md
@@ -18,9 +18,10 @@ The repository is the package, ManimGX, and holds more than its code:
├── docker/ ← the Docker image
├── docs/ ← the docs site: its pages, its settings, what its build loads
├── examples/ ← thirty example films, a Python file each
+├── benchmarks/ ← the README's benchmark against Manim CE, ManimGL and Blender:
+│ its scenes, its runner and its recorded results
├── scripts/ ← what writes and builds: the release's scripts, the docs' generated
-│ pages and pictures, the engine's DFG table, and the benchmark
-│ against Manim CE, ManimGL and Blender
+│ pages and pictures, and the engine's DFG table
├── skills/ ← the agent skill
├── pyproject.toml ← the package, its workspace (with fonts/), the tools and their settings
├── uv.lock ← the exact version of every Python package
@@ -298,8 +299,16 @@ What writes and builds, a folder for each thing it makes:
[`dfg_table.py`](https://github.com/academa-labs/manimgx/blob/main/scripts/engine/dfg_table.py) writes `rust/engine/src/dfg.bin`, the
split-sum table a lit surface's specular reflection is read from, run again only if the
lighting changes.
-- [`benchmark/`](https://github.com/academa-labs/manimgx/tree/main/scripts/benchmark): ManimGX against Manim CE, ManimGL and Blender on
- the README's scenes, and the README's chart from its results.
+
+### [`benchmarks/`](https://github.com/academa-labs/manimgx/tree/main/benchmarks)
+
+The README's benchmark: ManimGX against Manim CE, ManimGL and Blender on five scenes, each
+written in every engine's own API (`scenes/`). Its
+[README](https://github.com/academa-labs/manimgx/blob/main/benchmarks/README.md) is the
+method and the results, the source of the README's numbers. `run.py` times the engines into
+`results.json`; `chart.py` draws the README's chart from it, and `quality.py` makes the
+README's comparison images. `tests/benchmarks/test_comparison.py` checks that the numbers
+both READMEs give are the recorded ones.
### The docs' and the coverage's hosting
diff --git a/docs/content/developer-guide/testing.md b/docs/content/developer-guide/testing.md
index c54b478c..ddce49c2 100644
--- a/docs/content/developer-guide/testing.md
+++ b/docs/content/developer-guide/testing.md
@@ -68,7 +68,7 @@ tests/
└── benchmarks/
├── test_laws.py ← laws of cost: work grows as what is made does
├── test_speed.py ← timed: this checkout against another commit (just bench)
- ├── scenes/ ← the README's three scenes, which test_speed.py times
+ ├── scenes/ ← three scenes, which test_speed.py times
├── harness.py ← the trees compared, a render measured, and their rounds
└── work.py ← work, counted
```
@@ -390,8 +390,9 @@ what the timed benchmarks are for.
A workload is a scene rendered as a user renders it: `manimgx render`, in a process of its
own, from launch to the finished video. The workloads, in
[`test_speed.py`](https://github.com/academa-labs/manimgx/blob/main/tests/benchmarks/test_speed.py),
-are the README's three scenes as the README times them, at 1920 × 1080 and 60 frames per
-second ([`scenes/`](https://github.com/academa-labs/manimgx/tree/main/tests/benchmarks/scenes):
+are three scenes, at 1920 × 1080 and 60 frames per second as the README's
+[benchmark](https://github.com/academa-labs/manimgx/tree/main/benchmarks) makes its own
+([`scenes/`](https://github.com/academa-labs/manimgx/tree/main/tests/benchmarks/scenes):
a surface the camera circles, a surface rebuilt every frame, and a 2D explainer), and six
example films at 480 × 270 and 10 frames per second. In the suite, each is rendered once,
tiny: it still renders. `just bench` times them against another ManimGX:
diff --git a/docs/content/user-guide/coming-from-manim-ce.md b/docs/content/user-guide/coming-from-manim-ce.md
index 23e4c4db..81141bbf 100644
--- a/docs/content/user-guide/coming-from-manim-ce.md
+++ b/docs/content/user-guide/coming-from-manim-ce.md
@@ -84,4 +84,4 @@ ManimGX does the work of manim-voiceover and manim-slides, without plugins:
- [`add_subcaption`][manimgx.Scene.add_subcaption] adds captions. `manimgx render` writes
them next to the video, as subtitles.
-See [Sound and voice](sound-and-voice.md) and [Rendering and sharing](rendering.md#slides).
+See [Sound and voice](sound-and-voice.md) and [Rendering and sharing](rendering.md#present).
diff --git a/docs/content/user-guide/quickstart.md b/docs/content/user-guide/quickstart.md
index 44c49b49..d41ca879 100644
--- a/docs/content/user-guide/quickstart.md
+++ b/docs/content/user-guide/quickstart.md
@@ -18,46 +18,13 @@ network or the GPU, allow it.
### 1. Install ManimGX
-=== "uv"
+With [Python](https://www.python.org/downloads/) 3.13 or later, run this in a terminal:
- If you don't have [uv](https://docs.astral.sh/uv/), install it:
-
- === "macOS and Linux"
-
- ```sh
- curl -LsSf https://astral.sh/uv/install.sh | sh
- ```
-
- === "Windows"
-
- ```powershell
- powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
- ```
-
- Then close the terminal and open a new one, so that it finds uv. Make a folder for
- your videos, with ManimGX in it (uv also installs Python 3.14 if you don't have it):
-
- ```sh
- uv init --bare --python 3.14 my-videos
- cd my-videos
- uv add manimgx
- ```
-
-=== "pip"
-
- You need Python 3.13 or 3.14. Make a folder for your videos, with a virtual
- environment, and install ManimGX in it:
-
- ```sh
- mkdir my-videos
- cd my-videos
- python3 -m venv .venv # Windows: py -m venv .venv
- source .venv/bin/activate # Windows: .venv\Scripts\activate
- pip install manimgx
- ```
+```sh
+pip install manimgx
+```
- If Windows' PowerShell refuses to run the activate script, allow it once with
- `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`.
+It installs ManimGX and its command, `manimgx`.
### 2. Set up your editor
@@ -69,7 +36,7 @@ mistakes before you make a video.
Install the [ty extension](https://marketplace.visualstudio.com/items?itemName=astral-sh.ty).
Cursor, Windsurf and the other editors made from VS Code have it in their Extensions
- view too. Then open your folder, `my-videos`, with **File > Open Folder**.
+ view too. Then make a folder for your videos, and open it with **File > Open Folder**.
=== "Zed"
@@ -85,9 +52,7 @@ mistakes before you make a video.
},
```
- Then open your folder, `my-videos`, with **File > Open**.
-
-ty finds ManimGX in the folder's `.venv`, which step 1 made.
+ Then make a folder for your videos, and open it with **File > Open**.
### 3. Write a scene
@@ -110,22 +75,9 @@ class SquareToCircle(m.Scene):
Open your editor's terminal (++ctrl+grave++), and run:
-=== "uv"
-
- ```sh
- uv run manimgx preview scene.py
- ```
-
- With uv, start every `manimgx` command with `uv run`. The rest of these docs write
- the commands without it.
-
-=== "pip"
-
- ```sh
- manimgx preview scene.py
- ```
-
- In a new terminal, activate the environment first, as in step 1.
+```sh
+manimgx preview scene.py
+```
A window plays your scene. Put it next to your editor. Each time that you save
`scene.py`, the window plays the new version. Try it: change `m.PINK` to `m.YELLOW`, and
@@ -133,17 +85,9 @@ save.
### 5. Make the video
-=== "uv"
-
- ```sh
- uv run manimgx render scene.py
- ```
-
-=== "pip"
-
- ```sh
- manimgx render scene.py
- ```
+```sh
+manimgx render scene.py
+```
ManimGX writes the video, `SquareToCircle.mp4`, next to `scene.py`. It's the video above
the code in step 3. For a tall video (Shorts, Reels, TikTok), add `-r 1080x1920`.
diff --git a/docs/content/user-guide/rendering.md b/docs/content/user-guide/rendering.md
index ba2c63ee..68257baf 100644
--- a/docs/content/user-guide/rendering.md
+++ b/docs/content/user-guide/rendering.md
@@ -30,7 +30,28 @@ smaller: `-r 1280x720 --fps 30`.
`render` also writes a storyboard, with the picture at the end of each play that
changes it, and the captions of a voice, as subtitles (`.srt`).
-## Tall videos
+### Settings
+
+Set the video's settings on `m.config`, after the import: its size in pixels,
+`pixel_width` and `pixel_height`; its `frame_rate`; and its `background_color`:
+
+```python
+import manimgx as m
+
+m.config.background_color = m.WHITE
+
+
+class OnWhite(m.Scene):
+ def construct(self) -> None:
+ circle = m.Circle(radius=2, color=m.BLUE, fill_opacity=0.5)
+ label = m.Text("On white", color=m.BLACK)
+ label.next_to(circle, m.DOWN)
+ self.play(m.Create(circle), m.Write(label))
+```
+
+On the command line, `-r` and `--fps` set the size and the frame rate over the file's.
+
+### Tall videos
For Shorts, Reels and TikTok, make the video tall: 1080 × 1920. Give the size to the
command:
@@ -50,6 +71,12 @@ the same square of 8 by 8 units in their middle, so a scene that stays in that s
the same in both. [Positions](positions.md#the-frame) shows the two frames. A square
video, `-r 1080x1080`, is that square alone.
+### From Python
+
+A scene can make its own video: `SquareToCircle().render("square_to_circle.mp4")`
+returns its [`Film`][manimgx.Film] and writes the video. Without a path, it runs the
+scene quickly, without drawing it, for example in a test.
+
## Preview
`manimgx preview scene.py` plays the scene in a window. Each time that you save the file,
@@ -102,28 +129,7 @@ Pictures go in chronological order to `<Scene>.storyboard.png`, six per sheet, t
inspection leaves out consecutive identical pictures; explicit times keep every
requested picture. Checks cover the sampled moments, not every frame of the video.
-## Settings
-
-Set the video's settings on `m.config`, after the import: its size in pixels,
-`pixel_width` and `pixel_height`; its `frame_rate`; and its `background_color`:
-
-```python
-import manimgx as m
-
-m.config.background_color = m.WHITE
-
-
-class OnWhite(m.Scene):
- def construct(self) -> None:
- circle = m.Circle(radius=2, color=m.BLUE, fill_opacity=0.5)
- label = m.Text("On white", color=m.BLACK)
- label.next_to(circle, m.DOWN)
- self.play(m.Create(circle), m.Write(label))
-```
-
-On the command line, `-r` and `--fps` set the size and the frame rate over the file's.
-
-## Slides
+## Present
A video can be a talk: it plays to the end of a slide, and waits until you continue.
`self.next_section()` starts a new slide:
@@ -157,13 +163,7 @@ timer. To share the talk,
send the page and the video together. `--pdf` also writes a handout, with a page for each
slide.
-## From Python
-
-A scene can make its own video: `SquareToCircle().render("square_to_circle.mp4")`
-returns its [`Film`][manimgx.Film] and writes the video. Without a path, it runs the
-scene quickly, without drawing it, for example in a test.
-
-## In the browser
+## Embed in a web page
ManimGX runs in a web page, with no server: the page makes the video from your scene,
and plays it. Install the npm package `manimgx`, import it in your page's script
diff --git a/docs/content/user-guide/the-basics.md b/docs/content/user-guide/the-basics.md
index 4b4f5959..03eb8c26 100644
--- a/docs/content/user-guide/the-basics.md
+++ b/docs/content/user-guide/the-basics.md
@@ -19,8 +19,7 @@ class Hello(m.Scene):
```
Save it in a file named `hello.py`. Then, in a terminal, in the same folder, run this
-command (with uv, start it with `uv run`, as the [Quickstart](quickstart.md#4-preview-it)
-says):
+command:
```sh
manimgx render hello.py
diff --git a/examples/README.md b/examples/README.md
index ea7f4890..5064ceec 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -3,10 +3,10 @@
Forty-eight short films made with ManimGX, each one Python file that needs only numpy. Every
number on screen is computed as the film plays.
-Render one at 1920×1080, 60 fps:
+With ManimGX installed (`pip install manimgx`), render one at 1920×1080, 60 fps:
```sh
-uv run --frozen python examples/quadratic_formula.py # writes quadratic_formula.mp4 to the current directory
+manimgx render examples/quadratic_formula.py # writes examples/QuadraticFormula.mp4
```
## Equations and proofs
diff --git a/pyproject.toml b/pyproject.toml
index 5994a479..eadada27 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -171,8 +171,10 @@ strict = true
# a warning fails the test that raised it (the suite raises none)
filterwarnings = ["error"]
# `tests` is imported from the repository root (the corpus harness is `tests.integration.corpus`,
-# the shared `tests.strategies`); test modules are imported by path, so unit/ may repeat a name
+# the shared `tests.strategies`); test modules are imported by path, so unit/ may repeat a name,
+# and named from the root as well: `tests.benchmarks`, not `benchmarks`, the root's benchmark
pythonpath = ["."]
+consider_namespace_packages = true
testpaths = ["tests"]
# Workers finishing short tests can take queued renders from a busy worker.
addopts = ["-ra", "--import-mode=importlib", "--dist=worksteal"]
@@ -249,15 +251,15 @@ ignore = [
"src/manimgx/cli/__init__.py" = ["E402"]
# the benchmark's scenes in Manim CE and ManimGL, in their idioms: everything from one import,
# ManimGL's settings as class attributes
-"scripts/benchmark/scenes/*_manim_ce.py" = ["F403", "F405"]
-"scripts/benchmark/scenes/*_manimgl.py" = ["F403", "F405", "RUF012"]
+"benchmarks/scenes/*_manim_ce.py" = ["F403", "F405"]
+"benchmarks/scenes/*_manimgl.py" = ["F403", "F405", "RUF012"]
"tests/integration/**/*.py" = ["E731", "E741", "F841", "SIM110"]
[tool.ty.src]
-include = ["src", "fonts", "docs", "scripts", "tests"]
+include = ["src", "fonts", "docs", "scripts", "benchmarks", "tests"]
# the benchmark's scenes in the other tools (Manim CE, ManimGL, Blender), which import them; the
# corpus's scenes, which `tests/integration/test_corpus.py` checks with rules of their own
-exclude = ["scripts/benchmark/scenes", "tests/integration/cases"]
+exclude = ["benchmarks/scenes", "tests/integration/cases"]
[tool.ty.analysis]
# svgelements declares an ISO-8859-1 source encoding, which ty does not read (it sees an empty
diff --git a/scripts/benchmark/README.md b/scripts/benchmark/README.md
deleted file mode 100644
index f1489b76..00000000
--- a/scripts/benchmark/README.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Benchmarks
-
-Five scenes rendered by ManimGX, ManimGL, ManimCE, Blender Workbench, and Blender EEVEE at 1920 × 1080 and 60 fps. Each engine exports an H.264 MP4 through its native renderer. The scene implementations and rendering adapters are in `scenes/`.
-
-## Scenes
-
-| Scene | Duration | Content |
-| --- | ---: | --- |
-| `orbit` | 10 s | A 48 × 48 surface, three axes, a progressively drawn curve, a moving sphere, and an orbiting camera. |
-| `matrix` | 7.2 s | A matrix-vector product, expanded arithmetic, and the resulting vector. |
-| `pendulums` | 13 s | Twelve pendulums with different lengths, animated rods and bobs, and a title. |
-| `hierarchy` | 3 s | Five planets and five moons moving around a central sphere, viewed by an orbiting camera. |
-| `linked_rings` | 3 s | Eight animated 32 × 8 torus links with an orbiting camera and a shared key-light direction. |
-
-Total video duration: 36.2 seconds. Geometry, animation, text, and shading use each engine's native APIs.
-
-## Results
-
-Measured October 7, 2026, on an Apple M4 Pro with 12 CPU cores and 24 GB memory, running macOS 15.7.9. Engine versions: ManimGX 0.1.0, ManimGL 1.7.2, ManimCE 0.21.0, and Blender 5.2.2 LTS. Times are in seconds.
-
-| Scene | ManimGX | ManimGL | ManimCE | Blender Workbench | Blender EEVEE |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| Surface and orbiting camera | 1.184 | 6.463 | 211.809 | 16.563 | 220.242 |
-| Matrix-vector multiplication | 0.360 | 8.287 | 7.140 | 11.045 | 90.798 |
-| Twelve pendulums | 0.756 | 16.812 | 4.745 | 19.860 | 165.890 |
-| Planets and moons | 0.334 | 1.789 | 16.169 | 4.979 | 62.265 |
-| Linked rings | 0.443 | 1.933 | 38.962 | 5.163 | 62.200 |
-| Total | 3.078 | 35.284 | 278.826 | 57.611 | 601.395 |
-
-Values are arithmetic means of three runs per scene for GX and GL, and one run per scene for CE and each Blender renderer. Totals sum the five scene means. `results.json` contains all 45 measurements and their summaries. Lower is better.
-
-## Rendering settings
-
-GX, GL, and CE use x264's `ultrafast` preset with CRF 23. Blender uses `REALTIME`, its fastest available encoding preset, with custom CRF 23. Its encoded options correspond to x264 `superfast`. Video output uses `yuv420p`. EEVEE uses 64 samples; Workbench uses its native rasterizer.
-
-Each run starts a fresh process and uses a separate output and scene-cache directory. Wall time spans process launch through exit, including scene construction, rendering, encoding, and MP4 finalization. Full decoding, presentation-timestamp checks, resolution checks, and encoder-option verification run after the timer stops. GX's additional closing frame is permitted. Runs execute sequentially. Operating-system and GPU-driver caches remain available.
-
-## Run
-
-The runner supports macOS and Linux. Install this repository's environment with `just sync`. Install FFmpeg, including `ffprobe`, a LaTeX distribution for CE and GL, and Blender 5.2.2 LTS. GL requires an available OpenGL context.
-
-Create separate CE and GL environments from the repository root:
-
-```sh
-uv venv --python 3.13 .cache/benchmark-envs/ce
-uv pip install --python .cache/benchmark-envs/ce/bin/python 'manim==0.21.0'
-uv venv --python 3.12 .cache/benchmark-envs/gl
-uv pip install --python .cache/benchmark-envs/gl/bin/python 'manimgl==1.7.2' 'setuptools==80.9.0'
-```
-
-Run all five scenes and engines, supplying the Blender executable path:
-
-```sh
-uv run --frozen python -m scripts.benchmark.run \
- --out .cache/comparison/five-scenes \
- --ce-python .cache/benchmark-envs/ce/bin/python \
- --manimgl .cache/benchmark-envs/gl/bin/manimgl \
- --blender /path/to/blender
-```
-
-The output directory must not already exist. It receives every MP4, process log, command, validation result, and individual timing, with `results.json` checkpointed after each run. A failed, invalid, or timed-out run stops the command and remains recorded. A total is available only after all required runs for an engine complete.
-
-`--scenes orbit linked_rings` limits the scenes. `--tools manimgx manimgl` limits the engines. `--rounds 1` sets the number of runs for every engine. `--timeout 900` sets the timeout in seconds per render. `--dry-run` writes the command plan without starting renderers.
-
-## Chart
-
-Generate the static dark and light SVG charts from the recorded results:
-
-```sh
-uv run --frozen python scripts/benchmark/chart.py
-```
-
-The chart shows each engine's recorded total render time in seconds on a shared linear scale, from process launch to finished MP4. To chart a new complete run into a separate directory:
-
-```sh
-uv run --frozen python scripts/benchmark/chart.py \
- --results .cache/comparison/five-scenes/results.json \
- --out .cache/comparison/five-scenes/charts
-```
-
-## Quality images
-
-Render the linked-rings frame at 2.5 seconds:
-
-```sh
-uv run --frozen python -m scripts.benchmark.quality \
- --out .cache/comparison/linked-rings-images \
- --ce-python .cache/benchmark-envs/ce/bin/python \
- --gl-python .cache/benchmark-envs/gl/bin/python \
- --blender /path/to/blender
-```
-
-`native/` contains each renderer's transparent 1920 × 1080 PNG and process log. `images/` contains the ten website PNGs: five with `#0B0C0F` backgrounds and five with `#FFFFFF` backgrounds, matching the website's dark and light themes. Both backgrounds use the same native frame. The still-image script supplies CE and GL material colors separately; each engine retains its native shading. The website displays the same viewport of every frame.
diff --git a/tests/benchmarks/test_comparison.py b/tests/benchmarks/test_comparison.py
index 223186e2..8b4bbea3 100644
--- a/tests/benchmarks/test_comparison.py
+++ b/tests/benchmarks/test_comparison.py
@@ -1,15 +1,29 @@
-"""Process isolation, video validation, aggregation and chart scaling."""
+"""Process isolation, video validation, aggregation, chart scaling, the README's images,
+and the READMEs' numbers, which are the recorded results'."""
import argparse
import json
import sys
+from datetime import datetime
from pathlib import Path
from xml.etree import ElementTree
import numpy as np
import pytest
-from scripts.benchmark import chart, run
-from scripts.benchmark.scenes.suite_data import ring_pose
+from PIL import Image
+
+from benchmarks import chart, quality, run
+from benchmarks.scenes.suite_data import ring_pose
+
+RESULTS = json.loads((run.HERE / "results.json").read_text(encoding="utf-8"))
+# the engines as the READMEs name them, in the benchmark's table's order
+NAMES = {
+ "manimgx": "ManimGX",
+ "manimgl": "ManimGL",
+ "manim_ce": "ManimCE",
+ "blender_workbench": "Blender Workbench",
+ "blender_eevee": "Blender EEVEE",
+}
def test_unsupported_cpu_accounting_never_starts_a_process(
@@ -111,7 +125,6 @@ def test_totals_require_every_scene_and_repeat() -> None:
def test_recorded_totals_match_every_run() -> None:
- data = json.loads((run.HERE / "results.json").read_text(encoding="utf-8"))
rows = [
run.Run(
r["scene"],
@@ -121,13 +134,78 @@ def test_recorded_totals_match_every_run() -> None:
status=r["status"],
wall_seconds=r["wall_seconds"],
)
- for r in data["runs"]
+ for r in RESULTS["runs"]
]
result = run.summarize(rows, list(run.DURATIONS), run.REPEATS)
assert len(rows) == 45
assert result["complete"]
- assert result["totals"] == data["totals"]
- assert result["per_scene"] == data["per_scene"]
+ assert result["totals"] == RESULTS["totals"]
+ assert result["per_scene"] == RESULTS["per_scene"]
+
+
+def test_the_benchmark_s_readme_tabulates_the_recorded_results() -> None:
+ rows = (run.HERE / "README.md").read_text(encoding="utf-8").splitlines()
+ assert list(NAMES) == list(run.TOOLS)
+ assert f"| Scene | Video | {' | '.join(NAMES.values())} |" in rows
+ for scene, means in RESULTS["per_scene"].items():
+ cells = [f"{run.DURATIONS[scene]:g} s"]
+ cells += [f"{means[tool]['mean_seconds']:.3f}" for tool in run.TOOLS]
+ assert any(row.endswith(f"(`{scene}`) | {' | '.join(cells)} |") for row in rows)
+ totals = RESULTS["totals"]
+ video = sum(RESULTS["settings"]["scenes"].values())
+ cells = [f"{video:g} s", *(f"{totals[tool]:.3f}" for tool in run.TOOLS)]
+ assert f"| Total | {' | '.join(cells)} |" in rows
+ ratios = ["1×", *(f"{totals[t] / totals['manimgx']:.1f}×" for t in run.TOOLS[1:])]
+ assert f"| Relative to ManimGX | | {' | '.join(ratios)} |" in rows
+ # where and when the results were recorded, as their manifest says
+ text = " ".join(rows)
+ machine = RESULTS["machine"]
+ measured = datetime.strptime(RESULTS["date"], "%Y-%m-%dT%H:%M:%S%z")
+ assert f"Measured on {measured:%B} {measured.day}, {measured.year}," in text
+ assert f"({machine['cpus']} CPU cores," in text
+ assert f"macOS {machine['os'].split('-')[1]}:" in text
+ assert f"holds all {len(RESULTS['runs'])} runs" in text
+
+
+def test_the_readme_quotes_the_benchmark_and_links_it() -> None:
+ readme = (run.HERE.parent / "README.md").read_text(encoding="utf-8")
+ totals = RESULTS["totals"]
+ video = sum(RESULTS["settings"]["scenes"].values())
+ assert (
+ f"**{video:g} seconds of video, rendered in {totals['manimgx']:.2f} seconds.**"
+ in readme
+ )
+ for tool in ("manim_ce", "manimgl", "blender_workbench"):
+ ratio = totals[tool] / totals["manimgx"]
+ assert f"**{ratio:.1f}× faster than {NAMES[tool]}**" in readme
+ fastest_first = sorted(totals, key=totals.__getitem__)
+ seconds = ", ".join(f"{NAMES[tool]} {totals[tool]:.2f} s" for tool in fastest_first)
+ assert f'alt="Total render times: {seconds}"' in readme
+ assert "](https://github.com/academa-labs/manimgx/tree/main/benchmarks)" in readme
+
+
+def test_the_readme_s_images_are_one_part_of_each_frame(tmp_path: Path) -> None:
+ left, top, right, bottom = quality.CROP
+ assert (right - left, bottom - top) == (302, 524)
+ frame = Image.new("RGBA", (1920, 1080))
+ frame.putpixel((left, top), (255, 0, 0, 255))
+ frame.putpixel((left - 1, top), (0, 0, 255, 255))
+ path = tmp_path / "frame.png"
+ frame.save(path)
+ pictures = quality.website_images(path)
+ assert list(pictures) == ["", "-light"]
+ for picture, ground in zip(
+ pictures.values(), [(11, 12, 15), (255, 255, 255)], strict=True
+ ):
+ assert picture.size == (302, 524)
+ assert picture.getpixel((0, 0)) == (255, 0, 0)
+ colors = picture.getcolors()
+ assert colors is not None
+ assert {color for _, color in colors} == {(255, 0, 0), ground}
+ frame.putalpha(255)
+ frame.save(path)
+ with pytest.raises(ValueError, match="transparent 1080p frame"):
+ quality.website_images(path)
def test_static_chart_keeps_measured_seconds_and_proportional_bars() -> None:
diff --git a/tests/benchmarks/test_speed.py b/tests/benchmarks/test_speed.py
index 20b39d85..9c9914be 100644
--- a/tests/benchmarks/test_speed.py
+++ b/tests/benchmarks/test_speed.py
@@ -1,9 +1,9 @@
"""ManimGX is not slower than the ManimGX it is compared with, on any workload.
A workload is a scene rendered as a user renders it, `manimgx render`, in a process of its own
-from launch to exit: the README's three scenes as the README times them, and six example films,
-small. On Linux and macOS, the suite renders each once, tiny. Windows keeps the
-functional corpus and cost laws; these long benchmark films depend on its software GPU.
+from launch to exit: three scenes as the README's benchmark (`benchmarks/`) times its own, and
+six example films, small. On Linux and macOS, the suite renders each once, tiny. Windows keeps
+the functional corpus and cost laws; these long benchmark films depend on its software GPU.
`just bench REF` renders each workload with this checkout and with REF's ManimGX, in turns, round
after round on one machine, and compares what the runs cost: the instructions they retired where
@@ -53,7 +53,7 @@ TINY = ("--resolution", "64x36", "--fps", "5")
"""How the suite renders a workload once, to see that it still renders."""
WORKLOADS: dict[str, Workload] = {
- # the README's scenes, as it times them: 1920 x 1080 at 60 fps, to MP4
+ # three scenes as the README's benchmark times its own: 1920 x 1080 at 60 fps, to MP4
"orbit": Workload(SCENES / "orbit.py"),
"morph": Workload(SCENES / "morph.py"),
"explainer": Workload(SCENES / "explainer.py"),
diff --git a/tests/test_text_files.py b/tests/test_text_files.py
index f0682057..d8479b86 100644
--- a/tests/test_text_files.py
+++ b/tests/test_text_files.py
@@ -1,6 +1,7 @@
-"""Every text file ManimGX reads or writes (its packages, tests, docs and scripts) names its
-encoding. Without one, Python takes the locale's, which on Windows is its ANSI code page: a
-subtitle, a page or a scene with characters beyond it would fail to write, or read wrong.
+"""Every text file ManimGX reads or writes (its packages, tests, docs, scripts and benchmark)
+names its encoding. Without one, Python takes the locale's, which on Windows is its ANSI code
+page: a subtitle, a page or a scene with characters beyond it would fail to write, or read
+wrong.
"""
import ast
@@ -33,7 +34,7 @@ def _unnamed(tree: ast.Module) -> list[int]:
def test_every_text_file_is_read_and_written_as_utf_8() -> None:
unnamed = [
f"{path.relative_to(ROOT)}:{line}"
- for folder in ("src", "fonts", "tests", "docs", "scripts")
+ for folder in ("src", "fonts", "tests", "docs", "scripts", "benchmarks")
for path in (ROOT / folder).rglob("*.py")
# the corpus's scenes are Manim code, as users write it: what they read is theirs
if "cases" not in path.relative_to(ROOT).parts