Metasequoia file format specification

Feb 2014
Text by tetraface Inc.

This document is based on the specification of Metasequoia from Ver1.0 to 4.1.

This file format may be changed without a compatibility in the future.

There is a sample for loading .mqo files in the plug-in SDK. Please refer it.

Common rules
  • The return code is 0x0D0x0A; Windows standard.
  • Chunk names are not case-sensitive in principle.
  • A string is enclosed in "".
  • A chunk and data in a line are usually delimited by a space or a tab, and some symbol characters like as parentheses are used as delimiters.
  • A byte order for binary data is an Intel format.
  • A floating point value in binary data is IEEE standard format.

A chunk is a group of data, and it has a specified string in a head or an end of a line. The following rule are defined.
  • When a chunk spans multiple line, '{' is written at the end of the first line. And the chunk finishes at the line that has '}' at the head of the line.
  • A chunk may contain child chunks hierarchically.
  • A chunk with binary data has [Data size] at the end of the line. Subsequently, binary data is written.

MQO Objects (Document)
MQM Materials
MQP Palettes for a painting
MQB Brushes for a painting

MQO objects (document) file
A header and root chunks like as Scene, Material, Object, Blob and so on are in a .mqo file.

There is the following header at the head two lines in a file.
Metasequoia Document
Format %s Ver %.1f
Format %s Format [Text] Text
[Compress] Compression (Not support in the current version)
Ver %.1f Version [1.0] Not support a polygon with 5 or more points. Always 4 or lesser points.
[1.1] Support polygons with 5 or more points. (Ver4.0 or later)
A loading must be interrupted if the format or the version is not recognized. But, the difference of a minor version may cause no problem if the parser interprets a chunk hierarchy correctly.
'TrialNoise' chunk
This chunk is recorded when the license is not authenticated in Ver1.0. If this chunk is detected, a loading must be interrupted immediately.
This chunk has been obsoleted in Ver2.0 or later.
'IncludeXml' chunk
This chunk is for plug-in own information, and represented like as the following. No information is written by plug-ins, this chunk is not written.
IncludeXml "%s"
InlcudeXml %s Filename An extension for an external xml file is .mqx.
'Scene' chunk
 This chunk contains a viewport and so on. Details omitted.
'BackImage' chunk (Ver2.0 or later)
 This chunk contains a background image. Details omitted.
'Material' chunk

