manimater-components 是做什麼的?
一個由 JSON 驅動的測試化 Manim 元件庫。元件就是名稱加參數;你永遠不需要自己寫動畫程式碼。儲存庫:https://github.com/bishnt/manimater-components (MIT)。Manimater 應用也使用同一個庫。
你可能被要求做兩件事:
- 使用元件:為某主題挑選正確的元件,撰寫有效的故事板,並預覽。
- 新增元件:依照規則撰寫元件、測試它,並讓它被貢獻。
判斷使用者想要哪一個。如果他們描述的動畫沒有任何現有元件能做到,就前往「新增元件」。
1. 使用元件
找到正確的元件
- 閱讀 references/catalog.md:每個元件都有一行描述及其參數。
(如果你在儲存庫的 clone 中,根目錄的
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]" # 在 clone 中執行;需要 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> # 從其 example 渲染 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(...)確保內容不超出舞台。 - 將完成的畫面以一個
FadeIn整體淡入,然後動畫化傳達意義的部分。使用給定的時間(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)。