From BlenderWiki

Jump to: navigation, search


In the world of programming, the word 'object' has a specific meaning - the encapsulation of data and methods. But do not be scared! For our purposes the everyday meaning of the word will do. Objects are things around us - a book, a dog, a computer. They have properties, like color, or mass. They often have behaviors like 'fetch', 'chase-your-tail' or 'run-a-program'. Obviously, not all objects have the same properties or behaviors. However, all objects belonging to the same category or class do have similar properties.

Properties have a name and a value. An object may have the property named 'color'. A value for 'color' is 'green'.

It is important to draw a distinction between a class or type and an instance of that class. There is a type of animal called Dog. My dog is a specific instance of Dog. We can refer to this instance as myDog. One of the properties of myDog is 'name'. The value of 'name' for myDog is 'Spot'. All objects of a particular type have the same properties, but the properties for each instance have their own values.

Blender has many types of objects. Some examples are Cameras, Scenes, Meshes, Empties and IPO Curves. All Blender geometry objects like Cameras and Meshes have some common properties like 'name', 'location', 'size' and 'rotation'.

Blender objects are contained in a module named 'Blender'. Modules must be imported before they can be used. Therefore, one of the first statements in our scripts is

import Blender

Time for some examples! Start Blender. If your default scene has a Cube, fine. If not, add a Cube. Select it. If you look down in the lower left-hand corner of the 3d view, you see the name of our selected object - Cube, in this case.

Add another Cube and select it. Notice the name in the lower left is now Cube.001. This is Blender's standard naming convention, adding a number after the name. You can also see the name in the Buttons Window if you select the Editing (F9) context - Ob:Cube.001

These names are important because we can locate an object by its name.

All the properties and methods of Blender objects are listed in the API documentation for the Object Module. For now, the only ones we will concern ourselves with are name and location.

Getting Objects

In order to access the properties of an object, we need a way to refer to a specific object. One way to do this is by the Object name.

Get By Name using Object.Get()

Create a new, blank Text window and enter the following code. You can leave off the comments (everything on a line after the '#') if you feel lazy.

import Blender
ob = Blender.Object.Get('Cube')
print ob		# the object
print	# object name
print 'location', ob.loc	# object location

Run this by pressing ALT-PKEY or use 'Execute Script' from the RightMouse menu

Our output looks something like this:

[Object "Cube"]
location (0.0, 0.0, 0.0)

What is all this?

[Object "Cube"] - this is simply a character string that represents the object. All Blender objects have a printable representation. It is not always useful. Do not confuse the string representation of an object with the object itself.

Cube - the name of our object, same as in the 3D view and the Editing context

(0.0, 0.0, 0.0) - a set of 3 numbers the represents the location of our object. this sounds complicated so it is time to talk about 3D coordinates.

Notice that we referenced the Get() method by its full hierarchical name, Blender.Object.Get(). Later we will discuss a shorter way to do this.

A quick note about 3D Coordinates

Blender objects live in a 3 dimensional world. This is equivalent to saying we need a set of three numbers to represent the position or rotation of a Blender object. Our 3 dimensional Blender world is divided up into a grid. The three numbers correspond to positions on the coordinate axes and are named X, Y, and Z. You may remember these from math class as Cartesian Coordinates.

Getting Objects By Selection - Object.getSelected()

We have talked about getting objects by using their name, but that presents a chicken-and-egg problem. We can get a reference to an object if we know its name and we can get its name if we have a reference to it. One way out of this dilemma is to select an object and then run our script.

Continuing with our current scene with two cubes, select both Cubes and run the following code.

import Blender as B
# returns a list of selected objects
ob_list = B.Object.GetSelected() 
print ob_list

Our output looks something like this:

[[Object "Cube"], [Object "Cube.001"]]

The method Object.GetSelected() returns a list of selected objects. You can access the first object in a list like this:

print ob_list[0]

We can access each item in the list in turn by using a 'for' statement like this:

for i in ob_list:
  print i

When we run it, we get

[Object "Cube"]
[Object "Cube.001"]

The meaning of the 'for' statement is "for each element in the list, assign reference to the element ( our loop variable 'i' ) and do whatever is in the body of the loop".

Now is a good time to remind you about the python tutorial at


for statement:

The Object module and its Get() and GetSelected() methods:


Let's put together what we know so far and make a script to print out the name and location of all selected objects.

import Blender as B
selection = B.Object.GetSelected() 
for i in selection:
	# print name and location
	print 'object',, i.loc

Our output looks something like this:

object Cube.001 (4.6216516494750977, -0.28958892822265625, -0.0001121363093261607)
object Cube (0.0, 0.0, 0.0)
object Camera (0.0, -7.0, 0.0)

Try adding the camera or a lamp to the selection and run the script again.

Notice that our import statement is slightly different here

Import Blender as B

This form of the import statement creates an alias 'B' for the Blender module. If we do this, later we can refer the elements in the Blender module as B.something rather than by their full name of Blender.something. In this particular case we referenced the GetSelected() method as


Setting Properties

Now that we have looked at getting property values, the next obvious question is how to set them. To change the name of an object, we get a reference to it as usual and simply assign a new value of the correct type.

import Blender as B
# a list of selected objects
selection = B.Object.GetSelected() 
ob = selection[0] # the first selected object = 'MyObj' # name it 'MyObj'
B.Redraw(-1) # redraw Blender's Interface

Something new here is the line

B.Redraw( -1 )

This command tells Blender to redisplay the entire interface. When called without an argument, Redraw() only redisplays a 3d window. Redraw() is an alias for the Window.Redraw() command.

Program: MOVE

We can change other properties in addition to the object name. Let's change the location and size of our object:

import Blender as B
# a list of selected objects
selection = B.Object.GetSelected() 
ob = selection[0] # the first selected object
ob.LocX += 0.5 # increment the X position by 0.5
B.Redraw( -1 ) # redraw Blender's Interface

Our new feature here is

ob.LocX += 0.5 # increment the X position by 0.5

Previously, we use ob.loc to get a set of X, Y and Z coordinates as a tuple or set of numbers. This time, we are accessing the X coordinate as a single number. The += syntax is shorthand for adding the number on the right-hand side to whatever is on the left hand side: ob.LocX = ob.LocX + 0.5 in this case. This type of expression is common enough to deserve its own abbreviation.

Enter this script into a new window and run it a few times. Notice how the selected object moves across the view.

Try running this script with no object selected to see what happens.