Guía para organizar colecciones y renderizar con la API Python de Blender

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

A medida que las escenas de Blender crecen, puede resultar difícil mantener organizados los modelos arquitectónicos, el mobiliario, la iluminación y los elementos del entorno, así como controlar qué partes están visibles o se incluyen en la salida. La estructura Collection de la API Python de Blender permite agrupar objetos y organizarlos jerárquicamente mediante subcolecciones. En esta guía veremos paso a paso cómo crear una colección y vincularla a la escena, ajustar su visibilidad, conocer las opciones de Line Art y utilizar los operadores de render.

Los ejemplos se basan en las propiedades y operaciones enumeradas en la documentación actual de la API de Blender. Como la documentación no indica un número concreto de versión de Blender, conviene probar los ejemplos en el entorno de trabajo antes de utilizarlos. Adapta los nombres de las colecciones y la organización de la escena que aparecen en el código a cada proyecto.

Requisitos

• Se necesita Blender y acceso a la API Python. Las fuentes son la documentación actual de la API de Blender; no indican un número de versión concreto.

• Las fuentes no mencionan requisitos de cuenta ni de suscripción. La documentación tampoco ofrece información sobre los requisitos de hardware para usar Blender ni sobre la duración del render.

• Los ejemplos operan sobre las colecciones y los objetos de la escena. Antes de aplicarlos, es recomendable guardar una copia de los archivos importantes del proyecto y probar el código en una escena pequeña.

Paso a paso: organizar la escena con colecciones

1. Crea una colección y vincúlala a la escena

El código siguiente crea una colección y la vincula a la colección principal de la escena activa. La API de Blender documenta las operaciones para crear colecciones y vincular colecciones secundarias. “Mobilya” es un nombre de ejemplo que podría usarse para agrupar el mobiliario de un proyecto de interiores.

collection = bpy.data.collections.new("Mobilya")
bpy.context.scene.collection.children.link(collection)

Crear la colección no significa que los objetos de la escena se trasladen automáticamente a ella. La pertenencia de los objetos debe organizarse por separado. La propiedad objects de una colección hace referencia a los objetos que pertenecen directamente a ella, mientras que all_objects incluye también los objetos de las subcolecciones. Conocer esta diferencia ayuda a evaluar correctamente el contenido total de escenas con colecciones principales y grupos secundarios.

2. Crea una jerarquía con subcolecciones

En un archivo de visualización arquitectónica, por ejemplo, se pueden crear grupos como mobiliario e iluminación dentro de una colección principal llamada “Interior”. La documentación de la API de Blender define children como las subcolecciones directas y children_recursive como la propiedad que enumera todas las subcolecciones. Al examinar la jerarquía, determina qué nivel de contenido necesitas.

La propiedad all_objects incluye los objetos de la colección y de sus subcolecciones, y es de solo lectura. Por eso, para organizar el contenido hay que operar sobre los objetos y las subcolecciones, no a través de esta propiedad. Además, la documentación señala que crear la lista children_recursive lleva un tiempo que depende del número de subcolecciones; tenlo en cuenta al usarla en una jerarquía con muchos niveles.

3. Gestiona por separado la visibilidad en la vista 3D y en el render

hide_viewport desactiva la colección en la vista 3D, mientras que hide_render la desactiva en el render. Una opción no sustituye a la otra. Por ejemplo, para mantener un grupo oculto en la vista de trabajo, pero visible en el render, se pueden asignar valores independientes como en el siguiente código:

collection.hide_viewport = True
collection.hide_render = False

En este ejemplo, la colección se oculta en la vista 3D, pero no se desactiva para el render. Si necesitas otro comportamiento, cambia los valores según corresponda. No basta con comprobar el resultado en un solo lugar: revisa por separado la vista 3D y la salida del render.

4. Selecciona el comportamiento de Line Art en el nivel de colección

La documentación de Blender incluye opciones para determinar cómo se tratan las colecciones en el cálculo de Line Art. Entre los modos están INCLUDE, OCCLUSION_ONLY, EXCLUDE, INTERSECTION_ONLY, NO_INTERSECTION y FORCE_INTERSECTION. Estas opciones corresponden a distintos comportamientos, como generar líneas a partir de la colección, crear únicamente oclusión, excluirla del cálculo o gestionar las líneas de intersección.

