aminghaseminia/blender-animation

Animación en Blender — Trabajo 3D con Python

Controla Blender mediante bpy, en modo fondo, desde un script que puedes re-ejecutar. Trata el archivo .blend como un artefacto de construcción del script: el script es la fuente de verdad, el archivo es el entregable.

Lee references/BLENDER-PLAYBOOK.md para arquitectura y criterio, y references/BLENDER-RECIPES.md para patrones de código listos para copiar. Verifica cada detalle de la API contra la documentación de la versión de Blender instalada; la API de Python cambia entre versiones.

1. Verifica primero el entorno

blender --version
blender --background --factory-startup --python-expr \
  "import bpy, sys; print('BLENDER', bpy.app.version_string); print('PY', sys.version.split()[0]); print('ENGINES', [e.bl_idname for e in bpy.types.RenderEngine.__subclasses__()][:5])"

Reglas:

• bpy pertenece al Python incluido con Blender. Nunca hagas pip install bpy ni ejecutes scripts de escena con el Python del sistema.
• Usa --python-exit-code 1 para que una excepción de Python falle el comando de shell en lugar de producir un éxito silencioso.
• Usa --factory-startup para construcciones limpias; nunca lo uses para borrar el proyecto abierto de un usuario.
• Registra la versión de Blender, el motor, el rango de fotogramas, la resolución, los FPS y la ruta de salida al inicio de cada render.

2. Invocaciones canónicas

# Construir una escena desde cero y guardar el .blend
blender --background --factory-startup --python-exit-code 1 --python blender/scripts/build_scene.py

# Modificar un proyecto existente
blender --background project.blend --python-exit-code 1 --python blender/scripts/update_scene.py

# Renderizar la animación guardada
blender --background project.blend --render-anim

# Renderizar un fotograma
blender --background project.blend --render-frame 120

# Renderizar un rango de forma segura (secuencia de imágenes)
blender --background project.blend --python-exit-code 1 --python blender/scripts/render_frames.py

Ejecuta trabajos largos con la salida redirigida a logs/ y siempre prefiere una secuencia de imágenes para cualquier cosa que puedas necesitar reanudar.

3. Arquitectura del script

Comienza con un archivo para una escena pequeña. Divide cuando la escena supere aproximadamente las 300 líneas o tenga más de una toma:

blender/
  config.py          # fps, rango de fotogramas, resolución, paleta, rutas, semilla
  build.py           # punto de entrada: reinicio → configuración → construir tomas → guardar
  scene_setup.py     # mundo, unidades, colecciones, ajustes de render
  geometry.py        # primitivas, curvas, mallas paramétricas
  materials.py       # constructores de nodos, fábrica de materiales reutilizables
  animation.py       # fotogramas clave, drivers, movimiento procedural
  camera.py          # rigs, órbita/dolly, DOF, comprobaciones de encuadre
  lighting.py        # luz principal/relleno/contra, HDRI, acentos emisivos
  simulation.py      # partículas, cuerpo rígido, tela — configuración de caché
  render.py          # motor, muestras, salida, hoja de contactos, codificación
  shots/             # un módulo por toma: shot_01.py, shot_02.py

No negociables:

• Idempotente. Re-ejecutar la construcción actualiza solo tus colecciones/objetos nombrados; nunca duplica geometría ni borra contenido de usuario no relacionado.
• Nombrado. Main_Logo, Cam_Orbit, Light_Key, Emitter_Particles. Nunca envíes Cube.003.
• Configurado. Cada valor ajustable vive en config.py o un dataclass, de modo que una revisión sea un cambio de una línea.
• Asertivo. Falla ruidosamente si falta un activo, cámara, fuente o directorio de salida.
• Delimitado. La limpieza solo elimina colecciones cuyos nombres controlas, con prefijo, p. ej. MS_.

4. Construcción de la escena

