Page status (reviewing guidelines)
Copy This page is a copy of the same page in 2.4 manual, need to be updated
Drivers are used to control the animation of one property based on the value of another. This means that their animated value is not controlled by the frame number, but rather by any specified channel. Drivers can take their effects from single properties, differences in rotation, or scripted Python expressions which can be edited inside the UI controls.
For example you could use the X location of a driver to control the colors (RGB curves) of a material, use the rotation of a driver to control the scale of an object, use the scale of a driver to control the shape (through shape keys) of a mesh/curve/etc., use a python function to control a constraint’s influence, and much much more…
One key usage of drivers is in character animation: for example, you can add object drivers to the relative shape keys of a face. Then, you manipulate the expressions of your character just by moving these drivers objects (which are set unrenderable, of course!). A bit like using the NLA, but even more friendly! See Driven Shape Keys.
Although their interface and function is similar to that of an F-curve, they sit outside Actions, alongside them in the animation system hierarchy. Drivers are evaluated after Actions, so any F-Curve animation that may be in Actions on the data block will be overridden by the effects of a Driver.
A driven curve is not controlled by time (yes, we insist, but it’s very important to understand this). It’s rather its driver’s property changes that control where along the X axis of the curve its value is to be taken (i.e. the curve now maps the driver’s property value to the curve’s property value).
By default, there is a 1 to 1 mapping between the input value, and the output value, defined by a Generator F-Curve Modifier. You can create a custom mapping by deleting this modifier and entering keyframes into the graph area by pressing Ctrl + LMB .
To create a driver, find the desired attribute you want to drive, in the properties panel. This will be the attribute that will be driven by another attribute.
- Add Drivers
- This will create drivers for channels related to the selected one. For example, it will add drivers to the X, Y, and Z translate.
- Add Single Driver
- This will just add a single driver to the selected channel.
After you have created a driver, you need to specify how that channel will be driven, and by what.
The driver editor is located in the Graph Editor. You can switch from the F-Curve Editor view to the Driver view using the menu on the header.
The Driver editor displays all driver in the current scene. They are listed in the Channel pane on the left side.
If you have multiple drivers in the scene, you can toggle their visibility in the graph area. Also, you need to select the specific channel to begin editing it.
The driver's properties are located in the Properties Panel on the right side. (This panel is hidden, by default - you can open it by hitting N.)
- Update Dependencies
- Refreshes the drivers connections.
There are several different driver types that define how the input value of the driver is calculated:
- Maximum Value
- Takes the highest value of the user variables.
- Minimum Value
- Takes the lowest value of the user variables.
- Sum Values
- Takes the sum of user variables
- Averaged Values
- Averages the values of the user variables
- Scripted Expression
- Computes a value based on a simple python expression, which can also make use of user variables. (see below)
User Variables are what produce the input values for a driver. You need at least one variable, unless you are using a scripted expression. When using a single variable, all the driver types listed above, except scripted expression, will produce the same value.
Use the Single Property type to call an arbitrary unique datablock from anything within the scene. This can be anything from the intensity of a lamp, to the color of a texture
This type allow you to control curves through an object's transform properties – hence, one driver can control separately up to nine curves (the three components of its location, rotation and scale).
To set up an object driver:
- Select the channel you want to drive.
- In the OB field that appears, enter the name of the chosen driver object.
- Unless your driver is an armature, you have only one choice in the Driver type drop-down list, Object.
- Finally, select in the second drop-down list the property you want to drive your curve (Loc X, Scale Z, etc.).
Now, your curve is no more directly controlled by the time, but rather by the value of the property you chose. The values are in Blender Units.
Note that the space in which the driver’s properties are evaluated is the local one (i.e. parent’s transformations have no effect).
In this example, we are going to control the size of the well-known monkey head (
Suzanne) with the Y-location of the
Empty driver. So, we Add Driver to the three ScaleX, ScaleY and ScaleZ channel of the
Suzanne object (as usual, if there is no curve yet, it is automatically created). Note that for now, there is no curve, so Blender applies a one-to-one mapping, as if there was virtual unitary gradient linear curves (materialized as yellow dashed lines in the pictures below). This also illustrates that you can use the same driver property (here, the Y location) for several different drivers…
|Note that the Curve Editor window is pinned to |
Now, we can use curves on drivers to get more complex behavior than the basic one-to-one mapping. Below, we have the same scene as above, but the ScaleY channel now has a pseudo-sinusoidal curve, oscillating between 1.0 and -1.0 values on a one-frame period, created with three control points and the Cyclic extrapolation (E). This means that, while the X and Z components of
Suzanne’s scale are still directly controlled by the Y location of
Empty, the Y scale component now cyclically varies between 1.0 and -1.0, as the following pictures illustrate.
Rotational difference works only on bones, but are nearly the same as object ones.
You set up a bone driver by entering in the OB field an armature’s name, and then selecting the Pose option in the Driver type drop-down list. Then enter the bone’s name in the BO field that appears, and select its property to be used.
Note the following specificities:
- The transformations are evaluated in the bone’s space (i.e. parent bone’s transformations, as well as whole object’s ones, have no effects).
- When using the rotation as driver property, you’ll find a limitation: the evaluated bone’s rotation is always mapped into a
[-180°, 180°[range (which means that if you e.g. rotate your bone over the 180° value, the driven object will “jump back” to its -180° X-curve-position…).
- You have an extra driver property: Rotation Difference takes the name of another bone, and uses as driver the angle’s value between the two bones.
Distance mode simply takes the distance between two objects or bones
Python expression drivers (or “pydrivers” for short) allow you to use one-line Python expressions as input for a channel, instead of using a property of another object, like standard drivers do. An expression in programming is any combination of symbols that can be evaluated to a definite value.
To set up an expression driver, change the driver type to Scripted Expression – it will display a standard text field where you can type your Python expression.
These drivers open up many interesting possibilities: you 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 oscillate around a given point, or using random values at each animation frame to change some material attribute, like diffuse rgb, alpha, etc.
Note that 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).
We’ve already told the basics: there is a text field where you can type an expression in Python. Here are some examples of valid expressions:
- Any real value:
- 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
- Using the animated (driven) object, available as
self.LocX * 10
Builtin resources and aliases
Pydrivers use their own global dictionary that is cached and only gets recreated when any expression fails. In this dictionary, a few modules are pre-imported, so that they can be used inside pydriver expressions.
To save typing and keep expressions smaller, we’ve added aliases for each module: Blender can be referenced as “
- All from
m.cos(m.pi * b.Get("curframe") / n.random())
Aliases were also added for a few commonly needed data:
ob(name)is equivalent to
me(name)is equivalent to
ma(name)is equivalent to
ob("Cube").LocX + ob("Lamp").RotZ
The pydrivers.py Blender text
Besides the above modules, if there’s a Blender text buffer called “
pydrivers.py” loaded in the Text Editor, it’s also imported:
This allows users to create their own functions and add their own variables without the restriction of the one-line Python expression. For example, if your pydrivers.py text looks like this:
myvar = 10.0
# do something fancy here
You can access both
myfunction inside any expression:
p.myvar * p.myfunction(2) - 1
Note: if you make updates to the
pydrivers.py text, go to the Curve Editor 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.
Let’s say we want to give our
Suzanne a perfect two BU radius circle movement in the (XY) plane. This is not easy to achieve with standard curves, as you have to create perfect sinusoidal ones (for those who lost their math, a perfect circle in a Cartesian plane is obtained with
x = sin(t) and
y = cos(t)…). So let’s use Python drivers:
math functions take as input a radian value (i.e. a cycle takes
2π frames to complete), and output a value in range
[-1.0, 1.0]. So, to get a 2BU radius circle fully walked in 50 frames (two seconds in PAL videos), we have to use the following Python expression:
- For LocX:
2.0 * math.sin(Blender.Get("curframe")*math.pi/25)
- For LocY:
2.0 * math.cos(Blender.Get("curframe")*math.pi/25)
Suzanne will go in endless circles around the world’s origin (if you want to make it turn around another point, just add an offset to the above expressions, or drive dLoc… curves…).
- In the above example, we did not use F-curves.
- You can also get a perfect circular movement by using a NURBS circle curve as a path…
- The Blender 2.49 Python API reference and the chapter on extending Blender with Python.
- 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, the patch tracker entry, with patch and sample .blend files for pydrivers: right here.