1.1 Why does an operator’s poll fail?

为什么operater的poll会失败

当你调用一个操作有如下的错误提示时:

>>> bpy.ops.action.clean(threshold=0.001)
RuntimeError: Operator bpy.ops.action.clean.poll() failed, context is incorrect

Which raises the question as to what the correct context might be?

这就提出了一个问题:正确的环境可能是什么?

Typically operators check for the active area type, a selection or active object they can operate on, but some operators are more picky about when they run.

一般来说，操作员会检查活动区域类型，操作的是选择或活动对象，但是一些operators 在运行时更挑剔。

In most cases you can figure out what context an operator needs simply be seeing how it’s used in Blender and thinking about what it does.

在大多数情况下，你可以弄清楚一个操作需要什么上下文，只需看看它在Blender中是如何使用的，并思考它所做的事情。

Unfortunately if you’re still stuck - the only way to really know whats going on is to read the source code for the poll function and see what its checking.

如果你仍然迷惑的话，就去看看poll函数的源码，看看他在检测什么条件

For Python operators it’s not so hard to find the source since it’s included with Blender and the source file/line is included in the operator reference docs.

查看源码很简单，因为他们就包含在Blender中，并且具体在哪一行都包含在接口文档中

Downloading and searching the C code isn’t so simple, especially if you’re not familiar with the C language but by searching the operator name or description you should be able to find the poll function with no knowledge of C.

下载并查找C源码就不容易了，特别是如果您不熟悉C语言。但是通过搜索操作符名称或描述，您应该能够找到没有C知识的轮询函数。

>>> bpy.ops.gpencil.draw()
RuntimeError: Operator bpy.ops.gpencil.draw.poll() Failed to find Grease Pencil data to draw into

1.2 The operator still doesn’t work!

operater仍然不起作用

Certain operators in Blender are only intended for use in a specific context, some operators for example are only called from the properties window where they check the current material, modifier or constraint.

在Blender中的某些操作符只是为了在特定的环境中使用，一些操作符仅从属性窗口调用，在那里它们检查当前的内容、修饰符或约束。

像下面这些:

• bpy.ops.texture.slot_move
• bpy.ops.constraint.limitdistance_reset
• bpy.ops.object.modifier_copy
• bpy.ops.buttons.file_browse

Another possibility is that you are the first person to attempt to use this operator in a script and some modifications need to be made to the operator to run in a different context, if the operator should logically be able to run but fails when accessed from a script it should be reported to the bug tracker.

另一种可能是,你是第一个试图使用这个operater在脚本和一些要做修改操作符在不同的上下文中运行,如果operater在逻辑上应该能够运行,但不能从一个脚本访问的时候应该报告bug追踪器。

2.1 No updates after setting values

设置后就没再更新

Sometimes you want to modify values from Python and immediately access the updated values, eg:

有时，您想从Python修改值，并立即访问更新后的值，例如:

Once changing the objects bpy.types.Object.location you may want to access its transformation right after from bpy.types.Object.matrix_world, but this doesn’t work as you might expect.

当你修改了bpy.types.Object.location ，你可能想获取它的变换信息bpy.types.Object.matrix_world,但这并不如你所愿。

Consider the calculations that might go into working out the object’s final transformation, this includes:

考虑计算对象最终转换的计算，包括:

• animation function curves.
• 动画曲线函数。
• drivers and their Python expressions.
• 驱动程序及其Python表达式。
• constraints
• 约束
• parent objects and all of their f-curves, constraints etc.
• 父对象和所有的f曲线，约束等。

To avoid expensive recalculations every time a property is modified, Blender defers making the actual calculations until they are needed.

为了避免高昂的重复计算，Blender每次都在最终需要的时候才重新计算需要的值。

However, while the script runs you may want to access the updated values. In this case you need to call bpy.types.Scene.update after modifying values, for example:

如果你想立即使属性设置生效的话，需要调用bpy.types.Scene.update

bpy.context.object.location = 1, 2, 3
bpy.context.scene.update()

Now all dependent data (child objects, modifiers, drivers... etc) has been recalculated and is available to the script.