• Prefiere la API de datos (bpy.data.objects.new, bpy.data.meshes.new, collection.objects.link) sobre bpy.ops sensible al contexto, que depende de selección, modo y área.
• Cuando un operador sea realmente necesario, proporciona una anulación de contexto adecuada para esa versión y documenta por qué.
• Construye materiales a través de nodos y una pequeña función de fábrica; no copies y pegues árboles de 20 nodos por objeto.
• Usa escala del mundo real y establece el sistema de unidades de la escena; la escala incorrecta rompe DOF, física e iluminación.
• Mantén explícito el árbol de nodos del Mundo (color, intensidad, HDRI) para que los renders sean reproducibles en otra máquina.
• Empaqueta o relativiza los activos. Las rutas //assets/... más una carpeta de paquete superan a las rutas absolutas a las Descargas de alguien.

5. Animación

Elige el mecanismo deliberadamente:

Necesidad	Usa
Cambio de posición/rotación/escala/material creado manualmente	Fotogramas clave con interpolación explícita
Propiedad siguiendo otra propiedad o expresión	Drivers (expresiones simples y documentadas)
Movimiento repetitivo/paramétrico (órbitas, ondas, cuadrículas, espirales)	Matemáticas dependientes del fotograma, evaluadas sin estado
Miles de instancias, patrones, dispersión	Geometry Nodes
Movimiento físicamente emergente	Simulaciones (caché, verificar rango completo)
Trayectoria de cámara en el espacio	Curva + restricción Follow Path, o rig con fotogramas clave

Higiene de fotogramas clave:

obj.location = (0, 0, 0)
obj.keyframe_insert("location", frame=1)
obj.location = (4, 0, 0)
obj.keyframe_insert("location", frame=48)

for fc in obj.animation_data.action.fcurves:
    for kp in fc.keyframe_points:
        kp.interpolation = 'BEZIER'
        kp.easing = 'EASE_IN_OUT'
        kp.handle_left_type = kp.handle_right_type = 'AUTO_CLAMPED'

• Establece la interpolación intencionadamente. Bezier predeterminado está bien para movimientos orgánicos; usa LINEAR para velocidad constante y movimiento mecánico; usa CONSTANT para apariencia escalonada/pixelada.
• Nunca dejes una suavización no deseada en un bucle: produce un tirón en el punto de bucle.
• Para bucles: haz que el fotograma 1 y el fotograma N+1 sean idénticos, luego renderiza [1, N].
• Todo lo procedural debe ser una función pura del fotograma: f(frame). Sin estado acumulativo, sin random sin semilla.

6. Geometry Nodes e instancias

Usa Geometry Nodes cuando necesites escala, variación o control no destructivo:

• Dispersión/instancias (árboles, escombros, estrellas, bloques de multitudes).
• Matrices paramétricas, cuadrículas, patrones radiales, mosaicos geométricos islámicos.
• Desplazamiento animado, campos y rotación/escala por instancia.
• Convertir un bucle pesado de Python de 10,000 objetos en un árbol de nodos.

Construye nodos por nombre con nodes.new(...) y links.new(...), no por índice frágil. Expón los parámetros que el usuario pedirá (cantidad, radio, semilla, velocidad) como entradas de modificador para que una revisión no necesite cambios de código.

7. Materiales, iluminación, cámara

• Materiales: Base Principled BSDF; rugosidad/metalicidad explícitas; emisión para acentos (mantenlo contenido — el bloom no puede arreglar una toma plana). Transparencia real solo cuando sea necesaria, y verifícala en el motor final.
• Iluminación: principal → relleno → contra → entorno. La forma y la profundidad vienen antes que la decoración. Verifica la exposición y el recorte de brillos, no solo la ventana gráfica.
• Cámara: elige distancia focal y encuadre para el sujeto. Órbita, dolly, grúa o fija — cada una debe tener una razón. Verifica el encuadre en los fotogramas extremos, no solo en el fotograma 1. Prefiere manejadores Bezier suaves; añade un asentamiento sutil en lugar de una parada brusca.
• Profundidad de campo: enfoca en el punto de la historia; nunca desenfocar texto pequeño.

8. Motores y ajustes de render

