# 数境 ShuJing

> 中文数学动画引擎 · 基于 ManimGX · 极速 3D 数学动画

ManimGX 是一个面向 AI 智能体的自包含动画引擎：它从 Python 场景生成数学和 3D 视频。
场景使用 Manim Community Edition 的 API，ManimGX 为其全部标注了类型，因此类型检查器
能在渲染前发现错误。Rust 核心在 GPU 上绘制每一帧，用 Typst 排版文本和 LaTeX 数学公式，
并将视频及其声音编码为 MP4。动画在每一帧的时间点求值，基于时间的模拟使用独立于输出
帧率的固定时钟。逐帧回调应从时间或其他对象派生状态，而非计数帧。inspect 命令在不生成
视频的情况下运行场景，打印其时间线和布局问题（例如文本覆盖其他文本），并写出故事板。
在 Web 浏览器中，Pyodide 在 Web Worker 中运行相同的场景，核心的 WebAssembly 构建用
WebGPU 绘制它们。

以下是被要求用 ManimGX 制作视频的 AI 智能体的操作指南。请按顺序执行。

## 1. 安装

```sh
uv tool install --python 3.14 manimgx   # 将 `manimgx` 放到 PATH 上
manimgx --version
```

- 保留 `--python 3.14`：ManimGX 需要 Python 3.13 或 3.14，若机器上没有，uv 会下载一个。不加它，uv 会取机器的默认 Python（macOS 的是 3.9），然后找不到 `manimgx`。
- 没有 `uv`？安装它：`curl -LsSf https://astral.sh/uv/install.sh | sh`，然后 `source $HOME/.local/bin/env`（或调用 `~/.local/bin/uv`）。
- 不安装也能用：`uvx --python 3.14 manimgx <命令>` 运行相同的 CLI。
- pip 在 Python 3.13 或 3.14 的虚拟环境中可用（更旧的 Python 找不到 `manimgx`）：`python3.14 -m venv .venv && .venv/bin/pip install manimgx`。
- ManimGX 不是 `manim` 包：不要安装 `manim`、ffmpeg 或 LaTeX，也不要 `import manim`。
- 它在 GPU 上绘制：macOS 用 Metal，Windows 用 Direct3D 12，Linux 用 Vulkan。没有 GPU 时（服务器、容器）在 CPU 上绘制，无需额外安装：Linux wheel 自带 Mesa 的 lavapipe。

## 2. 编写场景

保存为 `scene.py`：

```python
import manimgx as m


class SquareToCircle(m.Scene):
    def construct(self) -> None:
        square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
        circle = m.Circle(radius=1.6, color=m.PINK, fill_opacity=0.5)
        self.play(m.Create(square))
        self.play(m.Transform(square, circle))
        self.wait()
```

- API 是 Manim CE 的，每个名称都在包上：`m.Circle`、`m.MathTex`、`m.Create`、`m.UP`、`m.BLUE`。
- 时间只在 `self.play(...)`（默认 1 秒，可用 `run_time=` 指定）和 `self.wait(seconds)` 中流逝；`self.add(...)` 显示一个 mobject 但不动画。
- 画面为 14.2 × 8 单位，以原点为中心：将所有内容保持在 x ∈ [-7, 7]、y ∈ [-4, 4] 范围内。

## 3. 检查，然后渲染

```sh
manimgx inspect scene.py     # 故事板、时间线和 2D 布局检查；有问题则退出码为 1
manimgx render scene.py      # 在 scene.py 旁写出 SquareToCircle.mp4 并打印其路径
```

