快速入門簡介
前言
此API通常是穩定的，但某些部分仍在添加和改進。
Blender / Python API可以執行以下操作：
編輯用戶界面可以使用的任何數據（場景，網格，粒子等）
修改用戶首選項，鍵盤圖和主題
使用自己的設置運行工具
創建用戶界面元素，例如菜單，標題和面板
創建新工具
創建交互式工具
創建與Blender集成的新渲染引擎
在現有Blender數據中定義新設置
使用Python中的OpenGL命令在3D視圖中繪圖
Blender / Python API?不能（還）......
創建新的空間類型。
為每種類型分配自定義屬性。
定義在數據更改時要通知的回調或偵聽器。
開始之前
本文檔無意完全涵蓋每個主題。相反，它的目的是讓您熟悉Blender Python API。
在開始之前要了解的有用事項的快速列表：
Blender使用Python 3.x;?一些在線文檔仍然使用2.x.
交互式控制臺非常適合測試單行程序。它還具有自動完成功能，因此您可以快速檢查API。
按鈕工具提示顯示Python屬性和操作名稱。
右鍵單擊按鈕和菜單項可直接鏈接到API文檔。
有關更多示例，文本菜單有一個模板部分，其中可以找到一些示例運算符。
要檢查使用Blender分發的其他腳本，請參閱：
scripts/startup/bl_ui 用戶界面，
scripts/startup/bl_operators 操作員。
確切位置取決于平臺，請參閱：?配置和數據路徑。????
運行腳本
執行Python腳本的兩種最常用方法是使用內置文本編輯器或在Python控制臺中輸入命令。
無論是文本編輯器和Python的控制臺都是面板類型，您可以從視圖標題選擇。
您可能更喜歡使用Scripting屏幕（默認情況下包含Blender），可以從頂部標題屏幕選擇器訪問，而不是手動配置Python開發空間。
從文本編輯器中，您可以打開.py文件或從剪貼板粘貼，然后使用“運行腳本”進行測試。
Python控制臺通常用于輸入代碼段和測試以獲得即時反饋，但也可以將整個腳本粘貼到其中。
腳本也可以使用Blender從命令行運行，但要學習Blender / Python，這不是必需的。
關鍵概念
數據訪問
訪問數據塊
Python以與動畫系統和用戶界面相同的方式訪問Blender的數據;?這意味著任何可以通過按鈕更改的設置也可以從Python更改。
使用該模塊訪問當前加載的混合文件中的數據bpy.data。這樣可以訪問庫數據。例如：
>>> bpy.data.objects
>>> bpy.data.scenes
>>> bpy.data.materials
關于集合
您會注意到索引和字符串可用于訪問集合的成員。
與Python的詞典不同，這兩種方法都是可以接受的;?但是，運行Blender時，成員的索引可能會發生變化。
>>> 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"]
訪問屬性
一旦有了數據塊，例如材料，對象，組等，就可以像使用圖形界面更改設置一樣訪問其屬性。事實上，每個按鈕的工具提示也會顯示Python屬性，這有助于查找腳本中要更改的設置。
>>> bpy.data.objects[0].name'Camera'
>>> bpy.data.scenes["Scene"]bpy.data.scenes['Scene']
>>> bpy.data.materials.new("MyMaterial")bpy.data.materials['MyMaterial']
為了測試訪問它的數據，使用“控制臺”很有用，它是自己的空間類型。這支持自動完成，為您提供了一種快速瀏覽文件中不同數據的方法。
可以通過控制臺快速找到的數據路徑示例：
>>> bpy.data.scenes[0].render.resolution_percentage
100
>>> bpy.data.scenes[0].objects["Torus"].data.vertices[0].co.x
1.0
數據創建/刪除
那些熟悉其他Python API的人可能會驚訝于無法通過調用類來創建bpy API中的新數據塊：
>>> bpy.types.Mesh()
Traceback (most recent call last):
File"", line1, in
TypeError:bpy_struct.__new__(type): expected a single argument
這是API設計的有意識部分。Blender / Python API無法創建存在于主Blender數據庫（通過其訪問bpy.data）之外的Blender數據，因為此數據由Blender管理（save / load / undo / append ...等）。
通過集合中的方法添加和刪除數據bpy.data，例如：
>>> mesh=bpy.data.meshes.new(name="MyMesh")
>>> print(mesh)
>>> bpy.data.meshes.remove(mesh)
自定義屬性
Python可以訪問具有ID的任何數據塊的屬性（可以鏈接和訪問的數據bpy.data。當分配屬性時，您可以組成自己的名稱，這些名稱將在需要時創建或覆蓋（如果存在）。
此數據與混合文件一起保存并與對象一起復制。
例：
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
整數/浮點數
字典（僅支持字符串鍵，值也必須是基本類型）
這些屬性在Python之外有效。它們可以通過曲線設置動畫或在驅動程序路徑中使用。
Context
雖然能夠通過名稱或列表直接訪問數據很有用，但更常見的是根據用戶的選擇進行操作。上下文始終可用bpy.context，并可用于獲取活動對象，場景，工具設置以及許多其他屬性。
常見用例：
>>> bpy.context.object
>>> bpy.context.selected_objects
>>> bpy.context.visible_bones
請注意，Context是只讀的。雖然可以通過運行API函數或使用數據API來更改這些值，但無法直接修改這些值。
因此會引發錯誤。bpy.context.object?=?obj
但是會按預期工作。bpy.context.scene.objects.active?=?obj
Context屬性根據訪問位置而變化。3D視圖具有與控制臺不同的Context成員，因此在訪問用戶狀態已知的Context屬性時要小心。
請參閱bpy.contextAPI參考。
Operators (Tools)
操作員通常是用戶通過按鈕，菜單項或鍵快捷鍵訪問的工具。從用戶的角度來看，它們是一個工具，但Python可以通過bpy.ops模塊使用自己的設置來運行它們。
例子：
>>> bpy.ops.mesh.flip_normals()
{'FINISHED'}
>>> bpy.ops.mesh.hide(unselected=False)
{'FINISHED'}
>>> bpy.ops.object.scale_apply()
{'FINISHED'}
注意
菜單項：幫助?運算符備忘單?提供了Python語法中所有運算符及其默認值的列表，以及生成的文檔。這是了解所有Blender運營商概況的好方法。
Operator Poll()
許多操作員都有一個“輪詢”功能，可以檢查光標是在有效區域還是對象處于正確模式（編輯模式，重量繪制等）。當操作符的poll函數在Python中失敗時，會引發異常。
例如，bpy.ops.view3d.render_border()從控制臺調用會引發以下錯誤：
RuntimeError: Operator bpy.ops.view3d.render_border.poll() failed, context is incorrect
在這種情況下，上下文必須是具有活動相機的3d視圖。
為了避免在調用運算符的地方使用try / except子句，可以調用運算符自己的poll()函數來檢查它是否可以在當前上下文中運行。
if bpy.ops.view3d.render_border.poll():
? ? bpy.ops.view3d.render_border()
整合
Python腳本可以通過以下方式與Blender集成：
·通過定義渲染引擎。
·通過定義操作。
·通過定義菜單，標題和面板。
·通過在現有菜單，標題和面板中插入新按鈕
在Python中，這是通過定義一個類來完成的，該類是現有類型的子類。
示例操作
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中注冊，可以從操作員搜索彈出窗口中調用或添加到工具欄中。
要運行腳本：
1、突出顯示上面的代碼然后按下Ctrl-C以復制它。
2、啟動Blender
3、按Ctrl-Right兩次以更改為“腳本”布局。
4、單擊標記的按鈕New并彈出確認以創建新的文本塊。
5、按Ctrl-V將代碼粘貼到文本面板（左上方框架）。
6、單擊“?運行腳本?”按鈕。
7、將光標移動到3D視圖，按空格鍵選擇操作員搜索菜單，然后鍵入“Simple”。
8、單擊搜索中的“Simple Operator”項。
具有bl_前綴的類成員記錄在API參考中bpy.types.Operator
注意
該main功能的輸出發送到終端;?為了看到這一點，一定要使用終端。
示例面板
面板將自己注冊為類，就像操作員一樣。注意bl_用于設置它們顯示的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以復制它
2、啟動Blender
3、按Ctrl-Right兩次以更改為“腳本”布局
4、單擊標記的按鈕New并彈出確認以創建新的文本塊。
5、按Ctrl-V將代碼粘貼到文本面板（左上方框架）
6、單擊“?運行腳本?”按鈕。
要查看結果：
1、選擇默認多維數據集。
2、單擊按鈕面板中的對象屬性圖標（最右側;顯示為一個小立方體）。
3、向下滾動以查看名為Hello World Panel的面板。
4、更改對象名稱還會更新Hello World Panel的名稱：字段。
請注意行分布以及代碼中可用的標簽和屬性。
也可以看看bpy.types.Panel
類型
Blender定義了許多Python類型，但也使用Python本機類??型。
Blender的Python API可以分為3類。
原生類型
在簡單的情況下，將數字或字符串作為自定義類型返回會很麻煩，因此可以將它們作為普通的Python類型進行訪問。
Blender float / int / boolean - > float / int / boolean
Blender枚舉器 - >字符串
>>> ? 。對象。rotation_mode = 'AXIS_ANGLE'
Blender枚舉器（多個） - >字符串集
＃設置多個相機覆蓋指南bpy 。背景。場景。相機。數據。show_guide = { 'GOLDEN' ，'CENTER' } ＃作為報告類型self 的運算符參數傳遞。報告（{ '警告' ，'信息' }，“有些消息！” ）
內部類型
用于Blender數據塊和集合：?bpy.types.bpy_struct
對于包含其自己的屬性組/網格/骨骼/場景等的數據...等。
有兩種主要類型包裝Blenders數據，一種用于數據塊（內部稱為bpy_struct），另一種用于屬性。
>>> bpy 。背景。對象bpy.data.objects ['Cube']
>>> ? 。場景。對象bpy.data.scenes ['Scene']。對象
請注意，這些類型引用了Blender的數據，因此可以立即看到它們的修改。
Mathutils類型
用于矢量，四元數，eulers，矩陣和顏色類型，可從?mathutils
某些屬性如bpy.types.Object.location，?bpy.types.PoseBone.rotation_euler和bpy.types.Scene.cursor_location?可以作為特殊數學類型訪問，這些類型可以一起使用并以各種有用的方式進行操作。
矩陣示例，向量乘法：
bpy 。背景。對象。matrix_world * bpy 。背景。對象。數據。verts [ 0 ] 。合作
注意
mathutils類型保留對Blender內部數據的引用，因此可以應用更改。
例：
＃修改Z軸到位。bpy 。背景。對象。位置。z + = 2.0 ＃location變量也包含對象的引用。location = bpy 。背景。對象。location location * = 2.0 ＃復制值會刪除引用，因此可以將值傳遞給#function并修改，而不會產生不必要的副作用。location = bpy 。背景。對象。位置。復制（）
動畫
有兩種方法可以通過Python添加關鍵幀。
第一種是直接通過鍵屬性，類似于從按鈕作為用戶插入關鍵幀。您也可以手動創建曲線和關鍵幀數據，然后設置屬性的路徑。以下是兩種方法的示例。
兩個示例都在活動對象的Z軸上插入關鍵幀。
簡單的例子：
obj = bpy 。背景。對象obj 。location [ 2 ] = 0.0 obj 。keyframe_insert （data_path = “location” ，frame = 10.0 ，index = 2 ）obj 。location [ 2 ] = 1.0 obj 。keyframe_insert （data_path = “location” ，frame = 20.0 ，index= 2 ）
使用低級功能：
obj = bpy 。背景。對象obj 。animation_data_create （）obj 。animation_data 。action = bpy 。數據。行動。new （name = “MyAction” ）fcu_z = obj 。animation_data 。行動。曲折。new （data_path = “location” ，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
