Dev:2.4/Source/Animation/PyDrivers

New (March 29, 2007)

Expressions can now use the name "self" to reference the object they belong to. Example: self.LocY. This should be available in Blender versions > 2.43.

Pydrivers: Python Ipo Drivers

Ipo Drivers

About: "An IpoDriver is like an IpoCurve, but instead of a Bezier curve, it allows to connect a property of other Objects as input for the "channel". For example, IpoDrivers can be used to have a Shape Key being "driven" by the rotation of a Bone. Or the RGB colors of a Material get driven by the XYZ location of an Object."
Where they are: "Editing of Drivers happens in the IpoWindow. Here you can notice that the channels (...) now have an "active" channel indicator. To add a Driver, you have to use the "Transform Properties" Panel (Nkey). Here you can add or remove a Driver to the active channel, and use the buttons to fill in what kind of relationship you want to establish."

(excerpts taken from http://www.blender.org/cms/Ipo_Drivers.680.0.html maintained by Ton Roosendaal)

Pydrivers

About: Pydrivers allow to use one-line Python expressions as input for a channel, instead of using a property of another object, like normal ipo drivers do. An expression in programming is any combination of symbols that can be evaluated to a definite value.
Where they are: When adding a driver, like explained above, click on the small "Python" icon at the "Transform Properties" panel and a text input box will appear. Write your py expression there.

These drivers open up many interesting possibilities: we can use mathematical functions and more general programming to drive object animations. The only restriction is that the pydriver expression itself must return a real number when evaluated and not, e.g., a string or something else.

Examples would be using sines or cosines to make objects oscilate around a given point, or using random values at each animation frame to change some material attribute, like diffuse rgb, alpha, etc.

Note for Python programmers

Pydriver evaluation is equivalent to what the builtin eval() function does, with the restriction that pydriver expressions must return real numbers (any type of number that can be automatically cast to a float).

Instructions

Valid Expressions

We've already told the basics: there are text input boxes where you can type expressions in Python. Here are some examples of valid expressions:

any real value: 1.0
expressions with numbers and operators: 4.5 + 8.9 * 7.0 - (2 / 3.0)
expressions also with variables: math.pi * 2 + 5.0
available data: Blender.Get("curframe") # the current animation frame
a little math: math.sin(Blender.Get("curframe")) # the sine of the current frame!?

Builtin resources and aliases

Pydrivers use their own global dictionary that is cached and only gets recreated when any expression fails.

In this dictionary we pre-import a few modules so they can be used inside pydriver expressions:

Note: to save typing and keep expressions smaller, we've added aliases for each module: Blender can be referenced as "Blender" or simply as "b". Below each module is followed by its available aliases:

all from builtin (the default builtin module)
Blender: blender, b
Blender.Noise: noise, n
math: math, m

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

Aliases were also added for a few commonly needed data:

ob(name) is equivalent to Blender.Object.Get(name)
me(name) is equivalent to Blender.Mesh.Get(name)
ma(name) is equivalent to Blender.Material.Get(name)

Example expression: ob("Cube").LocX + ob("Lamp").RotZ

NEW (March 29, 2007): the name "self" was added to the pydrivers dictionary, as a way to easily access the object that owns a given expression.

Example expression: self.LocX * 10

The pydrivers.py Blender text

Besides the above modules, if there's a Blender text called "pydrivers.py" loaded in the Text Editor, it's also imported:

pydrivers: pydrivers, p

This allows users to create their own functions and add their own variables without the restriction of the one-line py expression. For example, if your pydrivers.py text looks like this:

myvar = 10.0

def myfunction(arg):
  # do something fancy here
  return float_val

You can access both myvar and myfunction inside any expression:

'''Example expression:'''
<code>
p.myvar * p.myfunction(2) - 1

Note: if you make updates to the pydrivers.py text, go to the Ipo window and click in any pydriver's text input box (in the Transform Properties panel), then click out of it or press ENTER, to force reloading the pydrivers.py module and to update all pydrivers at once.

Patch and sample .blend files

Entry in the patch tracker: Pydrivers

The patch there is against current cvs.

There are a couple of lousy .blend files there, too, demonstrating a few possibilities. The fishes.blend one was inspired by an artist's demo pointed to me by UnNamed (GSR, thanks!). Please check the README text in each .blend to get specific info about them.

TODO

~~Commit?~~ UPDATE: pydrivers are in CVS as of Sun April 30.
UPDATE: clicking in and out of any pydriver's text input box is enough to at once reload "pydrivers.py" if available, re-evaluate all pydrivers (check console to see if errors were found) and update Blender's dependency graph (the DAG). Do we need to add an entry (like "Update PyDrivers") to some menu, too?
As a test I disabled the restriction that pydriver expressions can't reference their own object (this is an ipo driver restriction related to the dependancy graph). If we really have to follow that restriction also with pydrivers, the code to force it just needs to be uncommented in EXPP_interface.c.

Links

Check the docs in this very wiki's Main Page for Blender and Blender Python API references.
Python and its documentation
this might be a good hunting ground for those looking for functions to try with pydrivers: http://functions.wolfram.com/ (newcomers are recommended to start with elementary ones, specially trigonometric).
Finally (and again), the patch tracker entry, with patch and sample .blend files for pydrivers: right here