Skip to content

Accessing Blender data

Using bpy.data

All data in a Blender file can be accessed through bpy.data. This contains, for example, all objects (bpy.data.objects), all meshes (bpy.data.meshes), all scenes (bpy.data.scenes) and all materials (bpy.data.materials).

The data is stored in a data-type called bpy_collection whose members (data blocks) can be accessed with both an index as well as a string (this in contrary to regular Python dictionaries). For example. bpy.data.objects["Camera"] and bpy.data.objects[0] will be equivalent if Camera is the first object in the collection:

>>> bpy.data.objects
<bpy_collection[2], BlendDataObjects>

>>> len(bpy.data.objects)
2

>>> bpy.data.objects[0]
bpy.data.objects['Camera']

>>> bpy.data.objects['Camera']
bpy.data.objects['Camera']

Attributes of data blocks (e.g an object, collection or material) can be accessed as regular Python attributes, for example:

>>> bpy.data.objects[0].name
'Camera'

Here's two examples of changing those attributes (note that some operations only work if Blender is in the right mode):

bpy.data.objects["Cube"].location.z += 1              # this works in both edit and object mode
bpy.data.objects["Cube"].data.vertices[0].co.z += 10  # this works only in object mode

Tips

  • Use the Python Console in Blender and the auto-complete functionality (TAB) to see what attributes bpy.data has.
  • The Info Editor in Blender shows the python commands being executed when you do operations manually in Blender (See Fig. 2.)
  • Hovering over buttons and input boxes in Blender shows how to access the underlying values through the Python API.

Figure 2: The Info Editor is a nice way to see what python commands are executed when you use Blender. In this figure we see that we deleted the initial cube, made a UV Sphere and translated it.

Some notes on bpy.context and bpy.ops

In this section we want to briefly introduce how you can access something called the context, and use operators in the Blender Python API. bpy.context stores information about a user's selections and the context Blender is in. For example, if you want to check which mode is currently active in Blender you can check the value of bpy.context.mode.

Now if you want to change the mode, you can use an operator. Operators are tools that are usually accessed through the user interface with buttons and menus. You can access these operators with Python through bpy.ops. If we would like to change the mode we can do this using an operator, e.g. bpy.ops.object.mode_set(mode='OBJECT')

Of course the possibility of switching to, say, edit mode, depends on which objects are selected, which can be checked with bpy.context.selected_objects. But keep in mind that many of the variables in the context are read-only, for example altering bpy.context.selected_objects directly is not possible. Instead, you can select an object with the select_set() method of the object, e.g. bpy.data.objects['Cube'].select_set(True).

💻 Running a script and rendering from the console

  1. Write an external script that removes the Cube object that is part of the default scene 1
  2. Then, from the command line and without opening the Blender GUI execute this script and render the first frame. Let it output a PNG image file in the directory of the blender file.
  3. Was the cube indeed removed from the rendered image?
  4. Extra question: is the cube removed from the blender file?

  1. Although you might have altered your startup scene to not have the cube ↩

Last update: 28 November 2023 17:04:35 •