En resumen
- La Consola de Python sirve para probar comandos breves y explorar la API con ayuda del autocompletado.
- bpy.data permite acceder a los datos de objetos, escenas y materiales del archivo de Blender abierto.
- Es posible añadir propiedades personalizadas a los objetos y guardarlas junto con el archivo blend.
- Un operador puede registrarse en Blender y ejecutarse desde el menú de búsqueda.
¿Qué aprenderás en esta guía?
La API de Python de Blender permite acceder mediante Python a muchos de los datos que se pueden modificar desde la interfaz y editarlos. En modelado y visualización arquitectónica, esto puede servir para inspeccionar los elementos de una escena, añadir información del proyecto a los objetos o convertir tareas repetitivas en herramientas. En esta guía, primero leerás los datos de la escena, después añadirás una propiedad personalizada al objeto activo y, por último, crearás un operador sencillo.
Los ejemplos se basan en los métodos de la guía oficial de inicio rápido de la API de Python de Blender. Aunque la API se describe, en general, como estable, el documento señala que algunas partes siguen en desarrollo. Por eso, antes de utilizar una función en archivos de producción, conviene probarla en una escena de prueba pequeña.
Requisitos
Blender debe estar instalado. Como el documento de referencia no indica un número de versión concreto de Blender, aquí no especificamos una cifra de compatibilidad.
No es necesario instalar Python por separado: los ejemplos se ejecutan en la Consola de Python o el Editor de texto de Blender.
Las fuentes no indican requisitos de cuenta ni de licencia de pago.
Para explorar la API, puede ser útil activar las opciones Developer Extras y Python Tooltips en las preferencias de Blender. Las sugerencias de los botones pueden ayudar a encontrar atributos de Python y nombres de operadores relacionados.
La Consola de Python sirve para comandos breves y pruebas. Para editar y guardar scripts de varias líneas, resulta más práctico utilizar el espacio de trabajo Scripting y el Editor de texto de Blender. Puedes acceder a este espacio desde las pestañas de la barra superior.
Paso a paso: acceso a los datos de escena y primera herramienta
1. Enumera los objetos de la escena con Python
Abre el espacio de trabajo Scripting y cambia a la Consola de Python. Como ofrece autocompletado, la consola también resulta útil para explorar los nombres de datos y propiedades dentro de bpy. Ejecuta este código para imprimir, uno por uno, los objetos de la escena abierta:
import bpy
for ob in bpy.context.scene.objects:
print(ob)Este ejemplo recorre la colección de objetos de la escena actual y envía cada objeto a la salida de la consola. En un archivo arquitectónico, es un punto de partida básico para comprobar rápidamente qué objetos hay en la escena. Más adelante, puedes añadir al bucle operaciones para inspeccionar nombres, datos u otros atributos mediante los métodos de acceso documentados en la fuente.
2. Encuentra los datos a través de bpy.data
Se accede a los bloques de datos del archivo de Blender mediante bpy.data. El documento presenta colecciones como objetos, escenas y materiales. Es posible acceder a un elemento de una colección por su nombre:
bpy.data.objects["Cube"]También se puede acceder a la misma colección mediante un índice numérico, pero el documento advierte que el índice de un elemento puede cambiar durante la ejecución. Por eso, al buscar un elemento concreto de la escena, acceder a él por su nombre resulta más claro que dar por sentado que el índice es fijo. Ten en cuenta también que el nombre puede ser distinto en tu archivo: Cube es únicamente el nombre del objeto de ejemplo utilizado en el documento.
3. Añade información personalizada al objeto activo
Las propiedades personalizadas de la API de Python permiten añadir información a un objeto, una escena o una colección. El siguiente ejemplo guarda un valor de texto en el objeto activo, si existe:
import bpy
obj = bpy.context.object
if obj is not None:
obj["project_note"] = "interior study"En este caso, bpy.context.object devuelve el objeto activo según el contexto. La condición evita que se realice ninguna operación si no hay un objeto activo. Según el documento de referencia, este tipo de propiedades personalizadas se guarda en el archivo blend y se conserva al duplicar los objetos. Por tanto, puede servir para añadir una nota del proyecto u otra información sencilla definida por el equipo. Si eliges nombres coherentes para las propiedades, te resultará más fácil localizar los datos cuando trabajes con varios scripts y archivos.
A las propiedades personalizadas solo se les pueden asignar tipos básicos de Python: enteros, números de punto flotante, texto, secuencias numéricas y diccionarios que cumplan determinadas reglas. El documento establece un límite máximo de 1024 niveles para los diccionarios anidados; superar esa profundidad puede provocar errores y pérdida de datos. Este ejemplo utiliza un valor de texto sencillo, por lo que no contiene una estructura anidada de este tipo.
4. Convierte una tarea repetitiva en un operador
Puedes definir un operador para volver a ejecutar un fragmento de código desde Blender. El siguiente ejemplo crea un operador sencillo que imprime los objetos de la escena y no permite ejecutarlo si no hay un objeto activo:
import bpy
def main(context):
for ob in context.scene.objects:
print(ob)
class SimpleOperator(bpy.types.Operator):
"""Tooltip"""
bl_idname = "object.simple_operator"
bl_label = "Simple Object Operator"
@classmethod
def poll(cls, context):
return context.active_object is not None
def execute(self, context):
main(context)
return {'FINISHED'}
def menu_func(self, context):
self.layout.operator(
SimpleOperator.bl_idname,
text=SimpleOperator.bl_label
)
def register():
bpy.utils.register_class(SimpleOperator)
bpy.types.VIEW3D_MT_object.append(menu_func)
def unregister():
bpy.utils.unregister_class(SimpleOperator)
bpy.types.VIEW3D_MT_object.remove(menu_func)
if __name__ == "__main__":
register()En el espacio de trabajo Scripting, selecciona el Editor de texto, crea un nuevo bloque de datos de texto con el botón New, pega el código y pulsa Run Script. En el ejemplo del documento de referencia, después de registrar el operador puedes buscar Simple mediante Operator Search. La comprobación poll() impide que el operador se ejecute si no hay un objeto activo. Este detalle es importante cuando el script depende del contexto del usuario.
5. Ten en cuenta el contexto de la consola y de la interfaz
El contenido de bpy.context puede variar según el área desde la que se ejecute el código. La Consola de Python y el 3D Viewport, por ejemplo, no tienen por qué disponer de los mismos miembros de contexto. Además, los valores de contexto no se pueden cambiar directamente; la fuente explica que asignar directamente el objeto activo provoca un error y que, en su lugar, se puede utilizar bpy.context.view_layer.objects.active. Si un operador no funciona como esperabas, comprueba primero en qué área y modo lo estás ejecutando.
Errores frecuentes
Usar el índice como si fuera un identificador permanente: los índices de las colecciones pueden cambiar durante la ejecución. Para seleccionar un elemento concreto, es más claro acceder a él por su nombre; comprueba que ese nombre exista realmente en el archivo.
Dar por hecho que cualquier operador funcionará en cualquier lugar: algunos operadores requieren un área, modo o selección adecuados. La condición
poll()comprueba si se cumplen esos requisitos; una llamada con un contexto no válido puede producir un error.Intentar modificar directamente el contexto:
bpy.contextse define como de solo lectura. Si necesitas hacer cambios, utiliza la API de datos documentada o la función correspondiente de la API.Guardar datos complejos en propiedades personalizadas: los tipos compatibles son limitados y los valores de los diccionarios también deben ser tipos básicos. Es preferible usar propiedades sencillas y claras.
Buscar la salida del script en el lugar equivocado: la salida de
printdel ejemplo se envía al terminal. Si no ves el resultado, comprueba el terminal de Blender.
Próximos pasos: flujos de trabajo de arquitectura y visualización
Estos métodos básicos pueden ser un punto de partida para arquitectos, interioristas y artistas de visualización que quieran revisar la organización de una escena o asociar información adicional a los objetos. Por ejemplo, enumerar los objetos de un archivo puede facilitar la revisión del contenido en escenas grandes; las propiedades personalizadas pueden servir para guardar etiquetas sencillas acordadas por el equipo. Por sí solas, estas funciones no ofrecen un estándar BIM específico ni una solución automatizada de gestión de proyectos: su alcance depende de los scripts que escribas y de los datos que utilices.
Haz las primeras pruebas en una copia del archivo blend. Después, utiliza Python Tooltips y el autocompletado de la consola para explorar la ruta de datos que buscas; no añadas un atributo a un script de producción sin verificar primero su función. Más adelante, adapta el operador a una tarea repetitiva real y pruébalo con distintas selecciones, objetos activos y condiciones de contexto. Para los scripts que se compartirán en oficinas, también es necesario comprobar la compatibilidad con la versión de Blender; las fuentes no ofrecen una matriz de compatibilidad concreta.
Fuente y licencia
Esta guía se preparó adaptando los ejemplos y explicaciones de la guía de inicio rápido de la API de Python de Blender. El documento tiene licencia CC BY-SA 4.0. La entrada del blog de desarrollo de Blender de 2011 aporta contexto histórico sobre la ampliación de la documentación de la API, pero no sustituye a las instrucciones actuales de uso de la API.
Fuentes
2 fuentesNo republicamos los textos de las fuentes; las citas breves van marcadas y el resto es resumen y comentario propios.
La API de Python de Blender puede resultar especialmente útil para automatizar pequeñas comprobaciones repetitivas y organizar la información dentro de los archivos en estudios de arquitectura y equipos de visualización de Turquía. Como funciona dentro de Blender, que se puede utilizar de forma gratuita, empezar a probarla no requiere el coste adicional de otro software.
Sin embargo, el valor de la automatización depende de adaptar los scripts a la organización de archivos del equipo y a la versión de Blender. Es importante probarlos primero en una escena duplicada, tener en cuenta las partes de la API que siguen en desarrollo y mantener sencillas las propiedades personalizadas. Para los estudiantes, también es una forma concreta de ver cómo se organizan los datos de una escena mientras aprenden la API.
Preguntas frecuentes
¿Dónde se ejecuta el código de la API de Python de Blender?
Puedes probar comandos breves en la Consola de Python. Los scripts se pueden ejecutar desde el Editor de texto del espacio de trabajo Scripting de Blender.
¿Cómo se añade información personalizada a un objeto en Blender?
La API permite añadir propiedades personalizadas a los objetos. Estas pueden guardarse en el archivo blend y conservarse al duplicar el objeto.
¿La API de Python de Blender requiere una versión específica?
El documento de referencia utilizado no indica un número de versión concreto. La API se describe, en general, como estable, aunque se señala que algunas partes siguen en desarrollo.



