Blender Python API中文介绍文档二

2.交互终端用于测试一行代码很好，也可以自动补全，这使你可以很快地了解api

运行脚本
两种最常用执行脚本的方法是内嵌文本编辑器和 Python终端输入命令
这两种都是一种视图模式，你可以在视图模式中选择
不需要手动构建你的 python 开发视图，你可以选择 Scripting 界面模式，你可以在标题栏总选择界面
模式，一般是默认模式
终端一般是用于小片代码，一般用于测试获得迅速反馈，当然也可以将整个脚本粘贴执行
脚本也可以在系统终端命令行运行，但是为了学习 Blender-python 这是没必要的

关键概念

获得数据(data)

获得数据块

Python 获取 blender 的数据方式和动画系统及用户界面获取数据的方式相同，这也意味着任何通过界面
按钮设置的改变都可以通过脚本来实现
存当前加载的 blender 文件获取数据的方式来自 bpy.data 模块，这会获取库数据，例如：

>>> bpy.data.objects
<bpy_collection[3], BlendDataObjects>
>>> bpy.data.scenes
<bpy_collection[1], BlendDataScenes>
>>> bpy.data.materials
<bpy_collection[1], BlendDataMaterials>

关于集合
你会发现一个索引和一个字符串可以被用来获取集合中的成员

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"]

获取属性

一旦你得到数据块，例如材质，物体，组等等，他的属性就可以得到，这一点和你通过图形界面改变设
置很类似。事实上每个按钮的 tip 也同样显示了 python 属性，可以帮助你找到脚本对应的哪个设置更改
了

>>> bpy.data.objects[0].name
'Camera'
>>> bpy.data.scenes["Scene"]
bpy.data.scenes['Scene']
>>> bpy.data.materials.new("MyMaterial")

利用终端很有帮助，来测试哪些数据可以获取，他可以实现自动补全，让你快速挖掘不同的文件中的数
据
通过终端快速获取数据的例子如下:

>>> bpy.data.scenes[0].render.resolution_percentage
100
>>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x
1.0

数据创建和移除

对于其他python的 api 很不同的是，bpy-api中的新数据块无法通过调用类构造函数来创建：

<span style="color:#330033;">>>> bpy.types.Mesh()
Traceback (most recent call last):
File "<blender_console>", line 1, in <module>
TypeError: bpy_struct.__new__(type): expected a single argument</span>

这是api设计中故意做的，api无法创建存在于 blender 数据库（通过 bpy.data 获取）之外的 blender 数
据，因为这个数据需要被 blender 所管理
数据通过 bpy.data 中的集合来添加和移除，例如：

<span style="color:#330033;">>>> mesh = bpy.data.meshes.new(name="MyMesh")
>>> print(mesh)
<bpy_struct, Mesh("MyMesh.001")>
>>> bpy.data.meshes.remove(mesh)</span>

用户属性
python 可以获取任何数据块的属性，只要这个数据块有 ID
date 可以通过 bpy.data 来获取。对于一个属性，你可以自己创建它的名字，这些名字可以被重命名
例如：

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"]

注意这些属性仅仅可以是python基本类型：
int, float, string
array of ints/floats
dictionary (only string keys are supported, values must be basic types too)这些属性在 python之外同样有效，可以作为动画的曲线或者用于行走路线

内容context
尽管通过名字或列表直接获取数据很有效，基于用户选择来操作更普遍。内容可以通过获取
bpy.context，他可以用来获取激活的物体，场景，工具设置及其他属性
典型使用例子：

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

注意context是只读的，这些值无法直接被修改，尽管可以通过api 函数或数据的 api 来修改，因此：
bpy.context.object = obj这样的赋值或引发问题
但是 bpy.context.scene.objects.active = obj 则正确
context 属性因获取位置不同而不同，3D 视图获取的 context 与终端中获取的就不同，因此当用户
状态是确定的时候，要注意获取 context 的方式
详情参见：bpy.contextAPI手册.

操作（工具）
操作都可以通过按钮，菜单，快捷键来获取，从用户角度来讲这些操作是工具性质的，只不过 python
可以通过 bpy.ops 模块自己的设置来运行这些工具，例如：

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

注意：菜单选项，help-operator cheat sheet给出了所有操作的列表和他们默认的
python 语义，通用文档，方便你对 blender 有一个大致的了解
Operator Poll()

很多操作都有一个poll函数，他可以检查光标是否在有效区域或者物体是否在正确的模式（编辑模式，
权重绘制模式等等），当一个操作的 poll 函数发生错误，异常会抛出
例如，从终端调用 bpy.ops.view3d.render_border()会有以下错误：
RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect
这个例子中，context必须在3d 视图中且有一个激活的相机
为了避免在操作调用处大量使用 try/except，你可以调用操作自己的poll函数来检查它是否可以
运行在当前的 context 中

if bpy.ops.view3d.render_border.poll():
bpy.ops.view3d.render_border()

集成
python 脚本可以在 blender 中通过以下集中方式进行集成：
1.定义渲染引擎
2.定义操作
3.定义菜单标题和面板
4.在已经存在的菜单，标题和面板中内嵌新按钮

操作例子