所有相关数据(子对象、修饰符、驱动程序…(etc)已重新计算并可用于脚本。

2.2 Can I redraw during the script?

可以在脚本中重画么？

The official answer to this is no, or... “You don’t want to do that”.

官方给出的答案是 不。因为“你并不想那么做”

To give some background on the topic...

我们假设一个背景：

While a script executes Blender waits for it to finish and is effectively locked until its done, while in this state Blender won’t redraw or respond to user input. Normally this is not such a problem because scripts distributed with Blender tend not to run for an extended period of time, nevertheless scripts can take ages to execute and its nice to see whats going on in the view port.

当一个脚本执行时，Blender等待它完成并被有效锁定，直到它完成，而在这个状态下，Blender不会重新绘制或响应用户输入。通常情况下，这并不是一个问题，因为用Blender分发的脚本往往不会在很长一段时间内运行，但是脚本可以花费很长的时间来执行，而且很好地看到在视口上发生了什么。

Tools that lock Blender in a loop and redraw are highly discouraged since they conflict with Blenders ability to run multiple operators at once and update different parts of the interface as the tool runs.

在循环和重绘中锁定Blender的工具是非常不受鼓励的，因为它们与Blenders可以同时运行多个操作符 并在工具运行时更新接口的不同部分的能力 发生冲突。

So the solution here is to write a modal operator, that is - an operator which defines a modal() function, See the modal operator template in the text editor.

这里的解决方案是编写一个模态运算符，即定义一个modal()函数的操作符，在文本编辑器中看到模态操作符模板。

Modal operators execute on user input or setup their own timers to run frequently, they can handle the events or pass through to be handled by the keymap or other modal operators.

模态运算符执行用户输入或设置他们自己的定时器来频繁地运行，他们可以处理事件或通过键映射或其他模态运算符处理。

Transform, Painting, Fly-Mode and File-Select are example of a modal operators.

转换、绘图、飞行模式和文件选择是模式操作符的例子。

Writing modal operators takes more effort than a simple for loop that happens to redraw but is more flexible and integrates better with Blenders design.

编写模态运算符需要比简单的循环更大的努力，而不是简单的重新绘制，但更灵活，更集成了Blender的设计。

Ok, Ok! I still want to draw from Python

如果你还想在Python中重画的话

If you insist - yes its possible, but scripts that use this hack wont be considered for inclusion in Blender and any issues with using it wont be considered bugs, this is also not guaranteed to work in future releases.

如果你坚持——是的，这是可能的，但是使用这种方法的脚本不会被认为包含在Blender中，而且使用它的任何问题都不会被认为是错误的，这也不能保证在未来的版本中工作。

bpy.ops.wm.redraw_timer(type=‘DRAW_WIN_SWAP‘, iterations=1)

4.1 Support Overview

支持概述

4.2 Creating

All 3 datatypes can be used for face creation.

三种数据类型都可以用来创建面片。

• polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, you must have all your vertes and faces ready and create them all at once. This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), rather they reference an index and size in bpy.types.Mesh.loops which are a fixed array too.
• polygons是创建faces的最有效的方法，但其数据结构非常死板僵硬，你必须把所有的顶点和faces都准备好，并立即创建它们。由于每个多边形都不存储自己的顶点数据(与tessfaces一样)，更复杂的是，它们引用了bpy.types.Mesh.loops中的索引和大小，而这是一个固定的数组。
• tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, however for scripts upgrading from 2.62 this is by far the most straightforward option. This works by creating tessfaces and when finished - they can be converted into polygons by calling bpy.types.Mesh.update. The obvious limitation is ngons can’t be created this way.
• tessfaces 理论上不用来创建faces，因为它们只是多边形的细分缓存，但在2.62版本之后，这是一种最直接的操作。当细分操作完成后，通过调用 bpy.types.Mesh.update可以将其装换为多边形。一个明显的限制是ngons（多于四个边）不能以这种方法创建。
• bmesh-faces are most likely the easiest way for new scripts to create faces, since faces can be added one by one and the api has features intended for mesh manipulation. While bmesh.types.BMesh uses more memory it can be managed by only operating on one mesh at a time.
• bmesh-faces可能是用脚本创建faces最简单的方法了，由于faces可以一个接一个地添加，而api有一个用于网格操作的特性。虽然bmesh.types.BMesh使用更多的内存，它只能一次只在一个网格上运行。

