413 lines
11 KiB
Markdown
413 lines
11 KiB
Markdown
# Manim动画最佳实践技能库
|
||
|
||
`Manim` `数学动画` `AI技能` `Python` `可视化`
|
||
|
||
# Manim 技能仓库
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
> **⚡ 快速开始：** 一条命令将两个 Manim 技能添加到你的 AI 代理：
|
||
> ```bash
|
||
> npx skills add adithya-s-k/manim_skill
|
||
> ```
|
||
|
||
这是一个关于 **Manim 社区版** 和 **ManimGL**（3Blue1Brown 版本）的最佳实践、模式和示例的综合集合。本仓库提供经过实战验证的代码示例和指南，用于创建数学动画。
|
||
|
||
## 📚 两个版本介绍
|
||
|
||
### Manim 社区版（`manim`）
|
||
- **仓库**：https://github.com/ManimCommunity/manim
|
||
- **特点**：社区维护、稳定、文档完善
|
||
- **适用场景**：生产环境、教育内容、协作项目
|
||
- **命令**：`manim` CLI
|
||
- **导入**：`from manim import *`
|
||
|
||
### ManimGL（`manimgl`）
|
||
- **仓库**：https://github.com/3b1b/manim
|
||
- **特点**：Grant Sanderson（3Blue1Brown）的原版，使用 OpenGL 渲染
|
||
- **适用场景**：交互式开发、3D 场景、快速原型开发
|
||
- **命令**：`manimgl` CLI
|
||
- **导入**：`from manimlib import *`
|
||
|
||
> **重要提示**：这两个框架**相互独立、互不兼容**。为其中一个编写的代码不经修改无法在另一个上运行。
|
||
|
||
---
|
||
|
||
## 🚀 安装
|
||
|
||
### 前置条件（两个版本均需）
|
||
1. **Python 3.7+** - 必须
|
||
2. **FFmpeg** - 用于视频编码
|
||
3. **LaTeX** - 用于数学排版（TeX Live、MiKTeX 或 MacTeX）
|
||
|
||
#### 安装 FFmpeg
|
||
|
||
**macOS：**
|
||
```bash
|
||
brew install ffmpeg
|
||
```
|
||
|
||
**Ubuntu/Debian：**
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install ffmpeg
|
||
```
|
||
|
||
**Windows：**
|
||
从 https://ffmpeg.org/download.html 下载并添加到 PATH
|
||
|
||
#### 安装 LaTeX
|
||
|
||
**macOS：**
|
||
```bash
|
||
brew install mactex
|
||
```
|
||
|
||
**Ubuntu/Debian：**
|
||
```bash
|
||
sudo apt install texlive-full
|
||
```
|
||
|
||
**Windows：**
|
||
从 https://miktex.org/download 安装 MiKTeX
|
||
|
||
---
|
||
|
||
### 安装 Manim 社区版
|
||
|
||
```bash
|
||
# 使用 pip
|
||
pip install manim
|
||
|
||
# 使用 uv（推荐）
|
||
uv pip install manim
|
||
|
||
# 验证安装
|
||
manim --version
|
||
```
|
||
|
||
**文档**：https://docs.manim.community/
|
||
|
||
---
|
||
|
||
### 安装 ManimGL
|
||
|
||
```bash
|
||
# 使用 pip
|
||
pip install manimgl
|
||
|
||
# 使用 uv（推荐）
|
||
uv pip install manimgl
|
||
|
||
# 验证安装
|
||
manimgl --version
|
||
```
|
||
|
||
**macOS（ARM）额外要求：**
|
||
```bash
|
||
arch -arm64 brew install pkg-config cairo
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 Skills.sh 集成
|
||
|
||
本仓库提供两个 **AI 代理技能**，可使用 [skills.sh](https://skills.sh/) 一条命令安装：
|
||
|
||
### 使用 npx 安装（推荐）
|
||
|
||
```bash
|
||
# 安装 Manim 社区版最佳实践
|
||
npx skills add adithya-s-k/manim_skill/skills/manimce-best-practices
|
||
|
||
# 安装 ManimGL 最佳实践
|
||
npx skills add adithya-s-k/manim_skill/skills/manimgl-best-practices
|
||
|
||
# 或同时安装两者
|
||
npx skills add adithya-s-k/manim_skill/skills/manimce-best-practices adithya-s-k/manim_skill/skills/manimgl-best-practices
|
||
```
|
||
|
||
### 什么是技能（Skills）？
|
||
|
||
技能是 **AI 编程代理的可复用能力**。安装后，你的 AI 助手（如 Claude、GitHub Copilot 或 Cursor）将自动获得：
|
||
- ✅ 领域专属最佳实践
|
||
- ✅ 可运行的代码示例
|
||
- ✅ 常用模式与反模式
|
||
- ✅ 框架专项知识
|
||
|
||
技能遵循 [Agent Skills 开放标准](https://github.com/anthropics/skills)，可跨多种 AI 工具使用。
|
||
|
||
### 技能触发时机
|
||
|
||
**manimce-best-practices** - 在以下情况自动加载：
|
||
- 导入 `from manim import *`
|
||
- 使用 `manim` CLI 命令
|
||
- 处理 Scene 类、数学动画或 LaTeX 渲染
|
||
- 使用 Manim 社区版制作教育视频或视觉说明
|
||
|
||
**manimgl-best-practices** - 在以下情况自动加载：
|
||
- 导入 `from manimlib import *`
|
||
- 使用 `manimgl` CLI 命令
|
||
- 处理 InteractiveScene、3D 渲染或相机帧控制
|
||
- 使用 `.embed()` 或 `checkpoint_paste()` 的交互模式
|
||
|
||
---
|
||
|
||
## 📖 使用本仓库
|
||
|
||
### 仓库结构
|
||
|
||
```
|
||
manim_skill/
|
||
├── skills/
|
||
│ ├── manimce-best-practices/ # Manim 社区版技能
|
||
│ │ ├── SKILL.md # 技能元数据
|
||
│ │ └── rules/ # 各项最佳实践指南
|
||
│ │ ├── animations.md
|
||
│ │ ├── scenes.md
|
||
│ │ ├── mobjects.md
|
||
│ │ └── ...
|
||
│ │
|
||
│ └── manimgl-best-practices/ # ManimGL 技能
|
||
│ ├── SKILL.md
|
||
│ └── rules/
|
||
│ ├── animations.md
|
||
│ ├── 3d.md
|
||
│ ├── camera.md
|
||
│ └── ...
|
||
│
|
||
└── tests/
|
||
├── manimce/ # 社区版测试
|
||
└── manimgl/ # ManimGL 测试
|
||
```
|
||
|
||
### 每个技能文件包含什么？
|
||
|
||
每个 `.md` 文件包含：
|
||
- 特定 Manim 功能的**最佳实践**
|
||
- **可运行的代码示例**（全部经过测试！）
|
||
- **常用模式**和使用场景
|
||
- **需要避免的坑**
|
||
- 两个版本之间的 **API 差异**
|
||
|
||
---
|
||
|
||
## 🎯 快速示例
|
||
|
||
### Manim 社区版
|
||
|
||
```python
|
||
from manim import *
|
||
|
||
class BasicExample(Scene):
|
||
def construct(self):
|
||
circle = Circle()
|
||
circle.set_fill(BLUE, opacity=0.5)
|
||
circle.set_stroke(BLUE_E, width=4)
|
||
|
||
self.play(Create(circle))
|
||
self.wait()
|
||
```
|
||
|
||
**运行：**
|
||
```bash
|
||
manim -pql scene.py BasicExample
|
||
# -p：渲染后预览
|
||
# -q：质量（l=低，m=中，h=高）
|
||
```
|
||
|
||
### ManimGL
|
||
|
||
```python
|
||
from manimlib import *
|
||
|
||
class BasicExample(InteractiveScene):
|
||
def construct(self):
|
||
circle = Circle()
|
||
circle.set_fill(BLUE, opacity=0.5)
|
||
circle.set_stroke(BLUE_E, width=4)
|
||
|
||
self.play(ShowCreation(circle))
|
||
self.wait()
|
||
```
|
||
|
||
**运行：**
|
||
```bash
|
||
manimgl scene.py BasicExample --write_file
|
||
# --write_file：保存视频输出
|
||
# -s：跳到最后一帧
|
||
# -w：写入文件但不打开
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 运行测试
|
||
|
||
本仓库包含全面的测试，确保所有代码示例正常运行。
|
||
|
||
### 测试 Manim 社区版技能
|
||
|
||
```bash
|
||
# 测试所有文件
|
||
uv run python tests/manimce/test_all_skills.py
|
||
|
||
# 测试特定文件
|
||
uv run python tests/manimce/test_all_skills.py animations.md
|
||
|
||
# 多线程运行（更快）
|
||
uv run python tests/manimce/test_all_skills.py -j 4
|
||
```
|
||
|
||
### 测试 ManimGL 技能
|
||
|
||
```bash
|
||
# 测试所有文件
|
||
uv run python tests/manimgl/test_all_skills.py
|
||
|
||
# 测试特定文件
|
||
uv run python tests/manimgl/test_all_skills.py 3d.md
|
||
|
||
# 多线程运行（注意内存）
|
||
uv run python tests/manimgl/test_all_skills.py -j 4
|
||
```
|
||
|
||
> **注意**：使用过多线程进行并行测试可能导致内存溢出。最多使用 4-6 个线程，或逐文件测试。
|
||
|
||
---
|
||
|
||
## 🔍 两个版本的主要区别
|
||
|
||
| 功能 | Manim 社区版 | ManimGL |
|
||
|------|-------------|---------|
|
||
| **导入** | `from manim import *` | `from manimlib import *` |
|
||
| **CLI 命令** | `manim` | `manimgl` |
|
||
| **场景基类** | `Scene`、`MovingCameraScene` | `Scene`、`InteractiveScene` |
|
||
| **创建动画** | `Create()` | `ShowCreation()` |
|
||
| **文本类** | `Text()`、`MathTex()` | `Text()`、`Tex()` |
|
||
| **3D 渲染** | 有限支持 | 完整 OpenGL 支持 |
|
||
| **交互模式** | 无 | 有（`-se` 标志、`.embed()`） |
|
||
| **相机控制** | `MovingCameraScene` | `self.camera.frame` |
|
||
| **配置方式** | Python 配置 | YAML 文件 |
|
||
| **颜色常量** | 相同 | 相同 + 变体（如 `BLUE_A`、`BLUE_E`） |
|
||
|
||
---
|
||
|
||
## 📚 探索技能内容
|
||
|
||
### Manim 社区版：
|
||
从 `skills/manimce-best-practices/rules/` 中的以下指南开始：
|
||
1. **scenes.md** - 场景结构与生命周期
|
||
2. **animations.md** - 基本动画模式
|
||
3. **mobjects.md** - 创建和操作对象
|
||
4. **colors.md** - 颜色系统与样式
|
||
5. **text.md** - 文本与 LaTeX 渲染
|
||
|
||
### ManimGL：
|
||
从 `skills/manimgl-best-practices/rules/` 中的以下指南开始：
|
||
1. **scenes.md** - 场景类型与 InteractiveScene
|
||
2. **animations.md** - 动画基础
|
||
3. **camera.md** - 相机移动与 3D 朝向
|
||
4. **3d.md** - 3D 对象创建与渲染
|
||
5. **interactive.md** - 交互式开发工作流
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
发现示例有问题？想添加新的最佳实践？
|
||
|
||
1. 确保你的代码示例在目标 Manim 版本上可以运行
|
||
2. 将其添加到对应的技能文件中
|
||
3. 运行测试验证：`uv run python tests/<版本>/test_all_skills.py <文件名>`
|
||
4. 提交 Pull Request
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
本仓库采用 MIT 许可证——详情请参阅 [LICENSE](LICENSE) 文件。
|
||
|
||
**注意**：此许可证适用于本仓库中的教育材料和代码示例。底层 Manim 框架（Manim 社区版和 ManimGL）有各自的许可证。
|
||
|
||
---
|
||
|
||
## 🔗 相关资源
|
||
|
||
### Manim 社区版
|
||
- **文档**：https://docs.manim.community/
|
||
- **Discord**：https://www.manim.community/discord/
|
||
- **GitHub**：https://github.com/ManimCommunity/manim
|
||
|
||
### ManimGL
|
||
- **文档**：https://3b1b.github.io/manim/
|
||
- **GitHub**：https://github.com/3b1b/manim
|
||
- **教程视频**：Grant 的 YouTube 频道
|
||
|
||
### 综合
|
||
- **3Blue1Brown**：https://www.youtube.com/@3blue1brown
|
||
- **Manim 社区**：https://www.manim.community/
|
||
|
||
---
|
||
|
||
## ⚠️ 常见问题排查
|
||
|
||
### 常见问题
|
||
|
||
**"找不到命令：manim/manimgl"**
|
||
- 验证安装：`pip list | grep manim`
|
||
- 检查 PATH 配置
|
||
- 尝试：`python -m manim` 或 `python -m manimlib`
|
||
|
||
**LaTeX 错误**
|
||
- 安装完整版 LaTeX 发行版（非基础版）
|
||
- ManimCE：尝试 `manim --tex_template <模板>` 更换不同模板
|
||
- ManimGL：检查 `custom_defaults.yml` 中的 LaTeX 配置
|
||
|
||
**视频无法播放**
|
||
- 为你的操作系统安装媒体编解码器
|
||
- 尝试不同质量设置（`-ql`、`-qm`、`-qh`）
|
||
- 检查 FFmpeg 安装：`ffmpeg -version`
|
||
|
||
**内存溢出（并行测试）**
|
||
- 减少线程数：`-j 2` 或 `-j 4`
|
||
- 逐文件测试
|
||
- 关闭其他应用程序
|
||
|
||
**导入错误 / 版本错误**
|
||
- 确认导入了正确的版本：
|
||
- `from manim import *` → Manim 社区版
|
||
- `from manimlib import *` → ManimGL
|
||
- 卸载冲突版本：`pip uninstall manim manimgl manimlib`
|
||
- 重新安装所需版本
|
||
|
||
---
|
||
|
||
## 🙏 致谢
|
||
|
||
本仓库的诞生得益于以下人士的杰出工作：
|
||
|
||
### Grant Sanderson（3Blue1Brown）
|
||
**Manim** 动画引擎的原始创建者和 **3Blue1Brown** YouTube 频道的主理人。Grant 在数学可视化领域的开创性工作激励了全球数以百万计的学习者，并为通过程序化动画解释复杂概念创造了全新范式。他对开源教育和视觉叙事的坚持，从根本上改变了数学的教与学方式。
|
||
|
||
**网站**：https://www.3blue1brown.com/
|
||
**YouTube**：https://www.youtube.com/@3blue1brown
|
||
**Manim（ManimGL）**：https://github.com/3b1b/manim
|
||
|
||
### Manim 社区
|
||
维护 **Manim 社区版** 的专注团队和贡献者们，确保框架保持易用性、文档完整性和持续开发。他们在创建全面文档、管理社区支持和持续改进代码库方面的不懈努力，使数学动画对教育者、学生和创作者都触手可及。
|
||
|
||
**网站**：https://www.manim.community/
|
||
**GitHub**：https://github.com/ManimCommunity/manim
|
||
**Discord**：https://www.manim.community/discord/
|
||
|
||
---
|
||
|
||
### 站在巨人的肩膀上
|
||
|
||
两个框架都凝聚了无数小时的开发、文档、社区支持和创造性问题解决。本仓库的目标仅是整理和分享关于这些强大工具的知识。底层技术的所有荣誉归属于 Grant Sanderson 和 Manim 社区的贡献者们。
|
||
|
||
感谢你们让数学之美变得可编程、触手可及。🎓✨ |