Guía para editar rápidamente objetos de escena con la consola Python de Blender

La consola Python de Blender permite ejecutar fragmentos breves de código para inspeccionar los datos de la escena y explorar la API de Blender. Los ejemplos de la documentación de Blender muestran cómo cambiar la posición del objeto activo, ver los objetos seleccionados y añadir una nueva luz a la escena. Los pasos siguientes se centran en utilizar la consola Python para realizar operaciones pequeñas y controlables.

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

Además de ejecutar los comandos escritos, la consola Python ofrece un historial de comandos y la función de autocompletado. Primero consultaremos el contexto actual, es decir, el objeto y el modo activos en Blender. Después cambiaremos la posición del objeto activo, enumeraremos los objetos seleccionados y crearemos un nuevo objeto de luz.

Este enfoque es adecuado para hacer pruebas pequeñas, en lugar de preparar un script largo para cada operación. Cuando un comando funciona como se esperaba, el historial de la consola facilita volver a utilizarlo. Según la documentación de Blender, se puede acceder a los comandos anteriores y siguientes con las teclas de flecha arriba y abajo; la tecla Tab activa el autocompletado en la línea de comandos.

Requisitos y preparación

Estos ejemplos se basan en la consola Python de Blender y en bpy, la API de Python de Blender. La documentación de origen no especifica un número de versión concreto de Blender, requisitos de cuenta, requisitos mínimos de hardware ni un método de instalación. Por lo tanto, conviene comprobar por separado el comportamiento de la API en la versión que se vaya a utilizar.

En la consola, los comandos se ejecutan con la tecla Return. Al escribir un comando, se pueden ver sugerencias de autocompletado para los miembros disponibles pulsando Tab. La documentación de Blender también recomienda ejecutar el comando dir() para familiarizarse con el entorno de la consola. El primer ejemplo consulta el modo y el objeto activo en el contexto actual:

bpy.context.mode
bpy.context.active_object

La primera línea devuelve el modo de interacción actual y la segunda, el objeto activo. La documentación señala específicamente que debe haber un objeto seleccionado en la 3D Viewport para obtener los resultados correctos. Si no hay ningún objeto activo, los comandos que intenten acceder a sus propiedades no producirán el resultado esperado; por eso, antes de editar, comprueba que haya un objeto adecuado activo en la escena.

Paso a paso: operaciones básicas en la consola

1. Explora los miembros de la API

Puedes aprovechar el autocompletado para investigar qué propiedades están disponibles en la API de Blender. Escribe la expresión siguiente en la consola y pulsa Tab para ver sugerencias de submódulos, propiedades y métodos de bpy. La documentación explica que los métodos se distinguen en las sugerencias porque aparecen con paréntesis al final.

bpy.

Inspeccionar los miembros de una variable o un módulo permite avanzar consultando la API disponible, en lugar de escribir comandos de memoria. En el entorno de la consola también existen los alias C para bpy.context y D para bpy.data. Como primer paso, puedes ejecutar dir() para inspeccionar las funciones y variables generales definidas en el entorno.

2. Cambia la posición del objeto activo

Se puede acceder al objeto activo a través del contexto. La documentación incluye ejemplos para cambiar la coordenada X de un objeto y añadir un pequeño incremento a esa coordenada. Primero consulta la coordenada actual del objeto; después, aplica un incremento de 0.5 unidades en el eje X con el siguiente comando:

bpy.context.object.location.x += 0.5

Este comando modifica la propiedad de posición del objeto activo. Si no hay ningún objeto seleccionado, bpy.context.object podría no devolver un objeto adecuado. Por eso, es importante confirmar que hay un objeto activo antes de ejecutar el comando. La tecla de flecha arriba recupera el comando anterior del historial, pero no deshace los cambios realizados en la escena. Comprueba el objeto activo y el resultado en la escena antes de probar otra coordenada.

3. Asigna las tres coordenadas a la vez

Para editar los tres componentes de la posición de una sola vez, se pueden indicar las coordenadas como una tupla. El ejemplo siguiente asigna los valores 1, 2 y 3 a X, Y y Z, respectivamente:

bpy.context.object.location = (1, 2, 3)

También es posible cambiar solo los componentes X e Y. Este método sirve cuando se quieren asignar valores a ambas coordenadas a la vez y conservar la coordenada Z actual:

bpy.context.object.location.xy = (1, 2)

Estos ejemplos acceden directamente a la posición del objeto activo. En una edición de escena, tener presente qué objeto está activo evita modificar el objeto equivocado. Antes de realizar operaciones más complejas, probar con un solo objeto y comprobar el resultado en la escena es una forma prudente de trabajar.

4. Muestra los objetos seleccionados

