Quick3D Object File


A quick3D object file consists of a header and one to three chunks. The three possible types of chunks are the mesh definitions chunk, the material definitions chunk, and the texture definitions chunk. They are binary files and will always have at least a header and a meshes chunk, but may not have materials or textures chunks. The file format uses the following data types:

char   = 1 byte
bool   = 1 byte                  (0=FALSE or 1=TRUE)
short  = 2 bytes
int    = 4 bytes
long   = 4 bytes
float  = 4 bytes
vertex = 12 bytes                (three float's)
normal = 12 bytes                (three float's)
texUV  = 8 bytes                 (two float's)
pixel  = 3 bytes                 (three unsigned char's)
face   = (4 * X) bytes           (X int's)
string = length of string bytes  (including the '\0')
color  = 12 bytes                (three float's)
matrix = 64 bytes                (16 float's)

X represents the "shape" of the face, or in other words, the number of vertices involved in the particular face.
The header starts the file and has the following 22-byte structure:

HEADER {
   char signature[8];
   char version[2];
   int  numberMeshes;
   int  numberMaterials;
   int  numberTextures;
}

The signature field always contains "quick3Do" and identifies the file as a quick3D Object file. The next two char's contain the version of the quick3D file format used in the file. The current version is "30". Then follows three int's, the first being the number of meshes in the mesh definitions section, next the number of materials in the materials chunk, and finally the number of textures in the textures chunk. In the case where there are no materials and/or no textures, the number will be 0.

Each of the three chunk types also have their own single-byte header:

CHUNK_HEADER {
   char type;
}

The type will be one of 'm', 'c', or 't', signalling a meshes chunk, materials chunk, or textures chunk respectively.
The mesh definitions chunk contains numberMeshes(contained in the file header) mesh definitions following its 1-byte chunk header. The mesh definitions come one after the other and each definition has the following structure:

MESH {
   long   numberVertices;
   vertex vertices[numberVertices];
   long   numberFaces;
   short  faceShapes[numberFaces];
   face   faces[numberFaces]
   int    materialIndices[numberFaces];
   long   numberNormals;
   normal normals[numberNormals];
   long   numberTextureCoordinates;
   texUV  textureCoordinates[numberTextureCoordinates];
   face   textureIndices[numberFaces];
   vertex centerOfMass;
   float  boundingBox[6];
}

If numberTextures from the file header is zero, then there will be no textureCoordinates nor textureIndices.

The materials definitions chunk contains numberMaterials(contained in the file header) material definitions following its 1-byte chunk header. The material definitions come one after the other and each definition has the following structure:

MATERIAL {
   string materialName;
   color  ambientColor;
   color  diffuseColor;
   color  specularColor;
   float  transparency;
}

The texture definitions chunk contains numberTextures(contained in the file header) texture definitions following its 1-byte chunk header. The texture definitions come one after the other and each definition has the following structure:

TEXTURE {
   string textureName;
   int    textureWidth;
   int    textureHeight;
   pixel  texture[textureWidth * textureHeight]
}
Scene File Format (.q3s)

The quick3D scene file is almost identical to the object format except that there is a different value in the signature field, and there is one additional chunk. The additional chunk is the scene chunk and contains data related to a quick3D scene. These are also binary files and will always have at least a header and a scene chunk, but may not have meshes, materials, or textures chunks. The scene file format uses the same data types as the object format.
The header starts the file and has the following 22-byte structure:

HEADER {
   char signature[8];
   char version[2];
   int  numberMeshes;
   int  numberMaterials;
   int  numberTextures;
}

The signature field always contains "quick3Ds" and identifies the file as a quick3D Scene file. The next two char's contain the version of quick3D that wrote the file. The current version is "30". Then follows three int's, the first being the number of meshes in the mesh definitions section, next the number of materials in the materials chunk, and finally the number of textures in the textures chunk. In the case where there are no meshes, materials, and/or no textures, the number will be 0.

Each of the four chunk types also have their own header of the following 1-byte structure (this is just like an object file):

CHUNK_HEADER {
   char type;
}

The type will be one of 'm', 'c', 't', or 's', signalling a meshes chunk, materials chunk, textures chunk, or scene chunk respectively
The mesh, material, and texture definitions chunks in a scene file are exactly the same as in an object file. The scene chunk has the following structure:

SCENE {
   float  position[3];
   matrix transformation;
   float  axis[3];
   float  angle;
   float  eyePosition[3];
   float  eyeRotation[3];
   color  foregroundColor;
   color  backgroundColor;
   bool   usingEyeFilter;
   color  eyeFilterColor;
   float  eyeFilterAmount;
   color  lightColor;
   int    backgroundImageWidth;
   int    backgroundImageHeight;
   string backgroundFilename;
   pixel  backgroundImage[bgWidth * bgHeight];
   float  depthCuing;
   color  depthCueColor;
   float  gamma;
}

The position is the x, y, z in world space. The axis is the vector about which the model is rotated angle degrees about. This is also stored in matrix form in transformation. The eye point's orientation is represented by eyePosition and eyeRotation. Next are the foregroundColor and backgroundColor. Note that any materials specified in the mesh will override the foreground color. usingEyeFilter tells whether an eye filter is in use. The eyeFilterColor is the color of the eye filter, and eyeFilterAmount is its strength (if not used these may be all zero). The color of the light in the scene is stored in lightColor. If there is a background image, backgroundImageWidth and backgroundImageHeight will specify the image dimensions and backgroundImage will specify the pixel data. If backgroundImageWidth and backgroundImageHeight both equal zero, then there is no backgroundImage(the backgroundColor is used). Next, depthCuing specifies the amount of "depth" to be added to the scene (in the range of least to most, 0.0 - 1.0). The depthCueColor is next. The final part of the scene chunk is the gamma value used in the scene.