テンプレート:Release Notes/2.42/Python/Tools

Python Expressions

Better Integration

Blender 2.42 gives access to Python evaluation for numerical gui fields (buttons) and ipo drivers. So now users can write expressions in Python to define button values and to control ipo channels, like an object's location, rotation and scale, plus many more possibilities.

It does require some knowledge of Python and basic mathematics for anything but the most trivial uses, but even someone with absolutely no interest in programming can benefit from expressions written by other users, of course.

Button Evaluation

Any button in Blender that accepts a range of integer or float values accepts now a Python expression, as long as it evaluates to a number.

Important: to tell the program that you're entering an expression, it needs to start with the hash symbol (#), that's the only difference between expressions for buttons and for pydrivers, where the hash should not be used.

PyDrivers

About Ipo Drivers: "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)

About Python Ipo Drivers: 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.

Usage Instructions

The information below is valid both for buttons and pydrivers.

Python evaluation opens up many interesting possibilities: we can use mathematical functions and more general programming to define button values or drive object animations. (Note for Python programmers: this is equivalent to what the builtin eval() function does.) 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.

A simple example for drivers would be using sines or cosines to make objects oscilate around a given point, for example. Or (ugh) using random values at each animation frame to change some material attribute, like diffuse rgb, alpha, etc.

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 (reminder: these are for pydrivers, prepend a '#' to use them in number buttons):

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 and "pybuttons" 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 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

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:

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.

Demo .blend files

Old entry in the patch tracker: Pydrivers

There are a couple of lousy .blend files there, too, demonstrating a few possibilities. Please check the README text in each .blend to get specific info about them.

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