Taken together this means we can achieve a lot of things from Python scripts. We can:

That last statement shows one of the current weaknesses of the Blender API: any object property that the developers add in the Blender C source must be provided separately in the Python API. There is no automatic conversion from internal structures to the interface available in Python and this means that efforts must be duplicated and may lead to omitted functionality. For instance, in Blender 2.49 it is not possible at all to set up a fluid simulation from a script. Although it is possible to set up a particle system, there is no way to set the behavioral characteristics of a boids particle system.

Another problem of the 2.49 Python API is that many of the actions a user may choose to perform on an object have no equivalent in the API. Setting simple parameters such as the camera angle or performing a rotation of any object is easy and even associating for example, a subsurface modifier to a mesh is just a few lines of code but common actions, especially on mesh objects, such as subdividing selected edges or extruding faces are missing from the API and must be implemented by the script developer.

These problems led the Blender developers to completely redesign the Blender Python API for the 2.5 version, focusing on feature parity (that is, everything possible in Blender should be possible using the Python API). This means that in many situations it will be far easier to get the same results in Blender 2.5.

Finally, Python is used in more places than just standalone scripts: PyDrivers and PyConstraints enable us to control the way Blender objects behave and we will encounter them in later chapters. Python also allows us to write custom textures and shaders as part of the nodes system as we will see in Chapter 7, Creating Custom Shaders and Textures.

Also, it is important to keep in mind that Python offers us far more than just the (already impressive) tools to automate all sorts of tasks in Blender. Python is a general programming language with an extensive library of tools included, so we do not have to resort to external tools for common system tasks such as copying files or archiving (zipping) directories. Even networking tasks can be implemented quite easily as a number of render farm solutions prove.

When we install Blender, a Python interpreter is already part of the application. This means that it is not necessary to install Python as a separate application. But there is more to Python than just the interpreter. Python comes with a huge collection of modules that provide a wealth of functionality. Anything from file manipulation to XML processing and more is available, and the best bit is that these modules are a standard part of the language. They are just as well maintained as the Python interpreter itself and (with very few exceptions) available on any platform that Python runs on.

The downside is, of course, that this collection of modules is fairly large (40MB or so), so the Blender developers chose to distribute only the bare minimum, primarily the math module. This makes sense if you want to keep the size of the Blender downloads manageable. Many Python developers have come to depend on the standard distribution because not having to reinvent the wheel saves huge amounts of time, not to mention it's not an easy task to develop and test a full-fledged XML library say, just because you want to be able to read a simple XML file. That is why it is now more or less a consensus that it is a good thing to install the full Python distribution. Fortunately, the installation is just as easy as the installation of Blender itself, even for end users, as binary installers are provided for many platforms, such as Windows and Mac, also in 64-bit versions. (Distributions for Linux are provided as source code with instructions on how to compile them, but many Linux distributions either already provide Python automatically or make it very easy to install it afterwards from a package repository).

Chances are that you already have a full Python distribution on your system. You can verify this by starting Blender and checking the console window (the term console window refers to either the DOSBox that starts in parallel on Windows or the X terminal window where you start Blender from on other systems) to see if it displays the following text:

Compiled with Python version 2.6.2.
Checking for installed Python... got it!

If it does, then there is nothing you have to do and you can skip to The interactive Python console section. If it shows the following message then you do have to take some action:

Compiled with Python version 2.6.2.
Checking for installed Python... No installed Python found.
      Only built-in modules are available.  Some scripts may not run.
      Continuing happily.

The steps toward a full Python installation for Windows or Mac are as follows:

On Ubuntu Linux, the first step is not needed and installing can be done by using the built-in package manager:

sudo apt-get update
sudo apt-get install python2.6

Other distributions might use a different package management system so you might have to check the documentation for that. Under Windows it might be necessary to set the PYTHONPATH environment variable, although this is unlikely when using the provided packages.

