快速入門簡介

前言

此API通常是穩(wěn)定的，但某些部分仍在添加和改進(jìn)。

Blender / Python API可以執(zhí)行以下操作：

編輯用戶界面可以使用的任何數(shù)據(jù)（場景上枕，網(wǎng)格，粒子等）

修改用戶首選項弱恒，鍵盤圖和主題

使用自己的設(shè)置運行工具

創(chuàng)建用戶界面元素辨萍，例如菜單，標(biāo)題和面板

創(chuàng)建新工具

創(chuàng)建交互式工具

創(chuàng)建與Blender集成的新渲染引擎

在現(xiàn)有Blender數(shù)據(jù)中定義新設(shè)置

使用Python中的OpenGL命令在3D視圖中繪圖

Blender / Python API?不能（還）......

創(chuàng)建新的空間類型斤彼。

為每種類型分配自定義屬性分瘦。

定義在數(shù)據(jù)更改時要通知的回調(diào)或偵聽器蘸泻。

開始之前

本文檔無意完全涵蓋每個主題。相反嘲玫，它的目的是讓您熟悉Blender Python API悦施。

在開始之前要了解的有用事項的快速列表：

Blender使用Python 3.x;?一些在線文檔仍然使用2.x.

交互式控制臺非常適合測試單行程序。它還具有自動完成功能去团，因此您可以快速檢查API抡诞。

按鈕工具提示顯示Python屬性和操作名稱。

右鍵單擊按鈕和菜單項可直接鏈接到API文檔土陪。

有關(guān)更多示例昼汗，文本菜單有一個模板部分，其中可以找到一些示例運算符鬼雀。

要檢查使用Blender分發(fā)的其他腳本顷窒，請參閱：

scripts/startup/bl_ui 用戶界面，

scripts/startup/bl_operators 操作員源哩。

確切位置取決于平臺鞋吉，請參閱：?配置和數(shù)據(jù)路徑。????

運行腳本

執(zhí)行Python腳本的兩種最常用方法是使用內(nèi)置文本編輯器或在Python控制臺中輸入命令励烦。

無論是文本編輯器和Python的控制臺都是面板類型谓着，您可以從視圖標(biāo)題選擇。

您可能更喜歡使用Scripting屏幕（默認(rèn)情況下包含Blender）坛掠，可以從頂部標(biāo)題屏幕選擇器訪問赊锚，而不是手動配置Python開發(fā)空間。

從文本編輯器中屉栓，您可以打開.py文件或從剪貼板粘貼舷蒲，然后使用“運行腳本”進(jìn)行測試。

Python控制臺通常用于輸入代碼段和測試以獲得即時反饋友多，但也可以將整個腳本粘貼到其中阿纤。

腳本也可以使用Blender從命令行運行，但要學(xué)習(xí)Blender / Python夷陋，這不是必需的欠拾。

關(guān)鍵概念

數(shù)據(jù)訪問

訪問數(shù)據(jù)塊

Python以與動畫系統(tǒng)和用戶界面相同的方式訪問Blender的數(shù)據(jù);?這意味著任何可以通過按鈕更改的設(shè)置也可以從Python更改。

使用該模塊訪問當(dāng)前加載的混合文件中的數(shù)據(jù)bpy.data骗绕。這樣可以訪問庫數(shù)據(jù)藐窄。例如：

>>> bpy.data.objects

>>> bpy.data.scenes

>>> bpy.data.materials

關(guān)于集合

您會注意到索引和字符串可用于訪問集合的成員。

與Python的詞典不同酬土，這兩種方法都是可以接受的;?但是荆忍，運行Blender時，成員的索引可能會發(fā)生變化。

>>> list(bpy.data.objects)[bpy.data.objects["Cube"], bpy.data.objects["Plane"]]

>>> bpy.data.objects['Cube']bpy.data.objects["Cube"]

>>> bpy.data.objects[0]bpy.data.objects["Cube"]

訪問屬性

一旦有了數(shù)據(jù)塊刹枉，例如材料叽唱，對象，組等微宝，就可以像使用圖形界面更改設(shè)置一樣訪問其屬性棺亭。事實上，每個按鈕的工具提示也會顯示Python屬性蟋软，這有助于查找腳本中要更改的設(shè)置镶摘。

>>> bpy.data.objects[0].name'Camera'

>>> bpy.data.scenes["Scene"]bpy.data.scenes['Scene']

>>> bpy.data.materials.new("MyMaterial")bpy.data.materials['MyMaterial']

