四、API使用参考

官方文档：https://docs.blender.org/api/blender_python_api_current/info_api_reference.html

---

　　Blender有很多互连数据类型，它有一个自动生成的引用api，它通常有您需要编写脚本的信息，但是很难使用。

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

1 Reference API Scope

　　参考API覆盖了bpy.types，这里面存储了可以通过bpy.context（用户上下文）和bpy.data（Blend数据文件）获取的类型。

　　bge, bmesh and aud这些模块不使用Blender数据API，所以这篇文档不进行介绍。

2 Data Access

　　使用参考API最常见的情况就是想要在Blend文件中获取数据。

　　在此之前，你最好先了解一下ID数据块，因为你会经常发现和它联系的一些属性。

2.1 ID Data

　　　　ID数据块是Blender中最顶级的数据容器。

　　　　从用户界面看，这不是很明显，但是在开发过程中需要了解ID数据块。

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

　　　　下面是ID数据块公有的特征：

　　　　　　1）ID数据块是Blend文件数据，所以当你加载一个新的Blend文件时，将会从新加载一整套ID数据块

　　　　　　2）ID数据块可以通过Python在bpy.data.*中获取

　　　　　　3）每个数据块都有一个唯一的. name属性，显示在接口中。

　　　　　　4）动画数据存储在ID . animation_data中。

　　　　　　5）ID数据块的类型是唯一可以在blend文件之间链接的数据类型。

　　　　　　6）可以通过Python添加/复制和删除ID数据块。

　　　　　　7）ID有自己的垃圾收集系统，可以在保存时释放未使用的ID。

　　　　　　8）当数据块引用一些外部数据时，这通常是一个ID数据块。

2.2 Simple Data Access  简单的数据获取

　　　　展示一个简单地例子，假设你想调整一个物体的位置。

　　　　从你在用户界面找到Properties Window -> Object -> Transform -> Location按钮开始

　　　　右击按钮，选择Online Python Reference，将把你连接到bpy.types.Object.location

　　　　作为一个API引用，这个链接通常会提供更多的信息，然后是工具提示，尽管其中一些页面包括示例(通常在页面的顶部)。

　　　　这时你可能会说现在该怎么办?-你知道你必须使用.location且它是一个3浮点数组，但你仍然不知道如何在脚本中访问它。

　　　　因此下一步是找出访问对象的位置，向下到页面的底部到引用部分，对于对象来说有很多引用，但是访问对象最常见的地方之一是通过context。

　　　　这时你很容易受打击，因为Object在很多地方都被引用了——修饰符、函数、纹理和约束。

　　　　但是，如果您想访问用户选择的任何数据，通常只需要检查bpy.context的引用。

　　　　即便如此，在这种情况下，还是有相当一部分引用，如果你读过这些就会发现它们大多数是特定于模式的。如果您碰巧编写的工具只运行在weight paint模式下，那么

　　使用weight _paint_object将是合适的。然而，要访问用户最后选择的项目，查找活动成员，访问一个用户选择的单个活动成员是Blender中的约定:eg。active_bone、

　　active_pose_bone active_node……在这种情况下，我们可以使用- active_object。

　　　　这样我们就能找到活动物体的坐标，你可以输入控制台中查看结果

bpy.context.active_object.location

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

　　　　注意：这并没有列在bpy.data.objects中，因为 bpy.data是bpy.types.BlendData这个类的一个实例，因此文档指向那里。

　　　　使用bpy.data.objects,这是一个物体对象的集合，因此你可以访问他的一个属性。

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

2.3 Nested Properties  嵌套属性

　　　　前面的例子非常直接，因为location是Object的属性，它可以直接从context中获取。

　　　　下面有一些更复杂的例子：

# 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控制台的自动完成来查找属性。-这可能有点碰巧的，但优点就是你可通过交互的方式快速的得到属性的值，并看到它修改后的结果。
• 从用户界面复制。进一步解释 in :ref:`Copy Data Path <info_data_path_copy>`
• 使用参考文档。 Explained further in :ref:`Indirect Data Access <info_data_path_indirect>`

2.4 Copy Data Path  复制数据路径

　　　　Blender在工具提示栏的下方保存了一个通过Python脚本获取数据的属性字符串，这可以帮助你直接了解在Python中如何直接获取数据。

