Blender IndexRelease 2.59.0 - API

Blender Foundation

August 26, 2011

CONTENTS

1 Blender/Python Documentation 31.1 Quickstart Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Python API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3 Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2 Application Modules 272.1 Context Access (bpy.context) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.2 Data Access (bpy.data) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.3 Operators (bpy.ops) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.4 Types (bpy.types) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702.5 Utilities (bpy.utils) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10722.6 Path Utilities (bpy.path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10742.7 Application Data (bpy.app) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10752.8 Property Definitions (bpy.props) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076

3 Standalone Modules 10833.1 Math Types & Utilities (mathutils) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10833.2 Geometry Utilities (mathutils.geometry) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11123.3 OpenGL Wrapper (bgl) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11163.4 Font Drawing (blf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11463.5 Audio System (aud) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11493.6 Extra Utilities (bpy_extras) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157

4 Game Engine Modules 11634.1 Game Types (bge.types) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11634.2 Game Logic (bge.logic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12354.3 Rasterizer (bge.render) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12494.4 Video Texture (bge.texture) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12524.5 Game Keys (bge.events) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12604.6 Physics Constraints (bge.constraints) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265

5 API Info 12735.1 Blender API Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273

Python Module Index 1291

Index 1293

i

ii

Blender Index, Release 2.59.0 - API

Welcome, this document is an API reference for Blender 2.59.0. built Unknown.

A PDF version of this document is also available

CONTENTS 1

Blender Index, Release 2.59.0 - API

2 CONTENTS

CHAPTER

ONE

BLENDER/PYTHON DOCUMENTATION

1.1 Quickstart Introduction

1.1.1 Intro

This API is generally stable but some areas are still being added and improved.

The Blender/Python API can do the following:

Edit any data the user interface can (Scenes, Meshes, Particles etc.)

Modify user preferences, keymaps and themes

Run tools with own settings

Create user interface elements such as menus, headers and panels

Create new tools

Create interactive tools

Create new rendering engines that integrate with Blender

Define new settings in existing Blender data

Draw in the 3D view using OpenGL commands from Python

The Blender/Python API cant (yet)...

Create new space types.

Assign custom properties to every type.

Define callbacks or listeners to be notified when data is changed.

1.1.2 Before Starting

This document isnt intended to fully cover each topic. Rather, its purpose is to familiarize you with Blender 2.5s newPython API.

A quick list of helpful things to know before starting:

Blender uses Python 3.x; some 3rd party extensions are not available yet.

The interactive console in Blender 2.5 has been improved; testing one-liners in the console is a good way tolearn.

Button tool tips show Python attributes and operator names.

3

Blender Index, Release 2.59.0 - API

Right clicking on buttons and menu items directly links to API documentation.

For more examples, the text menu has a templates section where some example operators can be found.

To examine further scripts distributed with Blender, see ~/.blender/scripts/startup/bl_ui for theuser interface and ~/.blender/scripts/startup/bl_op for operators.

1.1.3 Key Concepts

Data Access

Accessing datablocks

Python accesses Blenders data in the same way as the animation system and user interface, which means any settingthat is changed via a button can also be changed from Python.

Accessing data from the currently loaded blend file is done with the module bpy.data. This gives access to librarydata. For example:

>>> bpy.data.objects

>>> bpy.data.scenes

>>> bpy.data.materials

About Collections

Youll notice that an index as well as a string can be used to access members of the collection.

Unlike Pythons dictionaries, both methods are acceptable; however, the index of a member may change while runningBlender.

>>> list(bpy.data.objects)[bpy.data.objects["Cube"], bpy.data.objects["Plane"]]

>>> bpy.data.objects[Cube]bpy.data.objects["Cube"]

>>> bpy.data.objects[0]bpy.data.objects["Cube"]

Accessing attributes

Once you have a data block such as a material, object, groups etc. its attributes can be accessed just like changinga setting in the interface; in fact, the button tooltip also displays the Python attribute which can help in finding whatsettings to change in a script.

>>> bpy.data.objects[0].nameCamera

>>> bpy.data.scenes["Scene"]bpy.data.scenes[Scene]

4 Chapter 1. Blender/Python Documentation

Blender Index, Release 2.59.0 - API

>>> bpy.data.materials.new("MyMaterial")bpy.data.materials[MyMaterial]

For testing what data to access its useful to use the Console, which is its own space type in Blender 2.5. Thissupports auto-complete, giving you a fast way to dig into different data in your file.

Example of a data path that can be quickly found via the console:

>>> bpy.data.scenes[0].render.resolution_percentage100>>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x1.0

Custom Properties

Python can access properties on any datablock that has an ID (data that can be linked in and accessed from bpy.data.When assigning a property, you can make up your own names, these will be created when needed or overwritten ifthey exist.

This data is saved with the blend file and copied with objects.

Example:

bpy.context.object["MyOwnProperty"] = 42

if "SomeProp" in bpy.context.object:print("Property found")

# Use the get function like a python dictionary# which can have a fallback value.value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")

# dictionaries can be assigned as long as they only use basic types.group = bpy.data.groups.new("MyTestGroup")group["GameSettings"] = {"foo": 10, "bar": "spam", "baz": {}}

del group["GameSettings"]

Note that these properties can only be assigned basic Python types.

int, float, string

array of ints/floats

dictionary (only string keys types on this list)

These properties are valid outside of Python. They can be animated by curves or used in driver paths.

Context

While its useful to be able to access data directly by name or as a list, its more common to operate on the usersselection. The context is always available from bpy.context and can be used to get the active object, scene, toolsettings along with many other attributes.

Common-use cases:

1.1. Quickstart Introduction 5

Blender Index, Release 2.59.0 - API

>>> bpy.context.object>>> bpy.context.selected_objects>>> bpy.context.visible_bones

Note that the context is read-only. These values cannot be modified directly, though they may be changed by runningAPI functions or by using the data API.

So bpy.context.object = obj will raise an error.

But bpy.context.scene.objects.active = obj will work as expected.

The context attributes change depending on where it is accessed. The 3D view has different context members to theConsole, so take care when accessing context attributes that the user state is known.

See bpy.context API reference

Operators (Tools)

Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. From the user perspectivethey are a tool but Python can run these with its own settings through the bpy.ops module.

Examples:

>>> bpy.ops.mesh.flip_normals(){FINISHED}>>> bpy.ops.mesh.hide(unselected=False){FINISHED}>>> bpy.ops.object.scale_apply(){FINISHED}

Note: The menu item: Help -> Operator Cheat Sheet gives a list of all operators and their default values in Pythonsyntax, along with the generated docs. This is a good way to get an overview of all blenders op