Google publishes the Draco bitstream as a draft specification, Draco Bitstream Specification version 2.2, which describes the decoding of a compressed triangle mesh. These pages follow it. A file has four sections, decoded in order: the header, the optional metadata, the connectivity and the attributes.
Number formats
| Notation | Meaning |
|---|---|
UI8, I8 | Unsigned and signed 8-bit integers |
UI16, I16, UI32, I32, UI64, I64 | Unsigned and signed integers of 16, 32 and 64 bits, little-endian |
Float | IEEE 754 single precision, little-endian |
varUI32, varUI64 | Unsigned integers in LEB128 form (see below), up to 232 − 1 and 264 − 1 |
f[n] | An unsigned n-bit number read from a bit stream, most significant bit first. When a run of bit reading ends, reading continues at the next whole byte |
LEB128 stores a number seven bits at a time, lowest bits first. Each byte holds seven
bits of the value in its low bits, and its top bit is 1 when another byte follows.
So 300 is AC 02, and 0x10000000 takes five bytes.
Header
| Offset | Size | Type | Name | Meaning |
|---|---|---|---|---|
| 0 | 5 | UI8[5] | draco_string | DRACO (44 52 41 43 4F) |
| 5 | 1 | UI8 | major_version | Bitstream major version |
| 6 | 1 | UI8 | minor_version | Bitstream minor version |
| 7 | 1 | UI8 | encoder_type | What the file holds; see below |
| 8 | 1 | UI8 | encoder_method | How the connectivity is encoded; see below |
| 9 | 2 | UI16 | flags | Bit 15 (0x8000, METADATA_FLAG_MASK): a metadata section follows. No other bit is defined |
| Field | Value | Name | Meaning |
|---|---|---|---|
encoder_type | 0 | POINT_CLOUD | A point cloud: attributes without faces |
| 1 | TRIANGULAR_MESH | A triangle mesh | |
encoder_method (mesh) | 0 | MESH_SEQUENTIAL_ENCODING | Faces stored as lists of vertex numbers |
| 1 | MESH_EDGEBREAKER_ENCODING | Faces encoded by the Edgebreaker traversal | |
encoder_method (point cloud) | 0 | POINT_CLOUD_SEQUENTIAL_ENCODING | Points in order |
| 1 | POINT_CLOUD_KD_TREE_ENCODING | Points encoded through a k-d tree |
The specification covers mesh bitstream version 2.2, the version the Draco library writes for meshes. The library writes point clouds as version 2.3, and the point cloud methods are named in its source but not described in the specification. Earlier versions (1.x, 2.0 and 2.1) differ in places, for example in which counts are fixed-width rather than LEB128; they too are defined only by the library’s source.
00000000 44 52 41 43 4F 02 02 01 01 00 80 DRACO......Metadata
When bit 15 of flags is set, metadata follows the header: first metadata
for individual attributes, then metadata for the whole file.
| Field | Type | Meaning |
|---|---|---|
num_att_metadata | varUI32 | Number of attributes that carry metadata |
| Then, for each of them: | ||
att_metadata_id | varUI32 | The unique id of the attribute it belongs to, which must match an att_dec_unique_id in the attribute section; each id appears once |
| Metadata element | See below | That attribute’s metadata |
| Finally: | ||
| Metadata element | See below | The file’s metadata |
A metadata element is a list of key–value pairs followed by named sub-elements, which nest to any depth:
| Field | Type | Meaning |
|---|---|---|
num_entries | varUI32 | Number of key–value pairs |
| For each entry: | ||
key_size | UI8 | Length of the key |
key | I8[key_size] | The key; keys in one element must be unique |
value_size | UI8 | Length of the value |
value | I8[value_size] | The value, as raw bytes |
| Then: | ||
num_sub_metadata | varUI32 | Number of sub-elements |
| For each sub-element: | ||
sub_metadata_key_size | UI8 | Length of its name |
sub_metadata_key | I8[size] | Its name |
| Metadata element | Recursive | Its contents, in this same form |
Keys and values are byte strings with no stated encoding; the library stores strings, integers and floats in them, and a reader needs to know by the key what a value holds.