Guía de la API Python de Blender: automatiza objetos y operadores de escena

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

La API Python de Blender permite definir mediante código algunas operaciones que se realizan en una escena y volver a aplicarlas. En esta guía verás cómo crear un bloque de datos de luz y un objeto que lo utiliza, y cómo vincular y posicionar el objeto en la colección activa. También abordaremos cómo llamar operadores mediante bpy.ops, usar poll() antes de invocarlos y evaluar el estado que devuelven.

Los ejemplos se basan en las explicaciones de la documentación oficial de la API de Blender. El objetivo no es ofrecer un sistema de automatización arquitectónica listo para usar, sino presentar de forma clara los componentes básicos de los scripts que operan sobre una escena. Antes de usar los fragmentos de código en tus propios archivos, revisa qué modifican y pruébalos en una escena de prueba pequeña.

Requisitos y notas sobre la versión

Estos ejemplos requieren trabajar con la API Python de Blender. Como la documentación no especifica un número concreto de versión de Blender, aquí tampoco se indica uno como referencia de compatibilidad. Al ejecutar el código, consulta la documentación de la API correspondiente a la instalación de Blender que estés utilizando. Las fuentes no detallan requisitos de cuenta, costos ni condiciones especiales de hardware.

El código utiliza el módulo bpy. Los nombres de API y los parámetros que aparecen en los ejemplos se basan en los usos descritos en la documentación oficial de Blender. En particular, los operadores pueden depender no solo de sus parámetros, sino también del contexto en el que se ejecutan. Por eso, antes de llamar a un operador, conviene revisar el objeto activo de la escena y las condiciones pertinentes para la operación.

Paso a paso: añade un objeto de luz a la escena

El ejemplo siguiente muestra el flujo para crear una luz que aparece en la documentación oficial de Blender. El bloque de datos de luz y el objeto que forma parte de la escena se preparan por separado; después, el objeto se añade a la colección de la capa de vista activa.

import bpy
view_layer = bpy.context.view_layer
# Create new light data-block.
light_data = bpy.data.lights.new(name="New Light", type='POINT')
# Create new object with our light data-block.
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)
# Link light object to the active collection of current view layer,
# so it'll appear in the current scene.
view_layer.active_layer_collection.collection.objects.link(light_object)
# Place light to a specified location.
light_object.location = (5.0, 5.0, 5.0)
# And finally select it and make it active.
light_object.select_set(True)
view_layer.objects.active = light_object

En la primera parte del flujo, se obtiene la capa de vista activa mediante bpy.context.view_layer. En las líneas siguientes se crea un bloque de datos de luz de tipo POINT y un objeto que utiliza esos datos. Una vez vinculado el objeto a la colección activa, se asigna su posición; por último, se selecciona y se establece como objeto activo. Las coordenadas corresponden al ejemplo de la documentación y no representan una ubicación recomendada para una escena arquitectónica o de interiores concreta.

Al seguir estos pasos, es útil no confundir la creación del bloque de datos con la incorporación del objeto a la escena. Vincular el objeto a una colección es el paso que se utiliza en el ejemplo para que forme parte de la escena actual. Seleccionar el objeto al final del código y establecerlo como activo determina con qué objeto se relacionarán las operaciones posteriores.

Llamar operadores y comprobar si pueden ejecutarse

Según la documentación de Blender, bpy.ops se utiliza para llamar operadores escritos en C++, Python o como macros. Las propiedades del operador se pasan mediante palabras clave, es decir, parámetros con nombre. Por ejemplo, la siguiente llamada envía dos propiedades al operador mesh.subdivide:

import bpy
bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)

Esto no significa que la llamada vaya a funcionar en las mismas condiciones en todas las escenas. Si un operador se invoca en un contexto inadecuado, puede producirse un RuntimeError. Uno de los métodos recomendados en la documentación es comprobar las condiciones actuales con poll() antes de ejecutar el operador. El ejemplo para cambiar de modo es el siguiente:

