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

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

    原文作者:小佩琪
    原文地址: https://segmentfault.com/a/1190000015906099
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