Datos de imagen y texturas ImageTexture con la API de Python de Blender

Qué aprenderás en esta guía

Aprenderás a crear un bloque de datos Image con la API de Python de Blender, escalar el búfer de imagen y modificar los valores de los píxeles. También veremos la función de update() para reflejar los cambios en la imagen y qué aspectos del búfer conviene tener en cuenta al copiar un bloque de datos Image. En la última sección, explicaremos cómo se relacionan las opciones de ImageTexture con la repetición de texturas, el alfa y los límites de la imagen.

Esta guía está dirigida a equipos de visualización arquitectónica y usuarios de Blender que quieran preparar datos de imagen mediante scripts o analizar con mayor control el comportamiento de las texturas. Los ejemplos se limitan a las operaciones descritas en la documentación de la API; no incluyen pasos para asignar materiales a una escena ni para crear redes de nodos.

Requisitos

• Se necesita acceso a la API de Python dentro de Blender. Las fuentes son la documentación actual de la API de Blender; estas páginas no especifican la versión mínima de Blender necesaria para las operaciones descritas.

• Los ejemplos de código usan el módulo bpy en el entorno de Python de Blender. Las fuentes no indican que se necesite una cuenta externa.

• La documentación de la API no proporciona información sobre requisitos de hardware, tarifas ni costes de licencia para estas operaciones. No se deben dar por sentados requisitos específicos en estos aspectos; conviene comprobar por separado la versión y el entorno de trabajo que se utilizarán.

Cómo trabajar paso a paso con un bloque de datos Image

1. Crear un bloque de datos de imagen

Puedes crear un nuevo bloque de datos Image con bpy.data.images.new(). El ejemplo siguiente usa las dimensiones iniciales de la fuente. La propiedad size permite consultar la anchura y la altura del búfer de imagen en píxeles.

import bpy

image_src = bpy.data.images.new("Mimari_Kontrol", 1024, 102)
print(image_src.size)

No conviene considerar el bloque de datos Image como el lugar donde se almacena toda la información de la propia imagen. La documentación indica que datos como el búfer de píxeles y las dimensiones se almacenan en un búfer de imagen, mientras que el bloque de datos Image hace referencia a un archivo de imagen o a una imagen creada. Esta distinción es especialmente importante al modificar el búfer y, después, copiar el bloque de datos.

2. Escalar el búfer y reflejar el cambio en la imagen

scale() cambia las dimensiones del búfer de imagen. La propiedad pixels permite acceder al búfer de píxeles, que está formado por valores de punto flotante. El ejemplo siguiente escala la imagen a 1024 × 720, modifica los cuatro primeros valores del búfer y, a continuación, actualiza la imagen.

image_src.scale(1024, 720)
image_src.pixels[0:4] = (0.5, 0.5, 0.5, 0.5)
image_src.update()

print(image_src.size)
print(image_src.pixels[0:4])

Este código asigna valores únicamente a los cuatro primeros elementos del búfer; no significa que rellene toda la imagen. La llamada a update() actualiza la visualización de la imagen para reflejar los cambios hechos en el búfer de punto flotante. Si el resultado no es el esperado, comprueba primero que la variable utilizada apunta al bloque de datos Image correcto y que la llamada de actualización se haya ejecutado.

3. Comprobar el comportamiento al copiar

Copiar un bloque de datos Image no significa necesariamente que los cambios del búfer también se copien de forma automática. La documentación advierte que los búferes no se comparten entre distintos bloques de datos Image ni se duplican al copiar una imagen. Por eso, los cambios del búfer que no se hayan guardado en disco podrían no aparecer en la copia.

image_dest = image_src.copy()
image_dest.update()

print(image_dest.size)
print(image_dest.pixels[0:4])

Después de crear la copia, comprueba por separado las dimensiones y los valores del búfer. No des por sentado que la copia incluirá las últimas modificaciones realizadas en la imagen de origen. Si necesitas que los cambios del búfer se reflejen en la copia, evalúa si debes guardar primero la imagen en disco y, después, verifica la copia.

4. Guardar la imagen o empaquetarla en el archivo del proyecto

La API de Image define save() para guardar una imagen y save_render() para guardarla en una ruta específica usando los ajustes de render de la escena. pack() se puede usar para incorporar la imagen como datos incrustados en el archivo .blend.

image_src.pack()

Empaquetar, guardar y volver a cargar son operaciones distintas. En la API, unpack() extrae a disco una imagen empaquetada, mientras que reload() vuelve a cargarla desde la ruta de origen. El método adecuado depende de cómo quieras gestionar la ruta del archivo de imagen y sus datos dentro del proyecto. Antes de entregar el trabajo, comprueba que la imagen esté en la ubicación prevista y revisa su estado en el archivo del proyecto.

Cómo elegir los ajustes de ImageTexture

Las opciones de ImageTexture determinan cómo se trata una imagen como textura. La propiedad extension selecciona el comportamiento del área que queda fuera de los límites de la imagen. REPEAT repite la imagen en horizontal y vertical; EXTEND prolonga los píxeles de los bordes; CLIP deja transparente el área que queda fuera de las dimensiones de la imagen. La documentación también incluye CLIP_CUBE y CHECKER entre las opciones.

repeat_x y repeat_y definen por separado los multiplicadores de repetición horizontal y vertical. Para usar alfa, está disponible use_alpha; para invertir los valores alfa, invert_alpha. use_interpolation afecta a la interpolación y filter_size, al tamaño del filtro utilizado en ella. Al revisar estos ajustes, ten en cuenta el canal alfa de la imagen de origen y el uso que se dará a la textura.

La API de Image enumera las opciones STRAIGHT, PREMUL, CHANNEL_PACKED y NONE para la visualización del alfa. La documentación describe CHANNEL_PACKED como un modo para usos en los que se empaquetan distintas imágenes en los canales RGB y alfa, y los canales no deben afectarse entre sí. Si no conoces la disposición de canales del archivo de origen, comprueba cómo se preparó la imagen antes de cambiar los ajustes de alfa.

Errores frecuentes

• Suponer que también se duplica el búfer al copiar: Es posible que los cambios no guardados no aparezcan en la copia. Comprueba las dimensiones y los valores del búfer de la copia.

• Olvidar llamar a update() después de editar: Actualiza la imagen después de modificar el búfer.

• No comprobar el comportamiento en los límites de la textura: REPEAT, EXTEND y CLIP producen resultados distintos. Determina qué comportamiento necesitas en los bordes de la imagen.

• Cambiar los ajustes de alfa sin tener en cuenta la imagen de origen: Confirma si se usa el canal alfa y qué modo de alfa es el adecuado.

• Confundir guardar con empaquetar: save(), pack(), unpack() y reload() tienen funciones distintas. Comprueba por separado el estado de la imagen en el archivo del proyecto y en disco.

Próximos pasos

Prueba primero las operaciones en un archivo de prueba pequeño. Tras crear la imagen, imprime sus dimensiones; después de escalarla y modificar los píxeles, actualiza el búfer y vuelve a comprobar los valores. Al probar el comportamiento de copia, compara los valores de la imagen de origen y de la copia. Luego, prueba de forma controlada el comportamiento de los límites y los ajustes de repetición de ImageTexture. Antes de pasar a una escena de visualización arquitectónica, confirma la ruta del archivo de origen, el uso del alfa y si la imagen se empaquetará dentro del proyecto.

Fuentes y licencia

Esta guía se basa en las páginas bpy.types.Image y bpy.types.ImageTexture de la documentación oficial de la API de Python de Blender. Ambas fuentes tienen licencia CC BY-SA 4.0; el contenido se ha adaptado al turco.