そういう、モデルなんです。

ビジネスモデル、3Dモデル、設計図、模型などの現状と動向を考察、関連書籍の紹介

Blender 3.2.2 Python API クイックスタートの意訳

まず最初のページ Quickstart — Blender Python API から。

はじめる前に Before Starting

  • 開発者用オプション Developer Extra と Python ツールチップを表示  Python Tooltips を有効にすること
    • Blender のメニューボタン等にマウスオーバーすると Python では何という名前の API 命令文 Operation なのか、とても薄暗い文字だけど、ツールチップに表示してくれる。
      3Dモデルのオブジェクトの名前とかは、教えてくれない。
    • Blender のメニューボタンなどの右クリックメニューで APIリファレンスに跳べる

    • 違う Blender ファイルを開くとき再設定が必要になる場合があるようだ?
  • Python コンソールのオートコンプリートを活用せよ
    Python コンソールの右クリックメニューの一番下に [オートコンプリートがある。タブキーを押しても発動する。
    • 途中まで入力した内容が正しくて一択の場合には自動的に補完され、
    • 正しいけれど複数候補がある場合は下に緑色の字で候補が表示される。メソッドとかデータとか属性とかの区別はつかない感じでひたすら。

    • 完全に間違っている場合は何も表示されない
  • テキストディタのテンプレートにサンプルがある
    何のサンプルなのかの説明はないので、慣れてから使うものなのだろう...

スクリプトの実行 Running Scripts

コンソールに直接タイプ(もしくはコピペ)するか、テキストエディタに書いてからスクリプト実行する。メニューバー右端に Scripting というメニューがある。

  • コンソールでは print 文の結果が見えるが、テキストエディタだと見えない orz
    • コンソールに複数行コピペの場合、最後の行は、改行 Enter キーを押さないと実行されていないことがよくある
    • パソコンのレスポンスが悪いのか?ショートカットでのコピー&ペーストの動作がもっさりしていて、うまくいかないころがままある
    • 文の先頭に空白文字(インデント)があって実行されないことがままある

基本概念 Key Concepts 

データアクセス

データブロックにアクセスする
  • bpy.data モジュールを使う
    • コンソールに bpy.data. と入力してオートコンプリートするとウンザリする位、選択肢が出てくる
    • その下に複数のデータがあるものを指定すると(例えば bpy.data.objects)、配列の要素数とデータ型を返してくるらしい
    • 大まかにいえば、このモジュールは、Blender の利用者インタフェース UI の命令 Operation とは無関係に、オブジェクト・データモデルを直接に操作する方法だといえる
配列にアクセスする Accessing Collections
  • 要素インデックスには、名前とインデックス数値が使用できるが、名前を使う方が安全なのはいうまでもない
  • list 命令にその下に複数のデータがあるものを指定すると、要素に入っているデータの名前が分かる。例えば list(bpy.data.objects)
属性にアクセスする Accessing Attributes

オブジェクトモデルが分かっていないと、何が属性なのか分かりませんが...

コンテクスト

  • 例えば bpy.context.selected_objects は、利用者が Blender の画面上で(複数)選択しているものが何かを返す
    • bpy.context.active_object なども便利

オペレーター(ツール)

  • 利用者が選択できるメニュー項目のことをオペレータというらしい。
    • 大まかにいえば、オペレータを操作する ops モジュールは、Blender の利用者インタフェース UI の命令 Operation そのものだといえる
    • 多くの操作は、bpy モジュールでオブジェクト・データモデルを直接に操作する方法で代替できるが、手作業を自動化するときには opsAPI の方がツールチップで命令を特定できるので移植はしやすいと思う

オペレーター(ポーリング) Operator Poll()

  • そのオペレーターを実施しようとするにあたって、そもそも現在のモードやカーソルの居場所が、正しいかどうかを事前チェックするもの。

次の Python API Overview — Blender Python API は作成したアドオンを Blender に登録する方法とかなので飛ばして Reference API Usage — Blender Python API へ。

データアクセス

ID データブロック

  • Blender の最上位レベルのデータの容れ物
  • シーン、グループ、オブジェクト、メッシュ、ワークスペース、ワールド、アーマチュア、画像、テクスチャなどの種類からなる Blender のオブジェクトモデルの根幹であり、bpy.data.何とか以下にある。

簡単なデータ処理の例

  • 利用者が選択したデータは大抵 bpy.context で処理でき、利用者は現在選択しているものに対する処理を期待するので、ほとんどの場合はこれが適切
  • モード(オブジェクト、編集、ポーズ)に依存することがほとんど
    • サクッと書かれている Blender あるあるだが、モードが違っていると命令が出せないので手作業の場合と同様、十分に注意が必要である
  • 現在、利用者が選択しているオブジェクトの座標を調べたい場合は bpy.context.active_object.location
    • 大抵、ローカル座標系が返ってくるので軸方向に注意
  • 名称が判明しているオブジェクトの座標を調べたい場合は bpy.data.objects["Cube"].location
    • 大抵、ローカル座標系が返ってくるので軸方向に注意

何段階も階層化されたプロパティ

  • データモデルを調べたい場合は、Python コンソールの自動コンプリートが便利
  • 利用者インタフェースのプロパティを調べたい場合は、データパスをコピーや Python コマンドをコピー
    • オペレーション opsAPI が直ぐに分かる
  • API  ドキュメントのリファレンス Reference をたどる

データパスをコピー Copy Data Path

  • データパスをコピーは、IDデータブロックより下のパスのみコピー
    modifiers["細分化"].levels
    • 利用者インタフェースのプロパティを調べたい場合、bpy.context.active_object. 以降にコピペ
  • フルデータパスをコピーは、IDデータブロックを含む全てをコピー
    bpy.data.objects["JeanCrawford"].modifiers["細分化"].levels

オペレータ Operator

  • ホットキーやボタンなどはオペレータであり、bpy.ops から操作できる
  • (オンにしてれば) Python ツールチップで名前を知ることができる
  • ツールチップが表示されない場合、それはオペレータではないか、Python から処理することができない

情報コンテクスト Info Editor

  • Python コンソールの下にある情報コンテクストに、利用者インタフェースで行った操作のオペレータが黙々と記録されており、コピペできる
    • 選択したオブジェクトなど、オペレータではないものは記録されないので前述のとおり bpy.context.active_object などで調べる

次の Best Practice — Blender Python API はコーディング規約なので飛ばして、

Tips and Tricks — Blender Python API に行く。

勘コツ Tips and Tricks

ターミナルを利用する

ターミナル、つまり Windows コマンドプロンプトなどから Blender を起動すると

  • デバッグ時に自分で埋め込んだ print() の出力を参照したい場合
  • デバッグトレース詳細を参照したい場合
  • スクリプトが無限ループになったとき [Ctrl]-[C] で止めたい場合

次の Tips and Tricks — Blender Python API はまとめぽいので飛ばして Gotchas — Blender Python API に行く。

ボーンを編集しまくる Edit Bones, Pose Bones, Bone… Bones

  • アーマチュアのボーンのデータは、モードごとに別々に格納されており、相互には参照できないかもしれない
  • ボーンの編集 bpy.context.object.data.edit_bones を使うにはまずアーマチュアを編集モードに切り替える。
  • ボーン(オブジェクトモード)では bpy.context.object.data.bones に含まれ色々変更できるが、ヘッド head とテール tail のプロパティは読み取りのみ。
  • ボーンのポーズ bpy.context.object.pose.bones には制約や IK 設定と同様にアニメーションのデータが反映される。
    • 厳密にはポーズボーンはボーンではなく、アーマチュアの状態なのだが、bpy.types.PoseBone.bone からボーンを処理できる。

アーマチュアのモード変更 Armature Mode Switching

頻繁にアーマチュアのモードを切り替えると思うが、編集モードにおけるボーン編集やヘッド/テールの座標を参照しないように。Blender がクラッシュする。