- `inspect` 采样 play 和 wait 的结束点。它列出每个 play 及其代码行号，报告 2D 布局问题，并写出 `<Scene>.storyboard.png`，其中问题被勾勒并编号。如果能查看图片就看一看。修复问题后再次 inspect。3D 场景会得到故事板和时间线；布局检查被跳过。
- `manimgx inspect scene.py -t 1.5,end` 改为检查 1.5 秒和结尾处的帧。可重复 `-t` 或用逗号分隔时间；`-o detail.png` 命名输出。图片按时间顺序排列，每张六帧；多余的写到 `…-2.png`，以此类推。不加 `end` 时，检查在最后一个请求帧的 play 之后停止。只有被采样的时刻会被检查。
- `render` 生成 1920×1080、60 fps；`-r 1280x720 --fps 30` 更快，适合草稿。一个文件含多个场景时需要指定场景名：`manimgx render scene.py MyScene`。
- 出错时打印失败的场景代码行，对于名称错误还会给出提示（`ShowCreation is Create in ManimGX`）。
- `no GPU adapter` 表示命令在隐藏 GPU 的沙箱中运行：在沙箱外运行（如果你的工具需要批准，请询问用户）。

## 4. 展示

为用户打开视频，并告知其路径：macOS 上 `open SquareToCircle.mp4`，Linux 上 `xdg-open SquareToCircle.mp4`。

## 5. API 速查表

- 图形：`Square`、`Circle`、`Rectangle`、`Triangle`、`Polygon([x, y, 0], ...)`、`Line`、`Arrow`、`Dot`、`Brace(mob, m.DOWN)`、`NumberPlane`。点为 `[x, y, 0]`。
- 文本：`Text("纯文本")`、`MathTex(r"a^2 + b^2 = c^2")`（LaTeX 数学）、`Tex(r"文本和 $x^2$")`。使用原始字符串。
- 动画：`Create`、`Write`、`FadeIn(mob, shift=m.UP)`、`FadeOut`、`Transform`、`ReplacementTransform`、`TransformMatchingTex`、`GrowFromCenter`、`Indicate`、`Circumscribe`、`Rotate(mob, m.PI / 2)`；用 `AnimationGroup`、`LaggedStart`、`Succession` 组合。`mob.animate.shift(m.RIGHT).scale(2)` 为任意方法调用生成动画。
- 放置：`.to_edge(m.UP)`、`.next_to(other, m.RIGHT, buff=0.3)`、`.move_to([x, y, 0])`、`.shift(2 * m.LEFT)`、`.scale(k)`、`m.VGroup(a, b).arrange(m.DOWN)`。
- 样式：`color=m.YELLOW`、`fill_opacity=0.5`、`stroke_width=6`、`font_size=48`。白色背景：在 import 之后设 `m.config.background_color = m.WHITE`。
- 图表：`axes = m.Axes(x_range=[-3, 3], y_range=[-2, 2])`，然后 `axes.plot(lambda x: x**2, color=m.BLUE)`。
- 声音：`self.add_sound("click.wav")` 立即开始播放声音；`self.play(m.FadeIn(mob), m.Sound("whoosh.mp3"))` 随动画播放声音。
- 旁白：`self.say("[x 平方]的导数是[二 x]。", m.Indicate(a), m.Write(b))` 在方括号标记的词语期间说话并播放每个动画；场景的语音为 `voice = m.voices.Fal("<模型>", ...)`（fal.ai 的文本转语音，由环境变量 FAL_KEY 控制），默认为 ElevenLabs 的 Eleven v3，或任何从文本到 `m.Speech` 的函数。
- 幻灯片：在 play 之间用 `self.next_section("名称")`；`manimgx present scene.py` 在浏览器中打开。

## 6. 查阅

文档如下，每页为 Markdown。用户指南讲述场景的工作方式。参考给出了每个类、其接受
的关键字和示例。画廊给出了三十部影片的代码。https://www.aipaikj.top/llms-full.txt
包含所有页面于一个文件中。

## 用户指南

