Blender參考API用法

Blender有許多互連資料型別，它們具有自動生成的引用api，它通常具有編寫指令碼所需的資訊，但可能難以使用。

本文件旨在幫助您瞭解如何使用參考API。

參考API範圍

參考API涵蓋bpy.types，儲存通過以下方式訪問的型別bpy.context- 使用者上下文 或bpy.data- 混合檔案資料。

其他模組，例如bge，bmesh並且aud沒有使用Blenders資料API，因此本文件不適用於這些模組。

資料訪問

使用參考API的最常見情況是找出如何訪問混合檔案中的資料。

在進一步瞭解Blender中的ID資料塊之前，您經常會找到與它們相關的屬性。

ID資料

ID資料塊在Blender中用作頂級資料容器。

從使用者介面來看，這不是那麼明顯，但在開發時，您需要了解ID資料塊。

ID資料型別包括場景，組，物件，網格，螢幕，世界，電樞，影像和紋理。有關完整列表，請參閱子類bpy.types.ID

以下是ID資料塊共享的一些特徵。

ID是混合檔案資料，因此載入新的混合檔案會重新載入一組全新的資料塊。
ID可以在Python中訪問 bpy.data.*
每個資料塊都有一個唯一的.name屬性，顯示在介面中。
動畫資料儲存在ID中.animation_data。
ID是唯一可以在混合檔案之間連結的資料型別。
可以通過Python新增/複製和刪除ID。
ID有自己的垃圾收集系統，可以在儲存時釋放未使用的ID。
當資料塊具有對某些外部資料的引用時，這通常是ID資料塊。

簡單的資料訪問

讓我們從一個簡單的案例開始，說你不是一個python指令碼來調整物件的位置。

首先在介面中找到此設定 Properties Window -> Object -> Transform -> Location

從按鈕，您可以右鍵單擊並選擇線上Python參考，這將連結到： bpy.types.Object.location

作為API參考，此連結通常提供的資訊比工具提示少，但有些頁面包含示例（通常位於頁面頂部）。

此時你可能會說現在是什麼？- 你知道你必須使用.location它的3個浮點陣列，但你仍然想知道如何在指令碼中訪問它。

所以下一步是找出訪問物件的位置，在頁面底部到References 部分，對於有很多引用的物件，但是訪問物件的最常見的地方之一是通過上下文。

在這一點上很容易被淹沒，因為Object在很多地方引用了它 – 修飾符，函式，紋理和約束。

但是，如果要訪問使用者選擇的任何資料，通常只需要檢查bpy.context引用。

即便如此，在這種情況下，如果您閱讀這些內容還有相當多的內容 – 大多數都是模式特定的。如果您正在編寫僅在重量塗料模式下執行的工具，那麼使用weight_paint_object 是合適的。但是，要訪問使用者上次選擇的專案，請查詢active成員，有權訪問使用者選擇的單個活動成員是Blender中的約定：例如。active_bone， active_pose_bone，active_node…在這種情況下，我們可以使用- active_object。

所以現在我們有足夠的資訊來查詢活動物件的位置。

bpy.context.active_object.location

您可以在python控制檯中鍵入它以檢視結果。

訪問引用中物件的另一個常見位置是bpy.types.BlendData.objects。

注意 這不是列為bpy.data.objects，這是因為bpy.data是bpy.types.BlendData類的一個例項，所以文件指向那裡。

使用bpy.data.objects，這是一組物件，因此您需要訪問其中一個成員。

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

巢狀屬性

前面的示例非常簡單，因為可以直接從上下文訪問location其屬性Object。

以下是一些更復雜的例子：

# 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

正如您所看到的，有時您希望訪問巢狀的資料，這種方式會導致您經歷一些間接。

這些屬性被安排為匹配資料在內部儲存的方式（在混合器C程式碼中），這通常是合乎邏輯的，但並不總是與使用Blender期望的完全相同。

因此，這需要一些時間來學習，它可以幫助您瞭解資料在Blender中的組合方式，這對於編寫指令碼非常重要。

在開始編寫指令碼時，您經常會遇到無法確定如何訪問所需資料的問題。

有幾種方法可以做到這一點。

• 使用Python控制檯的自動完成來檢查屬性。 這可能會出類拔萃，但其優勢在於您可以輕鬆檢視屬性值並將其分配給互動式檢視結果。
• 從使用者介面複製資料路徑。 進一步解釋：ref：複製資料路徑<info_data_path_copy>
• 使用文件來關注參考。 進一步解釋：ref：間接資料訪問<info_data_path_indirect>

複製資料路徑

Blender可以將Python字串計算為屬性，該屬性顯示在工具提示中，如下所示。這節省了必須使用API​​引用來單擊備份引用以查詢資料的訪問位置。Python: …

有一個使用者介面功能可以複製資料路徑，該路徑提供從bpy.types.ID資料塊到其屬性的路徑。

