Cómo escribir un complemento de Python para Blender: primer operador e instalación

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

En esta guía veremos cómo convertir un sencillo script de Python en un operador y, después, en un complemento instalable para Blender. La herramienta de ejemplo suma 1,0 a la coordenada X de cada objeto de la escena activa. El objetivo no es utilizar esta operación en todos los proyectos arquitectónicos, sino mostrar los componentes básicos del desarrollo de herramientas en Blender, cómo guardar el código y cómo ejecutarlo desde la interfaz de usuario.

También repasaremos algunas opciones para iniciar un renderizado en segundo plano desde la línea de comandos. El desarrollo de complementos y el renderizado son flujos de trabajo independientes; su punto en común es que convierten tareas repetitivas en pasos definidos y fáciles de seguir. Conviene probar las operaciones de estos ejemplos en una copia antes de utilizarlas en un archivo de proyecto importante.

Requisitos

Es necesario tener conocimientos básicos de Blender y saber ejecutar scripts desde el espacio de trabajo Text Editor. La guía de complementos de Blender también presupone conocimientos básicos de los tipos de datos, módulos y clases de Python. Para revisar mejor los mensajes de error, la guía oficial recomienda, entre otros métodos, ejecutar Blender desde la terminal.

En el diccionario bl_info del complemento de ejemplo, el valor (2, 80, 0) indica la versión mínima de Blender necesaria para ejecutar el complemento. Esto no significa que sea automáticamente compatible con versiones más recientes: hay que probar el código en la versión en la que se vaya a utilizar. La documentación de la línea de comandos está incluida en la guía de Blender 5.2 LTS.

Cómo crear tu primer complemento paso a paso

1. En Blender, abre un texto nuevo en el espacio de trabajo Text Editor y añade el siguiente código. Define un operador llamado ObjectMoveX. Al ejecutarlo, recorre los objetos de la escena activa y aumenta en 1,0 la coordenada X de cada uno. La opción UNDO habilita la posibilidad de deshacer la operación.

bl_info = {
    'name': 'Move X Axis',
    'blender': (2, 80, 0),
    'category': 'Object',
}

import bpy

class ObjectMoveX(bpy.types.Operator):
    """Move every scene object along the X axis."""
    bl_idname = 'object.move_x'
    bl_label = 'Move X by One'
    bl_options = {'REGISTER', 'UNDO'}

    def execute(self, context):
        scene = context.scene
        for obj in scene.objects:
            obj.location.x += 1.0
        return {'FINISHED'}

def register():
    bpy.utils.register_class(ObjectMoveX)

def unregister():
    bpy.utils.unregister_class(ObjectMoveX)

if __name__ == '__main__':
    register()

bl_info proporciona a Blender datos como el nombre y la categoría del complemento; el campo de versión del ejemplo indica el requisito mínimo. execute() contiene la operación que se realiza al ejecutar el operador. Aquí, el contexto de la escena se obtiene mediante el parámetro context de la función. La guía oficial recomienda utilizar este parámetro en los operadores siempre que sea posible.

1. Haz clic en el botón Run Script del espacio de trabajo Text Editor para ejecutar el código. En este paso se registra el operador, pero todavía no se mueven los objetos. Abre el menú Operator Search, busca Move X by One y pulsa Enter. En el ejemplo de la guía, este nombre visible se define en el campo bl_label.

2. Para instalar el script como complemento, guárdalo en un archivo con extensión .py y un nombre que cumpla las reglas de nomenclatura de módulos de Python. En Blender, ve a Preferences > Add-ons > Install… y selecciona el archivo. Cuando el complemento aparezca en la lista, actívalo. Si quieres que permanezca activo después de reiniciar, utiliza la opción Save as Default indicada en la guía.

Cuando se activa el complemento, Blender llama a la función register(); cuando se desactiva, llama a unregister(). En el código, estas funciones se encargan de registrar y eliminar la clase del operador. Ejecutar el script directamente durante el desarrollo permite hacer una prueba rápida; instalar el complemento, en cambio, permite gestionarlo desde la lista de complementos de las preferencias de Blender.