This chunk begins like as the following:
Material %d {
%d A number of materials

There is material data in each line in this chunk. Parameters after a name can be omitted if unnecessary.
%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 Name 31 bytes or lesser
shader(%d) Shader [0] Classic
[1] Constant
[2] Lambert
[3] Phong
[4] Blinn
vcol(%d) Vertex color [0] None
[1] Diffuse
dbls(%d) Double sided face [0] Single sided face
[1] Double sided face
col(%.3f %.3f %.3f %.3f) RGB color and opacity (Each) 0 to 1
dif(%.3f) Diffuse 0 to 1
amb(%.3f) Ambient 0 to 1
emi(%.3f) Emission 0 to 1
spc(%.3f) Specular 0 to 1
power(%.2f) Power of specular 0 to 100
reflect(%.3f) Reflection (Ver4.0 or later) 0 to 1
refract(%.3f) Refraction (Ver4.0 or later) 1 to 5
tex(%s) Texture mapping A relative path or an absolute path
aplane(%s) Alpha mapping A relative path or an absolute path
bump(%s) Bump mapping A relative path or an absolute path
proj_type(%d) Projection method for a mapping [0] UV
[1] Flat
[2] Cylindrical
[3] Spherical
proj_pos(%.3f %.3f %.3f) Projection position (XYZ)
proj_scale(%.3f %.3f %.3f) Projection scaling (XYZ)
proj_angle(%.3f %.3f %.3f) Projection angle (HPB) -180 to 180

A chunk for material will be changed to 'Material2' chunk, and 'Material' chunk will become obsolete. A definition of the 'Material2' chunk is not determined yet.
'Object' chunk

This chunk begins like as the following:
Object %s {
%s An object name 63 bytes or lesser

There are the following chunks in this chunk, and they can be omit if unnecessary.
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 Unique ID An unique ID used by plug-ins. Automatically assigned if not specified.
depth %d Depth for a hierarchy 0 is under root, and increment depending on the depth
folding %d A folding of a hierarchy in Object Panel [0] Normal
[1] Collapsed
scale %.6f %.6f %.6f Scaling factor for a local coordinate XYZ
rotation %.6f %.6f %.6f Angle for a local coordinate HPB
translation %.6f %.6f %.6f Translation for a a local coordinate XYZ
patch %d Patch type [0] None
[1] Spline type 1
[2] Spline type 2
[3] Catmull-Clark (Ver2.2 or later)
[4] OpenSubdiv (Ver4.0 or later)
patchtri %d Division of triangles for Catmull-Clark [0] Divide into quadrangles
[1] Reserve triangles
segment %d Division number of a patch 1 to 16
(1 to 4 for Catmull-Clark/OpenSubdiv)
visible %d Visibility [0] Invisible
[15] Visible
locking Lock [0] Editable
[1] Locked
shading %d Shading [0] Flat shading
[1] Gouraud shading
facet %.1f Smoothing angle 0 to 180
color %.3f %.3f %.3f Color (RGB) (Each) 0 to 1
color_type %d Color type for lines [0] Use a color in a configuration
[1] Use the object's unique color
mirror %d Mirroring type [0] None
[1] Separated
[2] Joined
mirror_axis %d Mirroring axis [1] X axis
[2] Y axis
[4] Z axis
mirror_dis %.3f Distance for a mirroring 0 to
lathe %d Lathe type [0] None
[3] Double sided
lathe_axis %d Lathe axis [0] X axis
[1] Y axis
[2] Z axis
lathe_seg %d Division number for a lathe 3 to
vertex %d 'vertex' chunk (Vertices) A number of vertices
BVertex %d 'BVertex' chunk (Binary vertices) A number of vertices
face %d 'face' chunk (Faces) A number of faces

'vertex' chunk
There is the following vertex data in each line in the chunk.
%.4f %.4f %.4f
%.4f %.4f %.4f A position (XYZ)

vertex {
  0.5000 1.0000 10.0000
  -2.0000 -20.0000 45.5000
'vertexattr' chunk (Ver2.2 or later)
This chunk contains attributes for each vertex. There are the following child chunks:
'uid' chunk (Ver3.1 or later)
An unique ID for each vertex. There are same number of IDs as the vertices.
%d An unique ID

uid {
'weit' chunk
This chunk contains a weight factor for a patch. 0 is set for a weight if this chunk is omitted.
%d An index of a vertex
%.3f A weight value

weit {
  0 1.000
  2 0.621
  7 0.121
'color' chunk
This chunk contains a vertex color for a vertex.
It has been substantially obsoleted because a vertex color is assigned to a corner vertex in a face in Ver2.3 or later.
%d %u
%d An index of a vertex
%u Vertex color
A color is composed by the following mask:
[0x000000FF] Red
[0x0000FF00] Green
[0x00FF0000] Blue
[0xFF000000] Opacity

color {
  0 4278255360
  2 4278190335
'BVertex' chunk
This chunk contains vertices as binary data, and there are following child chunks:
Vector %d [%d]
Vector %d [%d] A number of vertex
Data size

'Vector' chunk
3 float values represent the XYZ position for a vertex, and there are values for all vertices. The data size is (12 times the vertices) bytes.

'weit' chunk (Ver2.0 or later)
A value represents a weight factor for a patch. The content is same as the 'vertexattr' chunk.
'color' chunk (Ver2.0 or later)
A value represents a vertex color. The content is same as the 'vertexattr' chunk.

'BVertex' chunk is used as a standard chunk for vertices in from Ver1.0 to Ver2.1, and 'vertex' chunk is standard now. However, you can use 'BVertex' chunk in Ver2.2 or later by describing "MQOFormat=1" in the System category in the setting file.

'face' chunk
This chunk contains face data in each line.
%d V(%d ...) M(%d) UV(%.5f %.5f ...) COL(%u ...) CRS(%f ...)
%d A number of vertices 2 or larger value
(Always 4 or lesser in Format Version 1.0.)
V(%d ...) Vertex indices
(Same number of vertices)
0 to (# of vertices)-1
M(%d) A material index -1 (non-material face), or from 0 to (# of materials)-1
UV(%.5f %.5f ...) UV coordinate
Twice (# of vertices)
COL(%u ...) Vertex color
(Same number of vertices)
A color is composed by the following mask:
 [0x000000FF] Red
 [0x0000FF00] Green
 [0x00FF0000] Blue
 [0xFF000000] Opacity
CRS(%f ...) Edge crease for Catmull-Clark/OpenSubdiv
(Same number of vertices)
 [0] OFF
 [1] ON
OpenSubdiv: 0 or larger value
'Blob' chunk
This chunk contains a blobby object. Details omitted.

MQM material file
A content in a .mqm file is same as a .mqo file, and only a 'Material' chunk exists.

MQP palette file
Palettes for a painting of mapping images are defined. Details omitted.

MQB brush file
Brushes for a painting of mapping images are defined. Details omitted.