Module API_intro

The Blender Python API Reference 日本語版

(*)は更新した印。

トップモジュール：

• Blender

サブモジュール：

• Armature (*)
  • NLA
  • Action
• BezTriple (*)
• BGL
• Camera (*)
• Curve (*)
• Draw (*)
• Effect
• Geometry (*)
• Group (*)
• Image (*)
• Ipo (*)
  • IpoCurve (*)
• Key (*)
• Lamp
• Lattice (*)
• Library (*)
• Material (*)
• Mathutils (*)
• Mesh (*)
  • MeshPrimitives (*)
• Metaball (*)
• NMesh (*)
• Noise
• Object (*)
  • Modifier (*)
  • Pose (*)
  • Constraint (*)
  • ActionStrips (*)
• Registry
• Scene (*)
  • Radio
  • Render (*)
• Sound (*)
• Text
• Text3d
  • Font
• Texture (*)
• TimeLine
• Types
• Window
  • Theme (*)
• World
• sys

追加情報:

• 特別な機能:

  • スクリプト：メニューへの登録方法、説明文の書き方、設定に関すること (new)

  • コマンドラインの使用例 (new)
  • スクリプトリンク (*), space handler script links, Groupモジュール(new).

はじめに：

Blender Python APIは、 Blender内部のデータと機能にアクセスできるPythonモジュールの集まりです。 現在も改良が続いています。

Pythonはプログラミング言語のひとつです。 PythonでスクリプトをつくればBlenderをリアルタイムに拡張できます。 初心者はPythonのチュートリアル から始めると良いでしょう。

スクリプトの実行方法：

• Text Editorウィンドウから実行： Text Editorウィンドウにスクリプトファイルを読み込んだり、 スクリプトを直接打ち込んだりしてから、ALT+Pを押すと実行できます。Fileメニューや右クリックメニューからも実行できます。
• コマンドラインから実行： blender -P <scriptname>というコマンドでBlenderを起動すると、 指定したスクリプトが実行されます（<scriptname>はスクリプトのファイル名です）。 または、'blender myfile.blend -P textname'とすると、 .blendファイルに保存されているTextの名前から実行できます。
• コマンドラインからバックグラウンドモードで実行： '-b'フラグを使って、 blender -b <blendfile> -P <scriptname>としてください（語順が重要）。 <blendfile>は任意の.blendファイルです（Blenderのホームディレクトリ（Blender.Get('homedir')）にある.B.blendでも良い）。 このモードではウィンドウは表示されず、 スクリプトが終了したらすぐにBlenderが終了します。
• メニューから実行： スクリプトが適切に登録されていれば、 プログラムのメニューから選んで実行できます。
• スクリプトリンクとして実行： Text Editorウィンドウにあるスクリプトを、 Script ContextのScriptlinksパネルで、オブジェクトやマテリアルやシーンにリンクしてください。 スクリプトリンクは特定のイベント(OnLoad, Redraw, FrameChanged)が起こると自動的に実行されます。 通常のスクリプトからスクリプトリンクを作ることもできます （Textを作成してオブジェクトとイベントにリンクするという手順です）。 例についてはObject.Object.addScriptLinkを見てください。
• スクリプトから他のスクリプトを実行： Blender.Runモジュール関数を使ってください。 実行されるほうのスクリプトは、自身のグローバル辞書を持ち、自身のコンテクストで実行されます。

ユーザーとの相互作用：

• 実行開始とともに何か処理をしてすぐ終了する。

• メッセージ、メニュー、数値・文字列用の小さな入力ボックスを表示する。

• OpenGL呼び出しとBlenderのボタンを使って、 GUI（グラフィカルユーザーインターフェイス）を描画する。 ユーザーが閉じるまで、他のウィンドウと同じようにユーザーの入力を受け取り続けます。
• スクリプト自身をspace handlerに取りつける （ココを見てください）。
• 3D Viewに変更を加える（レイヤーの表示や、視点など）。

• 主な入力イベントキューを横取りして、キーボード操作、マウス操作、 再描画イベントを処理する（あるいはBlenderに渡す）。 この使い方は良くありません。個人使用のためにあります。

• 他のスクリプトを実行する（Blender.Run()を見よ）。
• 外部のPythonライブラリがあれば、それを使う。

コマンドラインモード：

PythonはBlenderに組み込まれているので、 BPythonモジュールにアクセスするにはBlender内でスクリプトを実行する必要があります。 外部のPythonインタプリタからはBlenderモジュールをインポートできません。

その一方で、いろいろな用途のために、スクリプトの自動処理によってBlenderを制御できます。 興味があれば、以下の機能について学んでください。 OnLoadスクリプトリンク、 "-b <blendfile>" （バックグラウンドモード）や"-P <script>" （スクリプトの実行）のコマンドラインオプション、 Blender.Save, Blender.Load, Blender.Quit などのAPI、 LibraryやRenderモジュール。