To see where Blender actually looks for modules you may look at Python's sys.path variable. To do this you have to start up Blender's interactive Python console. Note that you use a different and possibly confusing notion of console here—the DOSBox or the terminal window that is started alongside Blender's main application window and where various informational messages are displayed is referred to as console as well! The Python interactive console that we want to use now is started from the script window:

Once the interactive Python console is started, type the following commands:

import sys
print sys.path

Note that the interactive Python console does not show any prompt (unless when expecting indentation, for example within a for loop) but anything you type will be in a different color (white on black by default) from what is returned (that will be blue or black). The two preceding commands will give us access to Python's sys module that contains various variables with system information. The sys.path variable that we print here will hold all of the directories that will be searched when we try to import a module. (Note that importing sys will always work because sys is a built-in module.) The output will be something similar to:

['C:\\Program Files\\Blender Foundation\\Blender', 'C:\\Program Files\\Blender Foundation\\Blender\\python26.zip', 'C:\\Python26\\Lib', 'C:\\Python26\\DLLs', 'C:\\Python26\\Lib\\lib-tk', 'C:\\Program Files\\Blender Foundation\\Blender', 'C:\\Python26', 'C:\\Python26\\lib\\site-packages','C:\\Python26\\lib\\site-packages\\PIL', 'C:\\PROGRA~1\\BLENDE~1\\Blender', 'C:\\Documents and Settings\\Michel\\Application Data\\Blender Foundation\\Blender\\.blender\\scripts', 'C:\\Documents and Settings\\Michel\\Application Data\\Blender 
Foundation\\Blender\\.blender\\scripts\\bpymodules']

If your Python installation directory is not in this list then you should set the PYTHONPATH variable before starting Blender.

The dir() function lists all members of an object. That object can be an instance, but also a class or module. For example, we might apply it to the Blender.Lamp module:

dir(Blender.Lamp)

The output will be a list of all members of the Blender.Lamp module. You can spot the Get() function that we encountered earlier:

['ENERGY', 'Falloffs', 'Get', 'Modes', 'New', 'OFFSET', 'RGB','SIZE', 'SPOTSIZE', 'Types', '__doc__', '__name__', '__package__','get']

Once you know which members a class or module has, you can then check for any additional help information for these members by applying the help() function.

Of course both dir() and help() are most useful when you already have some clue where to look for information. But if so, they can be very convenient tools indeed.

To get used to the editor, create a new text buffer by choosing Text | New and type in the following example lines:

import sys
print sys.path

Most keys on the keyboard will behave in a familiar way, including Delete, Backspace, and Enter. The shortcut keys for cutting, pasting, and copying are listed in the Edit menu as Alt + X, Alt + V, and Alt + C respectively but the Ctrl key equivalents Ctrl + X, Ctrl + V, and Ctrl + C (familiar to Windows users) work just as well. A full keyboard map can be consulted on the Blender wiki, http://wiki.blender.org/index.php/Doc:Manual/Extensions/Python/Text_editor

Selecting portions of the text can be achieved by clicking and dragging the mouse, but you can also select text by moving the text cursor around while pressing the Shift key.

Text will be uncolored by default, but reading scripts can be made a lot easier on the eye by enabling syntax highlighting. Clicking on the little AB button will toggle this (it will be black and white when syntax highlighting is off and colored when on.) Like many aspects of Blender, text colors can be customized in the themes section of the User Preferences window.

Another feature that is very convenient to enable, especially when debugging scripts, is line numbering. (You might write a faultless code in one go, but unfortunately yours truly is less of a genius.) Every Python error message that will be shown will have a filename and a line number, and the offending line will be highlighted. But the lines of the calling function(s), if any, will not be highlighted although their line numbers will be shown in the error message, so having line numbers enabled will enable you to quickly locate the calling context of the trouble spot. Line numbering is enabled by clicking on the lines button.

Running a script is done by pressing Alt + P. Nothing is displayed in the editor when there are no errors encountered, but the output will be shown on the console (that is, the DOSBox or X terminal Blender started from, not the Python interactive console that we encountered earlier).

Your own script doesn't have to be a second class citizen. It can be made part of Blender on par with any of the bundled scripts that come with Blender. It can be added to the Add menu present in the header at the top of the View3D window.

It may supply information to Blender's help system just like any other script. The following few lines of code make that possible:

"""
Name: 'HelloWorld'
Blender: 249
Group: 'AddMesh'
Tip: 'Create a Hello World text object'
"""

We start the script with a standalone string containing several lines.

The labels at the beginning of each line serve the following purpose:

Blender has an integrated help system that is accessible from the Help menu at the top of the screen. It gives access to online resources and to information on registered scripts via the Scripts Help Browser entry. Once selected, it shows a collection of drop-down menus, one for each group, where you can select a script and view its help information.

If we want to enter our script in the integrated help system we need to define some additional global variables:

__author__    = "Michel Anders (varkenvarken)"
__version__   = "1.00 2009/08/01"
__copyright__ = "(c) 2009"
__url__       = ["author's site, http://www.swineworld.org"]
__doc__       = """
A simple script to add a Blender Text object to a scene.
It takes no parameters and initializes the object to contain the
text 'Hello World'
"""

These variables should be self-explanatory except for the __url__ variable—this one will take a list of strings where each string consists of a short description, a comma, and a URL. The resulting help screen will look like this:

Now all that we have left to do is to test it and then place this script in an appropriate location. We can test the script by pressing Alt + P. If no errors are encountered, this will result in our Hello World Text3d object being added to the scene but the script will not be appended to the Add menu yet.

If a script is to be added to the Add menu it has to reside in Blender's script directory. To do this, first save the script in the text buffer to a file with a meaningful name. Next, make sure that this file is located in Blender's script directory. This directory is called scripts and is a subdirectory of .blender, Blender's configuration directory. It is either located in Blender's installation directory or (on Windows) in the Application Data directory. The easiest way to find ours is to simply look at the sys.path variable again to see which listed directory ends in .blender\scripts.

Scripts located in Blender's scripts directory will be automatically executed on startup, so our hello world script will be available anytime we start up Blender. If we want Blender to reexamine the script directory (so that we don't have to restart Blender to see our new addition) we can choose Scripts | Update menus in the interactive console.