import bpy
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

Si poll() devuelve un resultado positivo, se llama al operador para cambiar de modo. Esta comprobación ayuda a evaluar si el operador puede ejecutarse en el contexto actual; no debe interpretarse como una garantía de que se eliminen todas las posibilidades de error. La documentación también indica que, si hay informes de error, puede producirse un RuntimeError después de que el operador haya terminado.

También hay que tener en cuenta lo que devuelven los operadores. En lugar de un único valor, como cabría esperar, devuelven un conjunto de estados. La documentación describe FINISHED y CANCELLED como estados habituales. CANCELLED puede indicar que la operación se canceló y que no se realizaron cambios. Por eso, en un script no basta con confiar en que la línea del operador se haya ejecutado: también hay que evaluar el estado devuelto.

Cambiar el contexto y sus implicaciones para los flujos de trabajo arquitectónicos

La documentación explica el uso de temp_override para cambiar el contexto que ve el operador. Este método permite hacer que el operador trabaje con datos concretos en lugar de los datos seleccionados o activos. Por ejemplo, entre los miembros del contexto puede haber un objeto activo u objetos seleccionados. La fuente indica que conviene basarse en una copia del contexto actual; de lo contrario, habría que obtener por separado la información que necesita el operador.

Lo importante es no crear un contexto temporal cambiando una sola variable y pasar por alto otros requisitos. Al usar temp_override, evalúa en conjunto los miembros del contexto que puede necesitar el operador. Partir del contexto actual ofrece un punto de partida más controlado que intentar recopilar desde cero todos los datos necesarios.

Para arquitectos, interioristas y artistas de visualización, estos fundamentos de la API muestran cómo describir mediante código operaciones repetitivas de la escena. Separar los pasos de creación del objeto, vinculación a una colección y asignación de posición puede facilitar el seguimiento de los cambios que realiza un script. Sin embargo, las fuentes no afirman que estos ejemplos automaticen un flujo de trabajo arquitectónico concreto ni que mejoren el rendimiento.

Al utilizar scripts en una oficina o en un entorno educativo, comprueba la colección de destino y el objeto activo, y prueba primero los cambios en los datos de escena en una copia del archivo. Si el equipo utiliza distintas versiones de Blender, valida el código por separado en cada instalación. Como la documentación no establece condiciones precisas de hardware, costos o compatibilidad entre versiones, es mejor probar en la instalación disponible que hacer suposiciones sobre estos aspectos.

Errores frecuentes y próximos pasos

El primer error es suponer que las llamadas a bpy.ops funcionan independientemente del contexto. Antes de usar un operador, comprueba qué datos están activos y, cuando corresponda, utiliza poll() para verificar si puede ejecutarse. El segundo error es dar por sentado que la llamada siempre tendrá éxito. Revisa estados como FINISHED y CANCELLED, y ten en cuenta que los informes de error pueden generar un RuntimeError.

Al crear un objeto, sigue los pasos de preparación del bloque de datos, creación del objeto, vinculación a la colección, asignación de posición y activación del objeto. Así será más fácil identificar en qué etapa surge el problema si no obtienes el resultado esperado. Al probar un operador nuevo, revisa sus parámetros y las explicaciones sobre el contexto en la documentación oficial de la API; después, valida los resultados en una escena de prueba pequeña.

Como siguiente paso, puedes revisar ejemplos de temp_override y probar cómo se pasan los miembros del contexto. Antes de usar este método, determina qué información del contexto necesita el operador. Ejecutar los scripts que realizan cambios amplios en la escena en una copia del archivo antes de probarlos en el proyecto real permite revisar los resultados de forma más controlada.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de las explicaciones y los ejemplos de la documentación de la API bpy.ops y bpy.types.Object de Blender. Ambas fuentes están bajo la licencia CC BY-SA 4.0.