Crear materiales y ajustar sus propiedades básicas con la API Python de Blender

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

La API Python de Blender permite crear materiales mediante código y ajustar sus propiedades básicas, en lugar de editarlos uno por uno desde la interfaz. En esta guía crearemos un bloque de datos de material, le asignaremos un nombre y ajustaremos el color, la cantidad de metalicidad y la rugosidad. Después veremos las opciones de transparencia enumeradas en la documentación de la API y cómo eliminar de la base de datos un material que ya no se utiliza.

La documentación de la API de Blender describe el bloque de datos Material como la estructura que define el aspecto de los objetos geométricos durante el renderizado. Los materiales se guardan en una colección de la base de datos principal de Blender. Los ejemplos siguientes se basan en el uso documentado de esta colección y de las propiedades de los materiales; no incluyen los pasos para asignar un material a una escena concreta o a un tipo de objeto determinado.

Requisitos y nota sobre la versión

Para utilizar los ejemplos se necesita un entorno de Blender con acceso a la API Python de Blender. La documentación de referencia presenta las páginas de la API como “current” y no exige una versión concreta de Blender. Por eso es importante comprobar que las propiedades de la página de la API coincidan con la versión utilizada en el proyecto. Las fuentes no mencionan requisitos de cuenta, suscripción ni licencia independiente.

Los fragmentos de código están escritos en Python y utilizan la API bpy de Blender. Ejecútalos en un entorno con acceso a la API Python de Blender; los ejemplos no garantizan que un entorno Python externo pueda acceder a los datos de Blender. Hacer la primera prueba en una copia de un archivo de proyecto importante ayuda a evitar que los cambios de datos no deseados afecten a la escena original.

Crear un material paso a paso

1. Crear un nuevo bloque de datos de material

BlendDataMaterials.new(name) añade un material nuevo a la base de datos principal y devuelve el bloque de datos Material creado. El parámetro name es el nombre que se asignará al nuevo bloque de datos; según la documentación, este valor no puede ser None.

import bpy

mat = bpy.data.materials.new(name="Mimari_Materyal")

Al terminar este paso, la variable mat permite acceder al material creado. El material se añade a la base de datos, pero el código no lo vincula a una geometría concreta. Por lo tanto, conviene considerar la creación del material y su uso en la colección de materiales de un objeto como pasos separados.

2. Ajustar el color y el aspecto de la superficie

La documentación incluye diffuse_color, metallic y roughness entre las propiedades del material. diffuse_color se define como una matriz de cuatro elementos. La cantidad de metalicidad y la rugosidad admiten valores entre 0 y 1; la documentación indica que la rugosidad predeterminada es 0,4 y que la cantidad de metalicidad predeterminada es 0.

mat.diffuse_color = (0.72, 0.64, 0.52, 1.0)
mat.metallic = 0.0
mat.roughness = 0.4

Estos valores son valores iniciales de ejemplo, no una receta verificada para un producto o material de construcción real. Puedes cambiar los cuatro componentes de la matriz de color y las propiedades numéricas según tus necesidades. Si preparas varias variantes, elegir nombres de material fáciles de distinguir facilita la gestión de los elementos de la base de datos.

3. Elegir el método de transparencia

En la API actual de Material, surface_render_method determina cómo se mezclan las superficies y la compatibilidad del método con ciertas funciones. La documentación ofrece dos opciones: DITHERED y BLENDED. DITHERED procesa la transparencia mediante una distribución en escala de grises y se describe como compatible con los pases de renderizado y el soporte de trazado de rayos. BLENDED proporciona transparencia coloreada, pero, según la documentación, no se puede utilizar junto con los pases de renderizado ni con el trazado de rayos.

mat.surface_render_method = 'DITHERED'

Esta línea selecciona el método de transparencia, pero no establece por sí sola un nivel de opacidad concreto. Si necesitas transparencia coloreada, puedes considerar la opción BLENDED. Al decidir, ten en cuenta si los pases de renderizado o la compatibilidad con el trazado de rayos son necesarios en tu flujo de trabajo.