Motor	Usar para	Coste
EEVEE	Motion graphics, trabajo estilizado, iteración rápida, previsualizaciones	Bajo
Cycles	Luz fotorrealista, reflejos, GI, vidrio, belleza final	Alto
Workbench	Bloqueo, siluetas, animáticas	Muy bajo

Prueba ambos cuando no estés seguro; la velocidad del motor depende de la escena, no del marketing. La GPU depende de la compilación, el controlador y el SO — mantén siempre una ruta de CPU.

Establece y registra explícitamente:

scene.render.engine = 'BLENDER_EEVEE_NEXT'   # 4.2+; versiones anteriores pueden usar 'BLENDER_EEVEE'
scene.render.resolution_x, scene.render.resolution_y = 1920, 1080
scene.render.resolution_percentage = 100
scene.render.fps, scene.render.fps_base = 30, 1.0
scene.frame_start, scene.frame_end = 1, 300
scene.render.image_settings.file_format = 'PNG'
scene.render.image_settings.color_mode = 'RGBA'
scene.render.filepath = "//renders/shot_01/frame_"

• Previsualización: resolución 25–50%, muestras bajas, EEVEE o Workbench.
• Final: resolución completa, motor elegido para el aspecto, denoise si ayuda, transformación de vista correcta.
• Color: decide la transformación de vista (AgX/Filmico/Estándar) una vez, aplícala a todos los pases y hazla coincidir aguas abajo en Remotion/FFmpeg. Las transformaciones no coincidentes son la causa más común de "la composición se ve lavada".
• Renders largos → secuencia PNG (o EXR cuando se necesite HDR), luego codifica. La salida directa de video es para revisiones rápidas.

9. Escalera de previsualización

1. Una imagen fija en un fotograma representativo.
2. Fotogramas clave: primero, revelación, pico, cada transición, último.
3. Segmento de baja muestra y baja resolución que contiene el movimiento más difícil.
4. Previsualización completa a escala reducida, FPS reales.
5. Solo final después de que 1–4 se vean bien.

Inspecciona con una hoja de contactos más fotogramas específicos:

ffmpeg -i preview.mp4 -vf "fps=2,scale=320:-1,tile=4x4" -frames:v 1 previews/contact.jpg

Busca parpadeo, z-fighting, popping, intersecciones, ondulación de texturas, recorte de cámara, cambios de exposición y texto ilegible.

10. Trabajo con texto, multilingüe y logotipos

• Convierte texto a malla solo después de confirmar el texto y la licencia de la fuente; mantén un objeto de texto editable en el origen.
• Verifica la cobertura de glifos antes de animar. Para persa/árabe, verifica la forma, unión, orden RTL, diacríticos y puntuación de escritura mixta en el fotograma renderizado — una cadena correcta puede renderizarse incorrectamente si la ruta del texto no da forma.
• Para trabajo de marca/logotipo, obtén fuente vectorial cuando sea posible; si es ráster, traza deliberadamente y verifica bordes a 4K.
• Bisela/pesa el tipo para que sobreviva a la luz; evita bordes negro sobre negro o blanco sobre blanco puros.

11. Rendimiento y fiabilidad

• Instancia, no dupliques. Reduce la subdivisión antes de reducir las muestras.
• Limita capas transparentes y volumétricos; son los asesinos habituales del tiempo de render.
• Almacena en caché las simulaciones y confirma que la caché esté dentro del proyecto o documentada.
• Renderiza en lotes de fotogramas para trabajos frágiles; verifica los recuentos de fotogramas y detecta fotogramas faltantes antes de codificar.
• Monitorea RAM/VRAM/disco. Las secuencias EXR 4K son grandes; verifica el espacio libre antes de un render largo.
• Haz una copia de seguridad de un .blend antes de abrirlo/guardarlo con una versión principal más nueva de Blender — los archivos más nuevos pueden no abrirse en versiones anteriores.

12. Ejemplo mínimo funcional

# build.py — ejecutar con:
# blender --background --factory-startup --python-exit-code 1 --python build.py
import bpy, bmesh, math, os

