Binary Mesh File Format - appleseedhq/appleseed GitHub Wiki
Introduction
The purpose of the BinaryMesh file format is to store tessellated 3D surfaces in a compact and efficient-to-read form.
Binary Mesh files conventionally use the .binarymesh file extension.
File Layout
Conventions
- All offsets are zero-based (the first byte of the file is at offset 0).
- All offsets and lengths are expressed in bytes.
- All multi-byte fields are using the little-endian (Intel) convention.
High-Level Structure
| Field Length | Field Type | Description |
|---|---|---|
| 10 | string | File signature. Must be equal to BINARYMESH (in capitals) for the file to be considered valid. |
| 2 | uint16 | File format version |
| variable | composite | Data block (see below) |
The format of the data block depends on the value of the file format version field.
Data Block Format Version 1
| Field Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Length of object #1's name |
| variable | string | Name of object #1 |
| 4 | uint32 | Number of vertices |
| 8 | double | X coordinate of vertex #1 |
| 8 | double | Y coordinate of vertex #1 |
| 8 | double | Z coordinate of vertex #1 |
| 8 | double | X coordinate of vertex #2 |
| ... | ||
| 4 | uint32 | Number of vertex normals |
| 8 | double | X coordinate of normal #1 |
| 8 | double | Y coordinate of normal #1 |
| 8 | double | Z coordinate of normal #1 |
| 8 | double | X coordinate of normal #2 |
| ... | ||
| 4 | uint32 | Number of texture coordinates |
| 8 | double | U coordinate of texcoord #1 |
| 8 | double | V coordinate of texcoord #1 |
| 8 | double | U coordinate of texcoord #2 |
| ... | ||
| 2 | uint16 | Number of material slots |
| 2 | uint16 | Length of material slot #1's name |
| variable | string | Name of material slot #1 |
| 2 | uint16 | Length of material slot #2's name |
| variable | string | Name of material slot #2 |
| ... | ||
| 4 | uint32 | Number of faces |
| 2 | uint16 | Number of vertices in face #1 |
| 4 | uint32 | Index of vertex #1 of face #1 |
| 4 | uint32 | Index of normal #1 of face #1 |
| 4 | uint32 | Index of texcoord #1 of face #1 |
| 4 | uint32 | Index of vertex #2 of face #1 |
| 4 | uint32 | Index of normal #2 of face #1 |
| 4 | uint32 | Index of texcoord #2 of face #1 |
| ... | ||
| 2 | uint16 | Index of material of face #1 |
| 2 | uint16 | Number of vertices in face #2 |
| ... |
Data Block Format Version 2
In version 2, the data block has the same format as in version 1 but it is compressed with the LZO library.
The data block is split into multiple sub-blocks that are compressed independently. Each sub-block has the following format:
| Field Length | Field Type | Description |
|---|---|---|
| 8 | uint64 | Length of uncompressed sub-block |
| 8 | uint64 | Length of compressed sub-block |
| variable | bytes[] | Compressed sub-block |
Note: Version 2 of the BinaryMesh file format is deprecated: no new files should be written using this format.
Data Block Format Version 3
In version 3, the data block has the same format as in version 1 but it is compressed with the LZ4 library.
The data block is split into multiple sub-blocks that are compressed independently. Each sub-block has the following format:
| Field Length | Field Type | Description |
|---|---|---|
| 8 | uint64 | Length of uncompressed sub-block |
| 8 | uint64 | Length of compressed sub-block |
| variable | bytes[] | Compressed sub-block |
Data Block Format Version 4
In version 4, vertices and normals are written in single precision instead of double precision. The data block, compressed with LZ4, has the following format:
| Field Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Length of object #1's name |
| variable | string | Name of object #1 |
| 4 | uint32 | Number of vertices |
| 4 | float | X coordinate of vertex #1 |
| 4 | float | Y coordinate of vertex #1 |
| 4 | float | Z coordinate of vertex #1 |
| 4 | float | X coordinate of vertex #2 |
| ... | ||
| 4 | uint32 | Number of vertex normals |
| 4 | float | X coordinate of normal #1 |
| 4 | float | Y coordinate of normal #1 |
| 4 | float | Z coordinate of normal #1 |
| 4 | float | X coordinate of normal #2 |
| ... | ||
| 4 | uint32 | Number of texture coordinates |
| 4 | float | U coordinate of texcoord #1 |
| 4 | float | V coordinate of texcoord #1 |
| 4 | float | U coordinate of texcoord #2 |
| ... | ||
| 2 | uint16 | Number of material slots |
| 2 | uint16 | Length of material slot #1's name |
| variable | string | Name of material slot #1 |
| 2 | uint16 | Length of material slot #2's name |
| variable | string | Name of material slot #2 |
| ... | ||
| 4 | uint32 | Number of faces |
| 2 | uint16 | Number of vertices in face #1 |
| 4 | uint32 | Index of vertex #1 of face #1 |
| 4 | uint32 | Index of normal #1 of face #1 |
| 4 | uint32 | Index of texcoord #1 of face #1 |
| 4 | uint32 | Index of vertex #2 of face #1 |
| 4 | uint32 | Index of normal #2 of face #1 |
| 4 | uint32 | Index of texcoord #2 of face #1 |
| ... | ||
| 2 | uint16 | Index of material of face #1 |
| 2 | uint16 | Number of vertices in face #2 |
| ... |