¿Qué hace manimater-components?
Una biblioteca de componentes Manim probados, impulsados por JSON. Un componente es un nombre más parámetros; nunca necesita código de animación de tu parte. Repositorio: https://github.com/bishnt/manimater-components (MIT). La aplicación Manimater usa la misma biblioteca.
Dos cosas que se te puede pedir hacer:
- Usar componentes: elegir los adecuados para un tema, escribir un storyboard válido, previsualizarlo.
- Agregar un componente: escribir uno que siga las reglas, probarlo y lograr que sea contribuido.
Determina cuál de las dos quiere el usuario. Si describe una animación que ningún componente existente puede realizar, pasa a "Agregar un componente".
1. Usar componentes
Encontrar el componente adecuado
- Lee references/catalog.md: cada componente con una descripción de una línea y sus parámetros.
(Si estás dentro de un clon del repositorio,
catalog.jsonen la raíz tiene los detalles completos de los parámetros y unexamplepara cada uno). - Elige el componente cuya descripción coincida con la idea a mostrar, no solo con el tema. Prefiere un componente específico
sobre uno genérico (
synchronous_motoren lugar debullet_pointspara una explicación de motores), y combina varios para una historia:title_card, luego los componentes del concepto, luegocalloutcomo conclusión final. - Lee la entrada del componente elegido en
catalog.jsonpara conocer sus nombres de parámetros exactos, tipos,choicesyexample.
Escribir un storyboard
Un storyboard es JSON; la biblioteca lo verifica por ti:
{ "title": "Cómo funciona un motor síncrono",
"scenes": [
{ "component": "title_card", "params": { "title": "Motores síncronos" }, "narration": "¿Por qué este motor nunca patina?" },
{ "component": "synchronous_motor", "params": { "poles": 2, "frequency_hz": 50 }, "narration": "El rotor se bloquea con el campo giratorio." },
{ "component": "callout", "params": { "text": "La velocidad es fija según la frecuencia y el número de polos.", "kind": "takeaway" }, "narration": "Por lo tanto, la velocidad depende solo de la frecuencia." }
] }
Reglas que el validador aplica: máximo 12 escenas, cadenas de hasta 300 caracteres, listas de hasta 8 elementos, los parámetros desconocidos se ignoran, los parámetros requeridos deben estar presentes, choices debe coincidir. Nunca inventes un nombre de componente o un parámetro; si falta alguno, dilo y ofrece escribir un nuevo componente.
Validar y previsualizar
pip install -e ".[dev]" # en un clon; necesita ffmpeg, Cairo y Pango para Manim
python - <<'PY'
import json
from manimate.storyboard import validate
sb, errors = validate(json.load(open("storyboard.json")))
print(errors or "válido")
PY
python -m manimate.preview <component> # renderiza previews/<component>.mp4 desde su ejemplo
python -m manimate.preview <component> --params '{"...": 1}' # con tus propios parámetros
python -m manimate.preview --list
Si no puedes ejecutar código en este entorno, produce el JSON del storyboard y los comandos exactos, y di claramente que no lo has validado ni renderizado.
2. Agregar un componente
Lee primero references/component-template.py. Es un componente completo y funcional.
Decidir
- Una idea, reutilizable. "Cómo funciona un transformador" es un video completo; "pesos de atención entre dos palabras" es un componente. Los parámetros (números, etiquetas, listas) deben hacerlo útil para muchos ejemplos.
- Revisa references/catalog.md para no duplicar un componente existente.
- Pregunta al usuario cualquier cosa que no puedas decidir por ti mismo (para quién es, qué debería ser ajustable), pero no más de dos preguntas; de lo contrario, toma decisiones sensatas y menciónalas.
Escribirlo
Guárdalo como manimate/components/community/<nombre>.py (snake_case, único). Se registra automáticamente. Sigue la plantilla
exactamente y estas reglas:
- Máximo 5 parámetros, cada uno con una descripción (una IA la lee), un valor predeterminado o
required=True, y unvalidatorque devuelva un mensaje en lenguaje sencillo para entradas incorrectas. Ajusta, recorta, falla suavemente; nunca falles con entradas extrañas. - El diccionario
exampledebe ser válido y debe renderizar. - Las matemáticas, algoritmos y diseño son funciones Python simples, sin Manim, para que puedan ser probados unitariamente.
- Solo colores de
manimate.theme(theme.ACCENT, ...), nunca hexadecimales. Texto corto y simple en pantalla.ctx.fit(...)para que nada salga del escenario. - Desvanece la imagen final completa con un
FadeIn, luego anima lo que transmite el significado. Usa el tiempo que se te da (ctx.remaining,Ctx.beat). Usactx.play/ctx.wait, nuncascene.play. - Solo código de dibujo: sin red, archivos, subprocesos,
eval,exec,getattrni acceso a dunder. Las importaciones se limitan amanim,numpy, la biblioteca estándar y los módulos propios de la biblioteca. CI y un bot rechazan cualquier otra cosa. - Está permitido envolver un plugin de Manim solo si tiene licencia MIT o Creative Commons; sigue
docs/WRITING_A_COMPONENT.md.
Escribe una prueba para la lógica Python simple en tests/community/test_<nombre>.py (casos límite: vacío, un elemento, el máximo, etiquetas
largas). La prueba genérica ya ejecuta en seco el ejemplo de cada componente de la comunidad.
Verificarlo
python -m manimate.preview <nombre>
python -m pytest tests/community
python -m manimate.catalog > catalog.json
python scripts/gen_docs.py
Informa qué ejecutaste y qué sucedió. Si no pudiste ejecutar nada, dilo.
Contribuirlo
Indica al usuario, en lenguaje sencillo, qué camino le conviene:
- Puede usar git/GitHub: bifurca el repositorio, confirma los nuevos archivos y el
catalog.jsonregenerado, abre una solicitud de extracción. ConsultaCONTRIBUTING.md(tiene la lista de verificación y las cinco preguntas de diseño para responder en la descripción). - No sabe programar (la mayoría): entrégale el archivo Python en un bloque de código (y la prueba en un segundo), y dile que abra el formulario de issue Nuevo componente (desde un LLM) en https://github.com/bishnt/manimater-components/issues/new?template=new-component.yml y pegue el código. Un bot lo verifica sin ejecutarlo y abre la solicitud de extracción por él, acreditándolo a él; un mantenedor lo revisa.
Termina con un resumen de tres líneas que el usuario pueda pegar en el formulario: qué enseña, los parámetros y los casos de fallo que manejaste.
Límites
- No afirmes que un componente existe a menos que esté en el catálogo. No afirmes que un renderizado se ve bien a menos que lo hayas renderizado.
- No copies código de otros repositorios en una contribución a menos que tenga licencia MIT o compatible y digas de dónde proviene.
El código fuente, documentación y ejemplos de manim-eng no deben usarse como datos de entrenamiento de IA (ver
docs/THIRD_PARTY.md).