注意：Blenderのウィンドウが初期化される前にスクリプトが実行されるので、 ウィンドウ関連の属性を取得・設定する関数（Windowの関数など）は使えません（ウィンドウを表示しない'-b'モードでも同様です）。 そういう関数を使いたいときは、OnLoadスクリプトリンクを利用してください （Scene.Scene.addScriptLink参照）。 コマンドラインスクリプトからOnLoadスクリプトリンクを作成してセットすることもできます。 Blenderがバックグラウンドモードなのかインタラクティブモードなのかを調べるには、 Blender.modeモジュールの変数を見てください。

デモモード：

ユーザーが操作しなくても自動的に動いて色々なことをしてみせるデモンストレーションを作れます。 デモでは、静止画や動画をレンダリングしたり、 レンダリングした動画を再生したり、リアルタイムにアニメーションを再生したり、 ラジオシティを計算したり、他にもいろんなことができます。 .blendファイルをデモにするには、自動実行をするためのスクリプトを書いて、 OnLoadスクリプトリンクとしてシーンにリンクしてください。 そうすれば、Blenderを "-y" 引数で起動しない限り、.blendファイルを開くと自動的にデモが開始されます。

ゲームエンジンAPI：

Blenderにはゲームエンジンが内蔵されていて、3Dゲームを作って遊べるようになっています。 ゲームのAIや制御などを強化するスクリプトを書けば、 より複雑な相互作用と仕掛けを実現できます。 ゲームエンジン用のAPIは、このリファレンスで説明するBlender Python APIとは分かれています。 ゲームエンジン用のAPIリファレンスは、www.blender.orgのDocumentationにあります。

Blenderのデータ構造：

そもそもプログラムとはデータ構造を操作するものであり、Blender Pythonスクリプトも例外ではありません。 Blenderの構造は「オブジェクト指向」です。 そしてBlender Pythonのインターフェースは、Blenderの画面と同じ方法でオブジェクトや属性を表現しようとしています。 そのため、Blender Pythonでプログラミングするときには、 BlenderのOOPSウィンドウの情報を理解することが重要です。 OOPSウィンドウは、Blenderのオブジェクトとその相互関係を表示するものです。

Blenderのグラフィック要素（メッシュ、ランプ、カーブなど）は、 ObjectとObDataという2つの部分から成っています。 Objectは、 どの要素にも存在する位置・回転・大きさという情報を持っています。 ObDataは、要素の種類ごとに特有の情報を持っています。

各ObjectはObDataにリンクしています。複数のObjectでひとつのObDataを共有できます。 また、グラフィック要素はマテリアル・リストにもリンクしています。 このリストを持つのは標準ではObDataです。

Blenderのすべてのオブジェクトは、それぞれ異なる名前を持つ必要があります。 しかし、名前にはオブジェクトの種類を示す文字列が自動的に付与されるので、例えばランプObjectとランプObDataの両方にLamp.001という同一の名前を付けることができます （それぞれOB:Lamp.001、LA:Lamp.001となります）。

スクリプト作成の初心者の方へ：

インタプリタ式はコンパイル式に比べて実行速度が遅い、とよく言われますが、 ほとんどのアプリケーションにとって問題にならない程度の差です。 とはいえ、遅くなる箇所をプロファイリング （あるいはBlender.sys.timeを使った単純な時間計測）で突き止めて上手に最適化すれば、 かなり高速化できる場合が多いです。最高のスクリプトをいくつか試しに使って、 どんな事が出来るのか体験してみてください。驚くかもしれません。

Version: 2.43

Author: The Blender Python Team (and Translator: morita)

Notes:

• このドキュメントはepydocで生成しました。 epydocはHTMLとPDFを出力できます。PDF出力にはLaTeX環境が必要です。
• このリファレンスガイドの公式リリースが更新されるのは、Blenderの新バージョンがリリースされたときだけです。 しかし、公式リリース前のCVS版は誰でも簡単にビルドできます。 epydocをインストールし、BlenderのCVSのsource/blender/python/api2_2x/doc/フォルダから全ファイルを取得し、 そのフォルダにあるepy_docgen.shスクリプトを使えば、 htmlドキュメントを生成できます。 当然ですが、新機能を試すには最新のBlenderバイナリも必要になります。 自分でコンパイルしたくない人はblender.orgの testing builds forumを見てください（訳注：日本語ではblender.jpのテストビルド　トピックがいいと思います）。

Requires: Blender 2.43 or newer.

See Also:

www.blender3d.org: main site, www.blender.org: documentation and forum, blenderartists.org: user forum, projects.blender.org, blender architecture: blender architecture document, www.python.org, www.python.org/doc, Blending into Python: User contributed documentation, featuring a blender/python cookbook with many examples.