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.
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
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.
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.
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.
Type the following in the Console (>>> stands for Console input prompt)
>>> bpy.context. and press CTRL+SPACE-KEY to list everything inside it.
For the above commands to show the proper output, make sure you have selected objects in your 3D view.
Will print the current 3D View mode (Object, Edit, Sculpt etc.,)
Will give access to the active object in the 3D View
Exercise: Try out.. (Enter following commands and press ENTER-KEY after each one)
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.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.
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
We create a reference to the operator that is used for creating a cube mesh primitive
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.
So far we have been typing directly in the built in Python console. For this exercise, do the following
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.