Uso en flujos de trabajo de arquitectura y visualización

El operador del ejemplo afecta a todos los objetos de la escena activa. Por eso, antes de ejecutarlo en una escena arquitectónica, es importante determinar qué objetos se moverán. Si se desarrolla una herramienta de este tipo para una oficina, conviene definir el alcance de la operación según la estructura del proyecto y probarla primero en una escena de prueba. Este ejemplo es un ejercicio inicial para explicar la lógica de los operadores, no una herramienta de distribución arquitectónica lista para usar.

La guía de complementos de Blender incluye otro ejemplo que coloca duplicados vinculados del objeto activo entre el cursor 3D y el objeto. Los duplicados se vinculan a la colección de la escena y sus posiciones se calculan según la relación entre el objeto y el cursor. En la primera versión, el número total de duplicados está fijado en 10. El ejemplo explica cómo crear herramientas para elementos repetitivos y muestra que también se pueden añadir ajustes modificables por el usuario.

Para renderizar desde la línea de comandos, puedes ejecutar Blender en segundo plano con la opción -b o --background. En el ejemplo de Cycles de la documentación oficial se seleccionan un fotograma y un dispositivo específicos:

blender -b file.blend -f 20 -- --cycles-device OPTIX

Este comando renderiza el fotograma 20 y selecciona el dispositivo OPTIX. La guía enumera CPU, CUDA, OPTIX, HIP, ONEAPI y METAL como opciones válidas de dispositivo para Cycles. El dispositivo elegido debe ser compatible con el sistema que se utilizará.

La documentación incluye también un comando independiente para exportar fotogramas de una animación en formato PNG:

blender -b animation.blend -o //render_ -F PNG -x 1 -a

En este comando, -o indica la ruta de salida, -F el formato de archivo, -x añade la extensión y -a renderiza los fotogramas de la animación. Las rutas que empiezan por // se interpretan como relativas al archivo .blend. Si se utilizan caracteres # en el nombre del archivo, funcionan como marcadores de posición para el número de fotograma. Los dos ejemplos responden a necesidades distintas; ajusta opciones como el fotograma, el formato de archivo, la ubicación de salida y el dispositivo al tipo de renderizado que necesites.

Este enfoque puede ser útil para usuarios de Blender que quieran automatizar operaciones repetitivas en la escena y para equipos que planeen renderizar fuera de la interfaz. Sin embargo, las fuentes no especifican requisitos de hardware ni costos de licencia. Para los complementos, hay que comprobar la compatibilidad con la versión de Blender; para el renderizado, el dispositivo seleccionado y la configuración de salida definida explícitamente.

Errores frecuentes y próximos pasos

• No confundas ejecutar el script con ejecutar el operador. En el ejemplo, el primer paso registra el operador; para modificar la escena, hay que ejecutarlo por separado.

• Revisa el alcance del operador. En el ejemplo, cambia la coordenada X de todos los objetos de la escena activa.

• Interpreta el valor (2, 80, 0) de bl_info como el requisito de versión mínima, no como una garantía de compatibilidad con versiones nuevas de Blender.

• En el renderizado en segundo plano, especifica la ruta del archivo, el formato de salida, el rango de fotogramas y el dispositivo de Cycles según tus necesidades. Un comando de ejemplo puede incluir opciones que no aparecen en el otro.

Como siguiente paso, puedes consultar los apartados bpy.context y bpy.types.Operator de la documentación de la API de Blender. La guía oficial de complementos también explica cómo convertir las propiedades de los operadores y los valores fijos en opciones ajustables por el usuario. A medida que la herramienta crezca, convertir valores como el número de duplicados en opciones configurables puede ayudar a adaptarla a distintas necesidades de la escena.

Fuentes y licencia

Esta guía se ha adaptado a partir de “Add-on Tutorial” y “Command Line Arguments” del Blender Manual. Ambas fuentes se publican con licencia CC BY-SA 4.0; el contenido se ha adaptado al español de acuerdo con las condiciones de dicha licencia.