From BlenderWiki

Jump to: navigation, search
Blender3D FreeTip.gif
IMPORTANT! Do not update this page!
We have moved the Blender User Manual to a new location. Please do not update this page, as it will be locked soon.
NdT
Cette page fait partie des pages développeurs, et non du manuel proprement dit. Elle est cependant utile, et est incluse dans l'index de la version originale (anglaise) du manuel, je l'ai donc traduite…


Nouveau (29 Mars 2007)

Les expressions peuvent maintenant utiliser le nom "self" pour référencer l'objet auquel elles appartiennent. Exemple: "self.LocY". Cela devrait être valable pour toute version de Blender 2.43 et supérieure.

Pydrivers: Python Ipo Drivers (alias contrôleurs Python d'IPO)

Ipo Drivers (alias contrôleurs d'IPO)

De quoi s'agit-il?
«Un IpoDriver est comme une IpoCurve, mais à la place d'une courbe de Bézier pour contrôler la valeur de ce "canal", on peut y relier une propriété d'un autre objet pour remplir ce rôle. Par exemple, les contrôleurs d'IPO peuvent être utilisés pour contrôler une Shape Key avec la rotation d'un Bone, ou une couleur RGB d'un matériau avec les coordonnées XYZ d'un objet…»
Où sont-ils?
«Les contrôleurs sont édités dans la fenêtre IPO. Vous pouvez notez ici que les canaux […] ont maintenant un indicateur "actif". Pour ajouter un Driver, vous devez utiliser le panneau Transform Properties (N). Vous pouvez alors y ajouter ou enlever un contrôleur au canal actif, et utiliser les boutons pour établir la relation que vous voudrez entre contrôleur et IPO.»

(Extraits traduits depuis la page [1], maintenue par Ton Roosendaal.)

PyDrivers

De quoi s'agit-il?
Les PyDrivers permettent d'utiliser une expression Python d'une seule ligne comme entrée pour un canal, au lieu d'utiliser une propriété d'un autre objet, comme le font les Ipo Drivers normaux. En programmation, une "expression" est toute combinaison de symboles pouvant être évaluée à une valeur précise.
Où sont-ils?
Quand vous ajoutez un contrôleur, comme expliqué ci-dessus, cliquez sur la petite icône "Python" dans le panneau Transform Properties, et un champ texte va apparaître. Entrez-y votre expression Python.

Ce type de contrôleur ouvre beaucoup de possibilités très intéressantes: nous pouvons utiliser des fonctions mathématiques, et plus généralement tout algorithme programmable, pour contrôler les animations d'objets. La seule contrainte est que l'expression elle-même doit retourner une nombre réel quand elle est évaluée, et non, par exemple, une chaîne de caractères, …

De simples exemples d'utilisation serait les sinus ou cosinus pour faire osciller des objets autour d'un point donné, ou (berk!) d'utiliser des valeurs aléatoires à chaque images pour modifier un attribut de matériau, comme Diffuse RGB, Alpha, etc.

Note pour les programmeurs Python
L'évaluation des PyDrivers est équivalente à celle faite par la fonction python "eval()", à ceci près que les expressions PyDriver doivent retourner un nombre réel (tout type de nombre pouvant être automatiquement converti en float).


Instructions

Expressions valides

Nous avons déjà présenté les bases: il s'agit d'une ligne de texte dans laquelle vous rentrez votre expression en Python. Voici quelques exemples d'expressions valides:

  • N'importe quelle valeur réelle: 1.0;
  • Des expressions avec nombres et opérations: 4.5 + 8.9 * 7.0 - (2 / 3.0);
  • Des expressions avec des variables: math.pi * 2 + 5.0;
  • Des données disponibles: Blender.Get("curframe") # l'image courante dans l'animation;
  • Un peu de maths: math.sin(Blender.Get("curframe")) # le sinus du numéro de l'image courante!?.


Ressources incorporées et alias

Les PyDrivers utilisent leur propre dictionnaire global qui est mis en cache, et n'est recréé que quand une expression ne réussit pas.

Dans ce dictionnaire nous pré-importons quelques modules qui peuvent alors être utilisés dans les expressions PyDrivers.

Note
Pour raccourcir les expressions, nous avons ajouté des alias pour chaque module: Blender peut être référencé comme "Blender" ou simplement "b". Ci-dessous chaque module est suivi par ses alias disponibles…


  • Tout ce qui est incorporé (builtin – le module incorporé par défaut);
  • Blender: blender, b;
  • Blender.Noise: noise, n;
  • math: math, m.

Exemple d'expression:

m.cos(m.pi * b.Get("curframe") / n.random())

Des alias ont également été ajoutés pour quelques données couramment utilisées:

  • "ob(name)" est équivalent à "Blender.Object.Get(name)";
  • "me(name)" est équivalent à "Blender.Mesh.Get(name)";
  • "ma(name)" est équivalent à "Blender.Material.Get(name)".

Exemple d'expression:

ob("Cube").LocX + ob("Lamp").RotZ

NOUVEAU (29 Mars 2007): Le nom "self" a été ajouté au dictionnaire des PyDrivers, comme manière d'accéder facilement à l'objet à qui appartient l'expression.

Exemple d'expression:

self.LocX * 10


Le tampon texte pydrivers.py

En plus des modules ci-dessus, s'il y a un texte chargé dans l'éditeur Text de Blender, appelé "pydrivers.py", il est aussi importé:

  • pydrivers: pydrivers, p.

Cela permet aux utilisateurs de créer leurs propres fonctions et leurs propres variables Python, sans la restriction de l'expression sur une seule ligne. Par exemple, si votre texte "pydrivers.py" ressemble à:

myvar = 10.0
def myfunction(arg): # faites quelque chose d'utile ici, retournez une float_val

vous pouvez accéder à "myvar" et à "myfunction" dans n'importe quelle expression:

Exemple d'expression:

p.myvar * p.myfunction(2) - 1
Note
Si vous modifiez le texte "pydrivers.py", allez à une fenêtre IPO et cliquez dans n'importe quel entrée texte PyDriver (dans le panneau Transform Properties), puis cliquez en dehors ou pressez ↵ Enter, pour forcer Blender à recharger le module "pydriver" et pour mettre à jour tous les PyDrivers en même temps.


"Patch" et fichiers .blend d'exemple

Entrée dans le tracker de patch:

Pydrivers

Ce patch est valable sur le CVS courant ("The patch there is against current cvs").

Il y a aussi une paire de mauvais fichiers .blend, comme exemple de quelques applications. Le fichier "fishes.blend" a été inspiré par une démo d'artiste qui m'a été indiquée par UnNamed (merci, GSR!). Lisez les textes README de chaque fichier .blend pour plus de détails à leur propos.

TODO

  • Commit? UPDATE: Les PyDrivers sont dans le CVS depuis dimanche 30 Avril (NdT: quelle année? 2007?).
  • UPDATE: cliquez dans puis hors le champ texte des PyDrivers suffit pour recharger d'un coup "pydrivers.py" s'il est présent, ré-évaluer tous les PyDrivers (contrôlez la console pour les éventuelles erreurs) et mettre à jour le DAG de Blender (Dependency Graph, graphe des dépendances). Besoin d'ajouter aussi une entrée (comme "Update PyDrivers") dans un menu?
  • Comme test j'ai désactivé la restriction comme quoi les expressions PyDrivers ne peuvent faire référence à leur propre objet (c'est une restriction des contrôleurs d'IPO liée au graphe des dépendances). Si nous avons vraiment besoin de respecter cette restriction même pour les PyDrivers, le code pour le forcer à juste besoin d'être dé-commenté dans "EXPP_interface.c".


Liens

  • Lisez la doc de ce wiki en français et en anglais sur les références sur Blender et son API Python.
  • Python et sa documentation.
  • Voici un bon "terrain de chasse" pour ceux qui cherchent des fonctions à essayer avec les PyDrivers: [2] (les nouveaux venus ont intérêt à commencer avec les fonctions élémentaires, comme les trigonométriques).
  • Pour finir (et à nouveau), l'entrée dans le tracker de patch, avec le patch et des fichiers .blend d'exemple, ici.