Render desde la línea de comandos y automatización con Python en Blender 5.2 LTS

¿Qué aprenderás en esta guía?

No es necesario hacer todo en Blender desde la interfaz. La línea de comandos permite renderizar en segundo plano e iniciar una tarea repetible con un comando. La API de Python de Blender, por su parte, permite acceder a los objetos y otros datos del archivo abierto y generar informes sencillos.

En esta guía usaremos las opciones de render de la documentación de la línea de comandos de Blender 5.2 LTS para obtener un fotograma y una animación. Después, crearemos un informe sencillo de la escena con el entorno de Python integrado en Blender y ejecutaremos el script desde la línea de comandos. Los ejemplos no presuponen la configuración de un archivo de escena real ni la compatibilidad del hardware; ajusta los comandos a tus propios archivos y necesidades de render.

Requisitos

• Blender debe estar instalado. Los ejemplos de comandos se basan en la documentación de la línea de comandos de Blender 5.2 LTS.

• Necesitas un archivo .blend para renderizar y acceso a la ubicación donde se encuentra.

• Para trabajar desde la línea de comandos, necesitas el terminal del sistema operativo. Para el ejemplo de Python, puedes usar el espacio de trabajo Scripting de Blender, el editor de texto o Python Console.

• La documentación de la línea de comandos no indica que se necesite una cuenta de usuario. La documentación de la API de Python de Blender señala que, en general, la API es estable, aunque algunas áreas siguen en desarrollo.

Paso a paso: renderizar en segundo plano

1. Renderiza un solo fotograma

-b o --background ejecuta Blender sin la interfaz de usuario. Con -f se indica el número del fotograma que se renderizará; con -o, la ruta de salida y el nombre del archivo; y con -F, el formato de salida. El siguiente ejemplo renderiza como PNG el fotograma 20 del archivo sahne.blend:

blender -b sahne.blend -o //render_ -F PNG -f 20

La ruta de salida que empieza por // indica una ubicación relativa al archivo .blend. Si el nombre del archivo no contiene #, Blender añade automáticamente un sufijo numérico para el fotograma. Si se generan varios fotogramas, es posible definir la posición del número de fotograma y el formato con ceros a la izquierda mediante caracteres # en el nombre del archivo.

2. Renderiza la animación dentro del rango de fotogramas de la escena

-a o --render-anim renderiza la animación entre los fotogramas inicial y final; ambos extremos están incluidos en el rango. En el siguiente ejemplo se elige una ruta relativa y el formato PNG:

blender -b sahne.blend -o //animasyon_## -F PNG -a

Puedes usar las opciones -s y -e para indicar por separado los fotogramas inicial y final. -j determina cuántos fotogramas se avanzan entre los que se renderizan. Al usar estas opciones, comprueba el rango de la escena y el patrón de muestreo de fotogramas deseado; renderizar solo los fotogramas necesarios facilita el control del directorio de salida.

-x o --use-extension determina si se añade la extensión del archivo a la salida. Para solicitar explícitamente que se añada, puedes usar -x 1, como en el ejemplo de la documentación. JPEG, PNG, TIFF y HDR están entre los formatos enumerados; la disponibilidad de algunos formatos puede depender de cómo se haya compilado Blender.

3. Elige el motor de render, los hilos y el dispositivo de Cycles

Puedes indicar el motor de render con -E; -E help muestra los motores disponibles. -t establece el número de hilos para el render y otras operaciones. Si el valor es 0, se utiliza el número de procesadores del sistema.

La opción del dispositivo de Cycles se separa de las opciones normales de la línea de comandos de Blender mediante dos guiones. La documentación enumera CPU, CUDA, OPTIX, HIP, ONEAPI y METAL. No des por hecho que estas opciones funcionarán en el equipo de destino: comprueba la selección en el sistema y la instalación de Blender que vayas a utilizar.

blender -b sahne.blend -f 20 -- --cycles-device OPTIX --cycles-print-stats

Este ejemplo selecciona OPTIX para Cycles y solicita que se registren estadísticas de uso de memoria y tiempo de render. Añadir +CPU al nombre del dispositivo GPU indica que se usarán conjuntamente la GPU y la CPU. Si el motor de render no es Cycles, consulta las opciones propias de ese motor en lugar de añadir una opción de dispositivo exclusiva de Cycles.