為了測試訪問它的數(shù)據(jù)，使用“控制臺”很有用岳守，它是自己的空間類型凄敢。這支持自動完成，為您提供了一種快速瀏覽文件中不同數(shù)據(jù)的方法湿痢。

可以通過控制臺快速找到的數(shù)據(jù)路徑示例：

>>> bpy.data.scenes[0].render.resolution_percentage

100

>>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x

1.0

數(shù)據(jù)創(chuàng)建/刪除

那些熟悉其他Python API的人可能會驚訝于無法通過調(diào)用類來創(chuàng)建bpy API中的新數(shù)據(jù)塊：

>>> bpy.types.Mesh()

Traceback (most recent call last):

File"", line1, in

TypeError:bpy_struct.__new__(type): expected a single argument

這是API設(shè)計的有意識部分涝缝。Blender / Python API無法創(chuàng)建存在于主Blender數(shù)據(jù)庫（通過其訪問bpy.data）之外的Blender數(shù)據(jù)，因為此數(shù)據(jù)由Blender管理（save / load / undo / append ...等）譬重。

通過集合中的方法添加和刪除數(shù)據(jù)bpy.data俊卤，例如：

>>> mesh=bpy.data.meshes.new(name="MyMesh")

>>> print(mesh)

>>> bpy.data.meshes.remove(mesh)

自定義屬性

Python可以訪問具有ID的任何數(shù)據(jù)塊的屬性（可以鏈接和訪問的數(shù)據(jù)bpy.data。當(dāng)分配屬性時害幅，您可以組成自己的名稱，這些名稱將在需要時創(chuàng)建或覆蓋（如果存在）岂昭。

此數(shù)據(jù)與混合文件一起保存并與對象一起復(fù)制以现。

例：

bpy.context.object["MyOwnProperty"] = 42

if "SomeProp" in bpy.context.object:

? ? print("Property found")

# Use the get function like a Python dictionary

# which can have a fallback value.

value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")

# dictionaries can be assigned as long as they only use basic types.

group = bpy.data.groups.new("MyTestGroup")

group["GameSettings"] = {"foo": 10, "bar": "spam", "baz": {}}

del group["GameSettings"]

請注意，這些屬性只能分配基本的Python類型约啊。

int邑遏，float，string

整數(shù)/浮點數(shù)

字典（僅支持字符串鍵恰矩，值也必須是基本類型）

這些屬性在Python之外有效记盒。它們可以通過曲線設(shè)置動畫或在驅(qū)動程序路徑中使用。

Context

雖然能夠通過名稱或列表直接訪問數(shù)據(jù)很有用外傅，但更常見的是根據(jù)用戶的選擇進(jìn)行操作纪吮。上下文始終可用bpy.context，并可用于獲取活動對象萎胰，場景碾盟，工具設(shè)置以及許多其他屬性。

常見用例：

>>> bpy.context.object

>>> bpy.context.selected_objects

>>> bpy.context.visible_bones

請注意技竟，Context是只讀的冰肴。雖然可以通過運行API函數(shù)或使用數(shù)據(jù)API來更改這些值，但無法直接修改這些值。

因此會引發(fā)錯誤熙尉。bpy.context.object?=?obj

但是會按預(yù)期工作联逻。bpy.context.scene.objects.active?=?obj

Context屬性根據(jù)訪問位置而變化。3D視圖具有與控制臺不同的Context成員检痰，因此在訪問用戶狀態(tài)已知的Context屬性時要小心包归。

請參閱bpy.contextAPI參考。

Operators (Tools)

操作員通常是用戶通過按鈕攀细，菜單項或鍵快捷鍵訪問的工具箫踩。從用戶的角度來看，它們是一個工具谭贪，但Python可以通過bpy.ops模塊使用自己的設(shè)置來運行它們境钟。

例子：

>>> bpy.ops.mesh.flip_normals()

{'FINISHED'}

>>> bpy.ops.mesh.hide(unselected=False)

{'FINISHED'}

>>> bpy.ops.object.scale_apply()

{'FINISHED'}

注意

菜單項：幫助?運算符備忘單?提供了Python語法中所有運算符及其默認(rèn)值的列表，以及生成的文檔俭识。這是了解所有Blender運營商概況的好方法慨削。

Operator Poll()

許多操作員都有一個“輪詢”功能，可以檢查光標(biāo)是在有效區(qū)域還是對象處于正確模式（編輯模式套媚，重量繪制等）缚态。當(dāng)操作符的poll函數(shù)在Python中失敗時，會引發(fā)異常堤瘤。

例如玫芦，bpy.ops.view3d.render_border()從控制臺調(diào)用會引發(fā)以下錯誤：

RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect

在這種情況下，上下文必須是具有活動相機的3d視圖本辐。

為了避免在調(diào)用運算符的地方使用try / except子句桥帆，可以調(diào)用運算符自己的poll()函數(shù)來檢查它是否可以在當(dāng)前上下文中運行。

if bpy.ops.view3d.render_border.poll():

? ? bpy.ops.view3d.render_border()

整合

Python腳本可以通過以下方式與Blender集成：

·通過定義渲染引擎慎皱。

·通過定義操作老虫。

·通過定義菜單，標(biāo)題和面板茫多。

·通過在現(xiàn)有菜單祈匙，標(biāo)題和面板中插入新按鈕

在Python中，這是通過定義一個類來完成的天揖，該類是現(xiàn)有類型的子類夺欲。

示例操作

import bpy

def main(context):

? ? for ob in context.scene.objects:

? ? ? ? print(ob)

class SimpleOperator(bpy.types.Operator):

? ? """Tooltip"""

? ? bl_idname = "object.simple_operator"

? ? bl_label = "Simple Object Operator"

? ? @classmethod

? ? def poll(cls, context):

? ? ? ? return context.active_object is not None

? ? def execute(self, context):

? ? ? ? main(context)

? ? ? ? return {'FINISHED'}

def register():

? ? bpy.utils.register_class(SimpleOperator)

def unregister():

? ? bpy.utils.unregister_class(SimpleOperator)

if __name__ == "__main__":

? ? register()

? ? # test call

? ? bpy.ops.object.simple_operator()

此腳本運行后，SimpleOperator將在Blender中注冊今膊，可以從操作員搜索彈出窗口中調(diào)用或添加到工具欄中洁闰。

要運行腳本：

1、突出顯示上面的代碼然后按下Ctrl-C以復(fù)制它万细。

2扑眉、啟動Blender

3纸泄、按Ctrl-Right兩次以更改為“腳本”布局。

4腰素、單擊標(biāo)記的按鈕New并彈出確認(rèn)以創(chuàng)建新的文本塊。

5弓千、按Ctrl-V將代碼粘貼到文本面板（左上方框架）衡便。

6、單擊“?運行腳本?”按鈕洋访。

7镣陕、將光標(biāo)移動到3D視圖，按空格鍵選擇操作員搜索菜單姻政，然后鍵入“Simple”呆抑。

8、單擊搜索中的“Simple Operator”項汁展。

具有bl_前綴的類成員記錄在API參考中bpy.types.Operator

注意

該main功能的輸出發(fā)送到終端;?為了看到這一點鹊碍，一定要使用終端。

示例面板

面板將自己注冊為類食绿，就像操作員一樣侈咕。注意bl_用于設(shè)置它們顯示的context的額外變量。

import bpy

class HelloWorldPanel(bpy.types.Panel):

? ? """Creates a Panel in the Object properties window"""

? ? bl_label = "Hello World Panel"

? ? bl_idname = "OBJECT_PT_hello"

? ? bl_space_type = 'PROPERTIES'

? ? bl_region_type = 'WINDOW'

? ? bl_context = "object"

? ? def draw(self, context):

? ? ? ? layout = self.layout

? ? ? ? obj = context.object

? ? ? ? row = layout.row()

? ? ? ? row.label(text="Hello world!", icon='WORLD_DATA')

? ? ? ? row = layout.row()

? ? ? ? row.label(text="Active object is: " + obj.name)

? ? ? ? row = layout.row()

? ? ? ? row.prop(obj, "name")

? ? ? ? row = layout.row()

? ? ? ? row.operator("mesh.primitive_cube_add")

def register():

? ? bpy.utils.register_class(HelloWorldPanel)

def unregister():

? ? bpy.utils.unregister_class(HelloWorldPanel)

if __name__ == "__main__":

? ? register()

要運行腳本：

1器紧、突出顯示上面的代碼然后按下Ctrl-C以復(fù)制它

2耀销、啟動Blender

3、按Ctrl-Right兩次以更改為“腳本”布局

4铲汪、單擊標(biāo)記的按鈕New并彈出確認(rèn)以創(chuàng)建新的文本塊熊尉。

5、按Ctrl-V將代碼粘貼到文本面板（左上方框架）

6桥状、單擊“?運行腳本?”按鈕。

要查看結(jié)果：

1硝清、選擇默認(rèn)多維數(shù)據(jù)集辅斟。

2、單擊按鈕面板中的對象屬性圖標(biāo)（最右側(cè);顯示為一個小立方體）芦拿。

3士飒、向下滾動以查看名為Hello World Panel的面板。

4蔗崎、更改對象名稱還會更新Hello World Panel的名稱：字段。

