blender python官网文档译解之快速入门介绍


类别:3d应用   

发布时间: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()

许多操作符都具有“轮询”功能,可以检查光标是否在有效区域内或对象是否处于正确模式(编辑模式,重量涂料等)。当操作符的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的“名称:”字段。

请注意行分布以及该代码中可用的标签和属性。

也可以看看

bpy.types.Panel

类型

Blender定义了许多Python类型,但也使用Python本机类??型。

Blender的Python API可以分为3类。

原生类型

在简单的情况下,返回数字或字符串作为自定义类型会很麻烦,因此可以将它们作为普通的Python类型进行访问。

Blender float / int / boolean-> float / int / boolean

Blender枚举器->字符串

  • >>> C.object.rotation_mode = 'AXIS_ANGLE'

Blender枚举器(多个)->字符串集

  • # 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

对于包含其自身属性的数据,包括集合/网格/骨骼/场景等。

包装Blenders数据的主要类型有2种,一种用于数据块(内部称为bpy_struct),另一种用于属性。

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

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

请注意,这些类型引用了Blender的数据,因此修改它们立即可见。

Mathutils类型

用于向量,四元数,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


本文网址:https://www.pyfield.com/blog/?id=31