title: a3format

Acerola3Dファイルのフォーマット仕様書
========================================

Acerola3Dファイルのフォーマットの詳細を説明します．
このドキュメントに関して間違いや
不明な点などを見付けた方は<ksaito.sourceforge.jp@gmail.com>
までご連絡いただけると助かります．

Acerola3Dフォーマットのファイルに含まれる要素
----------------------------------------

Acerola3DフォーマットのファイルはZIP形式の
圧縮ファイルであり，その中には以下のファイル
が含まれます．

* CATALOG.XML
* CATALOG.XMLから参照されるBVHファイル
* CATALOG.XMLから参照されるVRML97ファイルと
  これが参照するテクスチャなどのファイル
* CATALOG.XMLから参照される音声ファイル
* CATALOG.XMLから参照されるサムネール画像ファイル
* CATALOG.XMLから参照されるHTMLファイルと
  これが参照するファイル

CATALOG.XMLは必須のファイルです．その他は
オプションですが，特殊な場合を除いて
BVHファイルとVRML97ファイルはほぼ必須です．

CATALOG.XMLとはAcerola3Dファイルに含まれる
アクションの情報や，メタデータが記述される
XMLファイルで詳細は後述します．

CATALOG.XMLは
ZIP圧縮ファイルの直下になければなりません．
(フォルダの中などに入った形で圧縮され
ていてはなりません．)

それ以外のファイルはフォルダを作成して
その中に入れることも可能ですが，その場合は
CATALOG.XMLファイルでの記述でフォルダ名
から指定しなければなりません．VRML97の参照
するファイルはVRML97ファイル内で相対アドレス
で指定しそこに配置するものとします．

META-INFフォルダとその中身は，JavaのJARファイル
と同じ仕組みで署名を行う場合に使用したり，
将来の拡張のために予約されているので，
使用できないものとします．

CATALOG.XML
----------------------------------------

CATALOG.XMLはAcerola3Dファイルに含まれるアクション
の情報やメタデータなどを記述しておくXMLファイルです．

XMLの厳密なスキーマはacerola3dパッケージ内grammar
フォルダ内の[catalog.xsd](./catalog.xsd.txt)で
定義されますが，ここではスキーマの意味について
解説してゆきます．

### `<a3>`要素@(id,elm_a3)

CATALOG.XMLファイルのトップレベル要素です。
いくつかの属性を用いて、このAcerola3Dフォーマットの
ファイル全体に対する設定を行うことができます。そして
他の要素のコンテナになります。

`<a3>`要素が含むことのできる要素は以下のとうりです。
要素の出現順番は下のリストと同じでなければなりませんが、
多くは省略可能です。最後の`<a>`要素だけは必須で1つ以上の
要素がなくてはなりません。

