# Manim动画最佳实践技能库

`Manim` `数学动画` `AI技能` `Python` `可视化`

# Manim 技能仓库

![访问量](https://visitor-badge.laobi.icu/badge?page_id=adithya-s-k.manim_skill)
![GitHub stars](https://img.shields.io/github/stars/adithya-s-k/manim_skill?style=flat-square)
![GitHub forks](https://img.shields.io/github/forks/adithya-s-k/manim_skill?style=flat-square)
![GitHub issues](https://img.shields.io/github/issues/adithya-s-k/manim_skill?style=flat-square)
![许可证](https://img.shields.io/github/license/adithya-s-k/manim_skill?style=flat-square)

> **⚡ 快速开始：** 一条命令将两个 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 社区的贡献者们。

感谢你们让数学之美变得可编程、触手可及。🎓✨