Créer un matériau et régler ses paramètres de base avec l’API Python de Blender

Ce que vous apprendrez dans ce guide

L’API Python de Blender permet de créer des matériaux et d’en régler les propriétés de base par le code, plutôt que de les modifier un à un dans l’interface. Dans ce guide, nous allons créer un bloc de données matériau, lui donner un nom, puis régler sa couleur, sa métallicité et sa rugosité. Nous examinerons ensuite les options de transparence répertoriées dans la documentation de l’API, ainsi que la méthode permettant de supprimer de la base de données un matériau inutilisé.

La documentation de l’API Blender décrit le bloc de données Material comme la structure qui définit l’apparence des objets géométriques au rendu. Les matériaux sont stockés dans une collection de la base de données principale de Blender. Les exemples ci-dessous s’appuient sur l’utilisation documentée de cette collection et des propriétés des matériaux ; ils ne couvrent pas les étapes d’attribution d’un matériau à une scène ou à un type d’objet particulier.

Prérequis et note sur les versions

Pour utiliser ces exemples, il vous faut un environnement Blender donnant accès à l’API Python de Blender. La documentation source présente les pages de l’API comme étant « current » et n’impose pas de version particulière de Blender. Il est donc important de vérifier que les propriétés décrites dans la page de l’API correspondent à la version utilisée dans votre projet. Les sources ne mentionnent aucune exigence de compte, d’abonnement ou de licence distincte.

Les extraits de code sont écrits en Python et utilisent l’API bpy de Blender. Exécutez-les dans un environnement ayant accès à l’API Python de Blender ; les exemples ne garantissent pas qu’un environnement Python externe puisse accéder aux données de Blender. Effectuer un premier essai sur une copie d’un fichier de projet important permet d’éviter que des modifications de données indésirables n’affectent la scène d’origine.

Créer un matériau pas à pas

1. Créer un nouveau bloc de données matériau

BlendDataMaterials.new(name) ajoute un nouveau matériau à la base de données principale et renvoie le bloc de données Material créé. Le paramètre name indique le nom à attribuer au nouveau bloc de données ; selon la documentation, cette valeur ne peut pas être None.

import bpy

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

À la fin de cette étape, la variable mat donne accès au matériau créé. Celui-ci est ajouté à la base de données, mais le code ne l’associe pas à une géométrie particulière. Il faut donc considérer la création du matériau et son utilisation dans la collection de matériaux d’un objet comme deux étapes distinctes.

2. Régler la couleur et l’aspect de la surface

La documentation répertorie diffuse_color, metallic et roughness parmi les propriétés d’un matériau. diffuse_color est défini comme un tableau de quatre éléments. La métallicité et la rugosité acceptent des valeurs comprises entre 0 et 1 ; la documentation indique une rugosité par défaut de 0,4 et une métallicité par défaut de 0.

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

Ces valeurs sont des points de départ donnés à titre d’exemple ; elles ne constituent pas une recette validée pour un produit ou un matériau de construction réel. Vous pouvez modifier les quatre composantes du tableau de couleur et les propriétés numériques selon vos besoins. Si vous préparez plusieurs variantes, choisir des noms de matériaux faciles à distinguer simplifie la gestion des éléments dans la base de données.

3. Choisir une méthode de transparence

Dans l’API Material actuelle, surface_render_method définit la manière dont les surfaces sont mélangées ainsi que la compatibilité de la méthode avec certaines fonctionnalités. La documentation propose deux options : DITHERED et BLENDED. DITHERED traite la transparence au moyen d’une distribution en niveaux de gris et est présenté comme compatible avec les passes de rendu et la prise en charge du ray tracing. BLENDED offre une transparence colorée, mais ne peut pas être utilisé avec les passes de rendu et le ray tracing, selon la documentation.

mat.surface_render_method = 'DITHERED'

Cette ligne choisit la méthode de transparence ; elle ne règle pas à elle seule un niveau d’opacité particulier. Si vous avez besoin d’une transparence colorée, vous pouvez envisager l’option BLENDED. Pour faire votre choix, vérifiez si la compatibilité avec les passes de rendu ou le ray tracing est nécessaire dans votre flux de travail.