* [`<c>`要素](#elm_c) 0`<=`出現回数`<=`1
* [`<tag>`要素](#elm_tag) 0`<=`出現回数`<=`無制限
* [`<profile>`要素](#elm_profile) 0`<=`出現回数`<=`無制限
* [`<thumbnail>`要素](#elm_thumbnail) 0`<=`出現回数`<=`無制限
* [`<rdf:RDF>`要素](#elm_rdf) 0`<=`出現回数`<=`1
* [`<htmlfile>`要素](#elm_htmlfile) 0`<=`出現回数`<=`1
* [`<a>`要素](#elm_a) 1`<=`出現回数`<=`無制限

設定できる属性は以下のとおりです。

* haltActionNo: autoActionControlが有効な場合に停止している時の
  アクションのアクション番号として使用されます。デフォルトは0です。
* walkActionNo: autoActionControlが有効な場合に歩いている時の
  アクションのアクション番号として使用されます。デフォルトは0です。
* runActionNo: autoActionControlが有効な場合に走っている時の
  アクションのアクション番号として使用されます。デフォルトは0です。
* minWalkSpeed: autoActionControlが有効な場合に、ここで指定される
  値未満の速度で3Dオブジェクトが移動している時は停止していると
  判定されます。単位はm/sで、デフォルト値は0.1です。
* minRunSpeed: autoActionControlが有効な場合に、ここで指定される
  値未満で上のminWalkSpeed以上の速度で3Dオブジェクトが移動している
  時は歩いていると判定され、この値以上の速度で移動していれば走って
  いると判定されます。単位はm/sで、デフォルト値は1.0です。
* billboard: この値がtrueの場合はビルボード機能が有効になり
  カメラがどこにあっても，オブジェクトが常にカメラに対して
  正面を向くように自動的に回転します．デフォルト値はfalseです．

これらの全ての属性は省略可能です。

### `<c>`要素@(id,elm_c)

コメントやライセンスなど自由に文字列を書き入れることの
できる要素です。この要素の内容はテキストデータのみで、
属性はありません。

### `<tag>`要素@(id,elm_tag)

このAcerola3Dに含まれる3Dオブジェクトのタグ(キーワード)
を設定するための要素です。これは空要素で、name属性にて
タグ文字列を指定するようになっています。

### `<profile>`要素@(id,elm_profile)

このタグは，このAcerola3Dファイルに含まれる3Dオブジェクト
のプロファイルの識別子となるURIを指定するために使用されます．
このプロファイルとは，3Dオブジェクトが主として何を目的として
作成された物であるかと，どのような条件を満しているかを識別する
ためのもので，詳細については
[プロファイルのページ](http://acerola3d.sourceforge.jp/docs/format/profile/)
で説明するものとします．
これは空要素でありuri属性でプロファイルの識別子を指定します．

### `<thumbnail>`要素@(id,elm_thumbnail)

このAcerola3Dファイルに含まれる3Dオブジェクトのサムネール
画像を指定するための要素です。これは空要素でsrc属性にて
画像ファイルを指定します。この画像ファイルはAcerola3Dファイル
の中に含めておく必要があり、その画像がフォルダの中に保存されて
いるとすればそのフォルダ名から記述してやる必要があります。

### `<rdf:RDF>`要素@(id,elm_rdf)

このAcerola3DファイルのメタデータをRDF形式で含めておくための
要素です。必須の要素ではありません。

### `<htmlfile>`要素@(id,elm_htmlfile)

Acerola3Dファイルには、このファイルを紹介するためのHTMLファイルを
含めることができるものとします。そして、`<htmlfile>`要素は
そのHTMLファイルを指定するための要素です。空要素でsrc属性に
HTMLファイルを指定します。HTMLファイルがフォルダの中に保存されている
場合は、そのフォルダ名から記述するものとします。

### `<a>`要素@(id,elm_a)

このAcerola3Dファイルに含まれるアクションを指定するための要素
です。複数の`<a>`要素を含めることが可能で、この複数の`<a>`要素の
順番どうりに自動的に0からのアクション番号が付けられます。
`<a>`要素には以下の要素を以下の順番で含めることが可能です。

* [`<p>`要素](#elm_p) 0`<=`出現回数`<=`無制限
* [`<s>`要素](#elm_s) 0`<=`出現回数`<=`1

`<a>`要素に設定できる属性は以下のとうりです。

* an: このアクションのアクション名を文字列で指定します。
  他のアクション名とだぶらないようにして下さい。必須の属性です。
* bvh: BVHファイルを指定します。BVHファイルがフォルダの
  中などに保存されている場合はそのフォルダ名から指定して
  下さい。また、BVHファイルが必要無い場合は文字列として"none"を
  指定するか、この属性自体を省略すると動きの無いアクション
  や効果音だけが有効なアクションを作れます。
  ということで"none"という名前は予約語としておいて
  BVHのファイル名には"none"という名前は使用しないで下さい。
* loop: BVHファイルに保存されたモーションが終了した時に
  繰り返し再生するかどうかを指定します。デフォルト値はfalse
  です。
* scale: このアクションで指定される3Dオブジェクト全体を
  スケーリングします。デフォルト値は1.0です。
* offset: このアクションで指定される3Dオブジェクト全体を
  平行移動します。中心の位置あわせなどに使用することができます。
  値は三次元座標です。デフォルトは"0.0 0.0 0.0"です。
* rot: このアクションで指定される3Dオブジェクト全体を
  回転します。X,Y,Zのそれぞれの軸に対する回転を指定します。
  回転の順番はZ,X,Yの順で適用されます。(2010,01/18：順番を変更しました)
  単位は度(1回転360度)です。デフォルトは"0.0 0.0 0.0"です。
* rightBalloonOffset: 3Dオブジェクトの右にふきだしを出す場合、
  その吹き出しの位置を指定します。値は二次元座標で、デフォルトは
  "0.0 0.0"です。
* leftBalloonOffset: 3Dオブジェクトの左にふきだしを出す場合、
  その吹き出しの位置を指定します。値は二次元座標で、デフォルトは
  "0.0 0.0"です。
* topBalloonOffset: 3Dオブジェクトの上にふきだしを出す場合、
  その吹き出しの位置を指定します。値は二次元座標で、デフォルトは
  "0.0 0.0"です。
* bottomBalloonOffset: 3Dオブジェクトの下にふきだしを出す場合、
  その吹き出しの位置を指定します。値は二次元座標で、デフォルトは
  "0.0 0.0"です。
* labelOffset: 3Dオブジェクトにラベルを表示する場合、
  そのラベルの位置を指定します。値は二次元座標で、デフォルトは
  "0.0 0.0"です。
* segno: loop属性がtrueの時に意味を持つ設定で2回目以降の
  繰り返しでは最初まで戻らずに，この属性で指定した秒数まで
  戻って繰り返すように再生される．値は実数，単位は秒で
  デフォルト値は0.0です．(楽譜のセーニョマークと似た働き)
* dalsegno: loop属性がtrueの時に意味を持つ設定で，この属性で
  指定された秒数以降の動作は，アクションが打ち切られる最後の
  時にしか再生されない．値は実数，単位は秒でデフォルト値は
  -1.0です．(デフォルト値に深い意味はありません．)
  (楽譜のダルセーニョマークと似た働き)

scale,offset,rotの座標変換はscale,rot,offsetの順番で適用される
ものとします．

### `<p>`要素@(id,elm_p)

BVHファイルの中で記述されている一つ一つのBone(骨)と
3次元形状が保存されているVRMLファイルとの関係を記述
するための要素です。BVHで記述されている全てのBoneに
対してこの要素を指定する必要はありません。
これは空要素で以下の属性が指定できます。

* name: BVHファイル内で記述されているBoneの名前を指定します。
  もし、ここで指定されたBoneがBVHファイルで定義されていない
  場合や、そもそもBVHファイルを指定していない場合はモーションの
  無い物と見做します。必須の属性です。
* wrl: 上のBoneに対応付けるVRMLのファイルを指定します。フォルダ
  の中にファイルが保存されている場合にはフォルダ名から記述します。
  必須の属性です。
* scale: VRMLに保存されている3Dオブジェクトに対してスケーリングを
  設定します。使用するVRMLが大きすぎたり小さすぎる時などに使用します。
  デフォルト値は1.0です。
* offset: VRMLに保存されている3Dオブジェクトに対して平行移動を適用
  します。オブジェクトの位置あわせなどで使用して下さい。デフォルト値は
  "0.0 0.0 0.0"です。
* rot: VRMLに保存されている3Dオブジェクトに対して回転変換を適用します。
  X,Y,Z軸のそれぞれに対する回転角度を指定します。回転の順番は
  Z,Y,Xの順で適用されます。(2010,01/18：順番を変更しました)
  単位は度(1回転360度)で、デフォルト値は"0.0 0.0 0.0"です。

scale,offset,rotの座標変換はscale,rot,offsetの順番で適用される
ものとします．

### `<s>`要素@(id,elm_s)

アクションの中に配置して、アクションに効果音を設定
するための要素です。これは空要素で以下の属性が指定可能です。

* file: 音声ファイルを指定します。音声ファイルがフォルダの中に
  入っている場合にはフォルダ名から指定します。ここで指定できる
  音声ファイルの種類はwav,aiff,au,mp3,oggとします。
* type: 音声のタイプを指定します。指定できるタイプはPointSound、
  BackgroundSound、ConeSoundです。
  デフォルトはPointSoundです。
* loop: 音声の再生をループするかどうかの指定です。音声がBVHの
  モーションよりも長い場合は、余った部分はスキップされます。
  デフォルトはfalseです。
* gain: 音声が再生される時の大きさです。デフォルトは1.0です。
* offset: 音声が発生する場所を平行移動します。音声のタイプが
  BackgroundSoudの場合は無視されます。
* direction: 音声のタイプがConeSoundの場合に、その方向を指定します。
  デフォルトは"0.0 0.0 1.0"です。
* continue: アクションが終了した後も音を再生しつづけるかどうかを
  指定します．デフォルトはtrueです．

VRML97ファイルとその参照ファイル
----------------------------------------

VRMLファイルは通常のVRML97(VRML2.0)フォーマットのファイルですが、
音声やアニメーション、視点移動の機能は使用しないものとします。
しかし、SpotLightや,PointLight,DirectionalLight,Background,
そしてFogは利用できるものとします。
VRMLファイルからテクスチャ画像などを参照している場合にはそれらの
ファイルも一緒にAcerola3Dファイルの中に含めて下さい。

BVH(BioVision Hierarchy)ファイル
----------------------------------------

モーションキャプチャデータの保存のためのフォーマットである
BVH(BioVision Hierarchy)を採用しています。通常のものであれば、
そのまま使用することが可能です。

通常のBVHファイルはBoneの階層構造と各Boneのフレームごとの
位置と回転が記録されたものですが、Acerola3Dではこれにスケール
の情報を加えたBVHファイルも利用できるものとします。これは
Acerola3Dプロジェクトだけで利用されるフォーマットでCHANNELSの
指定にXscale,Yscale,Zscaleを加えて、これに対応付けて各フレーム
ごとのBoneの拡大縮小率を追加したデータになります。

この拡張されたBVHを作成するには、このプロジェクトのサブプロジェクト
であるBriskSkeletonsで公開されるblender用のPythonスクリプトが利用
できます．

CATALOG.XMLから参照される音声ファイル
----------------------------------------

CATALOG.XML内では，それぞれのアクションに対応付けて
再生される効果音を指定することができますが，これを指定
した場合には，かならずその効果音のファイルを含める
必要があります．対応フォーマットはwav,aiff,au,mp3,oggです。

再利用性を高めるための仕様
----------------------------------------

* 長さの単位はメートル
* 座標系はY軸が上，X軸が右．Z軸が手前となる座標系を採用
* キャラクタは原点を地面として作成
* キャラクタはZ軸の正の方向を正面とする
* サムネール画像はPNGかJPEGかGIFのどれかとすし，適当なサイズにする
* 音声ファイルはwav,aiff,au,mp3,oggのどれかとする．
* メタ情報はなるべく付ける

さらに，Acerola3Dで作成された3Dオブジェクトの用途を
明確化して，その条件を規定することにより再利用性を
高める工夫をプロファイルとして規定してゆきたいと思て
います．このプロファイルについては別の文章で規定して
ゆきます．

* <http://acerola3d.sourceforge.jp/docs/format/profile/>

