Metasequoia ファイルフォーマット

Apr, 2019
Text by tetraface Inc.

　このドキュメントはMetasequoia Ver1.0～4.7の仕様に基づいています。

注意
　このファイルフォーマットは将来互換性を維持できない形で仕様変更される可能性があります。
　MQOフォーマットはMetasequoia内で使用することを前提としており、中間フォーマットとして他のソフトで読み込むことは考慮されていません。MQO入力プログラムを作るよりも、Metasequoia上で出力プラグインを作ってMQO以外の形式に出力することが推奨されます。
　プラグインSDKにはMQOを読み込むサンプルが入っていますので、そちらもご参照下さい。

共通事項
  • 名前・ファイル名等に使用される文字コードはCodePageチャンクで定義されるが、定義がない場合はファイル出力時のシステムロケールに依存する。
  • 改行コードはWindows標準の0x0D0x0A
  • チャンク名は原則として大文字と小文字を区別しない
  • 一つの文字列は全体を""でくくる
  • 一行内のチャンクやデータは、通常スペースまたはタブで区切るが、カッコなど記号文字の中にも区切り文字として扱われるものがある
  • バイナリデータのバイトオーダーはIntel形式である
  • バイナリデータの浮動小数点データはIEEE標準形式である

チャンク
　チャンクとは、ひとまとまりのデータ群であり、行の先頭または末端に特定の文字列をもったものを指す。以下のルールがある。
  • チャンクが複数行にまたがる場合、先頭行の最後は { で終わっている。その後、行の先頭に } があると、チャンクを終了する。
  • チャンク内に、階層的にチャンクが存在することがある。
  • バイナリデータを持つチャンクの場合、行の最後は [データサイズ] で終わる。その後、バイナリデータがサイズ分だけ続く。

拡張子
MQO オブジェクト（ドキュメント）
MQX プラグイン用データの格納xmlファイル
MQOZ MQO,MQXファイルおよびサムネイル等の付随ファイルをzip圧縮した書庫ファイル
MQM 材質
MQP 画像ペイントのパレット
MQB 画像ペイントの模様ブラシ

MQO オブジェクト（ドキュメント）ファイル
　MQOファイル内は、ヘッダ、Scene、Material、Object、Blobなどの親チャンクで構成される。
ヘッダ