Like a Lamp or a Camera, a Mesh is a Blender object that encapsulates another object in this case, a Blender.Mesh object. But unlike Blender.Lamp or Blender.Camera objects it does not stop there. A Blender.Mesh object itself may contain many other objects. These objects are vertices, edges, and faces. Each of these may have a number of associated properties. They may be selected or hidden and may have a surface normal or an associated UV-texture.

Beside's any associated properties, a single vertex is basically a point in 3D space. In a Blender.Mesh object any number of vertices are organized in a list of Blender.Mesh.MVert objects. Given a Mesh object me, this list may be accessed as me.verts. An edge is a line connecting two vertices in Blender represented by a Blender.Mesh.MEdge object. Its main properties are v1 and v2, which are references to MVert objects. The list of edges in a Mesh object can be accessed as me.edges.

A MFace object is a like an edge, basically a list of references to the vertices that define it. If we have a MFace object face, this list may be accessed as face.verts.

This jumble of objects containing other objects may be confusing, so keep the previous diagram in mind and let's look at some example code to clarify things. We will define a cube. A cube consists of eight vertices connected by twelve edges. The eight vertices also define the six sides (or faces) of the cube.

from Blender import Mesh,Scene

corners=[ (-1,-1,-1), (1,-1,-1), (1,1,-1), (-1,1,-1),(-1,-1, 1), (1,-1, 1), (1,1, 1), (-1,1, 1) ]
sides= [ (0,1,2,3), (4,5,6,7), (0,1,5,4), (1,2,6,5), (2,3,7,6), (3,0,4,7) ]