scene = bpy.context.scene
scene.frame_start, scene.frame_end = 1, 120
scene.render.fps = 30
scene.render.resolution_x, scene.render.resolution_y = 1920, 1080
scene.render.engine = 'BLENDER_EEVEE_NEXT'
scene.render.filepath = "//renders/frame_"

# limpiar colección propia
col = bpy.data.collections.get("MS_Main") or bpy.data.collections.new("MS_Main")
if col.name not in scene.collection.children:
    scene.collection.children.link(col)

def add_sphere(name, loc, radius, mat):
    """Esfera con API de datos: sin operadores, sin dependencia de contexto."""
    mesh = bpy.data.meshes.new(name)
    bm = bmesh.new()
    bmesh.ops.create_uvsphere(bm, u_segments=32, v_segments=16, radius=radius)
    bm.to_mesh(mesh)
    bm.free()
    obj = bpy.data.objects.new(name, mesh)
    obj.location = loc
    col.objects.link(obj)
    obj.data.materials.append(mat)
    return obj

mat = bpy.data.materials.new("MS_Emission")
mat.use_nodes = True
bsdf = mat.node_tree.nodes["Principled BSDF"]
bsdf.inputs["Base Color"].default_value = (0.05, 0.6, 0.55, 1)
bsdf.inputs["Emission Color"].default_value = (0.1, 0.9, 0.8, 1)
bsdf.inputs["Emission Strength"].default_value = 3.0
bsdf.inputs["Roughness"].default_value = 0.3

core = add_sphere("MS_Core", (0, 0, 1), 0.8, mat)
core.keyframe_insert("scale", frame=1)
core.scale = (1.15, 1.15, 1.15)
core.keyframe_insert("scale", frame=40)
core.scale = (1.0, 1.0, 1.0)
core.keyframe_insert("scale", frame=90)

# cámara
cam_data = bpy.data.cameras.new("MS_Cam")
cam = bpy.data.objects.new("MS_Cam", cam_data)
col.objects.link(cam)
scene.camera = cam
cam.location = (6, -6, 3)
cam.rotation_euler = (math.radians(75), 0, math.radians(45))

# guardar
os.makedirs(bpy.path.abspath("//renders"), exist_ok=True)
bpy.ops.wm.save_as_mainfile(filepath=bpy.path.abspath("//scene.blend"))
print("BUILD OK", len(col.objects), "objects")

Más en references/BLENDER-RECIPES.md: rigs de órbita, easing, dispersión con Geometry Nodes, partículas, texto, pases alfa, scripts para granja de render y comandos de codificación.

13. Blender MCP (conveniencia opcional)

Los scripts en modo fondo son la ruta de producción: reproducibles, diferenciables, depurables, compatibles con CI. MCP es útil para inspección interactiva de escenas y ajustes en vivo en una sesión ya abierta. Es una integración de terceros, no un componente de Blender.

Si el usuario lo desea: revisa el repositorio y la licencia, verifica la compatibilidad con la versión instalada de Blender, comprende que otorga ejecución arbitraria de Python dentro de Blender, mantenlo vinculado a loopback y nunca lo expongas a una red no confiable. El nombre del paquete actual es mcp-for-blender; sigue las instrucciones de configuración actuales del repositorio en lugar de fragmentos antiguos de blender-mcp. No lo conviertas en una dependencia de ningún proyecto entregado.

14. Entregables

Un trabajo de Blender está terminado cuando tienes:

1. output/final.mp4 (o el formato solicitado), validado con ffprobe.
2. blender/scripts/*.py — el código fuente de construcción.
3. scene.blend — el proyecto editable, activos empaquetados o relativos.
4. renders/ secuencia de imágenes (o master documentado) conservada cuando sea útil.
5. README.md — versión exacta de Blender, instalación, construcción, previsualización, render final y comandos de revisión.
6. Un informe breve: herramientas, resolución, FPS, duración, recuento de fotogramas, qué se verificó visualmente.

Nunca entregues solo el MP4 cuando el usuario pidió una animación que pueda querer cambiar.