En el ejemplo siguiente se selecciona el modo que genera únicamente oclusión para la colección:

collection.lineart_usage = 'OCCLUSION_ONLY'

Si necesitas controles adicionales para las intersecciones, la documentación también incluye las propiedades lineart_use_intersection_mask y use_lineart_intersection_priority. La prioridad de intersección se puede definir con lineart_intersection_priority; la documentación de la API indica que su valor puede estar entre 0 y 255. Considera estas opciones si la escena utiliza el cálculo de Line Art y tienes claro qué comportamiento necesitas.

Capturar la vista activa y renderizar

El operador bpy.ops.render.opengl está documentado para capturar la imagen de la vista 3D activa. La opción write_still permite guardar la imagen en la ruta de salida cuando la animación está desactivada:

bpy.ops.render.opengl(write_still=True)

Esta operación no equivale al render general de la escena. El operador de la API bpy.ops.render.render se puede utilizar para iniciar el render de la escena. El ejemplo incluye la opción para guardar una imagen fija:

bpy.ops.render.render(write_still=True)

Entre los parámetros documentados del operador de render se encuentran la animación, el uso de la vista 3D, la selección de escena y los fotogramas inicial y final de la animación. Las opciones de intervalo de fotogramas están destinadas al render de animaciones. Aunque la página de la API describe estas operaciones y sus parámetros, no especifica todos los ajustes de salida necesarios para cada proyecto; revisa la configuración de la escena antes de renderizar.

Errores habituales

• Confundir los ajustes de la vista 3D y del render: hide_viewport y hide_render son propiedades distintas. Comprueba la visibilidad deseada en ambos casos.

• Pasar por alto las subcolecciones: objects muestra los miembros directos; para tener en cuenta también las subcolecciones, considera el alcance de la propiedad all_objects.

• Elegir al azar el modo de Line Art: las opciones definen distintos comportamientos de líneas e intersecciones. Elige según el resultado que busques y compruébalo en una escena de prueba pequeña.

• Confundir la captura de la vista 3D con el render de la escena: bpy.ops.render.opengl captura la vista activa; para el render general hay un operador independiente.

• Dar por hecho comportamientos que no aparecen en la documentación de la API: las fuentes no explican ajustes específicos de proyecto, velocidad de render ni requisitos de hardware. Prueba estos aspectos en tu propia escena y entorno de trabajo.

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

Los estudios de arquitectura y los equipos de visualización pueden agrupar modelos, mobiliario, iluminación y elementos del entorno en colecciones para organizar la jerarquía de la escena con mayor claridad. Gestionar por separado la visibilidad en la vista 3D y en el render permite ocultar durante el trabajo los elementos que no se necesitan y, al mismo tiempo, mantener un contenido distinto en la salida. En presentaciones basadas en dibujos que utilizan Line Art, los modos a nivel de colección pueden ayudar a definir cómo participan los grupos en el cálculo de líneas.

Esta documentación de la API no ofrece garantías de compatibilidad con un complemento concreto, un nivel de hardware o una versión de Blender. Antes de automatizar archivos compartidos en un estudio, prueba el código en el entorno de Blender que se utiliza y en un archivo de prueba pequeño. Ten también en cuenta la licencia CC BY-SA 4.0 de la documentación fuente, aplicable al uso de su contenido.

Próximos pasos

Primero, crea una jerarquía de colecciones en una escena de prueba pequeña y compara los resultados al cambiar por separado la visibilidad en la vista 3D y en el render. Después, si utilizas Line Art, elige el modo adecuado y revisa las líneas de la salida. Comprueba los ajustes de salida de la escena antes de pasar a los operadores de render. La documentación de la API también enumera operaciones para crear y limpiar la caché de texturas de Cycles; son operadores independientes de la organización de colecciones y del flujo básico de render.

Fuente y licencia

Esta guía adapta al turco la documentación de la API Python de Blender sobre Collection y los operadores de render. Ambas fuentes se ofrecen bajo la licencia CC BY-SA 4.0.