me = Mesh.New('Cube')
me.verts.extend(corners)
me.faces.extend(sides)
scn = Scene.GetCurrent()
ob = scn.objects.new(me, 'Cube')
Window.RedrawAll()

We start by defining a list of corners. Each of the eight corners is represented by a tuple of three numbers, its x, y, and z coordinates. Next we define a list of tuples defining the faces of the cube. The sides of a cube are squares so each tuple holds four integers—each integer is an index to the list of corners. It is important to get the order of these indices right: if we would list the first side as (0,1,3,2) we would get a twisted or a bow-tie face.

Now we can define a Mesh object and name it Cube (the highlighted part in the preceding code). As noted earlier, the vertices of a Mesh object are accessible as a list named verts. It has an extend() method that may take a list of tuples representing vertex positions to define additional MVert objects in our Mesh.

Likewise, we can add extra faces to the list of faces of a Mesh object by calling the extend() method of faces with a list of tuples. Because all edges of a cube are edges of the faces there is no need to add any edges separately. This is done automatically when we extend() the list of faces.

The Mesh object that we have defined so far can now be embedded in a Blender object that can be added to the active scene. Note that it is perfectly acceptable to have a Mesh object and a Blender Object with the same name (Cube in this case) because different kind of objects in Blender have separate namespaces. In the Blender GUI, names are always prefixed with a two letter prefix to distinguish them. (for example, LA for a lamp, ME for a mesh, or OB for a Blender object)

When creating Mesh objects a great deal of attention is needed to get all the vertices, edges, and faces added and correctly numbered. This is just the tip of the iceberg when creating meshes. In Chapter 2, Creating and Editing Objects, we will see what hides underwater.

In the previous sections, we saw that in order to integrate our script in Blender's menu system and help system we had to place the script in the .blender\scripts directory. A fully integrated script can be a big advantage, but this method has a clear drawback: the person who wants to use this script has to put it in the correct directory. This might be a problem if this person does not know how to locate this directory or does not have the permission to place scripts in that directory. That last problem may be overcome by setting an alternative script directory in the User Preferences, but not everybody might be that tech oriented.

A viable alternative is distributing a script as a text within a .blend file. A .blend file can be saved with the script clearly visible in the main window and one of the first comment lines of the script might read Press ALT-P to start this script. This way, the script can be used by anybody who knows how to open a .blend file.

An additional advantage is that it is easy to bundle extra resources in the same .blend file. For example, a script might use certain materials or textures or you might want to include sample output from your script. The only thing that is very difficult to do is distribute Python modules this way. You can use the import statement to access other text files but this may pose problems (see Appendix B). If you have a lot of code and it is organized in modules, you and your users are probably still better off if you distribute it as a ZIP file with clear instructions on where to unpack this ZIP file.

For Pynodes (or dynamic nodes, see Chapter 7) you don't have a choice. Pynodes can refer to only the Python code contained in text files within a .blend file. This is not really a limitation though as these Pynodes are an integral part of a material, and Blender materials can be distributed only within a .blend file. When these materials are linked to or appended their associated nodes and any texts associated with Pynodes are linked to or appended as well, completely hiding from the end user the way a material is actually implemented.

When developing Python programs in Blender it is important to understand what functionality is provided by the API and even more so, what not. The API basically exposes all data and provides functions for manipulating that data. Additionally, the API provides the developer with functions to draw on the screen and to interact with the user interface and windowing system. What the Blender API does not provide is object-specific functionality besides setting simple properties, especially lacking any functions to manipulate meshes on the level of vertices, edges, or faces other than adding or removing them.

This means that very high-level or complex tasks such as adding a subsurface modifier to a Mesh object or displaying a file selector dialog are as simple as writing a single line of code, while functions as essential and seemingly simple as subdividing an edge or selecting an edge loop are not available. That doesn't mean these tasks cannot be accomplished, but we will have to code them ourselves. So many examples in this book will refer to a module called Tools that we will develop in the next chapters and that will contain useful tools from extruding faces to bridging face loops. Where appropriate and interesting we will highlight the code in this module as well but mainly it is a device to squirrel away any code that might detract us from our goals.

