MRが楽しい

MRやVRについて学習したことを書き残す

Blender 2.8のPython APIドキュメントを少しずつ読み解く 落とし穴 その1

本日は Blender2.8 の調査枠です。
Blender 2.8 の Python API ドキュメントを少しずつ読みつつ試していきます。

Blender 2.8 Python API Documentation

以下のページを日本語訳しつつ実際に試して記事を進めていきます。
docs.blender.org
docs.blender.org

今日は「落とし穴」の「演算子の使い方」です。
f:id:bluebirdofoz:20200111221935j:plain

落とし穴

このドキュメントはBlender APIの使用でトラブルが発生した際の助けになります。

演算子の使い方

Blender演算子はユーザーがアクセスするためのツールです。
演算子Pythonで利用できることは便利ですが、演算子にはスクリプトが面倒になる制限があります。

主な制限は以下の通りです。

・操作するオブジェクト、メッシュ、マテリアルなどのデータを渡すことはできません
 (オペレーターは代わりにコンテキストを使用します)
・オペレーターの呼び出しからの戻り値は成功(終了またはキャンセルされた場合)を提供します。
 場合によっては、操作の結果を返す方がAPIの観点からより論理的です。
API関数が例外を発生させ、正確な理由の詳細を示す場合、オペレーターのポーリング関数は失敗する可能性があります。

オペレーターのポールが失敗する原因が分からない場合

演算子を呼び出すと、次のようなエラーが発生するケースについてです。

>>> bpy.ops.action.clean(threshold=0.001)
RuntimeError: Operator bpy.ops.action.clean.poll() failed, context is incorrect

f:id:bluebirdofoz:20200111221947j:plain

正しいコンテキストが何であるかを確認する必要があります。

通常、演算子はアクティブエリアタイプ、選択可能なオブジェクト、または操作可能なアクティブオブジェクトをチェックします。
しかし、一部のオペレータは実行時に注意を要する場合があります。
ほとんどの場合、演算子Blenderでどのように使用されているかを見ることで、それが必要なコンテキストを把握できます。
f:id:bluebirdofoz:20200111221957j:plain

演算子が動けない場合、実際に何が問題かを知る唯一の方法は、ポーリング関数のソースコードを読むことです。
Python演算子の場合、ソースを見つけるのはそれほど難しくありません。
ソースがBlenderに含まれており、オペレーターリファレンスドキュメントに含まれているためです。
f:id:bluebirdofoz:20200111222005j:plain

Cコードのダウンロードと検索はそれほど簡単ではありません。
演算子名または説明を検索すると、C言語の知識がなくてもポーリング関数を見つけることはできます。

Blenderには、ポーリング関数が失敗する理由を説明する機能があります。
ポーリングが失敗する理由がわからない場所に CTX_wm_operator_poll_msg_set 呼び出しを追加してください。

>>> bpy.ops.gpencil.draw()
RuntimeError: Operator bpy.ops.gpencil.draw.poll() Failed to find Grease Pencil data to draw into

それでも演算子が動作しない場合

Blenderの特定の演算子は、特定のコンテキストでの使用のみを目的としています。
例えば、一部の演算子は、現在のマテリアル、モディファイア、または制約をチェックするプロパティウィンドウからのみ呼び出されます。

この例は次の通りです。

・bpy.ops.texture.slot_move
・bpy.ops.constraint.limitdistance_reset
・bpy.ops.object.modifier_copy
・bpy.ops.buttons.file_browse

別の可能性は、あなたがスクリプトでこの演算子を使用しようとする最初の人である場合です。
この場合、異なるコンテキストで実行するために演算子にいくつかの変更を加える必要があります。
スクリプトをバグトラッカーに報告してください。

bluebirdofoz.hatenablog.com