import bpy
def main(context):
for ob in context.scene.objects:
print(ob)
class SimpleOperator(bpy.types.Operator):
"""Tooltip"""
bl_idname = "object.simple_operator"
bl_label = "Simple Object Operator"
@classmethod
def poll(cls, context):
return context.active_object is not None
def execute(self, context):
main(context)
return {'FINISHED'}
def register():
bpy.utils.register_class(SimpleOperator)
def unregister():
bpy.utils.unregister_class(SimpleOperator)
if __name__ == "__main__":
register()
# test call

脚本运行之后，SimpleOperator类被注册进blender 中，可以通过操作搜索调用也可以添加进工具条中
为了运行脚本
1.选择代码，复制
2.打开blender软件
3.按下ctrl-右键两次，打开脚本视图模式
4.点击按钮New，确认创建一个新的文本块
5.粘贴代码到文本编辑面板
6.点击运行脚本
7.将光标移到3D视图区，按下空格打开操作搜索菜单，输入 Simple
8.点击在搜索中找到的简单操作选项
类成员以 bl_前缀开头，参见 API 手册 bpy.types.Operator
注意：main函数的输出被输出到终端，请确认在终端启动blender

面板例子
面板作为一个类来注册自己，注意额外的 bl_变量用来设置它们显示的 context（视图模式）

import bpy
class HelloWorldPanel(bpy.types.Panel):
"""Creates a Panel in the Object properties window"""
bl_label = "Hello World Panel"
bl_idname = "OBJECT_PT_hello"
bl_space_type = 'PROPERTIES'
bl_region_type = 'WINDOW'
bl_context = "object"
def draw(self, context):

layout = self.layout
obj = context.object
row = layout.row()
row.label(text="Hello world!", icon='WORLD_DATA')
row = layout.row()
row.label(text="Active object is: " + obj.name)
row = layout.row()
row.prop(obj, "name")
row = layout.row()
row.operator("mesh.primitive_cube_add")
def register():
bpy.utils.register_class(HelloWorldPanel)
def unregister():
bpy.utils.unregister_class(HelloWorldPanel)
if __name__ == "__main__":
register()

查看结果：
1.选择默认的 cube
2.点击物体属性图标在按钮面板中
3.滚轮下滑，看见一个面板叫做 HelloWorldPanel
4.更改物体名字也更新 HelloWorldPanel 面板的名字：field
注意行分布，按钮，属性都可以通过代码来获取
参见 bpy.types.Panel

类型

blender定义了很多Python 类型也有 python 的原始类型，api中大致可以分为以下三种：

原始类型
在简单的例子中返回一个通用类型的数据或字符串，这些都可以以 Python 原始类型来获取

1.Blender float/int/boolean -> float/int/boolean
2.Blender enumerator -> string
>>> C.object.rotation_mode = 'AXIS_ANGLE'
3.Blender enumerator (multiple) -> set of strings
# setting multiple camera overlay guides
bpy.context.scene.camera.data.show_guide = {'GOLDEN', 'CENTER'}
# passing as an operator argument for report types
self.report({'WARNING', 'INFO'}, "Some message!")

内置类型

使用 blender 数据块和集合：bpy.types.bpy_struct
对于包含自定义属性：group/meshes/bones/scenes 等的数据
有两种主要的类型来封装 Blender 的数据，一种用于数据块（bpy_struct）,一种用于属性：

>>> bpy.context.object
bpy.data.objects['Cube']

>>> C.scene.objects
bpy.data.scenes['Scene'].objects

数值公式类型

用于向量，四元素，欧拉，矩阵和颜色类型，可以通过 mathutils 来获取
有一些属性例如 bpy.types.Object.location, bpy.types.PoseBone.rotation_euler 和
bpy.types.Scene.cursor_location可以获取作为特殊的数据类型，作为一个整体来使用并且以各种有
用的方式来相乘
矩阵和向量相乘的例子：

bpy.context.object.matrix_world * bpy.context.object.data.verts[0].co
注意：数值公式类型引用 blender 内置类型，例如：
# modifies the Z axis in place.
bpy.context.object.location.z += 2.0
# location variable holds a reference to the object too.
location = bpy.context.object.location
location *= 2.0
# Copying the value drops the reference so the value can be passed to
# functions and modified without unwanted side effects.
location = bpy.context.object.location.copy()

动画
有两种方法通过 python 来添加关键帧
第一种方法是通过关键属性直接添加，关键属性类似于用户按钮内嵌属性，第二种方法是手动创建曲线
和关键帧数据，然后将路径设置到属性当中。以下是两种方法的例子：
两个例子都是在激活的 z 轴添加关键帧

obj = bpy.context.object
obj.location[2] = 0.0
obj.keyframe_insert(data_path="location", frame=10.0, index=2)
obj.location[2] = 1.0
obj.keyframe_insert(data_path="location", frame=20.0, index=2)

obj = bpy.context.object
obj.animation_data_create()
obj.animation_data.action = bpy.data.actions.new(name="MyAction")
fcu_z = obj.animation_data.action.fcurves.new(data_path="location", index=2)
fcu_z.keyframe_points.add(2)
fcu_z.keyframe_points[0].co = 10.0, 0.0
fcu_z.keyframe_points[1].co = 20.0, 1.0