Guía para organizar colecciones y View Layers con Python en Blender

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

Las escenas de visualización arquitectónica pueden reunir la estructura del edificio, elementos interiores, mobiliario y muchos otros objetos. A medida que crece el contenido, es importante agrupar los elementos de la escena y gestionar distintas vistas de trabajo. La API de Python de Blender permite vincular objetos a colecciones y usar View Layers para controlar qué partes de la jerarquía de colecciones están activas.

En esta guía aprenderás a crear una colección con Python, vincularla a la escena, añadirle el objeto activo y excluirla del View Layer activo. También veremos las diferencias entre la configuración de visibilidad de los objetos y la organización mediante colecciones y View Layers. Los ejemplos se basan en la documentación oficial de la API de Python de Blender y en las descripciones de la API de escenas y objetos publicadas para Blender 2.80.

Requisitos

Ejecuta los ejemplos en un entorno de Blender que permita usar su API de Python. El código accede a la escena activa mediante bpy y, cuando corresponde, al objeto activo. El primer ejemplo crea una colección directamente con bpy.data.collections.new y la vincula a la colección raíz de la escena; no requiere que haya una colección activa. El ejemplo independiente que vincula el objeto activo a la nueva colección omite ese paso si no hay ningún objeto activo.

La documentación no especifica una versión concreta de Blender, una cuenta de usuario ni requisitos de software adicionales. Por eso, antes de usar el código, comprueba cómo se comporta la API en la versión de Blender instalada. La documentación para desarrolladores de Blender 2.80 explica los cambios de la API de la época de 2.8x, mientras que las páginas actuales de la API documentan las propiedades de Scene y Object. Ten en cuenta estas diferencias si trabajas con scripts de versiones anteriores.

Cómo organizar colecciones paso a paso

1. Distingue las funciones de las colecciones y los View Layers

En la época de Blender 2.7x, las escenas se organizaban con 20 capas fijas. Con los cambios de la API de 2.8x, la organización de los objetos pasó a las colecciones, mientras que el control de la jerarquía de colecciones en cuanto a visibilidad y render pasó a los View Layers. Por eso, conviene no confundir las propiedades de las capas de escena que aparecen en scripts antiguos con el nuevo sistema de colecciones.

Las colecciones agrupan objetos y otras colecciones de forma jerárquica. Los View Layers determinan qué partes de esa estructura están activas. Crear una colección no mueve automáticamente los objetos a ella; hay que vincularlos por separado.

2. Añade una colección nueva a la escena

El siguiente ejemplo vincula una colección nueva llamada Mimari_Govde debajo de la colección raíz de la escena activa. El código crea la colección y después la añade a la jerarquía de la escena:

import bpy

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

bpy.data.collections.new crea la colección nueva. scene.collection.children.link la vincula a la colección raíz de la escena. Este ejemplo no utiliza un objeto activo ni requiere una colección activa previamente. Si ya existe una colección con el mismo nombre en el archivo, revisa la organización actual de la escena antes de volver a ejecutar el script.

3. Vincula el objeto activo a la nueva colección

Una vez creada la colección, puedes usar el siguiente ejemplo para vincularle el objeto activo:

obj = bpy.context.object

if obj is not None:
    collection.objects.link(obj)

Si hay un objeto activo, se añade el vínculo a la colección; si no lo hay, no se ejecuta la operación dentro de la condición. Este vínculo no duplica el objeto. Según la documentación para desarrolladores de Blender, un mismo objeto puede formar parte de varias colecciones y sigue siendo un único objeto.

En escenas arquitectónicas, esta distinción ayuda a crear una estructura de agrupación sin duplicar los datos de los objetos. Sin embargo, el código del ejemplo no elimina el objeto de las colecciones a las que ya pertenece; solo lo vincula también a la nueva colección. Por eso, revisa por separado los demás vínculos de la escena.

4. Excluye la colección del View Layer activo

Si la colección está directamente debajo de la colección raíz de la escena, puedes excluirla mediante el acceso correspondiente a LayerCollection en el View Layer activo:

bpy.context.view_layer.layer_collection.children["Mimari_Govde"].exclude = True

