Simplestar Game

:::::::::::SimpleExporter ドキュメント:::::::::::

バージョン

バージョン 2.0 用のドキュメントです。
それ以外のバージョンに対しては正しくない表記が含まれている可能性があります。
最新版の入手場所（DownLoad）： SimpleExporter

ライセンス

GPLv3
編集、再配布が許されています。
ただし、再配布の際ソースコード冒頭のライセンスブロックを編集してはいけません。
再配布する際も GPLv3 ライセンスで配布しなければなりません。

概要

Blender 2.58 から モデルデータ、アニメーションデータを XML で出力する Python スクリプトツール です。
スクリプト( .py ファイル）を Blender の所定のフォルダに配置することで Blender 起動後、アドオンとして使用できるようになります。
インストール方法は同梱の ReadMe.txt ファイルに書きましたので、ご使用の際に参照してください。

入手場所（DownLoad）： SimpleExporter
いくつもバージョンがある場合は、「ドキュメントのバージョン r 一番大きい数字」をダウンロードすることをおススメします。

使い方

まず基本的な出力フローを説明します。

メニューの[File]→[Export]→[Simple XML(.xml)]で出力設定画面に進みます。
出力パスを指定して、「Export Simple XML」ボタンで XML ファイルを出力します。

続いて、出力設定画面の詳細説明をします。
出力設定画面

次の動画の 8:40 からも 2分 ほどの説明があります。操作例として参照してください。

フォーマット（プログラマー向け）

上記の使い方で出力できた XML ファイルについて、解析等を行う方のためにフォーマットの詳細を示します。

まずはエディタ XML Notepad 2007 を インストールしてない方はインストールしてください。
こちらのエディタで開いた画面を使用して説明を行います。

エディタで開いた直後の TreeView の画面を次に示します。
なお、使用したモデルは使い方で紹介した動画の Kio Miku Ver 1.5 に管理人がボーンを入れ直したものです。

すべての情報は ROOT タグの中に入っています。

FILE_INFO タグの下には MAGIC_CODE, VERSION タグがあります。
値にはそれぞれ SimpleXML, バージョン番号 が記されています。
読み込み側はまず、こちらの情報をもとにファイルの判別を行います。

FRAME_ROOT タグの中に MATRIX タグが入っていて、値に行列の16要素の float 値が記録されています。
出力設定にて 座標系とX軸で90°回転するか指定したと思いますが、その結果はこのルート行列に反映されます。
以下に示す値はすべて Blender の座標系で出力されたものなので、基本すべての値はこの行列を掛けてから使用することになるでしょう。
図に示されるルート行列は Blender → DirectX のもので、Y軸とZ軸の値を入れ替える行列であることが読み取れます。

OBJECT タグの中にはオブジェクトの情報が入っています。
属性 name には、オブジェクト名が書かれています。
FRAME_LOCAL タグの中には MATRIX タグが入っていて、ルート行列と同じ形式で
オブジェクトのローカル姿勢行列情報が記述されています。（ Blender の座標系です）

その下の FRAME タグは、ボーンフレームの情報を示しています。
name 属性にはボーンフレーム名が書かれています。
MATRIX タグには、ボーンフレームのワールド姿勢行列
MATRIX_INVERTED タグには、上記の姿勢行列の逆行列が記述されています。
（ Blender の座標系です）

メモ1：
スキンメッシュの計算を行うときは、MATRIX_INVERTED を掛けて、
頂点をボーンフレームのローカル座標系に移動させて
ボーンフレームのアニメーションで頂点を移動させ
MATRIX を掛け直して元の座標系に直すだけです。シンプルで簡単ですね。

OBJECT タグの中には FRAME タグと OBJECT タグしか存在しません。
また FRAME タグの中には FRAME タグしか存在しません。

メモ2：
Blender では、ボーンに子ボーンしか追加できず、
その子ボーンに対してオブジェクトを子として設定することができません。
そんなことから、FRAME タグの下には FRAME タグしか来れないのです。
ただし、FRAME タグ一式を格納したボーンオブジェクトは OBJECT ですので、
子としてオブジェクトを設定できることに注意してください。
ちょっとシンプルじゃないですね、理解できましたでしょうか？

Blender でオブジェクトを2つ選択して「Ctrl + P」や「Alt + P」をする、親子関係の設定と
Armatureオブジェクトのエディットモードで、「E」や「Shift + E」をする、子ボーンの追加を行う操作と
連動していると聞けば、わかりやすいでしょうか。
子として設定されたオブジェクトやボーンフレームは、親のタグの中に配置されるということです。
これで理解できないようなら、実際に試して感覚でつかんでください。（すみません）

OBJECT タグの中には、FRAME_LOCAL タグと MESH タグがあります。
属性 name にはオブジェクト名が記されています。
FRAME_LOCAL タグの中には MATRIX タグがあります。値にはオブジェクトのローカル姿勢行列が記されています。

MESH タグについて 属性 name にメッシュ名が記されているほか
VERTEX, INDEX, NORMAL タグがあります。
それぞれ、頂点位置情報、面を構成するインデックス配列情報、頂点と面の法線情報が記されています。
MESH_MATERIAL_LIST, MESH_VERTEX_COLORS,
MESH_TEXTURE_COORDS, SKIN_INFO タグについては、上記の説明後に後述します。

メモ3：
ちなみに MESH タグが無い OBJECT が Armature オブジェクトです。
つまり、MESH タグがある OBJECT タグの中には FRAME タグは存在しません。
逆に、MESH タグが無い OBJECT タグの中には少なくとも一つは FRAME タグがあり
親子関係を設定しているならば、子の OBJECT タグがあります。

MESH タグの VERTEX タグの説明です。
内部に POSITIONS タグがあり、値には図に示すようにずらりと頂点の位置情報が記されています。
Blender の座標系で、X,Y,Z 軸の値が記述されています。
基数は 0 から、この順番でインデックスアクセスして利用します。
num 属性値には頂点数が設定されています。
必ず num 属性値と POSITIONS タグの値の行数は一致します。

メモ4：
重要なことですが、この頂点情報にはオブジェクトの拡大縮小成分が既にかかっています。（適用済みです）
こうした理由には今後、当たり判定用のバウンディングボックスなどをあらかじめ計算する際、
ここですでに拡大縮小がかかっているとうれしいと思ったからです。
つまり、OBJECT の FRAME_LOCAL の MATRIX の行列には、回転と移動の成分しか含まれていません。（と言いきれます）

さて、DirectX の座標系の頂点位置を計算するには次の手順で行います。
この頂点位置に対して FRAME_ROOT の MATRIX をかけて、座標を変換します。
次に OBJECT の FRAME_LOCAL の MATRIX を FRAME_ROOT の MATRIX で DirectX の座標系に直し
その直した行列を変換後の頂点位置に掛けます。これで頂点位置は DirectX の座標系の正しい位置に来ます。
別にこれ一本という訳ではないですが、お好きなやり方で座標変換を行ってください。

INDEX タグの説明をします。
num 属性値には、面の数が記されています。
この数だけ FACE タグがあり、その FACE タグの num 属性値に面を構成している頂点の数が記されています。
構成している頂点数は 3 or 4 です。これの数だけ値として頂点インデックスが記されています。
トポロジは 3 の場合は三角形リスト、4 の場合は三角形ストリップです。

メモ5：
三角形リストは1,2,3と順番にインデックスを指定すればOKです。
4 の場合は三角形ストリップですので、インデックスは 1,2,3 と 3,4,1 で三角形を作ります。
トポロジを三角形リストで統一したい場合は、基本1,2,3の順番で三角形を作って num 属性値が4だったら
3,4,1 でもう一つ三角形を作るというやり方で対応できます。

NORMAL タグの説明をします。
name 属性値にはメッシュ名が記されています。
頂点の法線ベクトルが VERTEX_NORMAL タグの NORMALS タグの値として記されています。
num 属性値には頂点数が記されています。基本的に頂点位置の頂点数と同じです。
FACE_NORMAL タグの num 属性値には面の数が記されています。これもINDEX タグの面数と同期します。
面の数だけ FACE タグがあり、INDEX の時と同様、num 属性値が面を構成している頂点数を表し
値の頂点インデックスが、面を構成している頂点の法線ベクトルのインデックスです。

メモ6：
法線情報も頂点情報も形式は一緒です。面を構成している頂点数が
4 の場合は三角形ストリップですので、インデックスは 1,2,3 と 3,4,1 で三角形を作ります。
トポロジを三角形リストで統一したい場合は、基本1,2,3の順番で三角形を作って num 属性値が4だったら
3,4,1 でもう一つ三角形を作るというやり方で対応できます。

MESH_MATERIAL_LIST のタグについて説明します。
name 属性値にはメッシュ名が記されています。
material_num 属性値には、メッシュで使用するマテリアル数が記されています。
face_num 属性値には、マテリアルを割り当てる面数が記されています。
この face_num の数だけ INDEX タグがあり、num 属性値には面を構成している頂点数が記されています。
INDEX タグの値には面に割り当てられたマテリアルのインデックスが記されています。
基数は0です。

メモ7：
MATERIAL タグの数を超えたインデックスが面に割り当てられることはありません。
INDEX タグはこれまでの、頂点インデックスの面情報、法線の面情報と同様の並び順になっています。
三角形リストにトポロジを統一する場合は、順番に num 属性値が 4 に設定されているものを
3角形2つ分に分割する要領でインデックスを割り振るだけで、対応できます。

MATERIAL タグの説明をします。
name 属性値にはマテリアル名が記されています。
以下のタグについては値のみのものです。
DIFFUSE：拡散反射光カラー R,G,B,A の順番です。
SPECULARITY：鏡面反射係数
SPECULAR：居面反射カラー R,G,B,A の順番です。
以下のタグについては、Blender でのマテリアル表記の通りです。
こちらのページが参考になります。
DARKNESS
EMIT
DIFFUSE_FRESNEL
DIFFUSE_FRASNEL_FACTOR
DIFFUSE_INTENSITY
DIFFUSE_SHADER
DIFFUSE_TOON_SIZE
DIFFUSE_TOON_SMOOTH
MIRROR
PREVIEW_RENDER_TYPE
ROUGHNESS
SHADOW_BUFFER_BIAS
SHADOW_CAST_ALPHA
SHADOW_RAY_BIAS
SPECULAR_ALPHA
SPECULAR_HARDNESS
SPECULAR_IOR
SPECULAR_SHADER
SPECULAR_SLOPE
SPECULAR_TOON_SIZE
SPECULAR_TOON_SMOOTH
TRANS_LUCENCY
TYPE
USE_TEXTURES：テクスチャリストの右にあるチェックボックスの状態、全18個

テクスチャが設定されているマテリアルの場合は、TEXTURE_LIST タグが記述されます。
num 属性値には設定されているテクスチャ数が記されています。
TEXTURE タグの中には name 属性値があり、テクスチャ名が記されています。
FILE_PATH タグの値にはテクスチャの画像ファイルへの絶対パスが記されています。
TILES_X, TILES_Y タグの値には横軸、縦軸方向のタイリング値が記されています。
USE_NORMAL_MAP タグの値にはテクスチャをノーマルマップとして使用するかのフラグ状態が記されています。

MESH_VERTEX_COLORS タグの説明です。
name 属性値にはメッシュ名が記されています。
num 属性値には頂点カラーセットの数が記されています。
VERTEX_COLORS タグの説明です。
name 属性値には頂点カラーセットの名前が記されています。
COLOR タグの値には R,G,B の順番で頂点カラーが記述されています。

メモ8：
注意点があります。ここまで示してきた頂点情報の順番と同期していません。
VERTEX_COLORS タグには num 属性値あってしかりですが、無いのには理由があったのです。
ここに連なっている頂点カラーの順番は面を構成している頂点の順番を元に並べられています。
特殊なアドレッシングなので、使用の際は順番に十分注意してください。

まず、COLOR タグの数は面の数 x 4 になっています。
つまり面ごとに COLOR タグを4つ飛ばしでアクセスすることになります。
特殊なアドレッシングについてですが
たとえば FACE タグの num 属性値が 4 の場合は、面を構成している３角形二つに対して
4,1,2 と 2,3,4 の順番で COLOR タグの値が対応します。
また、FACE タグの num 属性値が 3 の場合は、2,3,4 の順番で COLOR タグの値が対応します。
なぜこんな順番なのか疑問です。エクスポータでどうにかできそうになかったので読み取り側で対応しました。

MESH_TEXTURE_COORDS タグの説明です。
name 属性値にはメッシュ名
num 属性値にはUVマップ座標セットの数が記されています。
この数だけ TEXTURE_COORDS タグが存在します。
name 属性値にはUVマップ座標セット名が記されています。
num 属性値には、頂点数が記されています。

メモ9：
こちらは頂点カラーとは違い
テクスチャ座標は頂点情報の頂点インデックスの順番で出力されるので、
頂点インデックスでアクセスすれば対応する頂点のUV座標が取得できます。

MESH タグの SKIN_INFO タグの説明です。
name 属性値には、メッシュに影響を与える Armature オブジェクトの名前が記されています。
MAX_PER_VERTEX タグの値には、頂点に影響を与えるスキンボーンの最大数が記されています。
LIMIT_PER_VERTEX タグの値には、出力時に指定した頂点の最大スキンボーン数が記されています。
SKIN_BONE_COUNT タグの値には、メッシュに影響を与えているボーンの総数が記されています。

このボーン数の数だけ SKIN_WEIGHTS タグがあります。
name 属性値には、ボーンフレーム名が記されています。
num 属性値には、影響を与えている頂点数が記されています。
この数だけ INDECIES タグの値には、頂点インデックスが書かれています。
また、同じ数だけ WEIGHTS タグの値には、スキンの重み係数が書かれています。

メモ：
スキンメッシュの影響を与えている頂点数は、ボーンによってまちまちです。
決してすべての頂点に対して重みが設定されているわけではないので、間違えないようにしてください。
また、頂点の最大スキンボーン数を決めたからといってその最大数を超えないとは限りません。
LIMIT_PER_VERTEX タグの値は指標であって、絶対にその値以下になるとは限りません。
読み取り側でこの数より多く頂点にスキンの重みを設定しないように実装する必要があります。

ANIMATION タグの説明をします。
name 属性値には出力時に指定したアニメの名前が記されています。
アニメーション情報を持っているオブジェクトについてのみ OBJECT_ANIM タグが出力されます。
objectName 属性値にはアニメーションするオブジェクト名が記されています。
actionName 属性値には Blenderの Action Editor で確認できるアクション名が記されています。

LOCATION タグには移動アニメ情報が記されています。
num 属性値にはキーフレーム総数が記されています。
この数だけ KEY_INFO タグが存在することになり
key 属性値には開始フレームから数えたフレーム数が記録されます。
値には X,Y,Z の値が記されています。
アニメのスタートフレームにおける位置からの差分として出力されます。
つまり終始止まっているアニメだった場合、X,Y,Z はすべて 0 のままであると言い切れます。

ROTATION タグには回転アニメの情報が記されています。
num 属性値にはキーフレーム総数が記されています。
この数だけ KEY_INFO タグが存在することになり
key 属性値には開始フレームから数えたフレーム数が記録されます。
値には四元数（クォータニオン）のw,x,y,z の値が記されています。
アニメのスタートフレームにおける回転からの差分として出力されます。
つまり終始回転しないアニメだった場合、w,x,y,z はそれぞれ -1, 0, 0, 0 のままであると言い切れます。

SCALE タグには拡大縮小アニメの情報が記されています。
num 属性値にはキーフレーム総数が記されています。
この数だけ KEY_INFO タグが存在することになり
key 属性値には開始フレームから数えたフレーム数が記録されます。
値には軸方向の拡大縮小係数 sx,sy,sz の値が記されています。
アニメのスタートフレームにおける拡大縮小係数からの差分として出力されます。
つまり終始拡大縮小しないアニメだった場合、sx,sy,sz はすべて 1 のままであると言い切れます。

メモ10：
重要な点として、ボーンフレームのアニメに関してだけは、
アニメの値はエディットモードで配置した位置からの差分になります。
言葉では伝えづらいですが、たとえば、エディットモードで指定したボーンの位置から動かしていなければ
すべての値は固定アニメになります。（これで理解してもらえるとうれしいです。）
そうですね、つまりルートボーンだけ動かせばルートボーンのみアニメを出力し、
やはりその他の子ボーンのアニメは固定アニメになります。（これでも理解できない方すみません）

キーフレームアニメに関しては Blender の Pose Mode でキーを
打った値しか出力されないことにも注意が必要です。

これらアニメーションの情報も Blender の座標系で出力されますので
DirectX で利用する前に座標変換を行う必要があります。

使用例

データをどうやって変換しているかを次に示しました。

シェーダマテリアル�B

変換したデータを描画するのは全く別の話なので、そこは自分で勉強しなければなりません。

2011/08/07 最終更新