manimater-components은(는) 무엇을 하나요?
테스트된 Manim 컴포넌트 라이브러리로, JSON으로 구동됩니다. 컴포넌트는 이름과 매개변수로 구성되며, 애니메이션 코드를 직접 작성할 필요가 없습니다. 저장소: https://github.com/bishnt/manimater-components (MIT). Manimater 앱도 동일한 라이브러리를 사용합니다.
다음 두 가지 작업 중 하나를 요청받을 수 있습니다:
- 컴포넌트 사용: 주제에 맞는 컴포넌트 선택, 유효한 스토리보드 작성, 미리보기.
- 컴포넌트 추가: 규칙을 따르는 컴포넌트를 작성하고, 테스트한 후 기여.
사용자가 원하는 것이 무엇인지 파악하세요. 사용자가 기존 컴포넌트로 구현할 수 없는 애니메이션을 설명한다면 "컴포넌트 추가"로 진행하세요.
1. 컴포넌트 사용
올바른 컴포넌트 찾기
- references/catalog.md를 읽으세요: 모든 컴포넌트의 한 줄 설명과 매개변수가 있습니다.
(저장소를 클론한 경우 루트의
catalog.json에 전체 매개변수 세부정보와 각각의example이 있습니다.) - 단순히 주제가 아니라 설명하려는 아이디어와 일치하는 컴포넌트를 선택하세요. 일반적인 컴포넌트보다 구체적인 컴포넌트를 선호하고(모터 설명에는
bullet_points대신synchronous_motor), 스토리 전개를 위해 여러 개를 조합하세요: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]" # 클론 내에서 실행; Manim에 필요한 ffmpeg, Cairo, Pango 필요
python - <<'PY'
import json
from manimate.storyboard import validate
sb, errors = validate(json.load(open("storyboard.json")))
print(errors or "유효함")
PY
python -m manimate.preview <컴포넌트> # example을 사용하여 previews/<컴포넌트>.mp4 렌더링
python -m manimate.preview <컴포넌트> --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, ...)만 사용하고, 16진수 색상은 사용하지 마세요. 화면 텍스트는 짧고 평이하게 작성하세요.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를 따르세요.
일반 Python 로직에 대한 테스트를 tests/community/test_<name>.py에 작성하세요(엣지 케이스: 빈 값, 하나의 항목, 최대값, 긴 레이블). 일반 테스트는 이미 모든 커뮤니티 컴포넌트의 예제를 dry-run합니다.
확인
python -m manimate.preview <name>
python -m pytest tests/community
python -m manimate.catalog > catalog.json
python scripts/gen_docs.py
실행한 내용과 결과를 보고하세요. 아무것도 실행할 수 없었다면 그렇게 말하세요.
기여
사용자에게 적합한 경로를 평이한 언어로 알려주세요:
- git/GitHub 사용 가능: 저장소를 포크하고, 새 파일과 재생성된
catalog.json을 커밋한 후 풀 리퀘스트를 여세요.CONTRIBUTING.md를 참조하세요(체크리스트와 설명에 답해야 할 다섯 가지 디자인 질문이 있습니다). - 코드 작성 불가 (대부분의 사용자): 하나의 코드 블록에 Python 파일(두 번째 코드 블록에 테스트)을 제공하고, https://github.com/bishnt/manimater-components/issues/new?template=new-component.yml 에서 New component (from an LLM) 이슈 양식을 열어 코드를 붙여넣도록 안내하세요. 봇이 실행 없이 코드를 확인하고, 사용자 이름으로 풀 리퀘스트를 엽니다. 유지보수자가 검토합니다.
사용자가 양식에 붙여넣을 수 있는 세 줄 요약으로 마무리하세요: 무엇을 설명하는지, 매개변수, 처리한 실패 케이스.
경계
- 카탈로그에 없는 컴포넌트가 존재한다고 주장하지 마세요. 직접 렌더링하지 않았다면 렌더링 결과가 올바르다고 주장하지 마세요.
- MIT 호환 라이선스가 아니거나 출처를 명시하지 않는 한, 다른 저장소의 코드를 기여에 복사하지 마세요. manim-eng의 소스, 문서, 예제는 AI 훈련 데이터로 사용할 수 없습니다(
docs/THIRD_PARTY.md참조).