alpha_threshold también es una propiedad documentada del material. Se renderizan los píxeles cuyo valor alfa supera este umbral. La propiedad admite valores entre 0 y 1, y la documentación indica un valor inicial de 0,5. Si vas a cambiar este valor, prueba el aspecto deseado y consulta la descripción de la API en la versión de Blender que utilices.

4. Eliminar el material cuando sea necesario

Si un material ya no es necesario, se puede eliminar del archivo blend actual con BlendDataMaterials.remove. do_unlink=True permite quitar los vínculos en los que se utiliza el material antes de borrarlo. Los demás parámetros están relacionados con la actualización de los contadores de usuarios y con evitar que la interfaz haga referencia al material eliminado.

bpy.data.materials.remove(mat, do_unlink=True)

Antes de ejecutar este código, asegúrate de que el material que vas a eliminar es el correcto. do_unlink=True también quita los vínculos de uso antes de borrarlo; este comportamiento puede tener consecuencias no deseadas si el material debe seguir utilizándose en la escena. Probar primero el paso de eliminación en una copia del archivo es una forma segura de comprobarlo.

Errores frecuentes

• Confundir una propiedad antigua con el método actual: blend_method es una propiedad antigua para las superficies transparentes y la documentación recomienda utilizar surface_render_method. Al preparar un proyecto nuevo, utiliza el método de la API actual.

• Usar la propiedad use_nodes como un interruptor de configuración: La documentación marca esta propiedad como obsoleta desde Blender 5.0. Indica que no tiene ningún efecto al establecerla, que al leerla siempre devuelve True y que está previsto eliminarla en Blender 6.0. Por eso no la utilizamos en el flujo de trabajo de ejemplo.

• Confundir el color con los rangos numéricos: diffuse_color es una matriz de cuatro elementos; metallic y roughness admiten valores entre 0 y 1. Comprueba en la documentación de la API el tipo de dato y los rangos esperados.

• Suponer que crear un material equivale a asignarlo a un objeto: Crear un nuevo bloque de datos añade el material a la base de datos principal; no lo asigna automáticamente a un objeto geométrico.

• Pasar por alto los vínculos de uso al eliminar: do_unlink=True quita todos los usos del material antes de borrarlo. No ejecutes código de limpieza en el archivo actual sin comprender el efecto de esta opción.

Uso en flujos de trabajo de arquitectura y visualización

Este método es un punto de partida para estudios de arquitectura, interioristas y equipos de visualización que quieran generar mediante código bloques de datos de materiales similares o modificar sus propiedades básicas de forma repetible. Cuando se necesita aplicar el mismo esquema de nombres y valores básicos a varios materiales, crearlos mediante código puede reducir las tareas repetitivas manuales. Sin embargo, esta guía no describe un flujo de trabajo para asignar materiales a objetos, el comportamiento de motores de renderizado concretos ni las bibliotecas de materiales externas.

Antes de incorporar el método a un proyecto, compara la versión de Blender utilizada con la documentación actual de la API y comprueba la compatibilidad del método de transparencia con los pases de renderizado y el trazado de rayos. Las fuentes no especifican requisitos de hardware, mediciones de rendimiento, tarifas ni costes de licencia, por lo que no se pueden extraer conclusiones definitivas sobre esos aspectos. En el código que se comparta en el estudio, conviene probar primero en una copia del archivo los pasos que modifican datos, como la eliminación.

Próximos pasos

Una vez que funcionen los pasos básicos de creación y configuración, consulta las páginas de la API Material y BlendDataMaterials de la versión de Blender que utilizas, según las necesidades del proyecto. La documentación también enumera la propiedad node_tree del bloque de datos de material y distintas colecciones que hacen referencia a materiales; esta guía no explica cómo modificarlas. Basarse en las propiedades documentadas y en los requisitos verificados del proyecto al decidir la siguiente fase de desarrollo ayuda a reducir los problemas de compatibilidad.

Fuente y licencia

Esta guía es una adaptación al turco de las páginas BlendDataMaterials y Material de la documentación de la API de Blender. Ambas fuentes se publican bajo la licencia CC BY-SA 4.0. Los ejemplos de código se han escrito para esta guía; no se ha citado código de las fuentes.