4.3 Editing

Editing is where the 3 data types vary most.

编辑是三种模式最不同的地方。

• Polygons are very limited for editing, changing materials and options like smooth works but for anything else they are too inflexible and are only intended for storage.
• Polygons编辑起来很有限制，改变材料和选择，比如平滑的作品，但对于其他任何东西，它们太不灵活，只用于存储。
• Tessfaces should not be used for editing geometry because doing so will cause existing ngons to be tessellated.
• Tessfaces不应该用于编辑几何，因为这样做会导致现有的ngons被镶嵌。
• BMesh-Faces are by far the best way to manipulate geometry.
• 到目前为止，BMesh-Faces 是操纵几何的最好方法。

4.4 Exporting

导出

All 3 data types can be used for exporting, the choice mostly depends on whether the target format supports ngons or not.

三种类型的数据都可以导出，选择哪一种主要取决于目标格式是否支持ngons。

• Polygons are the most direct & efficient way to export providing they convert into the output format easily enough.
• Polygons是最直接、最有效的导出方式，它们可以很容易地转换成输出格式。
• Tessfaces work well for exporting to formats which dont support ngons, in fact this is the only place where their use is encouraged.
• Tessfaces可以很好地导出不支持ngons的格式，事实上，这是唯一鼓励使用它们的地方。
• BMesh-Faces can work for exporting too but may not be necessary if polygons can be used since using bmesh gives some overhead because its not the native storage format in object mode.
• BMesh-Faces也可以用于导出，但如果使用polygons它就是没有必要的，因为使用bmesh提供了一些开销，因为它不是对象模式中的原生存储格式。

4.5 Upgrading Importers from 2.62

Importers can be upgraded to work with only minor changes.

只有很小的改动

The main change to be made is used the tessellation versions of each attribute.

最主要变化是使用每个属性的tessellation 版本。

• mesh.faces –> bpy.types.Mesh.tessfaces
• mesh.uv_textures –> bpy.types.Mesh.tessface_uv_textures
• mesh.vertex_colors –> bpy.types.Mesh.tessface_vertex_colors

Once the data is created call bpy.types.Mesh.update to convert the tessfaces into polygons.

一旦数据创建，就调用bpy.types.Mesh.update将tessfaces转换为多边形。

4.6 Upgrading Exporters from 2.62

导出的更新

For exporters the most direct way to upgrade is to use tessfaces as with importing however its important to know that tessfaces maynot exist for a mesh, the array will be empty as if there are no faces.

对于导出来说，最直接的升级方式是使用tessfaces作为导入，但是要知道对于一个网格来说tessfaces是不存在，数组将是空的，就好像没有faces一样。

So before accessing tessface data call: bpy.types.Mesh.update (calc_tessface=True).

所以要在访问tessface数据之前调用bpy.types.Mesh.update 。

5.1 Edit Bones

bpy.context.object.data.edit_bones contains a editbones; to access them you must set the armature mode to edit mode first (editbones do not exist in object or pose mode). Use these to create new bones, set their head/tail or roll, change their parenting relationships to other bones, etc.

Example using bpy.types.EditBone in armature editmode:

This is only possible in edit mode.

>>> bpy.context.object.data.edit_bones["Bone"].head = Vector((1.0, 2.0, 3.0))

This will be empty outside of editmode.

>>> mybones = bpy.context.selected_editable_bones

Returns an editbone only in edit mode.

>>> bpy.context.active_bone

5.2 Bones (Object Mode)

bpy.context.object.data.bones contains bones. These live in object mode, and have various properties you can change, note that the head and tail properties are read-only.

Example using bpy.types.Bone in object or pose mode:

Returns a bone (not an editbone) outside of edit mode

>>> bpy.context.active_bone

This works, as with blender the setting can be edited in any mode

>>> bpy.context.object.data.bones["Bone"].use_deform = True

Accessible but read-only

>>> tail = myobj.data.bones["Bone"].tail

5.3 Pose Bones

bpy.context.object.pose.bones contains pose bones. This is where animation data resides, i.e. animatable transformations are applied to pose bones, as are constraints and ik-settings.

