Blender (jusqu'à 2.49)
API Python

 
English Version
  Index principal  Index Python
précédentIndex Python
Python: Modifier un mesh(1/5) Suivant
Avertissement sur les numéros de version.


Jusqu'au mois d'aout 2000, cette page etait réservée aux utilisateurs de Blender qui possèdent une Ckey. La Ckey etait un code personnel  qui déverrouillait les options payantes du logiciel. Pour contrôler si la clef etait correctement installée il suffisait de vérifier que l'on avait  bien un cercle doré à coté du nom du logicel dans le coin en haut à droite de l'écran.

ATTENTION: Depuis la version 1.8a, blender n'est plus bridé par la Ckey.  La version 1.8a se reconnait à cette bague verte dans le coin droit de l'écran:

ATTENTION ENCORE: De la version 2.10 à la version 2.12  Blender Python n'est plus compatible avec l'ancienne API python, ni avec la nouvelle (y compris la 2.25 et suivantes). En particulier, cette API suppose l'utilisation de Python 2.0 à la place du Python 1.5x ou de toute autre version du python plus récente.

De plus, mais cela n'a rien à voir avec les extensions de la version intégrale, les modules définis dans le paragraphe suivant n'existent pas.  Donc si vous utilisez cette version du logiciel n'espérez pas faire fonctionner les scripts écrits pour l'API 1.80 ou l'API 2.14 et suivantes. Une certaine forme de compatibilité a été conservé entre ces deux versions car un certain nombre de scripts d'importation sont basés sur l'API Blender 2.10 voir la page cohabr2pyt.htm  pour le détail des opérations à effectuer.

Avec Blender 2.14 et jusqu'à Blender 2.26, l'API python est restée relativement stable. A partir de Blender 2.28, une réforme en profondeur a supprimés toute les possibilités d'utilisation des anciennes fonctions de l'API210 ainsi qu'un certain nombre de fonction dans le module IPO. 

Présentation.



Complete Blender est équipé d'un langage de programmation, le Python,  qui donne accès aux différents objets qu'il contient.

C'est un langage interprété à mi-chemin entre le Basic, le C++ et le Modula, c'est-à-dire qu'il est constitué d'un noyau auquel sont ajoutés des éléments  que l'on peut charger en fonction de besoin et des objectifs que doit atteindre le script .
 

Les modules actuellement disponibles  dans Blender/python
Blender Le  module principal de Blender
Types Le module des  types de Blender
NMesh Le module d'accès de bas-niveau au réseau de polygones
Draw Le module d'interfacage avec la fenêtre d'affichage
BGL Le  module OpenGL de Blender
Object Le module d'accès  aux objets
Lamp Le module d'accès aux lampes
Camera Le module de la caméra
Material Le module d'accès aux Matériaux
World Le module d'accès au Monde (World)
Ipo Le module d'accès aux clefs d'animation IPO
Armature Le module d'accès aux Armatures
Bone Le sous-module Armature d'accès aux Bones
NLA Le sous-module Armature d'accès  aux actions
Curve Le module d'accès aux Courbes nurbs et, pas tout-à-fait, Bezier
Effect Le module d'accès aux Effets : particules, built, wave.
Image Le module d'accès aux Images
Lattice Le module d'accès aux Lattices
Library Le module d'accès aux données contenues dans un  fichier blender
Mathutils Le module d'accès aux fonctions mathématiques supplémentaires
Metaball Le module d'accès aux Metaballs
Noise Le module d'accès aux fonctions de bruits divers et de hasard
Registry Le module de gestion de données entre scripts
Scene Le module d'accès aux données de la scène
Render Le sous-module Scene  d'accès aux données de rendu
Sound Le module d'accès aux données sonores
Text Le module d'accès aux données et à la fenêtre de traitement de texte
Texture Le module d'accès aux textures
Window Le module d'accès aux fenêtres
Theme Le sous-module  Window pour accéder au paramètres des thèmes

Il fonctionne sur les principaux systèmes d'exploitation  dont  toutes les variantes de Windows et d'Unix, mais aussi: NeXt, BeOS, Mac. Il est gratuit et peut être redistribué.

Il est suffisamment simple pour être maîtrisé rapidement si on a quelques notions indispensables: 
 

savoir ce qu'est une liste
llier un module à un scrip, 
différencier une variable locale d'une variableglobale 
construire une fonction
ce qu'est un objet ou  une classe ou encore savoir comment utiliser  les fonctions attachées à tel ou tel objet...

Autant dire qu'il est facile à apprendre si on a déjà de bonnes notions de programmation, surtout de programmation orientée objet.

L'objectif de ce didactitiel, cependant, n'est pas de faire comprendre ce qu'est la programmation mais de fournir à n'importe qui (et pas spécialement à des élèves ingénieurs, on excusera le coté un peu trivial des informations) la possibilité d'apprendre à utiliser cet outil dans Blender. Notons au passage qu'il existe d'excellents sites consacrés à la programmation de scripts Python pour Blender où l'on pourra trouver des exemples plus élaborés mais en anglais, hélas.

La description du langage lui-même peut être obtenu à cette adresse:  http://www.python.org .Pour les francophones .

Differences entre Fenêtre de script et fenêtre de "link" (reliure).



Avant toute chose, comment se présente matériellement l'outil lui-même? Extérieurement (sous windows) c'est une DLL, une bibliothèque dynamique de fonction  qui se trouve dans le même répertoire que le fichier binaire de Blender. Au niveau de l'interface graphique il y a deux icones qui ouvrent deux fenêtres consacrées au python:

cette fenêtre permet d'écrire, c'est un traitement de texte très simple. Le script y est obligatoirement contenu.

   Quelques raccourcis:

       Alt-S: Sauvegarder le fichier ( les versions récentes posent problème en première sauvegarde, préférer le menu File)
       Alt-O: Ouvrir un fichier

       Alt-A: Selectionne tout le texte

       Alt-C: Copier la sélection
       Alt-V:  Coller ce qui se trouve dans le tampon de copie.
       Alt-X: Effacer la sélection.
       Alt-J: Sauter à la ligne n
       Alt-F:Trouver le texte surligné ou recommencer à chercher le même texte
       Alt-M: (B2.27) Envoie le texte sélectionné dans le tampon de l'objet texte. Environ 1000 signes peuvent être créés en même temps.

      Ctrl-C : (B2.3) Copier la sélection.
      Ctrl-X : (B2.3) Couper la sélection.
      Ctrl-V : (B2.3) Coller la sélection.

       Ctrl-Shif-V (B2.27 et sous win32 uniquement) Copie le contenu du presse papier dan sla fenêtre de traitement de texte de Blender.
       Ctrl-Shif-C (B2.27 et sous win32 uniquement) Copie le texte sélectionné dans presse papier. Il est alors possible de l'importer dans une autre application windows.

       Alt-U: (undo) Annuler.
       Alt-R: (redo)  Répeter.

       Alt-Shift-S : Menu (Select) Selection dont Jump vers ligne, très interessant pour déboggage de code.
       Alt-Shift-F : Menu (File] Fichier commandes standard habituelles
       Alt-Shift-E : Menu (Edit ) Edition couper, coller, copier, afficher le contenu du tampon de selection.
       Alt-Shift-V : Menu (View) Visualisation saut en début et fin de fichier, page suivante, page précédente

Fenêtre de "linkage" pour associer le fichier soit 

à une animation en général, donc à la scene, le script s'exécute image par image en utilisant quelques constantes indiquants le numéro de l'image ou le temps écoulé, 
soit :
à un objet en particulier, objet 3D ou lampe ou camera ... 
On peut utiliser le python pou reffectuer l'opération de manière automatique voir les pages :
cpl_LOD.htm#Lierunscriptalascene
cpl_3dcursorposition.htm#connecterlescriptalascene
Pour charger un script :


Avant d'écrire ses propres scripts il sera peut-être plus simple d'utiliser ceux qui existent déjà. Encore faut-il savoir les mettre au bon endroit. Aller dans la fenêtre de texte  ou faire shift-f11 . Vérifier que la fenêtre possède bien un en-tête comme celui-ci :

    1. cliquer le bouton d'ouverture de bloc de données  ou le 

    2. choisir OPEN NEW, ce qui ouvre une fenêtre sur le répertoire courant pour charger un  fichier ".py".
 

Comment cela marche-t'il?


Pour comprendre ce qui se passe réellement un exemple sera plus éloquent.
Si on se trouve dans un environnement windows, il faut ouvrir une fenêtre script en cliquant ADD, à la place d'OPEN et taper le texte suivant:
 

import Blender
import sys

obj=Blender.Object.Get()
print str(obj)
sys.stdout.flush()

ou bien sous linux  :
 

import Blender

obj=Blender.Object.Get()
print str(obj)

Ce script fait un appel au module Blender pour obtenir le contenu d'un objet. La fonction qui permet d'effectuer cette opération est la fonction Blender.Object.Get(). Ce n'est pas une fonction standard du langage python. Le python, en effet, peut être complété par une serie de modules contenants de nouveaux objets. Pour rappel: un objet en programmation orienté objet est un ensemble formé de méthodes ( en fait la fonctions, Get() est une méthode du sous-module Object  qui est contenu par le module Blender) et de données. Il faut donc commencer le script par une ligne demandant à l'interpréteur de charger le module contenant cette fonction . Si aucun nom d'objet n'est fourni à la fonction d'appel (on pourrait écrire Get('Plane') ),elle renvoie la totalité de la liste des objets qui existent actuellement en mémoire sans différencier l'appartenace à telle ou telle scène . 
 

Quand ces lignes furent écrites, l'affichage du contenu d'un objet était problématique . Il était nécessaire d'encadrer obj par la fonction str() . Depuis l'APi python de Blender s'est bien améliorée et supporte sans problème un print obj  . Pour les mêmes  raisons, sous Window, il était nécessaire de forcer l'affichage dans la console dos  avec la fonction sys.stdout.flush() .

Lancer l'exécution du script



C'est la combinaison de touche Alt-PKEY qui va activer le script  dans l'exemple qui est utilisé ici. Il est indispensable que la fenêtre de script soit active, c'est à dire que le pointeur souris soit à l'intérieur.

On notera au passage que ce n'est pas la seule façon. En effet,  un script peut être lié à l'execution d'une animation ou à un objet en particulier Dans ce cas, c'est le déclanchement de l'animation, ou le déplacement de l'objet (qui oblige Blender à re-dessiner la fenêtre) qui lancera l'exécution du script.

Affichage sur la console.



Evidemment si on s'attend à voir s'afficher cette liste dans la fenêtre courante on a de forte chance d'être déçu.
Par contre le contenu de la "console" a été modifié.

Il suffit donc de cliquer le bouton pour voir son contenu:

Une alternative consisterait à lancer Blender avec les parametres suivants:  blender -p 0 200 640 480 (une astuce empruntée à l'article de Strubi et Cartsen qui se trouve à cette adresse: http://www.blenderbuch.de/tutor/python1/python1_eng.html )

 
Cet affichage correspond à la structure du fichier standard que  Blender charge au lancement. Le signe  indique qu'il  s'agit d'un objet. Le python, grace à la commande print obj, a bien renvoyé une liste contenant un objet camera et un objet plane.

La commande len(obj) permet de savoir quelle est la longueur de la liste obj. 

En langage python les listes sont declarées et contenues entre deux crochets  "[" et "]". Pour obtenir ces signes  sur un clavier européen azerty, voir: Comment faire?)

Attention aux erreurs de traitement de texte:



    Il est  important de garder l'ordre des lignes du modèle car le python les exécute  l'une après l'autre.
    Les indentations et tabulations indiquent  au langage qu'il doit regrouper les instructions dans un
    sous-programme; donc, le texte:
 
obj = Blender.Object.Get()
print str(obj)
# obj est une liste
...

    est  exécuté sans erreur; alors que le texte (l'espace indenté est noté en rouge):
 

obj = Blender.Object.Get()
print str(obj)
# obj est une liste

...

    engendrera une erreur d'exécution:

    Les espaces en fin de ligne sont aussi à proscrire.
 

obj = Blender.Object.Get()
print str(obj) 
# obj est une liste
...

Augmenter les possibilités en utilisant les bibliothèques d'extension du  langage Python .



Malgré cet ajout, les nouveaux utilisateurs de scripts, le plus souvent parce qu'ils veulent utiliser un script d'importation ou d'exportation particulier, peuvent être confrontés à l'erreur:
Ils  imaginent tout de suite que l'archive de Blender qu'ils ont installé est incomplète ou que le script est truffé d'erreur. En fait, c'est une sorte de "baptême du feu". La première rencontre avec les extensions de python.

Comme il a été indiqué plus haut, sous Windows, Blender est accompagné d'un fichier nommé 'python23.dll', c'est le minimum nécessaire pour travailler en "scripting" dans un logiciel. Mais on peut tirer profit de bibliothèques de fonctions supplémentaires qui accompagnent la version complète du python.

Variable d'environnement 

Pour cela, il faut installer le langage lui-même dans un répertoire de son disque dur. Peu importe le nom. Il y a cependant une règle à respecter pour ne pas avoir de problème: le nom complet du répertoire ne doit pas contenir d'espace vide. Par exemple: "C:\Program Files\python" ne sera pas trouvé, alors que "C:\ProgramFiles\python", oui. Ce problème est lié à l'obligation de définir une variable d'environnement dans son fichier autoexec.bat, or il se trouve que l'espace vide est interprété par le MSdos comme une limite de commande.
...
SET PYTHONPATH=C:\PROGRAMSFILES\PYTHON;C:\PROGRAMSFILES\PYTHON\DLLs;C:\PROGRAMSFILES\PYTHON\LIB
...
Le fichier autoexec.bat se trouve dans le répertoire racine du disque de démarrage de windows. Dans certaines versions de Windows comme Windows NT ou Windows 2000, il n'existe pas de fichier autoexec.bat mais on peut l'ajouter sans crainte, à condition de se limiter exclusivement aux variables d'environnement. Voir aussi la page :variables d'environnement python sous Window XP

Pour quelques renseignements sur l'environnement Linux voir: Python, corriger le  Path...
 

MODIFICATION IMPORTANTE  dans Blender 2.34
   à partir de cette version la dll python qui accompagne Blender est doublée d'un fichier zippé dans lequel sont regroupés  des modules  indispensables  à l'exécution des scripts qui accompagnent le logiciel en standard  . L'installation d'une version complète du python n'est plus plus absolument nécessaire dans tous les cas .

Une autre méthode consiste à indiquer le chemin dans Blender même. En effet, il y existe un bouton "Python:" dans la fenêtre Info

Il est indispensable d'y indiquer au moins l'adresse des librairies, exemple: "C:\PROGRAMSFILES\PYTHON\LIB" .
Il faut aussi penser à sauvegarder le fichier standard avec la commande Ctrl-U.

Nouvelle interface graphique pour le lancement des scripts

Dans les dernières versions du logiciel, il est possible de lancer les script à partir de menus . Ces menus sont dispercés dans l'ensemble du logiciel mais il toujours possible de passer par un menu principal qui les regroupe tous . 

Ce menu principal est disponible dans la fenêtre Scripts. Il est encore assez variable  .  D'une version à l'autre, des entrées apparaissent ou disparaissent, ou encore sont transférées dans d'autres sous menus

Attention à ne pas comettre de confusion :  ce menu lance les scripts mais ne les charge pas nécessairement  dans la fenêtre de traitement de texte. Ce qui peut porter à confusion car tous les sscripts ne sont pas obligatoirement préparés pour être lancés par menu. 

Conclusion:


Toutes ces notions sont nécessaires à la maîtrise matérielle de l'outil mais ne sont pas spécialement intéressantes pour la productions de formes ou d'images. La page suivante explique comment utiliser le python pour modifier les positions des sommets d'un réseau carré de polygones.
 
 
 
 
précédentIndex Python
Python: Modifier un mesh(1/5)  Suivant
Haut de page

Les questions concernant cette page peuvent être posées sur  :
 news://news.zoo-logique.org/3D.Blender


 

 

Livre en français
Blender : apprenez, pratiquez, Créez, livre, Ed. Campus Press, coll. Starter Kit
Blender Starter Kit

Forum
FAQ
Lexique
Didacticiels
Compilations
Blender2KT
Débuter
Modelage
Blender python
Materiaux
Lumière
Animation
API python (eng)
Archives nzn
Statistiques
Doc flash Sculptris
Galerie Sculptris

mon site de démos sur youtube