　ファイルの先頭の２行には以下のヘッダを持つ。 
Metasequoia Document
Format %s Ver %.1f
Format %s 形式 [Text] テキスト
[Compress] 圧縮（現バージョンでは非サポート）
Ver %.1f バージョン [1.0] 多角形をサポートせず4角以下
[1.1] 5角以上の多角形をサポート (Ver4.0以降）
[1.2] utf-8文字コードをサポート (Ver4.7以降）
　形式またはメジャーバージョンが認識できない場合は、ファイルの読込を中止すべきである。マイナーバージョンは、チャンク構造を正しく解釈できるなら無視してもおそらく問題ない。
CodePageチャンク （Ver4.7以降）
名前・ファイル名などに使用される文字コードを定義し、以下のように記述する。 
CodePage %s
CodePage %s 文字コード [utf8] UTF-8
[(数値)] Windowsコードページ（例:[932] 日本語Shift-JIS、[1252] 西ヨーロッパ言語）
TrialNoiseチャンク
　Ver1.0でユーザー登録を行わない状態で保存したMQOファイルの先頭の方に記録される。このチャンクを検出したら、直ちに読み込みを中止すること。読み込みを継続してもおかしなデータしか得られない。詳細は非公開。
　Ver2.0以降ではこのチャンクは廃止されている。
IncludeXmlチャンク
　プラグイン独自の情報を保存するために、以下のようにXMLファイル名を記述する。プラグインから情報が出力されない場合は、このチャンクも出力されない。 
IncludeXml "%s"
InlcudeXml %s ファイル名 外部XMLファイルの拡張子は.mqx
Thumbnailチャンク （Ver4.2以降）
　サムネイル画像を格納するチャンク。MQOZファイルでは書庫内に直接画像ファイルが格納されるため使用されない。詳細は省略。
Sceneチャンク
　視点情報などのためのチャンク。詳細は省略。
BackImageチャンク （Ver2.0以降）
　下絵情報などのためのチャンク。詳細は省略。
Materialチャンク

　材質を示すチャンクは、次のように開始する。
Material %d {
%d 材質数

　以下、チャンク内には一行ごとに材質データがある。材質名より後のパラメータは、必要なければ省略することができる。
%s shader(%d) vcol(%d) dbls(%d) col(%.3f %.3f %.3f %.3f) dif(%.3f) amb(%.3f) emi(%.3f) spc(%.3f)
power(%.2f) reflect(%.3f) refract(%.3f) tex(%s) alpha(%s) bump(%s) proj_type(%d) proj_pos(%.3f %.3f %.3f)
proj_scale(%.3f %.3f %.3f) proj_angle(%.3f %.3f %.3f)
%s 材質名 (Ver4.6以前) 31Byte以内
(Ver4.7以降) Wide文字コードで63文字以内
shader(%d) シェーダ [0] Classic
[1] Constant
[2] Lambert
[3] Phong
[4] Blinn
vcol(%d) 頂点カラー [0] なし
[1] あり
dbls(%d) 両面表示 [0] 片面
[1] 両面
col(%.3f %.3f %.3f %.3f) 色（ＲＧＢ）、不透明度 それぞれ0～1
dif(%.3f) 拡散光 0～1
amb(%.3f) 周囲光 0～1
emi(%.3f) 自己照明 0～1
spc(%.3f) 反射光 0～1
power(%.2f) 反射光の強さ 0～100
reflect(%.3f) 鏡面反射 （Ver4.0以降) 0～1
refract(%.3f) 屈折率 （Ver4.0以降) 1～5
tex(%s) 模様マッピング名 相対パスまたは絶対パスで記述
aplane(%s) 透明マッピング名 相対パスまたは絶対パスで記述
bump(%s) 凹凸マッピング名 相対パスまたは絶対パスで記述
proj_type(%d) マッピング方式 [0] UV
[1] 平面
[2] 円筒
[3] 球
proj_pos(%.3f %.3f %.3f) 投影位置（ＸＹＺ）
proj_scale(%.3f %.3f %.3f) 投影拡大率（ＸＹＺ）
proj_angle(%.3f %.3f %.3f) 投影角度（ＨＰＢ） -180～180

　材質用のチャンクは将来Material2チャンクに変更され、Materialチャンクは廃止される可能性がある。Material2チャンクの定義は未定。
Objectチャンク

　オブジェクトを示すチャンクは、次のように開始する。
Object %s {
%s オブジェクト名 (Ver4.6以前) 63Byte以内
(Ver4.7以降) Wide文字コードで63文字以内

　チャンク内には、以下のチャンクが存在する。必要なければ省略することができる。
uid %d
depth %d
folding %d
scale %.6f %.6f %.6f
rotation %.6f %.6f %.6f
translation %.6f %.6f %.6f
patch %d
patchtri %d
segment %d
visible %d
locking %d
shading %d
facet %.1f
color %.3f %.3f %.3f
color_type %d
mirror %d
mirror_axis %d
mirror_dis %.3f
vertex %d {
}
BVertex %d {
}
face %d {
}
uid %d ユニークID プラグインで利用されるユニークID。指定されない場合、自動的に連番が割り当てられる。
depth %d 階層の深さ ルート直下を0として深くなるごとに+1
folding %d オブジェクトパネル上の
階層の折りたたみ		 [0] 通常表示
[1] 子オブジェクトを折りたたんで非表示に
scale %.6f %.6f %.6f ローカル座標の拡大率 XYZ
rotation %.6f %.6f %.6f ローカル座標の回転角 HPB
translation %.6f %.6f %.6f ローカル座標の平行移動量 XYZ
patch %d 曲面の形式 [0] 平面(曲面指定をしない)
[1] 曲面タイプ１ （スプライン Type1）
[2] 曲面タイプ２ （スプライン Type2）
[3] Catmull-Clark （Ver2.2以降）
[4] OpenSubdiv （Ver4.0以降）
patchtri %d Catmull-Clark曲面の三角形面の処理 [0] 四角形に分割
[1] 三角形のまま分割
segment %d 曲面の分割数 1～16
(Catmull-Clark/OpenSubdivの場合、再帰分割数を示すため1～4となる）
visible %d 表示・非表示 [0] 非表示
[15] 表示
locking オブジェクトの固定 [0] 編集可能
[1] 編集禁止
shading %d シェーディング [0] フラットシェーディング
[1] グローシェーディング
facet %.1f スムージング角度 0～180
color %.3f %.3f %.3f 色（ＲＧＢ） それぞれ0～1
color_type %d 辺の色タイプ [0] 環境設定での色を使用
[1] オブジェクト固有の色を使用
mirror %d 鏡面のタイプ [0] なし
[1] 左右を分離
[2] 左右を接続
mirror_axis %d 鏡面の適用軸 [1] X軸
[2] Y軸
[4] Z軸
mirror_dis %.3f 接続距離 0～
lathe %d 回転体のタイプ [0] なし
[3] 両面
lathe_axis %d 回転体の軸 [0] X軸
[1] Y軸
[2] Z軸
lathe_seg %d 回転体の分割数 3～
vertex %d vertexチャンク（頂点群） 頂点数
BVertex %d BVertexチャンク
（バイナリ頂点群）		 頂点数
face %d faceチャンク（面群） 面数

vertexチャンク
　頂点群を示すチャンク内には、一行ごとに以下の頂点データが存在する。
%.4f %.4f %.4f
%.4f %.4f %.4f ＸＹＺ方向の位置

例
vertex {
  0.5000 1.0000 10.0000
  -2.0000 -20.0000 45.5000
}

補足：
　頂点用のチャンクはVer2.2からは"vertex"が標準であるが、どちらも使用することができる。Ver2.0/2.1ではmetaseq.iniの[System]項の "AsciiMQO=1"、Ver2.2からは "MQOFormat=0" とすることでvertexで保存することが出来る。

vertexattrチャンク （Ver2.2以降）
　頂点ごとの属性を記録する。子チャンクとして以下を持つ。
uidチャンク  (Ver3.1以降)
　頂点ごとのユニークID。頂点の個数分のIDが記述される。
%d
%d ユニークID

例
uid {
  1
  2
  4
}
weitチャンク
　頂点ごとの曲面の重み係数を示す。重み係数が割り当てられていない頂点は0.000がセットされることを意味する。
%d %.3f
%d 頂点インデックス
%.3f 重み係数

例
weit {
  0 1.000
  2 0.621
  7 0.121
}
colorチャンク
　頂点カラーを示す。
　Ver2.3以降では頂点カラーは面内頂点として保持するため、実質的に廃止。
%d %u
%d 頂点インデックス
%u 頂点カラー
以下のマスクにより各色要素が決定される
0x000000FF 赤
0x0000FF00 緑
0x00FF0000 青
0xFF000000 不透明度

例
color {
  0 4278255360
  2 4278190335
}


BVertexチャンク
　バイナリデータでの頂点群を示すチャンク内には、現在では以下のチャンクが存在する。
Vector %d [%d]
Vector %d 頂点数
データサイズ

Vectorチャンク
　ＸＹＺの順で３つのfloat型浮動小数点数（32bit）が１頂点となり、それが頂点数分だけ存在する。データサイズは頂点数×12Byteとなる。
　Intel形式の処理系ではデータサイズ分を頂点配列にデータをダイレクトに読み込むことで格納することが可能である。

weitチャンク （Ver2.0以降）
　頂点ごとの曲面の重み係数を示す。内容はvertexattrチャンク内のものと同一。
colorチャンク （Ver2.0以降）
　頂点カラーを示す。内容はvertexattrチャンク内のものと同一。

補足：
　頂点用のチャンクはVer1.0～2.1では"BVertex"チャンクが標準であるが、Ver2.2以降はvertexチャンクが標準である。
Ver2.0/2.1ではmetaseq.iniの[System]項で "AsciiMQO=0"、Ver2.2からは "MQOFormat=1" とすることでBVertexで保存することが出来る。

faceチャンク
　面群を示すチャンク内には、一行ごとに以下の面データが存在する。
%d V(%d ...) M(%d) UV(%.5f %.5f ...) COL(%u ...) CRS(%f ...)
%d 頂点数 2以上の値
フォーマットバージョンが1.0のときは常に4以下
V(%d ...) 頂点インデックス
（頂点数分の数が存在）		 0～頂点数-1
M(%d) 材質インデックス -1（未着色面）または0～材質数-1
UV(%.5f %.5f ...) ＵＶ値
（頂点数×２の数が存在）
COL(%u) 頂点カラー
（頂点数分の数が存在）		 以下のマスクにより各色要素が決定される
 [0x000000FF] 赤
 [0x0000FF00] 緑
 [0x00FF0000] 青
 [0xFF000000] 不透明度
CRS(%f ...) Catmull-Clark/OpenSubdiv曲面用のエッジの折れ目
（頂点数分の数が存在）		 Catmull-Clarkの場合
 [0] OFF
 [1] ON
OpenSubdivの場合0以上の値
Blobチャンク
　メタボール（粘土）用のチャンク。詳細は省略。

MQX プラグイン用データファイル
　プラグイン用のデータをxml形式で格納している。
MQM 材質ファイル
　内容はMQOと同じであり、Materialチャンクのみを持つ。
MQP パレットファイル
　マッピング画像のペイントに用いられるパレットを定義する。詳細は省略。
MQB ブラシファイル
　マッピング画像のペイントに用いられるブラシを定義する。詳細は省略。