Blender参考API用法

Blender参考API用法

Blender有许多互连数据类型，它们具备自动生成的引用api，它一般具备编写脚本所需的信息，但可能难以使用。

本文档旨在帮助您了解如何使用参考API。

参考API范围

参考API涵盖bpy.types，存储经过如下方式访问的类型bpy.context- 用户上下文 或bpy.data- 混合文件数据。

其余模块，例如bge，bmesh而且aud没有使用Blenders数据API，所以本文档不适用于这些模块。

数据访问

使用参考API的最多见状况是找出如何访问混合文件中的数据。

在进一步了解Blender中的ID数据块以前，您常常会找到与它们相关的属性。

ID数据

ID数据块在Blender中用做顶级数据容器。

从用户界面来看，这不是那么明显，但在开发时，您须要了解ID数据块。

ID数据类型包括场景，组，对象，网格，屏幕，世界，电枢，图像和纹理。有关完整列表，请参阅子类bpy.types.ID

如下是ID数据块共享的一些特征。

ID是混合文件数据，所以加载新的混合文件会从新加载一组全新的数据块。
ID能够在Python中访问 bpy.data.*
每一个数据块都有一个惟一的.name属性，显示在界面中。
动画数据存储在ID中.animation_data。
ID是惟一能够在混合文件之间连接的数据类型。
能够经过Python添加/复制和删除ID。
ID有本身的垃圾收集系统，能够在保存时释放未使用的ID。
当数据块具备对某些外部数据的引用时，这一般是ID数据块。

简单的数据访问

让咱们从一个简单的案例开始，说你不是一个python脚原本调整对象的位置。

首先在界面中找到此设置 Properties Window -> Object -> Transform -> Location

从按钮，您能够右键单击并选择在线Python参考，这将连接到： bpy.types.Object.location

做为API参考，此连接一般提供的信息比工具提示少，但有些页面包含示例（一般位于页面顶部）。

此时你可能会说如今是什么？- 你知道你必须使用.location它的3个浮点数组，但你仍然想知道如何在脚本中访问它。

因此下一步是找出访问对象的位置，在页面底部到References 部分，对于有不少引用的对象，可是访问对象的最多见的地方之一是经过上下文。

在这一点上很容易被淹没，由于Object在不少地方引用了它 - 修饰符，函数，纹理和约束。

可是，若是要访问用户选择的任何数据，一般只须要检查bpy.context引用。

即使如此，在这种状况下，若是您阅读这些内容还有至关多的内容 - 大多数都是模式特定的。若是您正在编写仅在重量涂料模式下运行的工具，那么使用weight_paint_object 是合适的。可是，要访问用户上次选择的项目，请查找active成员，有权访问用户选择的单个活动成员是Blender中的约定：例如。active_bone， active_pose_bone，active_node...在这种状况下，咱们可使用- active_object。

因此如今咱们有足够的信息来查找活动对象的位置。

bpy.context.active_object.location

您能够在python控制台中键入它以查看结果。

访问引用中对象的另外一个常见位置是bpy.types.BlendData.objects。

注意 这不是列为bpy.data.objects，这是由于bpy.data是bpy.types.BlendData类的一个实例，因此文档指向那里。

使用bpy.data.objects，这是一组对象，所以您须要访问其中一个成员。

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

嵌套属性

前面的示例很是简单，由于能够直接从上下文访问location其属性Object。

如下是一些更复杂的例子：

# access a render layers samples
bpy.context.scene.render.layers["RenderLayer"].samples

# access to the current weight paint brush size
bpy.context.tool_settings.weight_paint.brush.size

# check if the window is fullscreen
bpy.context.window.screen.show_fullscreen

正如您所看到的，有时您但愿访问嵌套的数据，这种方式会致使您经历一些间接。

这些属性被安排为匹配数据在内部存储的方式（在混合器C代码中），这一般是合乎逻辑的，但并不老是与使用Blender指望的彻底相同。

所以，这须要一些时间来学习，它能够帮助您了解数据在Blender中的组合方式，这对于编写脚本很是重要。

在开始编写脚本时，您常常会遇到没法肯定如何访问所需数据的问题。

有几种方法能够作到这一点。

• 使用Python控制台的自动完成来检查属性。 这可能会出类拔萃，但其优点在于您能够轻松查看属性值并将其分配给交互式查看结果。
• 从用户界面复制数据路径。 进一步解释：ref：复制数据路径<info_data_path_copy>
• 使用文档来关注参考。 进一步解释：ref：间接数据访问<info_data_path_indirect>

复制数据路径

Blender能够将Python字符串计算为属性，该属性显示在工具提示中，以下所示。这节省了必须使用API​​引用来单击备份引用以查找数据的访问位置。Python: ...

