发布时间:2019/10/16 17:33:43   更新时间:2020/07/31 19:49:42
本文官网地址:https://docs.blender.org/api/current/info_api_reference.html
本文基于Blender2.80。
提示:译解是指翻译和注解。【注解】是作者的一些个人解释,用【】符号括起来。
Blender具有许多相互链接的数据类型,这些数据类型具有自动生成的参考api,该参考api通常具有编写脚本所需的信息,但可能难以使用。
本文档旨在帮助您了解如何使用参考api。
参考API覆盖bpy.types,其存储类型通过访问bpy.context(用户上下文)或bpy.data(blend文件数据)。
其他模块(例如bmesh和aud不使用Blenders数据API),因此本文档不适用于这些模块。
使用参考API的最常见情况是找出如何访问blend文件中的数据。
在进行任何进一步工作之前,最好先了解Blender中的ID数据块,因为您经常会发现与其相关的属性。
ID Data-Blocks在Blender中用作顶级数据容器。
从用户界面来看,这不是很明显,但是在开发时,您需要了解ID数据块。
ID数据类型包括场景,组,对象,网格,屏幕,世界,电枢,图像和纹理。有关完整列表,请参见的子类。bpy.types.ID
以下是ID数据块共享的一些特征:
* ID是blend文件数据,因此加载新的blend文件会重新加载整个新的数据块集。
* 可以在Python中从bpy.data.*访问ID。
* 每个数据块都有一个唯一的.name属性,显示在界面中。
* 动画数据存储在ID的.animation_data。
* ID是唯一可以在blend文件之间链接的数据类型。
* 可以通过Python添加/复制和删除ID。
* ID有其自己的垃圾收集系统,可以在保存时释放未使用的ID。
* 当数据块引用某些外部数据时,通常是ID数据块。
让我们从一个简单的案例开始,假设您要使用python脚本来调整对象的位置。
首先在界面中找到此设置 Properties Window -> Object -> Transform -> Location
从按钮上您可以右键单击并选择Online Python Reference,这将使您链接到:bpy.types.Object.location
作为API参考,此链接通常只提供比工具提示更多的信息,尽管某些页面包含示例(通常在页面顶部)。
此时您可能会说现在呢?-您知道必须使用它.location,并且它由3个浮点数组成,但是您仍然想知道如何在脚本中访问它。
因此,下一步是找出要访问对象的位置,然后转到页面底部的“ 引用” 部分,对于对象,有很多引用,但是最常见的访问对象之一是通过上下文。
在这一点上很容易不知所措,因为Object在很多地方都引用了它-修饰符,函数,纹理和约束。
但是,如果要访问用户选择的任何数据,通常只需要检查bpy.context引用即可。
即使这样,在这种情况下,如果您仔细阅读这些内容,还是相当一部分是用于特定于模式的。如果您恰巧正在编写仅在加重绘制模式下运行的工具,则使用weight_paint_object 会合适。但是,要访问用户最后选择的项目,请查找活动成员。访问用户选择的单个活动成员是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
如您所见,有时候您想访问嵌套的数据,从而导致您经历一些间接访问。
属性的设置是为了匹配数据在内部的存储方式(在blenders C代码中),这通常是合乎逻辑的,但并不总是与使用Blender所期望的完全一致。
因此,这需要花费一些时间来学习,它可以帮助您了解Blender中数据如何组合在一起,这在编写脚本时必须要了解。
开始编写脚本时,通常会遇到不确定如何访问所需数据的问题。
有几种方法可以做到这一点。
* 使用Python控制台的自动完成功能检查属性。 这可以是碰碰运气,但它的优点是您可以轻松查看属性的值并将其分配给交互地查看结果。
* 从用户界面复制数据路径。 复制数据路径<info_data_path_copy>中进一步解释。
* 使用文档遵循参考。 间接数据访问<info_data_path_indirect>中进一步解释
Blender可以将Python字符串计算为一个属性,该属性显示在工具提示下一行Python: ... 的下面,这省去了使用API??引用单击备份引用以查找从何处访问数据的麻烦。
有一个用户界面功能可将数据路径(该路径提供从bpy.types.ID数据块到其属性的路径)进行复制。
要了解其工作原理,我们将获得Subdivision-Surface修改器细分设置的路径。
从默认场景开始,然后选择“ 修改器”选项卡,然后将“ 细分表面”修改器添加到多维数据集。
现在,将鼠标悬停在标签为View的按钮上,该工具提示包括bpy.types.SubsurfModifier.levels 但我们想要从对象到此属性的路径。
请注意,复制的文本将不包含该bpy.data.collection["name"].组件,因为它假定您不会在每次访问时都进行集合查找,并且通常您希望使用上下文而不是bpy.types.ID按名称访问每个实例。
在Python控制台中输入ID路径bpy.context.active_object。包括尾随点,不要点击“ enter”。
现在,右键单击该按钮,然后选择复制数据路径,然后将结果粘贴到控制台中。
所以现在您应该有了答案:
bpy.context.active_object.modifiers["Subsurf"].levels
点击“ enter”,您将获得当前值1。现在尝试将值更改为2:
bpy.context.active_object.modifiers["Subsurf"].levels = 2
您可以在Subdivision-Surface修改器的UI和多维数据集中看到值更新。
对于此示例,我们将介绍更多相关内容,显示访问活动雕刻笔刷纹理的步骤。
假设我们要通过Python访问画笔的纹理,contrast例如进行调整。
* 从默认场景开始,并从3D-View标头启用“雕刻”模式。
* 在工具栏中,展开“ 纹理”面板,然后添加新的纹理。 请注意,纹理按钮本身没有非常有用的链接(您可以查看工具提示)。
* 对比度设置未显示在雕刻工具栏中,因此请在属性面板中查看纹理…
在属性按钮中,选择纹理上下文。
选择“画笔”图标以显示画笔纹理。
展开“ 颜色”面板,找到“ 对比度”按钮。
* 右键单击对比按钮,并选择在线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中的大多数按键和按钮都调用了一个运算符,该运算符也通过bpy.ops,
要查看等效的Python,请将鼠标悬停在该按钮上并查看工具提示,例如Python: bpy.ops.render.render(),如果没有工具提示或缺少Python:行,则此按钮未使用运算符,因此无法从Python访问。
如果要在脚本中使用它,则可以Control-C在鼠标悬停在按钮上时按将其复制到剪贴板。
您也可以右键单击该按钮并查看Online Python Reference,它主要显示参数及其默认值,但是用Python编写的运算符显示其文件和行号,如果您有兴趣检查源代码,这可能会很有用。
注意
并非所有的运算符都可以从Python中有用地调用,有关更多信息,请参见使用operator。
Blender会记录您运行的运算符,并将其显示在“ 信息”空间中。它位于文件菜单上方,可以向下拖动以显示其内容。
选择Blender随附的默认脚本屏幕以查看其输出。您可以执行一些操作并看到它们出现-例如删除一个顶点。
可以选择每个条目(鼠标右键),然后复制Control-C,通常将其粘贴到文本编辑器或python控制台中。
注意
并非所有运算符都已注册显示,例如缩放视图并没有太大用处,因此可以将其从输出中排除。
要显示每个运行的运算符,请参阅显示所有运算符。