Cuando hay varios objetos seleccionados, bpy.context.selected_objects devuelve la lista de objetos seleccionados. Para ver los objetos seleccionados que no sean el objeto activo, se puede utilizar la siguiente expresión:

[obj for obj in bpy.context.selected_objects if obj != bpy.context.object]

Este ejemplo recorre los objetos seleccionados e incluye en la lista de resultados aquellos que no son el objeto activo. Así, puedes examinar desde la consola la diferencia entre el objeto activo y los demás objetos seleccionados. bpy.context permite acceder a información contextual, como la escena actual, los objetos seleccionados y el modo actual; bpy.data da acceso a los datos del archivo blend, estén o no seleccionados o activos.

5. Añade una luz puntual a la escena

El ejemplo de la documentación de la API de Blender crea un nuevo bloque de datos de luz y un objeto que lo utiliza, y lo vincula a la colección activa. A continuación, define la posición de la luz, selecciona el objeto y lo establece como activo. El código siguiente reproduce el ejemplo básico de luz puntual de la documentación:

import bpy

view_layer = bpy.context.view_layer
light_data = bpy.data.lights.new(name="New Light", type='POINT')
light_object = bpy.data.objects.new(name="New Light", object_data=light_data)
view_layer.active_layer_collection.collection.objects.link(light_object)
light_object.location = (5.0, 5.0, 5.0)
light_object.select_set(True)
view_layer.objects.active = light_object

El código primero crea los datos de la luz y, después, añade a la colección de la escena un objeto vinculado a esos datos. Una vez asignada la posición y seleccionado el objeto, la nueva luz pasa a ser el objeto activo. El ejemplo de la documentación muestra la secuencia para crear un objeto de este tipo, vincularlo a la escena, posicionarlo y activarlo.

Errores frecuentes

Uno de los problemas más básicos es intentar acceder a las propiedades de un objeto sin que haya ninguno activo. Antes de probar los ejemplos de posición, comprueba que haya un objeto seleccionado y activo. Modificar otro objeto suele deberse a no haberse fijado en cuál es el objeto activo en el contexto.

Otra confusión habitual es pensar que el historial de comandos y borrar la pantalla de la consola son lo mismo. Según la documentación de Blender, Clear All, en el menú de la consola, actualiza la vista, pero no borra el historial de comandos. Las teclas de flecha permiten recuperar los comandos anteriores y siguientes. Shift+Return añade el comando al historial sin ejecutarlo; para ejecutarlo, se utiliza Return.

Quienes quieran guardar los comandos como un script después de hacer pruebas breves pueden copiar todo el búfer del historial al portapapeles con el atajo Copy as Script, indicado en la documentación. Después, pueden pegar el contenido en un archivo de texto y utilizarlo como script de Python. Revisar el código y sus efectos en la escena antes de pasar a un trabajo más grande ayuda a evitar que los comandos de prueba se trasladen por accidente a un archivo de producción.

Uso en flujos de trabajo de arquitectura y visualización

En trabajos de arquitectura, diseño de interiores y archviz, la consola puede ser útil para probar pequeñas operaciones repetitivas, como cambiar rápidamente la posición del objeto activo, inspeccionar objetos seleccionados o añadir una luz a la escena. En particular, estudiantes y artistas de visualización que empiezan a familiarizarse con la API de Python de Blender pueden observar la relación entre el contexto y las propiedades de los objetos mediante pruebas de un solo comando.

Sin embargo, los ejemplos que se presentan aquí son básicos; las fuentes no ofrecen información sobre una plantilla de proyecto concreta, ajustes de render, requisitos de hardware o compatibilidad con otros programas. Si se está planificando una automatización para el flujo de trabajo de una oficina, es necesario probar los ejemplos con la versión de Blender utilizada y la estructura de los objetos del proyecto. Comprobar los efectos de los comandos en la escena y guardar el historial como script cuando sea necesario permite integrar las pruebas pequeñas en un proceso más ordenado.

Próximos pasos

Empieza con comandos que consulten el contexto y, después, prueba por separado los ejemplos de posición y de objetos seleccionados. Cuando necesites combinar varios comandos, consulta el ejemplo Object de la documentación de la API de Blender y sigue la secuencia para crear un bloque de datos, vincularlo a una colección y activar el objeto. Los operadores también permiten invocar programáticamente operaciones que normalmente se inician con un botón o un menú; para saber qué operador utilizar, consulta la documentación correspondiente de la API.

Fuentes y licencia

Esta guía se adaptó a partir de la página “Python Console” del Blender Manual y de la referencia “Object” de la API de Python de Blender. Ambas fuentes están bajo la licencia CC BY-SA 4.0; el contenido se tradujo al turco y se reformuló, y los ejemplos de código se basan en los usos de la documentación correspondiente de la API.