The following sections give a short and very high-level overview of what is available in the Blender API. Many modules and utilities will feature prominently in the next chapters as we will develop practical examples. This overview is meant as a way to help you get started if you want to find out about some functionality and do not know where to look first. It is nowhere near a full documentation of the Blender API. For that, check the most recent version of the API documentation online. You can find the link in the Appendix A Links and Resources.

The Blender module serves as a container for most other modules and provides functionality to access system information and perform general tasks.

For example, information such as the Blender version that you are using can be retrieved with the Get() function:

import Blender
version = Blender.Get('version')

Incorporating all externally referred files in a .blend file (called packing in Blender) or saving your current Blender session to a .blend file are other examples of functionality implemented in the top-level Blender module:

import Blender
Blender.PackAll()
Blender.Save('myfile.blend')

Each Blender object type (Object, Mesh, Armature, Lamp, Scene, and so on) has an associated module which is a submodule of the top-level Blender module. Each module supplies functions to create new objects and find objects of a given type by name. Each module also defines a class with the same name that implements the functionality associated with the Blender object.

Note that in Blender, not only the things directly visible in your scene, such as meshes, lamps, or cameras are objects, but also materials, textures, particle systems, and even IPOs, actions, worlds, and scenes.

Many other data items in Blender are not Objects in the Blender sense (you cannot append them from another .blend file or move them about in your scene) but are objects in the Python sense. For example, vertices, edges, and faces within a mesh are implemented as classes: Blender.Mesh.MVert, Blender.Mesh.MEdge, and Blender.Mesh.MFace respectively.

Many modules also have submodules of their own; for example the Blender.Scene module provides access to the rendering context by way of the Blender.Scene.Render module. Among other things, this module defines a RenderData class that allows you to render a still image or animation.

So with what we know now it is possible to draw two slightly different family trees of Blender objects.

The first one illustrates what kind of Blender objects may be contained within or referred to by another Blender object where we limit ourselves to the less abstract objects:

Of course, the diagram above is greatly simplified as we left out some less relevant objects and as it only illustrates a single kind of relationship. There are of course many more types of relationship in a scene, such as parent-child relationships or constraints.

We may contrast the previous diagram with the one that shows in which module a type of object (a class) is defined:

The differences are quite noticeable and are important to keep in mind, especially when looking for specific information in the Blender API documentation. Don't expect to find information on a Curve object in the documentation for the Blender.Object module because a Blender Curve is a specific Blender Object; the Curve class is defined and documented in the Blender.Curve module. In general you can expect the documentation of a class to be in the module of same name.

Besides the Blender module, there is another top-level module called bpy that provides a unified way to access data. It is considered experimental, but it is stable and might be used as a more intuitive way of accessing objects. For example, if we want to access an object called MyObject we normally would do something like this:

import Blender
ob = Blender.Object.Get(name='MyObject')

With the bpy module we might rephrase this:

import bpy
ob = bpy.data.objects['MyObject']

Likewise, to get access to the active scene object we might write this:

import Blender
scene = Blender.Scene.GetCurrent()

Which can be written in an alternative way:

import bpy
scene = bpy.data.scenes.active

Which one to prefer is a matter of taste. The bpy module will be the only way to access data in the upcoming Blender 2.5 but the changes in Blender 2.5 go deeper than just this data access so don't be fooled by the superficial similarity of the module name!

Access to Blender's windowing system is provided by the Blender.Draw module. Here you will find classes and functions to define buttons and pop-up menus and ways to interact with the user. The types of graphical elements that you can display using the Draw module are limited to the commonly used ones and customization is not an option.

More advanced functions are provided in the Blender.BGL module that gives you access to virtually all OpenGL functions and constants, allowing you to draw almost anything on screen and to let the user interact in many different ways.

Finally, there are a number of modules that encapsulate various functionality that do not fit in any of the previous categories: