摘要：在交互式控制臺(tái)中運(yùn)行此操作時(shí)，您將看到視口更新。鍵入或粘貼到交互式控制臺(tái)中。用戶首選項(xiàng)加載項(xiàng)列表使用顯示有關(guān)每個(gè)加載項(xiàng)的信息。最后兩行僅用于測(cè)試這允許腳本直接在文本編輯器中運(yùn)行以測(cè)試更改。

本文檔的目的是解釋Python和Blender如何組合在一起，涵蓋了一些在閱讀API參考和示例腳本時(shí)可能不明顯的功能。

Blender有一個(gè)嵌入式Python解釋器，它在Blender啟動(dòng)時(shí)加載，并在Blender運(yùn)行時(shí)保持活動(dòng)狀態(tài)。該解釋器運(yùn)行腳本來(lái)繪制用戶界面，并用于Blender的一些內(nèi)部工具。
Blender的嵌入式解釋器提供了典型的Python環(huán)境，因此關(guān)于如何編寫(xiě)Python腳本的教程中的代碼也可以使用Blender的解釋器運(yùn)行。Blender為嵌入式解釋器提供了Python模塊，例如bpy和mathutils，因此可以將它們導(dǎo)入到腳本中，并可以訪問(wèn)Blender的數(shù)據(jù)，類(lèi)和函數(shù)。處理Blender數(shù)據(jù)的腳本需要導(dǎo)入模塊才能工作。
這是一個(gè)簡(jiǎn)單的示例，它移動(dòng)附加到名為Cube的對(duì)象的頂點(diǎn)：

import bpy
bpy.data.objects["Cube"].data.vertices[0].co.x += 1.0

這會(huì)直接修改Blender的內(nèi)部數(shù)據(jù)。在交互式控制臺(tái)中運(yùn)行此操作時(shí)，您將看到3D視口更新。

在開(kāi)發(fā)自己的腳本時(shí)，了解Blender如何設(shè)置其Python環(huán)境可能會(huì)有所幫助。許多Python腳本與Blender捆綁在一起，可以用作參考，因?yàn)樗鼈兪褂媚_本作者編寫(xiě)工具的相同API。腳本的典型用法包括：用戶界面，導(dǎo)入/導(dǎo)出，場(chǎng)景操作，自動(dòng)化，定義自己的工具集和定制。
在啟動(dòng)時(shí)，Blender會(huì)掃描scripts/startup/目錄中的Python模塊并導(dǎo)入它們。此目錄的確切位置取決于您的安裝。請(qǐng)參閱目錄布局文檔。

這看起來(lái)很明顯，但重要的是要注意直接執(zhí)行腳本和將腳本作為模塊導(dǎo)入之間的區(qū)別。
通過(guò)直接執(zhí)行腳本來(lái)擴(kuò)展Blender意味著腳本完成執(zhí)行后腳本定義的類(lèi)在Blender中保持可用。與將腳本作為模塊導(dǎo)入相比，以這種方式使用腳本使得將來(lái)訪問(wèn)其類(lèi)（例如取消注冊(cè)它們）變得更加困難。將腳本作為模塊導(dǎo)入時(shí)，其類(lèi)實(shí)例將保留在模塊中，稍后可以通過(guò)再次導(dǎo)入該模塊來(lái)訪問(wèn)。
因此，最好避免直接執(zhí)行通過(guò)注冊(cè)類(lèi)來(lái)擴(kuò)展Blender的腳本。
以下是在Blender中直接運(yùn)行腳本的一些方法。

在文本編輯器中加載并按Run Script。

鍵入或粘貼到交互式控制臺(tái)中。

使用Blender從命令行執(zhí)行Python文件，例如：

blender --python /home/me/my_script.py

要作為模塊運(yùn)行：

顯而易見(jiàn)的方法，來(lái)自文本窗口或交互式控制臺(tái)的命令。import some_module

打開(kāi)文本塊并勾選“注冊(cè)”選項(xiàng)，這將加載混合文件。

復(fù)制到其中一個(gè)目錄中scripts/startup，它們將在啟動(dòng)時(shí)自動(dòng)導(dǎo)入。

定義為加載項(xiàng)，啟用加載項(xiàng)將其加載為Python模塊。

一些Blenders功能最好保持可選，除了在啟動(dòng)時(shí)加載的腳本我們有附加組件，這些附加組件保存在它們自己的目錄中scripts/addons，并且只有在從用戶首選項(xiàng)中選擇時(shí)才會(huì)在啟動(dòng)時(shí)加載。
附加組件和內(nèi)置Python模塊之間的唯一區(qū)別是附加組件必須包含bl_info Blender用于讀取元數(shù)據(jù)的變量，例如名稱(chēng)，作者，類(lèi)別和URL。
用戶首選項(xiàng)加載項(xiàng)列表使用bl_info顯示有關(guān)每個(gè)加載項(xiàng)的信息。
有關(guān)bl_info字典的 詳細(xì)信息，請(qǐng)參閱加載項(xiàng)。

在文本編輯器中運(yùn)行Python腳本對(duì)于測(cè)試很有用，但是您需要擴(kuò)展Blender以使工具可以像其他內(nèi)置功能一樣訪問(wèn)。
Blender Python api允許集成：

bpy.types.Panel

bpy.types.Menu

bpy.types.Operator

bpy.types.PropertyGroup

bpy.types.KeyingSet

bpy.types.RenderEngine

這是故意限制的。目前，對(duì)于更高級(jí)的功能，例如網(wǎng)格修改器，對(duì)象類(lèi)型或著色器節(jié)點(diǎn)，必須使用C / C ++。
對(duì)于Python集成，Blender定義了所有類(lèi)型共有的方法。這可以通過(guò)創(chuàng)建Blender類(lèi)的Python子類(lèi)來(lái)實(shí)現(xiàn)，該類(lèi)包含由父類(lèi)指定的變量和函數(shù)，這些變量和函數(shù)是預(yù)定義為與Blender接口的。
例如：

import bpy
class SimpleOperator(bpy.types.Operator):
    bl_idname = "object.simple_operator"
    bl_label = "Tool Name"

    def execute(self, context):
        print("Hello World")
        return {"FINISHED"}

bpy.utils.register_class(SimpleOperator)

首先請(qǐng)注意，我們將其成員子類(lèi)化bpy.types，這對(duì)于可以與Blender集成并使用的所有類(lèi)都是通用的，因此我們知道這是一個(gè)運(yùn)算符而不是注冊(cè)時(shí)的Panel。
兩個(gè)類(lèi)屬性都以bl_前綴開(kāi)頭。這是一個(gè)用于區(qū)分Blender屬性和您自己添加的屬性的約定。
接下來(lái)看到execute函數(shù)，它接受運(yùn)算符的實(shí)例和當(dāng)前上下文。公共前綴不用于函數(shù)。
最后調(diào)用寄存器函數(shù)，這將獲取類(lèi)并將其加載到Blender中。請(qǐng)參閱班級(jí)注冊(cè)。
關(guān)于繼承，Blender不對(duì)所使用的類(lèi)繼承施加限制，注冊(cè)檢查將使用父類(lèi)中定義的屬性和函數(shù)。
class mix-in示例：

import bpy
class BaseOperator:
    def execute(self, context):
        print("Hello World BaseClass")
        return {"FINISHED"}

class SimpleOperator(bpy.types.Operator, BaseOperator):
    bl_idname = "object.simple_operator"
    bl_label = "Tool Name"

bpy.utils.register_class(SimpleOperator)

請(qǐng)注意，這些類(lèi)沒(méi)有定義__init__(self)函數(shù)。而__init__()和__del__()如果定義了將被調(diào)用，在類(lèi)實(shí)例壽命僅跨越執(zhí)行。因此，例如一個(gè)面板將為每次重繪都有一個(gè)新實(shí)例，因此很少有理由在面板實(shí)例中存儲(chǔ)變量。相反，持久變量應(yīng)存儲(chǔ)在Blenders ata中，以便在重新啟動(dòng)Blender時(shí)可以恢復(fù)狀態(tài)。
注意

模態(tài)運(yùn)算符是一個(gè)例外，它們的實(shí)例變量保持為Blender運(yùn)行，請(qǐng)參見(jiàn)模態(tài)運(yùn)算符模板。
因此，一旦類(lèi)在Blender中注冊(cè)，實(shí)例化類(lèi)并調(diào)用函數(shù)就由Blender完成。實(shí)際上，您無(wú)法像在大多數(shù)Python API中所期望的那樣從腳本中實(shí)例化這些類(lèi)。
要運(yùn)行運(yùn)算符，可以通過(guò)運(yùn)算符api調(diào)用它們，例如：

import bpy
bpy.ops.object.simple_operator()

用戶界面類(lèi)給出了繪制，按鈕窗口，文件頭，工具欄等的上下文，然后在顯示該區(qū)域時(shí)繪制它們，因此Python腳本不會(huì)直接調(diào)用它們。

啟動(dòng)時(shí)加載的Blender模塊需要register()和unregister()功能。這些是Blender從您的代碼調(diào)用的唯一函數(shù)，否則它是常規(guī)的Python模塊。
一個(gè)簡(jiǎn)單的Blender / Python模塊可能如下所示：

import bpy

class SimpleOperator(bpy.types.Operator):
    """ See example above """

def register():
    bpy.utils.register_class(SimpleOperator)

def unregister():
    bpy.utils.unregister_class(SimpleOperator)

if __name__ == "__main__":
    register()

這些函數(shù)通常出現(xiàn)在包含類(lèi)注冊(cè)的腳本的底部，有時(shí)會(huì)添加菜單項(xiàng)。您也可以將它們用于內(nèi)部目的，為您自己的工具設(shè)置數(shù)據(jù)，但要小心，因?yàn)榧虞d新的混合文件時(shí)寄存器不會(huì)重新運(yùn)行。
使用了注冊(cè)/取消注冊(cè)調(diào)用，因此可以在Blender運(yùn)行時(shí)切換加載項(xiàng)和重新加載腳本。如果寄存器調(diào)用放在腳本的主體中，則會(huì)在導(dǎo)入時(shí)調(diào)用注冊(cè)，這意味著導(dǎo)入模塊或?qū)⑵漕?lèi)加載到Blender之間沒(méi)有區(qū)別。
當(dāng)腳本從另一個(gè)模塊導(dǎo)入類(lèi)時(shí)，這會(huì)成為問(wèn)題，因?yàn)楹茈y管理正在加載哪些類(lèi)以及何時(shí)加載。
最后兩行僅用于測(cè)試：

if __name__ == "__main__":
    register()

這允許腳本直接在文本編輯器中運(yùn)行以測(cè)試更改。register()將腳本作為模塊導(dǎo)入時(shí)，此調(diào)用將不會(huì)運(yùn)行，因?yàn)開(kāi)_main__保留用于直接執(zhí)行。

使用Blender注冊(cè)類(lèi)會(huì)導(dǎo)致類(lèi)定義被加載到Blender中，并在現(xiàn)有功能的同時(shí)可用。
加載此類(lèi)后，您可以bpy.types使用bl_idname而不是類(lèi)原始名稱(chēng)來(lái)訪問(wèn)它。
加載類(lèi)時(shí)，Blender執(zhí)行完整性檢查，確保找到所有必需的屬性和函數(shù)，屬性具有正確的類(lèi)型，并且函數(shù)具有正確數(shù)量的參數(shù)。
大多數(shù)情況下，你不需要擔(dān)心這個(gè)問(wèn)題，但是如果類(lèi)定義有問(wèn)題，它將在注冊(cè)時(shí)引發(fā)：
使用函數(shù)參數(shù)，將引發(fā)異常：def execute(self, context, spam)
ValueError: expected Operator, SimpleOperator class "execute" function to have 2 args, found 3
使用將提高。bl_idname = 1
TypeError: validating class error: Operator.bl_idname expected a string type, not int

上面描述了將類(lèi)加載到Blender中，對(duì)于簡(jiǎn)單的情況，調(diào)用bpy.utils.register_class（SomeClass）就足夠了，但是當(dāng)有很多類(lèi)或子模塊子模塊有自己的類(lèi)時(shí)，將它們?nèi)苛腥胱?cè)可能會(huì)很繁瑣。
為了更方便的加載/卸載bpy.utils.register_module（模塊）和bpy.utils.unregister_module（模塊）功能存在。
一個(gè)腳本，它定義了許多自己的操作符，面板菜單等，你只需要編寫(xiě)：

def register():
    bpy.utils.register_module(__name__)

def unregister():
    bpy.utils.unregister_module(__name__)

