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控制台中。

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