Blender參考API用法

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控制檯中。

注意 並不是全部操做員都註冊顯示，例如縮放視圖對於重複這樣作是沒有用的，所以將其排除在輸出以外。要顯示運行的每一個運算符，請參閱顯示全部運算符