快速入门简介
前言
此API通常是稳定的，但某些部分仍在添加和改进。
Blender / Python API可以执行以下操作：
编辑用户界面可以使用的任何数据（场景，网格，粒子等）
修改用户首选项，键盘图和主题
使用自己的设置运行工具
创建用户界面元素，例如菜单，标题和面板
创建新工具
创建交互式工具
创建与Blender集成的新渲染引擎
在现有Blender数据中定义新设置
使用Python中的OpenGL命令在3D视图中绘图
Blender / Python API 不能（还）......
创建新的空间类型。
为每种类型分配自定义属性。
定义在数据更改时要通知的回调或侦听器。
开始之前
本文档无意完全涵盖每个主题。相反，它的目的是让您熟悉Blender Python API。
在开始之前要了解的有用事项的快速列表：
Blender使用Python 3.x; 一些在线文档仍然使用2.x.
交互式控制台非常适合测试单行程序。它还具有自动完成功能，因此您可以快速检查API。
按钮工具提示显示Python属性和操作名称。
右键单击按钮和菜单项可直接链接到API文档。
有关更多示例，文本菜单有一个模板部分，其中可以找到一些示例运算符。
要检查使用Blender分发的其他脚本，请参阅：
scripts/startup/bl_ui 用户界面，
scripts/startup/bl_operators 操作员。
确切位置取决于平台，请参阅： 配置和数据路径。
运行脚本
执行Python脚本的两种最常用方法是使用内置文本编辑器或在Python控制台中输入命令。
无论是文本编辑器和Python的控制台都是面板类型，您可以从视图标题选择。
您可能更喜欢使用Scripting屏幕（默认情况下包含Blender），可以从顶部标题屏幕选择器访问，而不是手动配置Python开发空间。
从文本编辑器中，您可以打开.py文件或从剪贴板粘贴，然后使用“运行脚本”进行测试。
Python控制台通常用于输入代码段和测试以获得即时反馈，但也可以将整个脚本粘贴到其中。
脚本也可以使用Blender从命令行运行，但要学习Blender / Python，这不是必需的。
关键概念
数据访问
访问数据块
Python以与动画系统和用户界面相同的方式访问Blender的数据; 这意味着任何可以通过按钮更改的设置也可以从Python更改。
使用该模块访问当前加载的混合文件中的数据bpy.data。这样可以访问库数据。例如：
>>> bpy.data.objects
>>> bpy.data.scenes
>>> bpy.data.materials
关于集合
您会注意到索引和字符串可用于访问集合的成员。
与Python的词典不同，这两种方法都是可以接受的; 但是，运行Blender时，成员的索引可能会发生变化。
>>> 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"]
访问属性
一旦有了数据块，例如材料，对象，组等，就可以像使用图形界面更改设置一样访问其属性。事实上，每个按钮的工具提示也会显示Python属性，这有助于查找脚本中要更改的设置。
>>> bpy.data.objects[0].name'Camera'
>>> bpy.data.scenes["Scene"]bpy.data.scenes['Scene']
>>> bpy.data.materials.new("MyMaterial")bpy.data.materials['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中的新数据块：
>>> bpy.types.Mesh()
Traceback (most recent call last):
File"", line1, in
TypeError:bpy_struct.__new__(type): expected a single argument
这是API设计的有意识部分。Blender / Python API无法创建存在于主Blender数据库（通过其访问bpy.data）之外的Blender数据，因为此数据由Blender管理（save / load / undo / append ...等）。
通过集合中的方法添加和删除数据bpy.data，例如：
>>> mesh=bpy.data.meshes.new(name="MyMesh")
>>> print(mesh)
>>> bpy.data.meshes.remove(mesh)
自定义属性
Python可以访问具有ID的任何数据块的属性（可以链接和访问的数据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
整数/浮点数
字典（仅支持字符串键，值也必须是基本类型）
这些属性在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参考。
Operators (Tools)
操作员通常是用户通过按钮，菜单项或键快捷键访问的工具。从用户的角度来看，它们是一个工具，但Python可以通过bpy.ops模块使用自己的设置来运行它们。
例子：
>>> bpy.ops.mesh.flip_normals()
{'FINISHED'}
>>> bpy.ops.mesh.hide(unselected=False)
{'FINISHED'}
>>> bpy.ops.object.scale_apply()
{'FINISHED'}
注意
菜单项：帮助‣运算符备忘单 提供了Python语法中所有运算符及其默认值的列表，以及生成的文档。这是了解所有Blender运营商概况的好方法。
Operator Poll()
许多操作员都有一个“轮询”功能，可以检查光标是在有效区域还是对象处于正确模式（编辑模式，重量绘制等）。当操作符的poll函数在Python中失败时，会引发异常。
例如，bpy.ops.view3d.render_border()从控制台调用会引发以下错误：
RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect
在这种情况下，上下文必须是具有活动相机的3d视图。
为了避免在调用运算符的地方使用try / except子句，可以调用运算符自己的poll()函数来检查它是否可以在当前上下文中运行。
if bpy.ops.view3d.render_border.poll():
bpy.ops.view3d.render_border()
整合
Python脚本可以通过以下方式与Blender集成：
·通过定义渲染引擎。
·通过定义操作。
·通过定义菜单，标题和面板。
·通过在现有菜单，标题和面板中插入新按钮
在Python中，这是通过定义一个类来完成的，该类是现有类型的子类。
示例操作
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
bpy.ops.object.simple_operator()
此脚本运行后，SimpleOperator将在Blender中注册，可以从操作员搜索弹出窗口中调用或添加到工具栏中。
要运行脚本：
1、突出显示上面的代码然后按下Ctrl-C以复制它。
2、启动Blender
3、按Ctrl-Right两次以更改为“脚本”布局。
4、单击标记的按钮New并弹出确认以创建新的文本块。
5、按Ctrl-V将代码粘贴到文本面板（左上方框架）。
6、单击“ 运行脚本 ”按钮。
7、将光标移动到3D视图，按空格键选择操作员搜索菜单，然后键入“Simple”。
8、单击搜索中的“Simple Operator”项。
具有bl_前缀的类成员记录在API参考中bpy.types.Operator
注意
该main功能的输出发送到终端; 为了看到这一点，一定要使用终端。
示例面板
面板将自己注册为类，就像操作员一样。注意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、突出显示上面的代码然后按下Ctrl-C以复制它
2、启动Blender
3、按Ctrl-Right两次以更改为“脚本”布局
4、单击标记的按钮New并弹出确认以创建新的文本块。
5、按Ctrl-V将代码粘贴到文本面板（左上方框架）
6、单击“ 运行脚本 ”按钮。
要查看结果：
1、选择默认多维数据集。
2、单击按钮面板中的对象属性图标（最右侧;显示为一个小立方体）。
3、向下滚动以查看名为Hello World Panel的面板。
4、更改对象名称还会更新Hello World Panel的名称：字段。
请注意行分布以及代码中可用的标签和属性。
也可以看看bpy.types.Panel
类型
Blender定义了许多Python类型，但也使用Python本机类型。
Blender的Python API可以分为3类。
原生类型
在简单的情况下，将数字或字符串作为自定义类型返回会很麻烦，因此可以将它们作为普通的Python类型进行访问。
Blender float / int / boolean - > float / int / boolean
Blender枚举器 - >字符串
>>> Ç 。对象。rotation_mode = 'AXIS_ANGLE'
Blender枚举器（多个） - >字符串集
＃设置多个相机覆盖指南bpy 。背景。场景。相机。数据。show_guide = { 'GOLDEN' ，'CENTER' } ＃作为报告类型self 的运算符参数传递。报告（{ '警告' ，'信息' }，“有些消息！” ）
内部类型
用于Blender数据块和集合： bpy.types.bpy_struct
对于包含其自己的属性组/网格/骨骼/场景等的数据...等。
有两种主要类型包装Blenders数据，一种用于数据块（内部称为bpy_struct），另一种用于属性。
>>> bpy 。背景。对象bpy.data.objects ['Cube']
>>> Ç 。场景。对象bpy.data.scenes ['Scene']。对象
请注意，这些类型引用了Blender的数据，因此可以立即看到它们的修改。
Mathutils类型
用于矢量，四元数，eulers，矩阵和颜色类型，可从 mathutils
某些属性如bpy.types.Object.location， bpy.types.PoseBone.rotation_euler和bpy.types.Scene.cursor_location 可以作为特殊数学类型访问，这些类型可以一起使用并以各种有用的方式进行操作。
矩阵示例，向量乘法：
bpy 。背景。对象。matrix_world * bpy 。背景。对象。数据。verts [ 0 ] 。合作
注意
mathutils类型保留对Blender内部数据的引用，因此可以应用更改。
例：
＃修改Z轴到位。bpy 。背景。对象。位置。z + = 2.0 ＃location变量也包含对象的引用。location = bpy 。背景。对象。location location * = 2.0 ＃复制值会删除引用，因此可以将值传递给#function并修改，而不会产生不必要的副作用。location = bpy 。背景。对象。位置。复制（）
动画
有两种方法可以通过Python添加关键帧。
第一种是直接通过键属性，类似于从按钮作为用户插入关键帧。您也可以手动创建曲线和关键帧数据，然后设置属性的路径。以下是两种方法的示例。
两个示例都在活动对象的Z轴上插入关键帧。
简单的例子：
obj = bpy 。背景。对象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 。背景。对象obj 。animation_data_create （）obj 。animation_data 。action = bpy 。数据。行动。new （name = “MyAction” ）fcu_z = obj 。animation_data 。行动。曲折。new （data_path = “location” ，index = 2 ）fcu_z 。keyframe_points 。添加（2 ）fcu_z 。keyframe_points [ 0 ] 。共= 10.0 ，0.0 fcu_z 。keyframe_points [ 1 ] 。共= 20.0 ，1.0