Examples using bpy.types.PoseBone in object or pose mode:

# Gets the name of the first constraint (if it exists)
bpy.context.object.pose.bones["Bone"].constraints[0].name

# Gets the last selected pose bone (pose mode only)
bpy.context.active_pose_bone

5.4 Armature Mode Switching

While writing scripts that deal with armatures you may find you have to switch between modes, when doing so take care when switching out of edit-mode not to keep references to the edit-bones or their head/tail vectors. Further access to these will crash blender so its important the script clearly separates sections of the code which operate in different modes.

This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode, however for operator access you may still need to enter pose mode.

6.1 Naming Limitations

命名限制

A common mistake is to assume newly created data is given the requested name.

一个常见的错误是假定新创建的数据被给定请求的名称。

This can cause bugs when you add some data (normally imported) then reference it later by name.

当您添加一些数据(通常是导入的)，然后再引用它的名称时，这可能会导致bug。

bpy.data.meshes.new(name=meshid)

# normally some code, function calls...
bpy.data.meshes[meshid]

Or with name assignment...

或名称赋值

obj.name = objname

# normally some code, function calls...
obj = bpy.data.meshes[objname]

Data names may not match the assigned values if they exceed the maximum length, are already used or an empty string.

如果赋的值超过了最大长度或者已经使用过了或者是一个空串，那么将不会使用。

Its better practice not to reference objects by names at all, once created you can store the data in a list, dictionary, on a class etc, there is rarely a reason to have to keep searching for the same data by name.

最好的做法是不引用对象的名称，一旦创建了可你以将数据存储在列表、字典、类等的列表中，很少有理由需要继续搜索相同的数据。

If you do need to use name references, its best to use a dictionary to maintain a mapping between the names of the imported assets and the newly created data, this way you don’t run this risk of referencing existing data from the blend file, or worse modifying it.

如果你确实需要使用名字作为索引，最好用字典维持一个名字和数据间的映射，这样，您就不会冒着从blend文件中引用现有数据的风险，或者更糟糕地修改它。

# typically declared in the main body of the function.
mesh_name_mapping = {}

mesh = bpy.data.meshes.new(name=meshid)
mesh_name_mapping[meshid] = mesh

# normally some code, or function calls...

# use own dictionary rather than bpy.data
mesh = mesh_name_mapping[meshid]

6.2 Library Collisions

碰撞库

Blender keeps data names unique - bpy.types.ID.name so you can’t name two objects, meshes, scenes etc the same thing by accident.

在Blender中数据名字是唯一的，你不可能给两个对象命名相同的名字。

However when linking in library data from another blend file naming collisions can occur, so its best to avoid referencing data by name at all.

但当你从其它blend文件中连接库数据时可能出现名字相同的情况，所以最好避免使用名字索引。

This can be tricky at times and not even blender handles this correctly in some case (when selecting the modifier object for eg you can’t select between multiple objects with the same name), but its still good to try avoid problems in this area.

这有时很棘手，甚至在某些情况下，甚至连Blender都不能正确处理(当选择修改器对象时，例如不能在多个对象之间选择相同的名称)，但在这一领域中，尽量避免出现问题仍然很好。

If you need to select between local and library data, there is a feature in bpy.data members to allow for this.

如果您需要在本地和库数据之间进行选择，那么bpy.data中有一个特性成员允许这样做。

# typical name lookup, could be local or library.
obj = bpy.data.objects["my_obj"]

# library object name look up using a pair
# where the second argument is the library path matching bpy.types.Library.filepath
obj = bpy.data.objects["my_obj", "//my_lib.blend"]

# local object name look up using a pair
# where the second argument excludes library data from being returned.
obj = bpy.data.objects["my_obj", None]

# both the examples above also works for ‘get‘
obj = bpy.data.objects.get(("my_obj", None))

10.1 Undo/Redo

Undo invalidates all bpy.types.ID instances (Object, Scene, Mesh, Lamp... etc).

Undo操作使所有的实例失效。

This example shows how you can tell undo changes the memory locations.

这个例子展示了如何知道撤销更改内存位置。