　　　　有一个用户界面特性来复制数据路径，该路径从一个bpy.types.ID数据块，到它的属性。

　　　　为了看看这是怎么操作的，我们先获得“the Subdivision-Surface modifiers subdivision setting”的路径

　　　　在默认场景中，选择Modifiers选项卡，然后给Cube添加一个 Subdivision-Surface 。

　　　　把鼠标放到View按钮上，将会显示bpy.types.SubsurfModifier.levels，但是我们想要的是从物体到它属性的路径。

　　　　注意，路径拷贝并不包含bpy.data.collection["name"]。因为它假定您不会在每次访问中都进行收集查找，通常您会希望使用上下文，而不是访问每个bpy. types.ID实例

　　的名字。

　　　　接着，在Python控制台中键入bpy.context.active_object，加上.但不要回车，右击View选择Copy Data Path，再在控制台中粘贴，如下所示：

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

　　　　回车后，将会得到 1 。然后试着改变它的值，你会发现，在用户界面View 的值也跟着改变了。

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

2.5 Indirect Data Access  直接数据获取

　　　这个例子，我们进行一些复杂的操作，来获取活动的雕刻笔刷纹理，来调整它的contrast 。

• 在默认场景中，从3D视图中进入Sculpt模式

• 在属性界面选择 Texture 面板并添加一个纹理. Notice the texture button its self doesn’t have very useful links (you can check the tool-tips).

• 对比设置不在 sculpt 工具栏, 所以看下属性区域的texture面板...

  • 在属性按钮中选择纹理上下文。
  • 选择画笔图表以显示画笔纹理。
  • 展开颜色面板来定位对比按钮。

• 右击contrast button并选择 Online Python Reference 这将带你去bpy.types.Texture.contrast页面

• 现在我们可以发现contrast 是 texture的一个属性, 因此下一步我们将找找如何从brush获取access.

• 检查页面底部的 References , 有时下面有很多 references, 可能需要一些猜测才能找到正确的答案, 但在这里很明显是 Brush.texture.

  现在我们知道texture可以从bpy.data.brushes["BrushName"].texture 获取。但是通常情况下我们不想通过名字来获取Brush，我们想要的是通过当前活动的Brush来获取。

• 接下来就是要从References里找找从哪里获取Brush. 在这个例子中 bpy.context.brush显然使我们需要的.

　　现在你可以在Python控制台中 根据我们已经掌握的逻辑来从嵌套属性中获取笔刷纹理的对比

　　Context -> Brush -> Texture -> Contrast  因此我们可以把上每个属性组合到一起

bpy.context.brush.texture.contrast

　　通常有多种方式来获取同一个数据，这取决于你的工作任务。也可以使用下面这种方式

bpy.context.sculpt.brush.texture.contrast

　　或者直接获取brush

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

　　如果你想编写一个小工具，你更希望使用bpy.context，因为用户的操作往往是在具体的上下文环境中。

　　对于自动化操作，你更希望使用bpy.data，这样你可以使用具体的数据并且操纵它，而不用考虑用户当前正在干什么。

3 Operators  操作

　　Blender中的按键和按钮统称为operater，在Python中可以通过bpy.ops来访问。

　　将鼠标放到按钮上，就会在提示框中显示等价的Python操作，如果不显示，就说明在Python中不能进行这个操作。

　　如果你想使用这个接口时，你可以在你鼠标放在它上面时按Control-C。

　　也可以右击选择Online Python Reference这主要显示了参数和它们的默认值，以及用Python中编写的操作符显示了它们的文件和行号，如果您有兴趣检查源代码的话，

它们可能是有用的。注意：并不是所有operater都可以在Python中使用，详见using operators

3.1 Info View  信息窗口

　　Blender在信息窗口中记录了你的所有操作，它在file-menu窗口下方，你可以向下拖动，以显示它的内容。

　　选择默认为Blender的脚本屏幕，以查看其输出。您可以执行一些操作并看到它们显示——例如删除一个顶点。

　　每个条目都可以选择(鼠标右键)，然后复制control - c，通常在文本编辑器或python控制台进行粘贴。

　　注意：并不是所有的操作符都可以注册以显示，例如将视图放大到重复的视图并不是很有用，因此它被排除在输出之外。

　　Show All Operators这里显示了所有的操作符。