內(nèi)部Blender在可注冊(cè)類(lèi)型上收集子類(lèi)，通過(guò)定義它們的模塊存儲(chǔ)它們。通過(guò)將模塊名稱(chēng)傳遞給bpy.utils.register_module Blender，可以注冊(cè)該模塊及其子模塊創(chuàng)建的所有類(lèi)。

在自定義Blender時(shí)，您可能希望將自己的設(shè)置組合在一起，畢竟，它們可能必須與其他腳本共存。要對(duì)這些屬性進(jìn)行分組，需要定義類(lèi)，對(duì)于組內(nèi)的組或組內(nèi)的集合，您可以發(fā)現(xiàn)自己必須處理注冊(cè)/取消注冊(cè)的順序。
自定義屬性組本身就是需要注冊(cè)的類(lèi)。
假設(shè)您要存儲(chǔ)自定義引擎的材質(zhì)設(shè)置。

# Create new property
# bpy.data.materials[0].my_custom_props.my_float
import bpy

class MyMaterialProps(bpy.types.PropertyGroup):
    my_float = bpy.props.FloatProperty()

def register():
    bpy.utils.register_class(MyMaterialProps)
    bpy.types.Material.my_custom_props = bpy.props.PointerProperty(type=MyMaterialProps)

def unregister():
    del bpy.types.Material.my_custom_props
    bpy.utils.unregister_class(MyMaterialProps)

if __name__ == "__main__":
    register()

注意

該類(lèi)必須在用于屬性之前注冊(cè)，否則將引發(fā)錯(cuò)誤：
ValueError: bpy_struct "Material" registration error: my_custom_props could not register

# Create new property group with a sub property
# bpy.data.materials[0].my_custom_props.sub_group.my_float
import bpy

class MyMaterialSubProps(bpy.types.PropertyGroup):
    my_float = bpy.props.FloatProperty()

class MyMaterialGroupProps(bpy.types.PropertyGroup):
    sub_group = bpy.props.PointerProperty(type=MyMaterialSubProps)

def register():
    bpy.utils.register_class(MyMaterialSubProps)
    bpy.utils.register_class(MyMaterialGroupProps)
    bpy.types.Material.my_custom_props = bpy.props.PointerProperty(type=MyMaterialGroupProps)

def unregister():
    del bpy.types.Material.my_custom_props
    bpy.utils.unregister_class(MyMaterialGroupProps)
    bpy.utils.unregister_class(MyMaterialSubProps)

if __name__ == "__main__":
    register()

注意

最低級(jí)別需要首先注冊(cè)，而unregister（）是register（）的鏡像

可以在Blender運(yùn)行時(shí)添加和刪除屬性，通常在注冊(cè)或取消注冊(cè)時(shí)發(fā)生，但對(duì)于某些特殊情況，在腳本運(yùn)行時(shí)修改類(lèi)型可能很有用。
例如：

# add a new property to an existing type
bpy.types.Object.my_float = bpy.props.FloatProperty()
# remove
del bpy.types.Object.my_float

這適用于您自己定義的PropertyGroup子類(lèi)。

class MyPropGroup(bpy.types.PropertyGroup):
    pass
MyPropGroup.my_float = bpy.props.FloatProperty()

......這相當(dāng)于：

class MyPropGroup(bpy.types.PropertyGroup):
    my_float = bpy.props.FloatProperty()

在某些情況下，數(shù)據(jù)的說(shuō)明符可能不在Blender，renderman著色器定義中，例如，將它們定義為類(lèi)型并在運(yùn)行中刪除它們可能很有用。
for i in range(10):

idname = "object.operator_%d" % i

def func(self, context):
    print("Hello World", self.bl_idname)
    return {"FINISHED"}

opclass = type("DynOp%d" % i,
               (bpy.types.Operator, ),
               {"bl_idname": idname, "bl_label": "Test", "execute": func},
               )
bpy.utils.register_class(opclass)

注意

type()被調(diào)用來(lái)定義類(lèi)。這是Python中類(lèi)創(chuàng)建的替代語(yǔ)法，更適合動(dòng)態(tài)構(gòu)造類(lèi)。
要從上一個(gè)示例中調(diào)用運(yùn)算符：

>>> bpy.ops.object.operator_1()
Hello World OBJECT_OT_operator_1
{"FINISHED"}

>>> bpy.ops.object.operator_2()
Hello World OBJECT_OT_operator_2
{"FINISHED"}