Blender (jusqu'à 2.49)
API Python
Version Française
 Main Index           Python Index
Previous Python Index
Python: Modifying a Mesh (1) Next
A Warning with regards to the version number
B Presentation
C Differences between Script Window and " Link " Window (binding).
- Some short cuts for the text editor.
D How to load a script .
E How does it work?
- To start the execution of a script
- Display Python output in the console
- Avoiding errors due to text editing

Warning with regards to the version number.

A Brief Blender History Lesson : Prior to the release of Blender 1.8a (Complete Blender) the more advanced features (including Python scripting) were reserved for the users of Blender who had purchased a Ckey. The Ckey was a personal code which unlocked the advanced features of the software, and was a necessary method for NaN (Not a Number - the creators of Blender) to raise money to fund further development of Blender. To indicate that the key was correctly installed, a golden donut  appeared just to the  left of Blender's web address and version number in the right side of the top Information Window.

CAUTION : As of version 1.8a, Blender is no longer restricted by the Ckey, and all of the advanced features, available at this time (June 21, 2000), have been transferred to the free version of Blender. Version 1.8a is recognizable by the green donut which appears in the right corner of the Information Window:

Note that some of the Python scripts that you encounter on the Internet may have been written for an older version of Blender and may not have been updated by the author yet. Usually, the version number that the script was written for, will appear in a comment at the top of the script. For those not yet familiar with Python, comments are indicated by a line beginning with the symbol "#". Normally, for small scripts, the required changes to update the script, due to changes in the Blender / Python module as newer versions of Blender were released, are minimal and can be easily recognized once you are familiar with the Python scripting features of Blender.


Since version 1.67, Complete Blender utilizes the Python   programming language, to access  various objects of the software.

It is an interpreted language halfway between BASIC, C++ and Modula, that is, it consists of a core to which are added elements,  which can be loaded according to the needs and objectives that the script must perform .

Currently, the available modules in Blender/Python are the following :
Blender  Main  Blender module 
Types  Blender's types module
NMesh  Low-level access to meshes module
Draw  Display module
BGL  OpenGL module 
Object  Object's module 
Lamp  Lamp module 
Camera  Camera module 
Material  Material module
World  World module 
IPO  IPO animation key's module 

Python works in all of the principal operating systems, in particular, all versions of Windows and Unix, and also: NeXt, BeOS, Mac. It is free and can be redistributed.

It is sufficiently simple to be assimulated quickly if  some essential concepts are already known. These include : what a list is, how to bind a module to a script, how to differentiate a local or global variable,   how to build a function,   what an object or a class is, and how to use  the functions/methods attached to a particular object... suffice it to say, that it is easy to learn if we already have a good grasp of programming concepts, especially from an object oriented  programming perspective.

However, the objective of this tutorial is not to explain details of the Python programming language, but rather to provide everybody (and not strictly engineering students, who will forgive the trivial details included in the information) the possibility of learning how to use this tool in Blender. Also, it should be noted, that there are some excellent sites devoted to Blender Python script programming where you will be able to find more elaborate examples.

The description of the Python language itself can be obtained at the following address: For the French-speaking people.

Differences between  the Script Window  and   "Link" Window  (binding).

First of all,  how does the tool physically present itself? Outside (under Windows) it is a DLL, a dynamically linked library of functions   which is in the same directory as the Blender binary file. On the graphic interface level, there are two icons which open two windows devoted to Python:

this window enables you to write scripts, it is a very simple text editor. This is the only window which can contain a script.

   Some short cuts:

       Alt-s : Save a file
       Alt-o : Open  a file

       Alt-a : Select all of the text

       Alt-c : Copy the selection.
       Alt-v : Paste the selection.
       Alt-x : Cut the selection.
       Alt-j  : Jump to line number N

       Alt-U : Undo.
       Alt-R : Redo.

       Alt-shift-S : Menu Selection which includes "Jump to line number", very usefull for debugging the code.
       Alt-shift-F : Menu File contains the usual standard file commands
       Alt-shift-E : Menu Edit to copy, cut, and paste the text selection between the display and the buffer contents.
       Alt-shift-V : Menu View jump to the beginning or end of a file, next page, and previous page

  "Link" window to associate the file either : 1) with an animation (in this case, the script is carried out image by image by using some constants which indicate the frame number of the image or elapsed time), or 2) with a particular object.