alpha_threshold est également une propriété documentée du matériau. Les pixels dont la valeur alpha dépasse ce seuil sont rendus. La propriété accepte des valeurs comprises entre 0 et 1 et sa valeur initiale est indiquée comme étant de 0,5 dans la documentation. Si vous la modifiez, testez le résultat visuel souhaité et consultez la description de l’API pour la version de Blender utilisée.

4. Supprimer le matériau si nécessaire

Lorsqu’un matériau n’est plus nécessaire, BlendDataMaterials.remove permet de le supprimer du fichier blend actuel. do_unlink=True supprime les liens qui utilisent le matériau avant sa suppression. Les autres paramètres concernent la mise à jour des compteurs d’utilisateurs et la suppression des références de l’interface au matériau supprimé.

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

Avant d’exécuter ce code, vérifiez que le matériau à supprimer est le bon. do_unlink=True supprime également les liens d’utilisation avant la suppression ; si le matériau doit continuer à être utilisé dans la scène, cela peut entraîner un résultat indésirable. Tester d’abord cette étape sur une copie du fichier est une précaution utile.

Erreurs fréquentes

• Prendre une ancienne propriété pour la méthode actuelle : blend_method est une ancienne propriété pour les surfaces transparentes, et la documentation recommande d’utiliser surface_render_method. Pour un nouveau projet, privilégiez la méthode de l’API actuelle.

• Utiliser la propriété use_nodes comme un réglage : la documentation indique que cette propriété est obsolète depuis Blender 5.0. Elle précise que la modifier n’a aucun effet, que sa lecture renvoie toujours True et que sa suppression est prévue pour Blender 6.0. Nous ne l’utilisons donc pas dans le flux de travail présenté ici.

• Confondre les plages de valeurs des couleurs et des propriétés numériques : diffuse_color est un tableau de quatre éléments ; metallic et roughness acceptent des valeurs comprises entre 0 et 1. Vérifiez les types de données attendus et les plages dans la documentation de l’API.

• Confondre la création d’un matériau avec son attribution à un objet : la création d’un nouveau bloc de données ajoute le matériau à la base de données principale ; elle ne l’attribue pas automatiquement à un objet géométrique.

• Oublier les liens d’utilisation lors de la suppression : do_unlink=True supprime toutes les utilisations du matériau avant de le supprimer. Ne lancez pas de code de nettoyage dans le fichier actuel sans avoir compris les effets de cette option.

Utilisation dans les flux de travail d’architecture et de visualisation

Cette méthode constitue un point de départ pour les cabinets d’architecture, les architectes d’intérieur et les équipes de visualisation qui souhaitent générer par le code des blocs de données matériau similaires ou modifier leurs propriétés de base de manière reproductible. Lorsque plusieurs matériaux doivent suivre la même convention de nommage et les mêmes réglages de base, la création par le code peut réduire les opérations répétitives effectuées manuellement. Ce guide ne décrit toutefois pas de flux de travail portant sur l’attribution d’un matériau à un objet, le comportement de moteurs de rendu particuliers ou les bibliothèques de matériaux externes.

Avant de passer à un projet, comparez la version de Blender utilisée à la documentation actuelle de l’API et vérifiez la compatibilité de la méthode de transparence avec les passes de rendu et le ray tracing. Les sources ne précisant ni les exigences matérielles, ni les mesures de performance, ni les tarifs ou frais de licence, il est impossible d’en tirer une conclusion certaine sur ces points. Pour du code partagé au sein d’un cabinet, il est prudent de tester d’abord les étapes modifiant les données, comme la suppression, sur une copie du fichier.

Étapes suivantes

Une fois les étapes de création et de réglage de base opérationnelles, consultez les pages de l’API Material et BlendDataMaterials correspondant à la version de Blender utilisée, en fonction des besoins du projet. La documentation répertorie également la propriété node_tree du bloc de données matériau ainsi que différentes collections faisant référence aux matériaux ; ce guide n’explique pas comment les modifier. Pour définir la prochaine étape de développement, appuyez-vous sur les propriétés documentées et sur les besoins vérifiés du projet afin de limiter les problèmes de compatibilité.

Sources et licence

Ce guide a été adapté en turc à partir des pages BlendDataMaterials et Material de la documentation de l’API Blender. Les deux sources sont proposées sous licence CC BY-SA 4.0. Les exemples de code ont été écrits pour ce guide ; aucun extrait de code des sources n’a été repris.