Blender 3D: Noob to Pro/Advanced Tutorials/Python Scripting/Introduction

Python is a powerful, high-level, dynamic language. The version of Python used in Blender 2.67 is 3.3. If you are unfamiliar with Python, start with the Python book. If you are familiar with older (2.x) versions of Python, this page summarizes what’s new in 3.x.

If you are familiar with Python scripting in older versions of Blender, be aware that 2.5x/2.6x is completely different; the old Blender module is gone. Much of the functionality is now available through the bpy module, but don’t expect an exact 1:1 correspondence.

First Steps In Blender Scripting

Open a new, default Blender document. If you haven’t customized your settings, there will be a Timeline window along the bottom; change this to a Python Console . Perhaps increase its height to let you see more lines at once.

To start with, let’s find out what objects are present in the document. At the “>>>” prompt, type

bpy.data.objects

You should see the response

<bpy_collection[3], BlendDataObjects>

which isn’t actually all that informative. In fact what you have here is an iterator; to see its contents, just do the usual Python thing and convert it to a list. Try entering this:

list(bpy.data.objects) #or bpy.data.objects[:]

This time the response should be

[bpy.data.objects["Camera"], bpy.data.objects["Cube"], bpy.data.objects["Lamp"]]

which shows you how to refer to the three default objects you can see in the 3D View window.

Let’s get a reference to the Cube object for more convenient access: type

Cube = bpy.data.objects["Cube"]

Now let’s try querying the value of one of its attributes: type

Cube.delta_location

You should see the response

Vector((0.0, 0.0, 0.0))

The Vector type comes from the mathutils module provided by Blender. But unlike bpy, this is not automatically imported into the Python Console. So let’s bring it in for subsequent use: type

import mathutils

OK, now let’s try changing the location of the default Cube: type

Cube.delta_location += mathutils.Vector((1, 1, 1))

(Note the doubled parentheses: mathutils.Vector takes a single argument, which is a tuple of X, Y and Z coordinate values.)

Were you watching the 3D View when you pressed  ENTER ? You should have seen the cube jump to a different position. To make it move again, press  UPARROW  to bring back the above command, so you can execute it again with  ENTER . As soon as you do this, the cube will jump another step, like before. And that’s it—you’re scripting!

The bpy Module

The contents of the bpy module are divided into several submodules, among which are:

• bpy.data — This is where you find the contents of the current document.
• bpy.types — information about the types of the objects in bpy.data.
• bpy.ops — operators perform the actual functions of Blender; these can be attached to hotkeys, menu items and buttons. And of course they can be invoked from a script. When you write an addon script, it will typically define new operators. Every operator must have a unique name.
• bpy.context — contains settings like the current 3D mode, which objects are selected, and so on. Also accessible in the Console window via the global variable C.
• bpy.props — functions for defining properties. These allow your scripts to attach custom information to a scene, that for example the user can adjust through interface elements to control the behaviour of the scripts.

The mathutils Module

The module mathutils defines several important classes that are used heavily in the rest of the Blender API.

• Vector: the representation of 2D or 3D coordinates.
• Matrix: the most general way of representing any kind of linear transformation.
• Euler: a straightforward way of representing rotations as a set of Euler angles, which are rotation angles about the X, Y and Z axes. Prone to well-known pitfalls such as gimbal lock.
• Quaternion: on the face of it, a more mathematically abstruse way of representing rotations. But in fact this has many nice properties, like absence of gimbal lock, and smoother interpolation between two arbitrary rotations. The latter is particularly important in character animation.
• Color: a representation of RGB colours and conversion to/from HSV space (no alpha channel).

See Also

• Scripting & Extending Blender Advanced
• Blender 2.67.0 r56533 API Reference
• Blender site Python scripts catalog