manimater-components 是做什么的?
一个由 JSON 驱动的测试 Manim 组件库。组件是一个名称加参数;你永远不需要编写动画代码。仓库地址:https://github.com/bishnt/manimater-components (MIT)。Manimater 应用程序使用相同的库。
你可能被要求做两件事:
- 使用组件:为某个主题选择合适的组件,编写有效的故事板,并预览它。
- 添加组件:编写一个符合规则的组件,测试它,并将其贡献上来。
请判断用户想要哪一个。如果用户描述的动画没有现有组件能够实现,则转到“添加组件”。
1. 使用组件
找到合适的组件
- 阅读 references/catalog.md:每个组件都有一行描述和它的参数。
(如果你在仓库的克隆中,根目录下的
catalog.json包含完整的参数详细信息以及每个组件的example。) - 选择描述与要展示的想法匹配的组件,而不仅仅是主题。优先选择一个具体的组件,而不是通用的组件(对于电机解释,选择
synchronous_motor而不是bullet_points),并组合几个组件来讲述一个故事:title_card,然后概念组件,最后callout作为总结要点。 - 在
catalog.json中阅读所选组件的条目,了解其确切的参数名称、类型、choices和example。
编写故事板
故事板是 JSON;库会为你校验它:
{ "title": "同步电机如何工作",
"scenes": [
{ "component": "title_card", "params": { "title": "同步电机" }, "narration": "为什么这个电机从不失步?" },
{ "component": "synchronous_motor", "params": { "poles": 2, "frequency_hz": 50 }, "narration": "转子锁住旋转磁场。" },
{ "component": "callout", "params": { "text": "速度由频率和极数决定。", "kind": "takeaway" }, "narration": "所以速度只取决于频率。" }
] }
校验器强制执行的规则:最多 12 个场景,字符串最多 300 个字符,列表最多 8 项,未知参数会被丢弃,必需参数必须存在,choices 必须匹配。永远不要虚构组件名称或参数;如果缺少某个组件,请说明原因并提供编写新组件的选项。
验证和预览
pip install -e ".[dev]" # 在克隆中;需要 ffmpeg、Cairo 和 Pango 来运行 Manim
python - <<'PY'
import json
from manimate.storyboard import validate
sb, errors = validate(json.load(open("storyboard.json")))
print(errors or "valid")
PY
python -m manimate.preview <component> # 根据示例渲染 previews/<component>.mp4
python -m manimate.preview <component> --params '{"...": 1}' # 使用你自己的参数
python -m manimate.preview --list
如果你无法在此环境中运行代码,请生成故事板 JSON 和确切的命令,并明确说明你尚未验证或渲染它。
2. 添加组件
首先阅读 references/component-template.py。它是一个完整的、可工作的组件。
决定
- 一个想法,可复用。“变压器如何工作”是一个完整的视频;“两个词之间的注意力权重”是一个组件。参数(数字、标签、列表)应使其对许多示例有用。
- 检查 references/catalog.md,以免与现有组件重复。
- 询问用户任何你无法自行决定的内容(针对谁、应该可调整什么),但问题不要超过两个;否则做出合理的决定并说明理由。
编写它
保存为 manimate/components/community/<name>.py(snake_case,唯一)。它会自动注册。严格按照模板编写,并遵守以下规则:
- 最多 5 个参数,每个参数带有一个描述(供 AI 读取)、一个默认值或
required=True,以及一个返回通俗错误消息的validator(针对错误输入)。进行截断、修剪、回退;不要在异常输入上崩溃。 example字典必须有效且能够渲染。- 数学计算、算法和布局是不含 Manim 的纯 Python 函数,因此可以进行单元测试。
- 只使用
manimate.theme颜色(theme.ACCENT,...),绝不使用十六进制颜色。屏幕文本简短、清晰。使用ctx.fit(...)确保内容不超出舞台。 - 将完成好的画面作为一个整体淡入,然后动画化传达含义的部分。使用给定的时间(
ctx.remaining、Ctx.beat)。使用ctx.play/ctx.wait,绝不使用scene.play。 - 纯绘制代码:无网络、文件、子进程、
eval、exec、getattr或 dunder 访问。导入仅限于manim、numpy、标准库以及库自身的模块。CI 和机器人会拒绝任何其他内容。 - 包装 Manim 插件仅在插件采用 MIT 或 Creative Commons 许可时才允许;遵循
docs/WRITING_A_COMPONENT.md。
为 tests/community/test_<name>.py 中的纯 Python 逻辑编写测试(边界情况:空、一个项目、最大值、长标签)。通用测试已经对每个社区组件的示例进行了空运行。
检查它
python -m manimate.preview <name>
python -m pytest tests/community
python -m manimate.catalog > catalog.json
python scripts/gen_docs.py
报告你运行了什么以及结果。如果你无法运行任何东西,请说明原因。
贡献它
用通俗的语言告诉用户,哪条路径适合他们:
- 他们可以使用 git/GitHub: fork 该仓库,提交新文件以及重新生成的
catalog.json,然后打开一个 pull request。请参阅CONTRIBUTING.md(其中有清单和在描述中需要回答的五个设计问题)。 - 他们不写代码(大多数人): 在一个代码块中给他们 Python 文件(在第二个代码块中给测试),并告诉他们打开 New component (from an LLM) 问题表单,地址为 https://github.com/bishnt/manimater-components/issues/new?template=new-component.yml ,然后粘贴代码。机器人会检查代码但不运行它,并为他们打开 pull request(署名归他们);维护者会进行审查。
最后提供一个用户可以粘贴到表单中的三行总结:它教什么、参数、以及你处理的失败情况。
界限
- 除非组件在目录中,否则不要声称存在该组件。除非你渲染过,否则不要声称渲染结果看起来正确。
- 不要将其他仓库的代码复制到贡献中,除非该代码是 MIT 或兼容许可,并且你说明了来源。manim-eng 的源代码、文档和示例不得用作 AI 训练数据(请参阅
docs/THIRD_PARTY.md)。