To load a script:

Before writing your own scripts, it would perhaps be simpler to use an already existing script. If you haven't already opened a Script Window,  do so now by pressing Shift-F11.

    1. Push the Browse Datablock button  to open the data block.

    2. Choose OPEN NEW , which opens a window in the current directory to load  a Python script file ". py ".

How does it work?

To understand what really occurs, it would probably be best explained by using an example. Note: In case you have a file selection window open from the previous discussion, simply press 'Esc' to cancel the Blender operation.
If you are using a Windows operating system, it is necessary to "add" a script window  by selecting  ADD NEW instead of  OPEN NEW and type the following text:

# Windows version 
import Blender
import sys

print str(obj)

(to obtain a # sign with an European azerty keyboard, refer to: How to make? )

or with Linux:
# Linux version
import Blender

print str(obj)

(all of the following explanations will not be 100% valid
for those using a Windows environment)

This script calls upon the Blender module to obtain the contents of an object. The function which makes it possible to carry out this operation, is the function Blender.Object.Get("name") . It is not a standard function of the Python language. Indeed, Python can be supplemented by a series of modules containing new objects. If you recall: an object in  object oriented programming, is a set of methods (in fact  the function Get() is a method of the Object submodule   which is contained by the Blender module ) and data. Thus, it is necessary to begin the script with a line asking the interpreter to load the module containing this function. ie. To load the Blender module, the line "import Blender" is used.

If no name of an object is provided as an argument to the function Get() ,  it returns the entire list of objects which currently exists in memory.

To start the execution of a script

In the above example which is used here, it is the combination of the Alt-P keys which is used to activate the script . It is important to note that this is not the only way to initiate a script. In fact,   a script can be related to the execution of an animation. In this case, it is the release of the animation which, in turn, will launch the execution of the script.

Display Python output in the console.

Obviously, if you were expecting to see this list  displayed in the current window, there is a good chance that you were disappointed.
On the other hand, if you check the contents of the "console" (DOS Window or Shell) you will see that it has been modified.

Just push the button shown in the above image to see its content:

Another alternative would be to launch Blender from the console/shell with the following parameters:   blender - p 0 200 640 480 (an easy way borrowed from the article of Strubi and Cartsen which is at the following address:

This display corresponds to the structure of the standard file that   Blender loads when started. The symbol  indicates that the   block represents an object. Python, via the command print obj, returned a list, containing a camera object and a plane object .

The command len(obj) makes it possible to know what the length of the list obj  is, ie. for the above example, 2.

Note: In the Python language, lists are declared and contained between two square brackets   " [ " and " ] ". To obtain  these characters on an European azerty keyboard, see: How to make? )

Avoiding errors due to text editing :

It is important to maintain the horizontal line spacings of the script  because Python carries them out  one after the other, based upon the level of indentation.
The indentations and tabulations indicate  to the Python language how it must arrange the instructions to form a  subroutine; thus the text:
O bj = Blender.Object.Get()
print str(obj)

is carried out without an error, whereas the text (indented space is indicated in red):

O bj = Blender.Object.Get()
print str(obj)

will generate an execution error:

Spaces at the end of the line are also to be avoided.

O bj = Blender.Object.Get()
print str(obj) 

All of these concepts are necessary to control the tool, but are not especially helpful to produce shapes and pictures. The next page explains how  to use Python to modify a square mesh.
Previous Index 
 Python: Modifying a Mesh (1) Next
  Top of page 

Les questions concernant cette page   peuvent ê tre pos é es sur   :


Livre en français
Blender : apprenez, pratiquez, Créez, livre, Ed. Campus Press, coll. Starter Kit
Blender Starter Kit

Blender python
API python (eng)
Archives nzn
Doc flash Sculptris
Galerie Sculptris

mon site de démos sur youtube