Esta línea excluye la colección Mimari_Govde del View Layer activo. Para volver a activarla, cambia el valor de exclude a False. El código presupone que la colección es hija directa de la jerarquía del View Layer. Si está dentro de otra colección, tendrás que acceder a ella desde la ubicación correcta de la jerarquía.

Los View Layers controlan qué partes de la organización de colecciones están activas. Esto no es lo mismo que cambiar individualmente las propiedades de visibilidad de cada objeto. Al evaluar el resultado, ten en cuenta si los objetos pertenecen también a otras colecciones y cuál es la estructura de View Layers que utilizas.

5. Gestiona la visibilidad de los objetos por separado

Si necesitas controlar un objeto concreto en lugar de la visibilidad de una colección, puedes usar las propiedades del objeto. hide_viewport afecta a la visibilidad del objeto en el viewport, mientras que hide_render afecta a su visibilidad en el render. Por ejemplo, para ocultar el objeto activo en el render:

obj = bpy.context.object

if obj is not None:
    obj.hide_render = True

En este caso solo se modifica la visibilidad en el render. La propiedad independiente documentada para ocultar el objeto en el viewport es hide_viewport. Elige la propiedad adecuada según el resultado que busques; no uses una en lugar de la otra.

Errores frecuentes

Suponer que los objetos se añaden automáticamente al crear una colección: Crear una colección y vincular un objeto son operaciones diferentes. Añade por separado a la colección los objetos correspondientes.

Usar los métodos antiguos de capas de escena con la API nueva: Con 2.8x cambió la organización de colecciones y View Layers. No apliques usos como object.layers de scripts antiguos sin compararlos con la estructura actual de colecciones.

Confundir el vínculo a una colección con la copia de un objeto: Un mismo objeto puede estar en varias colecciones. Vincularlo a una colección no crea un objeto nuevo ni una copia de la geometría.

Buscar en el nivel incorrecto de la jerarquía de View Layers: La línea de exclusión del ejemplo presupone que la colección es hija directa de la capa activa. Para las subcolecciones, hay que ajustar la ruta de acceso a la jerarquía real de la escena.

Suponer que la visibilidad en el viewport y en el render se controla con el mismo ajuste: hide_viewport y hide_render son propiedades distintas. Determina si el problema está en el viewport o en el resultado del render y modifica la propiedad correspondiente.

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

Las colecciones pueden servir para agrupar la estructura del edificio, el mobiliario u otros elementos de la escena que deban controlarse en conjunto. La organización de View Layers permite gestionar qué partes de esa jerarquía de colecciones están activas. Esta estructura puede ayudar a mantener ordenado el contenido de la escena y a gestionar la visibilidad por grupos, especialmente en proyectos con muchos componentes.

Este enfoque puede ser útil para despachos de arquitectura, interioristas y artistas de archviz que quieran establecer una organización repetible mediante Python en escenas de Blender. Sin embargo, las fuentes no prometen compatibilidad con un motor de render concreto, mejoras de rendimiento ni ventajas de hardware. En los proyectos, conviene comprobar la versión de Blender, la jerarquía real de las colecciones y el flujo de trabajo previsto para compartir el archivo con otras personas.

Próximos pasos

Primero, ejecuta el ejemplo de creación de colecciones en una copia del archivo. Después, prueba el paso de vinculación con un objeto activo y comprueba que un objeto puede pertenecer a varias colecciones. Antes de aplicar el código de exclusión de View Layer, confirma dónde se encuentra la colección dentro de la capa activa.

Luego, prueba por separado las propiedades hide_viewport y hide_render para determinar qué nivel de visibilidad responde a tus necesidades. Si vas a usar los scripts en distintas versiones de Blender, consulta la documentación de la API de la versión en la que ejecutarás el código y prueba los cambios antes de aplicarlos al archivo del proyecto.

Fuentes y licencia

“Blender 2.80: Scene and Object API” (K2), de la documentación para desarrolladores de Blender, explica los cambios en las colecciones y los View Layers. La documentación de la API de Python de Blender para Scene (K1) y Object (K4) está bajo la licencia CC BY-SA 4.0. Esta guía adapta al español la información técnica de esas fuentes y la explica con ejemplos originales.