- [欢迎](<https://www.aipaikj.top/index.md>)
- [快速开始](<https://www.aipaikj.top/user-guide/quickstart/index.md>)
- [动画](<https://www.aipaikj.top/user-guide/animations/index.md>)
- [相机与 3D](<https://www.aipaikj.top/user-guide/camera-and-3d/index.md>)
- [从 Manim CE 迁移而来](<https://www.aipaikj.top/user-guide/coming-from-manim-ce/index.md>)
- [图形](<https://www.aipaikj.top/user-guide/graphs/index.md>)
- [数学对象](<https://www.aipaikj.top/user-guide/mobjects/index.md>)
- [位置](<https://www.aipaikj.top/user-guide/positions/index.md>)
- [渲染与分享](<https://www.aipaikj.top/user-guide/rendering/index.md>)
- [声音与语音](<https://www.aipaikj.top/user-guide/sound-and-voice/index.md>)
- [文本和数学](<https://www.aipaikj.top/user-guide/text-and-math/index.md>)
- [基础](<https://www.aipaikj.top/user-guide/the-basics/index.md>)
- [更新器](<https://www.aipaikj.top/user-guide/updaters/index.md>)

## 参考

- [概览](<https://www.aipaikj.top/reference/index.md>)
- [为变化添加动画](<https://www.aipaikj.top/reference/animations/animate/index.md>)
- [出现与消失](<https://www.aipaikj.top/reference/animations/appear-and-disappear/index.md>)
- [强调](<https://www.aipaikj.top/reference/animations/emphasis/index.md>)
- [概览](<https://www.aipaikj.top/reference/animations/index.md>)
- [移动与变形](<https://www.aipaikj.top/reference/animations/move-and-deform/index.md>)
- [速率函数](<https://www.aipaikj.top/reference/animations/rate-functions/index.md>)
- [同时与依次](<https://www.aipaikj.top/reference/animations/together-and-in-turn/index.md>)
- [变换](<https://www.aipaikj.top/reference/animations/transforms/index.md>)
- [相机](<https://www.aipaikj.top/reference/camera-and-3d/camera/index.md>)
- [概览](<https://www.aipaikj.top/reference/camera-and-3d/index.md>)
- [灯光与材质](<https://www.aipaikj.top/reference/camera-and-3d/lights-and-materials/index.md>)
- [曲面与立体](<https://www.aipaikj.top/reference/camera-and-3d/surfaces-and-solids/index.md>)
- [3D 场景](<https://www.aipaikj.top/reference/camera-and-3d/three-d-scenes/index.md>)
- [标注](<https://www.aipaikj.top/reference/mobjects/annotations/index.md>)
- [颜色](<https://www.aipaikj.top/reference/mobjects/colors/index.md>)
- [副本与状态](<https://www.aipaikj.top/reference/mobjects/copies-and-states/index.md>)
- [坐标轴](<https://www.aipaikj.top/reference/mobjects/graphs/axes/index.md>)
- [图表](<https://www.aipaikj.top/reference/mobjects/graphs/charts/index.md>)
- [曲线](<https://www.aipaikj.top/reference/mobjects/graphs/curves/index.md>)
- [概览](<https://www.aipaikj.top/reference/mobjects/graphs/index.md>)
- [数轴](<https://www.aipaikj.top/reference/mobjects/graphs/number-lines/index.md>)
- [平面](<https://www.aipaikj.top/reference/mobjects/graphs/planes/index.md>)
- [绘图](<https://www.aipaikj.top/reference/mobjects/graphs/plotting/index.md>)
- [向量场](<https://www.aipaikj.top/reference/mobjects/graphs/vector-fields/index.md>)
- [分组](<https://www.aipaikj.top/reference/mobjects/groups/index.md>)
- [图像与 SVG](<https://www.aipaikj.top/reference/mobjects/images-and-svg/index.md>)
- [概览](<https://www.aipaikj.top/reference/mobjects/index.md>)
- [矩阵与表格](<https://www.aipaikj.top/reference/mobjects/matrices-and-tables/index.md>)
- [网络](<https://www.aipaikj.top/reference/mobjects/networks/index.md>)
- [路径](<https://www.aipaikj.top/reference/mobjects/paths/index.md>)
- [点云](<https://www.aipaikj.top/reference/mobjects/point-clouds/index.md>)
- [位置](<https://www.aipaikj.top/reference/mobjects/positions/index.md>)
- [圆与弧](<https://www.aipaikj.top/reference/mobjects/shapes/circles-and-arcs/index.md>)
- [组合形状](<https://www.aipaikj.top/reference/mobjects/shapes/combining-shapes/index.md>)
- [概览](<https://www.aipaikj.top/reference/mobjects/shapes/index.md>)
- [线与箭头](<https://www.aipaikj.top/reference/mobjects/shapes/lines-and-arrows/index.md>)
- [多边形](<https://www.aipaikj.top/reference/mobjects/shapes/polygons/index.md>)
- [尺寸与角度](<https://www.aipaikj.top/reference/mobjects/size-and-angle/index.md>)
- [样式](<https://www.aipaikj.top/reference/mobjects/style/index.md>)
- [概览](<https://www.aipaikj.top/reference/mobjects/text-and-math/index.md>)
- [数学](<https://www.aipaikj.top/reference/mobjects/text-and-math/math/index.md>)
- [数字](<https://www.aipaikj.top/reference/mobjects/text-and-math/numbers/index.md>)
- [文本](<https://www.aipaikj.top/reference/mobjects/text-and-math/text/index.md>)
- [命令行](<https://www.aipaikj.top/reference/rendering/command-line/index.md>)
- [配置](<https://www.aipaikj.top/reference/rendering/configuration/index.md>)
- [从 Python](<https://www.aipaikj.top/reference/rendering/from-python/index.md>)
- [概览](<https://www.aipaikj.top/reference/rendering/index.md>)
- [概览](<https://www.aipaikj.top/reference/scenes/index.md>)
- [现成场景](<https://www.aipaikj.top/reference/scenes/ready-made-scenes/index.md>)
- [场景](<https://www.aipaikj.top/reference/scenes/scene/index.md>)
- [概览](<https://www.aipaikj.top/reference/sound/index.md>)
- [语音](<https://www.aipaikj.top/reference/sound/voice/index.md>)
- [概览](<https://www.aipaikj.top/reference/updaters/index.md>)
- [值跟踪器](<https://www.aipaikj.top/reference/updaters/value-trackers/index.md>)

## 画廊

- [全部影片](<https://www.aipaikj.top/gallery/index.md>)
- [曼德博集合中的倍周期](<https://www.aipaikj.top/gallery/bifurcation-mandelbrot/index.md>)
- [弯而不伸](<https://www.aipaikj.top/gallery/catenoid-helicoid/index.md>)
- [切伦科夫光](<https://www.aipaikj.top/gallery/cherenkov-cone/index.md>)
- [展开圆周](<https://www.aipaikj.top/gallery/circle-area/index.md>)
- [翻面的环面](<https://www.aipaikj.top/gallery/clifford-torus/index.md>)
- [两木块数出 π](<https://www.aipaikj.top/gallery/colliding-blocks/index.md>)
- [复函数弯曲平面](<https://www.aipaikj.top/gallery/complex-maps/index.md>)
- [导数度量什么](<https://www.aipaikj.top/gallery/derivative/index.md>)
- [随机游走长成的珊瑚](<https://www.aipaikj.top/gallery/dla-coral/index.md>)
- [欧拉恒等式即一段行走](<https://www.aipaikj.top/gallery/euler-identity/index.md>)
- [圆周画出 π](<https://www.aipaikj.top/gallery/fourier-pi/index.md>)
- [高尔顿钉板](<https://www.aipaikj.top/gallery/galton-board/index.md>)
- [谐波驱动](<https://www.aipaikj.top/gallery/harmonic-drive/index.md>)
- [旋转陀螺](<https://www.aipaikj.top/gallery/heavy-top/index.md>)
- [希尔伯特空间填充曲线](<https://www.aipaikj.top/gallery/hilbert-curve/index.md>)
- [霍普夫纤维化](<https://www.aipaikj.top/gallery/hopf-fibration/index.md>)
- [球上的万花筒](<https://www.aipaikj.top/gallery/kaleidoscope-sphere/index.md>)
- [同步的萤火虫](<https://www.aipaikj.top/gallery/kuramoto-fireflies/index.md>)
- [拉格朗日点](<https://www.aipaikj.top/gallery/lagrange-points/index.md>)
- [时空中的生命游戏](<https://www.aipaikj.top/gallery/life-spacetime/index.md>)
- [矩阵移动平面](<https://www.aipaikj.top/gallery/linear-maps/index.md>)
- [洛伦兹吸引子](<https://www.aipaikj.top/gallery/lorenz-attractor/index.md>)
- [立方体与北极圈](<https://www.aipaikj.top/gallery/lozenge-cubes/index.md>)
- [门格海绵中的星](<https://www.aipaikj.top/gallery/menger-slice/index.md>)
- [Miura 折叠](<https://www.aipaikj.top/gallery/miura-ori/index.md>)
- [网络解开螺旋](<https://www.aipaikj.top/gallery/neural-untangle/index.md>)
- [用相位操控波束](<https://www.aipaikj.top/gallery/phased-array/index.md>)
- [素数螺旋](<https://www.aipaikj.top/gallery/prime-spirals/index.md>)
- [重排证明勾股定理](<https://www.aipaikj.top/gallery/pythagoras/index.md>)
- [二次公式](<https://www.aipaikj.top/gallery/quadratic-formula/index.md>)
- [矩形变为积分](<https://www.aipaikj.top/gallery/riemann-sums/index.md>)
- [√z 住在哪里](<https://www.aipaikj.top/gallery/riemann-surfaces/index.md>)
- [鲁珀特王子立方体](<https://www.aipaikj.top/gallery/rupert-cube/index.md>)
- [噪声变字](<https://www.aipaikj.top/gallery/score-diffusion/index.md>)
- [堆橘子](<https://www.aipaikj.top/gallery/sphere-packing/index.md>)
- [圆还是方？](<https://www.aipaikj.top/gallery/sugihara-cylinder/index.md>)
- [公式生成地貌](<https://www.aipaikj.top/gallery/surface-plots/index.md>)
- [泰勒级数为何停止](<https://www.aipaikj.top/gallery/taylor-poles/index.md>)
- [多项式逼近正弦](<https://www.aipaikj.top/gallery/taylor-series/index.md>)
- [网球拍翻转](<https://www.aipaikj.top/gallery/tennis-racket/index.md>)
- [圆上的乘法表](<https://www.aipaikj.top/gallery/times-tables/index.md>)
- [无中生有的交通堵塞](<https://www.aipaikj.top/gallery/traffic-helix/index.md>)
- [环面上的图灵斑图](<https://www.aipaikj.top/gallery/turing-torus/index.md>)
- [圆周画出正弦与余弦](<https://www.aipaikj.top/gallery/unit-circle/index.md>)
- [范艾伦辐射带](<https://www.aipaikj.top/gallery/van-allen/index.md>)
- [晶体与锥](<https://www.aipaikj.top/gallery/voronoi-cones/index.md>)
- [蛙跳烟环](<https://www.aipaikj.top/gallery/vortex-rings/index.md>)
- [量子隧穿](<https://www.aipaikj.top/gallery/wave-packet/index.md>)

## 可选

- [环境搭建](<https://www.aipaikj.top/developer-guide/index.md>)
- [文档](<https://www.aipaikj.top/developer-guide/documentation/index.md>)
- [引擎](<https://www.aipaikj.top/developer-guide/engine/index.md>)
- [GitHub 工作流](<https://www.aipaikj.top/developer-guide/github-workflows/index.md>)
- [项目管理](<https://www.aipaikj.top/developer-guide/project-management/index.md>)
- [测试](<https://www.aipaikj.top/developer-guide/testing/index.md>)
- [理解 ManimGX](<https://www.aipaikj.top/developer-guide/understanding-manimgx/index.md>)
- [变更日志](<https://www.aipaikj.top/changelog/index.md>)