发布时间:2019/10/11 11:51:03   更新时间:2020/07/31 19:49:36
本文官网地址:https://docs.blender.org/api/current/info_quickstart.html
本文基于Blender2.80。
提示:译解是指翻译和注解。【注解】是作者的一些个人解释,用【】符号括起来。
这些API通常是稳定的,但仍然在某些方面进行着添加和改进。
【blender python 常常简称bpy】
Blender Python Api可以执行以下操作:
* 编辑用户界面可以操作的任何数据(场景,网格,粒子等)。
* 修改用户首选项,键映射和主题。
* 使用自己的设置运行工具。
* 创建用户界面元素,例如菜单,标题和面板。
* 创建新工具。
* 创建交互式工具。
* 创建与Blender集成的新渲染引擎。
* 订阅对数据及其属性的更改。
* 在现有Blender数据中定义新设置。
* 使用Python在3D视图中绘制。
Blender Python Api还无法做到的事情:
* 创建新的空间类型。
* 为每种分类分配自定义属性。
本文档无意覆盖所有主体。相反,其目的是让您熟悉Blender Python Api。
在开始之前,需要了解的有用事项的快速列表:
* Blender使用Python 3.x;一些在线文档仍假定使用2.x。
* 交互式控制台非常适合测试单条命令。它还具有自动补全功能,因此您可以快速检查API。
【python控制台编辑器好比python的cmd,可以敲单行命令。Ctlr + Space自动补全。】
* 按钮工具提示显示Python属性和操作符名称。
* 右键单击按钮和菜单项可直接链接到API文档。
* 对于更多示例,文本菜单具有模板部分,可在其中找到一些示例操作符。
* 要检查使用Blender分发的其他脚本,请参阅:
scripts/startup/bl_ui 对于用户界面,
scripts/startup/bl_operators 对于操作符。
确切位置取决于平台,请参阅: 目录布局docs。
【在你的安装目录比如C:\Program Files\Blender Foundation\Blender\2.80\scripts\startup\bl_operators,可以找到这些脚本。】
执行Python脚本的两种最常见的方法是使用内置的文本编辑器或在Python控制台中输入命令。
无论是文本编辑器和Python的控制台都是是编辑器类型,您可以从视图标题选择。
与其手动配置用于Python开发的工作空间,不如使用Blender随附的默认脚本空间屏幕,可从顶部标题屏幕选择器访问该空间。
【这里说的是blender最上方的 Scripting工作空间。工作空间默认有10个,Scripting排序在最后一个,可能看不见。你需要通过右键重排或者显示下一个的方法去打开。】
在文本编辑器中,您可以打开.py文件或粘贴,然后从剪贴板中打开,然后使用“运行脚本”进行测试。
Python控制台通常用于键入代码片段和进行测试以获取即时反馈,但也可以将整个脚本粘贴到其中。
脚本也可以使用Blender从命令行运行,但是要学习Blender / Python并不是必须的。
【3d视图编辑器中操作物体,会在信息编辑器看到命令,命令复制粘贴到python控制台编辑器里,即可再次使用。很多默认参数也可以删除。】
【
Blender Python(bpy)有9个主要部分。您不需要记住这些,但是了解其中一些可以帮助您了解Blender的工作原理。
bpy.app:有关Blender本身的信息,在运行时不会更改。
bpy.context:Blender中当前活动内容的只读列表。
bpy.data:Blender的所有内部数据,例如对象。
bpy.msgbus:代表“消息总线”,用于通知Blender某些更改。不用担心。
bpy.ops:您可以在Blender中执行的所有操作,从建模到将文件附加到渲染。
bpy.path:处理文件路径的函数。
bpy.props:Blender使用的不同属性。您可以使用它来告诉Blender输入应该是数字还是颜色。
bpy.types:Blender中存在的每种事物类型,从修改器到纹理再到灯等等。
bpy.utils:实用程序功能,仅适用于Blender,但不处理内部数据。
】
Python以与动画系统和用户界面相同的方式访问Blender的数据;这意味着可以通过按钮更改的任何设置也可以从Python更改。
使用模块可以完成从当前加载的blend文件访问数据的操作bpy.data。这样就可以访问库数据。例如:
>>> bpy.data.objects
<bpy_collection[3], BlendDataObjects>
>>> bpy.data.scenes
<bpy_collection[1], BlendDataScenes>
>>> bpy.data.materials
<bpy_collection[1], BlendDataMaterials>
您会注意到,索引和字符串都可以用来访问集合的成员。
这与Python的字典【dict】不同,这两种方法都是可以接受的。但是,在运行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 "<blender_console>", line 1, in <module>
TypeError: bpy_struct.__new__(type): expected a single argument
这是API设计的故意部分。Blender / Python API无法创建在Blender主数据库之外(通过访问bpy.data)的Blender数据,因为该数据由Blender管理(保存/加载/撤消/附加…等)。
可以通过中的集合上的方法来添加和删除数据bpy.data,例如:
>>> mesh = bpy.data.meshes.new(name="MyMesh")
>>> print(mesh)
<bpy_struct, Mesh("MyMesh.001")>
>>> bpy.data.meshes.remove(mesh)
Python可以访问具有ID的任何数据块上的属性(可以链接和访问的数据bpy.data。分配属性时,您可以组成自己的名称,这些名称将在需要时创建,或者如果存在则被覆盖。
此数据与blend文件一起保存,并与对象一起复制。
例:
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.
collection = bpy.data.collections.new("MyTestCollection")
collection["MySettings"] = {"foo": 10, "bar": "spam", "baz": {}}
del collection["MySettings"]
请注意,只能为这些属性分配基本的Python类型。
整数,浮点数,字符串
整数/浮点数数组
字典(仅支持字符串键,值也必须是基本类型)
这些属性在Python外部有效。它们可以通过曲线设置动画或在驱动路径中使用。
能够直接通过名称或列表访问数据非常有用,但更常见的是根据用户的选择进行操作。上下文始终可从中获得bpy.context,并可用于获取活动对象,场景,工具设置以及许多其他属性。
常用案例:
>>> bpy.context.object
>>> bpy.context.selected_objects
>>> bpy.context.visible_bones
请注意,上下文是只读的。这些值不能直接修改,尽管可以通过运行API函数或使用数据API来更改它们。
因此会引发错误。bpy.context.object = obj
但是会按预期工作。bpy.context.scene.objects.active = obj
上下文属性根据访问它们的位置而变化。3D视图具有与控制台不同的上下文成员,因此在访问已知用户状态的上下文属性时要格外小心。
请参阅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操作符的好方法。
许多操作符都具有“轮询”功能,可以检查光标是否在有效区域内或对象是否处于正确模式(编辑模式,重量涂料等)。当操作符的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两次以更改为脚本布局。【就是进入Scripting工作区】
4、单击标记为的按钮New,然后弹出确认以创建新的文本块。
5、按下Ctrl-V可将代码粘贴到文本面板(左上框架)中。
6、点击按钮运行脚本。
7、将光标移到3D视图中,按空格键进入操作符搜索菜单,然后键入“Simple”。
8、单击在搜索中找到的“Simper Operator”项。
也可以看看
bl_API参考中记录了带有前缀的类成员bpy.types.Operator
注意
main函数的输出发送到终端;为了看到这一点,请务必使用终端。
面板像操作符一样将自己注册为类。注意bl_用于设置它们显示上下文的额外变量。
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、单击“ 脚本”工作区的选项卡。
4、单击标记New为创建新文本块的按钮。
5、按下Ctrl-V可将代码粘贴到文本面板(左上框架)中。
6、点击按钮运行脚本。
要查看结果:
1、选择默认的立方体。
2、单击按钮面板中的“对象属性”图标(最右边;显示为一个小立方体)。
3、向下滚动以查看名为Hello World Panel的面板。
4、更改对象名称还会更新Hello World Panel的“名称:”字段。
请注意行分布以及该代码中可用的标签和属性。
也可以看看
Blender定义了许多Python类型,但也使用Python本机类??型。
Blender的Python API可以分为3类。
在简单的情况下,返回数字或字符串作为自定义类型会很麻烦,因此可以将它们作为普通的Python类型进行访问。
Blender float / int / boolean-> float / int / boolean
Blender枚举器->字符串
Blender枚举器(多个)->字符串集
用于Blender数据块和集合: bpy.types.bpy_struct
对于包含其自身属性的数据,包括集合/网格/骨骼/场景等。
包装Blenders数据的主要类型有2种,一种用于数据块(内部称为bpy_struct),另一种用于属性。
>>> bpy.context.object
bpy.data.objects['Cube']
>>> C.scene.objects
bpy.data.scenes['Scene'].objects
请注意,这些类型引用了Blender的数据,因此修改它们立即可见。
用于向量,四元数,euler,矩阵和颜色类型,可从以下位置访问 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
注意
mathutils类型保留对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