Version 1.0, August 2013

The FP3D (FlatPyramid 3D) scene file format is designed to be as easy as possible, while providing exactly the data that typical augmented reality or mobile 3D applications might need from their 3D models. An important design characteristic is that all texture files are directly embedded into the file format.

Basics

FP3D files are binary files written in Little-Endian Byte Order. The data types mentioned in this document refer to the standard C data types. An int is 4 bytes, a short is 2 bytes, char is 1 byte and floatis a 4-byte, IEEE 754 floating-point value. Integer values are written as twos-complement. The character set for strings, if not otherwise mentioned, is UTF8. Strings are written as arrays with a zero-byte-termination. The [] bracket notation denotes an (bounded) array of the type.

The canonical file extension for FP3D is .fp3d

File Structure

A FP3D file is structured as follows:

Size (Bytes) Data type Meaning
4 char[4] ‘FP3D’ magic string
4 int File format version, currently 1
4 int Number of Meshes in the scene
4 int Number of Materials in the scene
4 int Number of Textures in the scene
? Mesh[] Mesh List
? Material[] Material List
? Texture[] Texture List

See the following sections for the format of the meshes, materials and textures.

Meshes

The structure of a Mesh record is:

Size (Bytes) Data type Meaning
4 int Number of vertices
4 int Number of triangles
4 int Index into the global Material List assigning a material to the mesh
? char[] Zero-terminated name of the mesh
? Vertex[] Vertex list
? int[3][] Triangle list, each triangle given by three indices into the Vertex list.

Where a Vertex is:

Size (Bytes) Data type Meaning
12 float[3] 3D-Position of the vertex
12 float[3] Geometric normal of the vertex
12 float[3] Geometric tangent of the vertex
12 float[3] Geometric binormal of the vertex
12 float[2] 2D Texture coordinate

The texture coordinate is undefined iff the mesh doesn’t have a material with a texture assigned. Tangents and binormals need not necessarily be available. If they are not, they are written as (0,0,0), which is linearly dependent on the normal vector and therefore does not span a valid tangent space.

Materials

The structure of a Material record is:

Size (Bytes) Data type Meaning
? char[] Zero-terminated name of the material
12 float[3] Diffuse color, RGB in range [0,1]
12 float[3] Specular color, RGB in range [0,1]
12 float[3] Ambient color, RGB in range [0,1]
12 float[3] Emissive color, RGB in range [0,1]
4 float Specularity (Phong Exponent) – 0 to disable specular lighting
4 float Opacity in range [0,1] where 0 means “fully transparent”
4 int Index of an entry in the global Texture List, or -1 if no texture is assigned

Textures

The structure of a Texture record is:

Size (Bytes) Data type Meaning
4 int Width of the texture
4 int Height of the texture
? unsigned char[4] Array of Width*Height RGBA color values in range [0,255], written in row-order.