4. Lee los datos de la escena con Python en Blender

La API de Python de Blender permite trabajar con los datos de la escena y los objetos a los que se accede desde la interfaz. Para empezar, basta con un pequeño script que imprima los nombres de los objetos de la escena:

import bpy

for obj in bpy.data.objects:
    print(obj.name)

Puedes ejecutar este script en Blender desde el espacio de trabajo Scripting: abre un nuevo bloque de texto en el editor de texto y ejecútalo con Run Script después de pegar el código. Python Console también permite probar comandos breves e inspeccionar la API con autocompletado.

El mismo archivo de script puede ejecutarse desde la línea de comandos mediante la opción --python:

blender -b sahne.blend --python rapor.py

Este método permite ejecutar de forma repetible informes que examinan los datos de un archivo sin abrir la interfaz. La documentación también incluye la opción --python-exit-code, que permite que un script ejecutado desde la línea de comandos finalice con un código de salida específico si se produce un error de Python. Configurar el código de salida puede ayudar a detectar ejecuciones fallidas al integrar el script en un flujo de trabajo automatizado.

Errores frecuentes

• Interpretar mal la ruta de salida: la ruta relativa // está vinculada al archivo .blend. Buscar la salida suponiendo que el archivo está en otra carpeta puede dar la impresión de que el render ha desaparecido.

• Confundir el número o el rango de fotogramas: -f renderiza un solo fotograma; -a procesa la animación entre los fotogramas inicial y final de la escena. Comprueba los valores de -s y -e para el rango deseado.

• Escribir la opción de Cycles en el lugar equivocado: opciones como --cycles-device deben ir después del separador -- en la línea de comandos.

• Seleccionar un dispositivo que no está disponible en el hardware: que la documentación enumere un dispositivo no significa que todas las instalaciones lo admitan. Primero, haz una prueba de render breve en el equipo de destino.

• Buscar en el lugar equivocado la salida del script de Python: según la documentación de la API de Blender, la salida de algunos ejemplos se envía al terminal. Si el script termina pero no ves la salida, comprueba el terminal desde el que se ejecutó Blender.

Efectos en los flujos de trabajo de arquitectura y visualización

El render en segundo plano puede ser útil para equipos de visualización que quieran iniciar mediante comandos renders repetidos de fotogramas o animaciones. Los scripts de Python también ayudan a inspeccionar los datos de la escena y generar informes sencillos. Este enfoque no sustituye las decisiones de modelado ni de diseño; estandariza algunas tareas del proceso de producción.

Antes de empezar, verifica la versión de Blender, el motor de render, el formato de salida y la compatibilidad del dispositivo de Cycles con el equipo de destino. Las opciones de la línea de comandos facilitan iniciar un render, pero por sí solas no garantizan que la escena produzca el resultado correcto. Probar primero con un solo fotograma la ruta, el formato y el dispositivo, y pasar después a la animación, es un método más controlado. La documentación no explica los requisitos de licencia ni de cuenta; en un entorno de equipo, conviene comprobar por separado las condiciones de instalación y uso.

Próximos pasos

Después de verificar el ejemplo de un solo fotograma con tu archivo, pasa a la opción de animación y al nombrado de los archivos de salida. Para empezar con Python, utiliza un script de informe de solo lectura; listar los nombres de los objetos es una forma sencilla de comprobar que se puede acceder a la escena. Después, consulta las opciones de los comandos y la referencia de la API para añadir las tareas que necesites. La documentación de la API de Python advierte que el contexto puede variar según el área en la que se use y que algunos operadores requieren un contexto válido. Por eso es importante probar el script con la versión de Blender y el contexto de escena en los que se ejecutará.

Fuentes y licencia

La guía se basa en la página “Command Line Arguments” de Blender Manual y en las páginas “Quickstart” y “API Overview” de la API de Python de Blender. Las tres fuentes tienen licencia CC BY-SA 4.0; el contenido se ha adaptado y vuelto a explicar en español. Los comandos de ejemplo y el breve script de Python se han preparado para esta guía a partir de las opciones y el uso de la API que documentan las fuentes.