為了瞭解這是如何工作的，我們將獲得Subdivision-Surface修改器細分設定的路徑。

從預設場景開始，選擇“ 修改器”選項卡，然後將“ 細分 – 曲面”修改器新增到多維資料集。

現在將滑鼠懸停在標記為View的按鈕上，工具提示包括bpy.types.SubsurfModifier.levels 但我們想要從物件到此屬性的路徑。

請注意，複製的文字將不包含該bpy.data.collection[“name”].元件，因為它假定您不會在每次訪問時進行集合查詢，並且通常您希望使用上下文而不是bpy.types.ID按名稱訪問每個例項。

在Python控制檯中輸入ID路徑bpy.context.active_object。包括尾隨點，但不要點選“輸入”。

現在，右鍵單擊該按鈕並選擇“ 複製資料路徑”，然後將結果貼上到控制檯中。

所以現在你應該得到答案：

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

按“輸入”，您將獲得當前值1.現在嘗試將值更改為2：

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

您可以在Subdivision-Surface修改器的UI和多維資料集中看到值更新。

間接資料訪問

在這個例子中，我們將討論更多涉及的內容，顯示訪問活動的雕刻畫筆紋理的步驟。

讓我們說我們想通過Python訪問畫筆的紋理，以調整它contrast的例子。

• 從預設場景開始，從3D-View標題啟用“Sculpt”模式。
• 從工具欄中展開“ 紋理”皮膚並新增新紋理。 注意紋理按鈕，它自己沒有非常有用的連結（你可以檢查工具提示）。

• 對比度設定未在雕刻工具欄中顯示，因此在屬性皮膚中檢視紋理…

  • 在屬性按鈕中，選擇“紋理”上下文。
  • 選擇“畫筆”圖示以顯示畫筆紋理。
  • 展開“ 顏色”皮膚以找到“ 對比度”按鈕。
• 右鍵單擊對比按鈕，並選擇線上Python的引用 這需要你bpy.types.Texture.contrast
• 現在我們可以看到這contrast是紋理的屬性，接下來我們將檢查如何從畫筆訪問紋理。
• 檢查頁面底部的參考文獻，有時會有很多參考文獻，並且可能需要一些猜測才能找到合適的參考文獻，但在這種情況下顯然是這樣Brush.texture。
• 現在我們知道可以從中訪問紋理， bpy.data.brushes[“BrushName”].texture 但通常您不希望按名稱訪問畫筆，因此我們現在將看到訪問活動畫筆。
• 因此，下一步是通過參考檔案檢查訪問畫筆的位置。在這種情況下，bpy.context.brush我們只需要它。

現在，您可以使用Python控制檯來形成訪問畫筆紋理對比所需的巢狀屬性，邏輯上我們現在知道了。

上下文 – >畫筆 – >紋理 – >對比度

由於每個屬性都是按照我們在python控制檯中組成資料路徑的方式給出的：

bpy.context.brush.texture.contrast

可以有多種方式來訪問相同的資料，您選擇的方法通常取決於任務。

訪問相同設定的備用路徑是……

bpy.context.sculpt.brush.texture.contrast

或者直接訪問畫筆……

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

如果您正在編寫使用者工具，則通常需要使用，bpy.context因為使用者通常希望該工具對他們選擇的內容進行操作。

對於自動化，您更有可能使用，bpy.data因為您希望能夠訪問特定資料並對其進行操作，無論使用者當前具有何種檢視集。

操作

Blender中的大多數按鍵和按鈕都會呼叫一個操作符，該操作符也會暴露給python via bpy.ops，

要檢視Python等效項，請將滑鼠懸停在按鈕上並檢視工具提示，例如，如果沒有工具提示或缺少行，則此按鈕不使用運算子，無法從Python訪問。Python: bpy.ops.render.render()Python:

如果要在指令碼中使用它，可以Control-C在滑鼠懸停在按鈕上時將其複製到剪貼簿。

您也可以右鍵單擊按鈕並檢視線上Python參考，這主要顯示引數及其預設值，但是用Python編寫的運算子顯示其檔案和行號，如果您有興趣檢查原始碼，這可能很有用。

注意 並非所有運算子都可以從Python中有用地呼叫，有關詳細資訊，請參閱使用運算子。

資訊檢視

Blender記錄您執行的運算子並在資訊空間中顯示它們。它位於檔案選單上方，可以向下拖動以顯示其內容。

選擇Blender預設的指令碼螢幕以檢視其輸出。您可以執行某些操作並看到它們顯示 – 例如刪除頂點。

可以選擇每個條目（右鍵 – 滑鼠 – 按鈕），然後複製Control-C，通常貼上到文字編輯器或python控制檯中。

注意 並非所有操作員都註冊顯示，例如縮放檢視對於重複這樣做是沒有用的，因此將其排除在輸出之外。
要顯示執行的每個運算子，請參閱顯示所有運算子