請注意行分布以及代碼中可用的標(biāo)簽和屬性。

也可以看看bpy.types.Panel

類型

Blender定義了許多Python類型槽奕，但也使用Python本機類??型看峻。

Blender的Python API可以分為3類。

原生類型

在簡單的情況下，將數(shù)字或字符串作為自定義類型返回會很麻煩笔刹，因此可以將它們作為普通的Python類型進(jìn)行訪問芥备。

Blender float / int / boolean - > float / int / boolean

Blender枚舉器 - >字符串

>>> ? 。對象舌菜。rotation_mode = 'AXIS_ANGLE'

Blender枚舉器（多個） - >字符串集

＃設(shè)置多個相機覆蓋指南bpy 萌壳。背景。場景日月。相機袱瓮。數(shù)據(jù)。show_guide = { 'GOLDEN' 爱咬，'CENTER' } ＃作為報告類型self 的運算符參數(shù)傳遞尺借。報告（{ '警告' ，'信息' }台颠，“有些消息褐望！” ）

內(nèi)部類型

用于Blender數(shù)據(jù)塊和集合：?bpy.types.bpy_struct

對于包含其自己的屬性組/網(wǎng)格/骨骼/場景等的數(shù)據(jù)...等。

有兩種主要類型包裝Blenders數(shù)據(jù)串前，一種用于數(shù)據(jù)塊（內(nèi)部稱為bpy_struct）瘫里，另一種用于屬性。

>>> bpy 荡碾。背景谨读。對象bpy.data.objects ['Cube']

>>> ? 。場景坛吁。對象bpy.data.scenes ['Scene']劳殖。對象

請注意，這些類型引用了Blender的數(shù)據(jù)拨脉，因此可以立即看到它們的修改哆姻。

Mathutils類型

用于矢量，四元數(shù)玫膀，eulers矛缨，矩陣和顏色類型，可從?mathutils

某些屬性如bpy.types.Object.location帖旨，?bpy.types.PoseBone.rotation_euler和bpy.types.Scene.cursor_location?可以作為特殊數(shù)學(xué)類型訪問箕昭，這些類型可以一起使用并以各種有用的方式進(jìn)行操作。

矩陣示例解阅，向量乘法：

bpy 落竹。背景。對象货抄。matrix_world * bpy 述召。背景朱转。對象。數(shù)據(jù)桨武。verts [ 0 ] 肋拔。合作

注意

mathutils類型保留對Blender內(nèi)部數(shù)據(jù)的引用，因此可以應(yīng)用更改呀酸。

例：

＃修改Z軸到位凉蜂。bpy 。背景性誉。對象窿吩。位置。z + = 2.0 ＃location變量也包含對象的引用错览。location = bpy 纫雁。背景。對象倾哺。location location * = 2.0 ＃復(fù)制值會刪除引用轧邪，因此可以將值傳遞給#function并修改，而不會產(chǎn)生不必要的副作用羞海。location = bpy 忌愚。背景。對象却邓。位置硕糊。復(fù)制（）

動畫

有兩種方法可以通過Python添加關(guān)鍵幀。

第一種是直接通過鍵屬性腊徙，類似于從按鈕作為用戶插入關(guān)鍵幀简十。您也可以手動創(chuàng)建曲線和關(guān)鍵幀數(shù)據(jù)，然后設(shè)置屬性的路徑撬腾。以下是兩種方法的示例螟蝙。

兩個示例都在活動對象的Z軸上插入關(guān)鍵幀。

簡單的例子：

obj = bpy 民傻。背景胰默。對象obj 。location [ 2 ] = 0.0 obj 饰潜。keyframe_insert （data_path = “l(fā)ocation” 初坠，frame = 10.0 和簸，index = 2 ）obj 彭雾。location [ 2 ] = 1.0 obj 。keyframe_insert （data_path = “l(fā)ocation” 锁保，frame = 20.0 薯酝，index= 2 ）

使用低級功能：

obj = bpy 半沽。背景。對象obj 吴菠。animation_data_create （）obj 者填。animation_data 。action = bpy 做葵。數(shù)據(jù)占哟。行動。new （name = “MyAction” ）fcu_z = obj 酿矢。animation_data 榨乎。行動。曲折瘫筐。new （data_path = “l(fā)ocation” 蜜暑，index = 2 ）fcu_z 。keyframe_points 策肝。添加（2 ）fcu_z 肛捍。keyframe_points [ 0 ] 。共= 10.0 之众，0.0 fcu_z 拙毫。keyframe_points [ 1 ] 。共= 20.0 酝枢，1.0