>>> hash(bpy.context.object)
-9223372036849950810
>>> hash(bpy.context.object)
-9223372036849950810
# ... move the active object, then undo

>>> hash(bpy.context.object)
-9223372036849951740

As suggested above, simply not holding references to data when Blender is used interactively by the user is the only way to ensure the script doesn’t become unstable.

如上所述，当用户交互式地使用Blender时，不保存对数据的引用是确保脚本不会变得不稳定的唯一方法。

10.2 Edit Mode / Memory Access

编辑模式/内存访问

Switching edit-mode bpy.ops.object.mode_set(mode=‘EDIT‘) / bpy.ops.object.mode_set(mode=‘OBJECT‘) will re-allocate objects data, any references to a meshes vertices/polygons/uvs, armatures bones, curves points etc cannot be accessed after switching edit-mode.

切换到编辑模式后，所有对象的数据将被重新分配。所有指向其他资源的索引都不能使用。

Only the reference to the data its self can be re-accessed, the following example will crash.

只有对数据本身的引用可以被重新访问，下面的例子将会崩溃。

mesh = bpy.context.active_object.data
polygons = mesh.polygons
bpy.ops.object.mode_set(mode=‘EDIT‘)
bpy.ops.object.mode_set(mode=‘OBJECT‘)

# this will crash
print(polygons)

So after switching edit-mode you need to re-access any object data variables, the following example shows how to avoid the crash above.

因此，在切换编辑模式后，您需要重新访问任何对象数据变量，下面的示例显示了如何避免上面的崩溃。

mesh = bpy.context.active_object.data
polygons = mesh.polygons
bpy.ops.object.mode_set(mode=‘EDIT‘)
bpy.ops.object.mode_set(mode=‘OBJECT‘)

# polygons have been re-allocated
polygons = mesh.polygons
print(polygons)

These kinds of problems can happen for any functions which re-allocate the object data but are most common when switching edit-mode.

这些问题可能发生于任何重新分配对象数据的时候，但在切换编辑模式时最常见的函数。

10.3 Array Re-Allocation

数组重新分配

When adding new points to a curve or vertices’s/edges/polygons to a mesh, internally the array which stores this data is re-allocated.

当向一个网格中添加新的指向曲线或顶点/边/多边形的新点时，将重新分配存储该数据的数组。

bpy.ops.curve.primitive_bezier_curve_add()
point = bpy.context.object.data.splines[0].bezier_points[0]
bpy.context.object.data.splines[0].bezier_points.add()

# this will crash!
point.co = 1.0, 2.0, 3.0

This can be avoided by re-assigning the point variables after adding the new one or by storing indices’s to the points rather than the points themselves.

这可以通过在添加新变量后重新分配点变量来避免，或者通过存储点的索引而不是点本身。

The best way is to sidestep the problem altogether add all the points to the curve at once. This means you don’t have to worry about array re-allocation and its faster too since reallocating the entire array for every point added is inefficient.

最好的解决办法是一次性添加所有的点。这就意味着你不需要再担心数组的重新分配，而且那也很快比起每次

10.4 Removing Data

删除数据

Any data that you remove shouldn’t be modified or accessed afterwards, this includes f-curves, drivers, render layers, timeline markers, modifiers, constraints along with objects, scenes, groups, bones.. etc.

您删除的任何数据都不应该再修改或访问，包括f曲线、驱动程序、渲染层、时间轴标记、修饰符、约束以及对象、场景、组、骨头。等等

The remove() api calls will invalidate the data they free to prevent common mistakes.

调用remove()将使它释放的数据无效，这样避免了共同的错误

The following example shows how this precortion works.

下面是个例子

mesh = bpy.data.meshes.new(name="MyMesh")
# normally the script would use the mesh here...
bpy.data.meshes.remove(mesh)
print(mesh.name)  # <- give an exception rather than crashing:

# ReferenceError: StructRNA of type Mesh has been removed

But take care because this is limited to scripts accessing the variable which is removed, the next example will still crash.

要避免在脚本中访问已经删除的数据，这会导致崩溃。

mesh = bpy.data.meshes.new(name="MyMesh")
vertices = mesh.vertices
bpy.data.meshes.remove(mesh)
print(vertices)  # <- this may crash