有一个用户界面功能能够复制数据路径，该路径提供从bpy.types.ID数据块到其属性的路径。

为了了解这是如何工做的，咱们将得到Subdivision-Surface修改器细分设置的路径。

从默认场景开始，选择“ 修改器”选项卡，而后将“ 细分 - 曲面”修改器添加到多维数据集。

如今将鼠标悬停在标记为View的按钮上，工具提示包括bpy.types.SubsurfModifier.levels 但咱们想要从对象到此属性的路径。

请注意，复制的文本将不包含该bpy.data.collection["name"].组件，由于它假定您不会在每次访问时进行集合查找，而且一般您但愿使用上下文而不是bpy.types.ID按名称访问每一个实例。

在Python控制台中输入ID路径bpy.context.active_object。包括尾随点，但不要点击“输入”。

如今，右键单击该按钮并选择“ 复制数据路径”，而后将结果粘贴到控制台中。

因此如今你应该获得答案：

bpy.context.active_object.modifiers["Subsurf"].levels

按“输入”，您将得到当前值1.如今尝试将值更改成2：

bpy.context.active_object.modifiers["Subsurf"].levels = 2

您能够在Subdivision-Surface修改器的UI和多维数据集中看到值更新。

间接数据访问

在这个例子中，咱们将讨论更多涉及的内容，显示访问活动的雕刻画笔纹理的步骤。

让咱们说咱们想经过Python访问画笔的纹理，以调整它contrast的例子。

• 从默认场景开始，从3D-View标题启用“Sculpt”模式。
• 从工具栏中展开“ 纹理”面板并添加新纹理。 注意纹理按钮，它本身没有很是有用的连接（你能够检查工具提示）。

• 对比度设置未在雕刻工具栏中显示，所以在属性面板中查看纹理...

  • 在属性按钮中，选择“纹理”上下文。
  • 选择“画笔”图标以显示画笔纹理。
  • 展开“ 颜色”面板以找到“ 对比度”按钮。
• 右键单击对比按钮，并选择在线Python的引用 这须要你bpy.types.Texture.contrast
• 如今咱们能够看到这contrast是纹理的属性，接下来咱们将检查如何从画笔访问纹理。
• 检查页面底部的参考文献，有时会有不少参考文献，而且可能须要一些猜想才能找到合适的参考文献，但在这种状况下显然是这样Brush.texture。
• 如今咱们知道能够从中访问纹理， bpy.data.brushes["BrushName"].texture 但一般您不但愿按名称访问画笔，所以咱们如今将看到访问活动画笔。
• 所以，下一步是经过参考文件检查访问画笔的位置。在这种状况下，bpy.context.brush咱们只须要它。

如今，您可使用Python控制台来造成访问画笔纹理对比所需的嵌套属性，逻辑上咱们如今知道了。

上下文 - >画笔 - >纹理 - >对比度

因为每一个属性都是按照咱们在python控制台中组成数据路径的方式给出的：

bpy.context.brush.texture.contrast

能够有多种方式来访问相同的数据，您选择的方法一般取决于任务。

访问相同设置的备用路径是......

bpy.context.sculpt.brush.texture.contrast

或者直接访问画笔......

bpy.data.brushes["BrushName"].texture.contrast

若是您正在编写用户工具，则一般须要使用，bpy.context由于用户一般但愿该工具对他们选择的内容进行操做。

对于自动化，您更有可能使用，bpy.data由于您但愿可以访问特定数据并对其进行操做，不管用户当前具备何种视图集。

操做

Blender中的大多数按键和按钮都会调用一个操做符，该操做符也会暴露给python via bpy.ops，

要查看Python等效项，请将鼠标悬停在按钮上并查看工具提示，例如，若是没有工具提示或缺乏行，则此按钮不使用运算符，没法从Python访问。Python: bpy.ops.render.render()Python:

若是要在脚本中使用它，能够Control-C在鼠标悬停在按钮上时将其复制到剪贴板。

您也能够右键单击按钮并查看在线Python参考，这主要显示参数及其默认值，可是用Python编写的运算符显示其文件和行号，若是您有兴趣检查源代码，这可能颇有用。

注意 并不是全部运算符均可以从Python中有用地调用，有关详细信息，请参阅使用运算符。

信息视图

Blender记录您运行的运算符并在信息空间中显示它们。它位于文件菜单上方，能够向下拖动以显示其内容。

选择Blender默认的脚本屏幕以查看其输出。您能够执行某些操做并看到它们显示 - 例如删除顶点。

能够选择每一个条目（右键 - 鼠标 - 按钮），而后复制Control-C，一般粘贴到文本编辑器或python控制台中。

注意 并不是全部操做员都注册显示，例如缩放视图对于重复这样作是没有用的，所以将其排除在输出以外。要显示运行的每一个运算符，请参阅显示全部运算符