Blender参考API用法

摘要：在控制台中输入路径。因此，下一步是通过参考文件检查访问画笔的位置。上下文画笔纹理对比度由于每个属性都是按照我们在控制台中组成数据路径的方式给出的可以有多种方式来访问相同的数据，您选择的方法通常取决于任务。

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

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

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

其他模块，例如bge，bmesh并且aud没有使用Blenders数据API，因此本文档不适用于这些模块。

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

在进一步了解Blender中的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：复制数据路径

使用文档来关注参考。 进一步解释：ref：间接数据访问

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

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