Introduction to Blender Python API

satishgoda
at
gmail
dot
com

Introduction

Blender is a powerful 3D application for creating 3D images and animations and bring your creativity to life. The strength of Blender is its philosophy to provide a smooth and seamless work flow and tools for the artist. By interacting with the multitude of buttons, menu's using keyboard and mouse you can create objects, sculpt them, rig those objects etc., and eventually render your scene composed of aforementioned objects.

Apart from creating objects using devices, Python also enables you to create objects and other things using a scripting interface.

Blender uses the awesome and user-friendly Python scripting language
It provides extensive programming interface to match almost all the functionality of the application (hence called Blender Python API or BPY API).

Incase, you are new to Blender, please do watch the following video to get a hang on Blender 2.5 UI.

Blender 2.5 Overview from Jonathan Williamson on Vimeo.

Now, If you are absolutely new to Programming, please go through the excellent and free online e-book Learning With Python. (Note: I am in the process of writing a quick primer covering Python 3.1 which Blender 2.5 and up will be using)

In a nutshell, in order for us to program, one should be comfortable with creating, extracting and manipulating data with operations. Python provides us with very nice ways of dealing with data and get out job done.

Accessing Blender's Built-in Python Console

By pressing SHIFT+F4 in any Blender Window (3D View, Timeline etc.,) you can change it to a Console

Note:

Python is a case-sensitive language, so make sure you type the commands as shown in this tutorial (using the same case)

To check what symbols are loaded into the default environment, type dir() and press ENTER-KEY

Now, type bpy. and then press CTRL+SPACE-KEY and you will see the Console auto-complete feature in action. We will make use of this a lot to help our learning the API faster.

You will notice that a list of sub-modules inside of bpy appear. These modules encapsulate all that we can do with Blender Python API and are very powerful tools.

Exercise:

List all stuff inside the bpy.app module

We can now access the stuff (that was listed previously) one by one by typing bpy.app.stuff1and pressing ENTER-KEY

Now that you got a hang of this, lets proceed to investigate the more useful modules in bpy.

Basic BPY API Modules

If you look at the 3D Viewport in the default Blender scene, you will notice 3 objects: Cube, Lamp and Camera.

All objects exist in a context and there can be various modes under which they are operated upon.
At any instance, only one object is active and there can be more then one selected objects.
All objects are data in the Blender file.
There are operators/functions that create and modify these objects.

For all the scenarios listed above (not all were listed, mind you..) the bpy module provides functionality to access and modify data.

Let's start with the Contextual access of information in a Blender file/scene.

bpy.context

Type the following in the Console (>>> stands for Console input prompt)

>>> bpy.context. and press CTRL+SPACE-KEY to list everything inside it.

Names that end in ( are functions (driver_add, get, etc., )

Rest all are variables (mode, object, etc.,)

Note:

For the above commands to show the proper output, make sure you have selected objects in your 3D view.

bpy.context.mode

Will print the current 3D View mode (Object, Edit, Sculpt etc.,)

bpy.context.object

bpy.context.active_object

Will give access to the active object in the 3D View

Exercise: Try out.. (Enter following commands and press ENTER-KEY after each one)

>>> bpy.context.object.location.x = 1


Change x location to a value of 1

>>>

bpy.context.object.location.x += 0.5
Move object from previous x location by 1 unit

>>>

bpy.context.object.location = [1, 2, 3]
Changes x, y, z location

>>>

bpy.context.object.location.xyz = [1, 2, 3]
Same as above

>>>

type(bpy.context.object.location)
Data type of objects location

>>> dir(bpy.context.object.location)
Now that is a lot of data that you have access to

bpy.context.selected_objects

Will give access to a list of all selected objects (including the active object)

Exercise: Try out the following commands in the Blender console window.

>>> bpy.context.selected_objects then press CTRL+SPACE-KEY

>>>

bpy.context.selected_objects[0]
Prints out name of first object in the list

>>>

[object for object in bpy.context.selected_objects if object != bpy.context.object]


Complex one.. But this prints a list of objects not including the active object

bpy.data

bpy.data has bunch of functions and variables that give you access to all the data in the Blender file.

You can access following data in the current Blender file

objects, meshes, materials, textures, scenes, screens, sounds, scripts, texts, cameras, curves, lamps, brushes, armatures, images, lattices, libraries, worlds, groups, metaballs, particles, node_groups

Aint' it awesome.

Let's look at some examples.

Exercise:

>>> for object in bpy.data.scenes['Scene'].objects: print(object.name) (Press ENTER-KEY twice)


Prints the names of all objects belonging to the Blender scene with name "Scene"

>>>

bpy.data.scenes['Scene'].objects.unlink(bpy.context.active_object)


Unlink the active object from the Blender scene named 'Scene'

>>>

bpy.data.materials['Material'].shadows

>>>

bpy.data.materials['Material'].shadows = False

bpy.ops

The tool/action system in Blender 2.5 is built around the concept of operators. These operators can be called directly from console or can be executed by click of a button or packaged in a python script. Very powerful they are..

For a list of various operator categories, click here

Lets create a set of five Cubes in the 3D Viewport. First, delete the existing Cube object by selecting it and pressing X-KEY

The following commands are used to specify that the objects are created in layer 1

>>> layers = [False]*32

>>>

layers[0] = True

We create a reference to the operator that is used for creating a cube mesh primitive

>>> add_cube = bpy.ops.mesh.primitive_cube_add

Now in a for loop, we create the five objects like this (In the screenshot above, I used another method)
Press ENTER-KEY twice after entering the command at the shell prompt.

>>> for index in range(0, 5):
. . . add_cube(location=(index*3, 0, 0), layer=layers)

TADA!

Mega Exercise:

So far we have been typing directly in the built in Python console. For this exercise, do the following

With the mouse over the console, press SHIFT+F11 key to change window type to a Text Editor.
Press ALT+N to create a new empty file.
Type the following commands in the text editor
Press ALT+P to run the script.
Tada!
Now, change the 3D cursor location and press ALT+P in the Text Editor again.
Nice!!! Congratulations on finishing the exercise. :-)

Conclusion

So, I hope this quick introduction was helpful to get a basic understanding of the BPY API.

Just explore around, read the documentation and try it out. The official introduction to the Blender 2.5 Python API is here and you can also read about the Data Access API that was included as part of the first Blender 2.5 Alpha 0 Release.

If you have any suggestions/comments (or you found mistakes), please drop me a mail at the address below.

satishgoda at gmail dot com

Thank You,
Satish Goda.

Links & References

satishgoda at gmail dot com