Alembic Ogawa container

Ogawa is the storage layer under every Alembic file written since Alembic 1.5. It knows nothing about geometry: it stores a tree of groups, whose leaves are blocks of bytes. The Alembic project documents it on its wiki, and its source is open. How Alembic arranges objects and properties inside the tree is on Archive, objects and properties. All numbers are little-endian.

File header

Offset	Size	Type	Name	Description
0	5	char[5]	magic	`Ogawa` (`4F 67 61 77 61`)
5	1	u8	frozen	`00` while the file is being written, `FF` once the Ogawa library has closed it properly
6	2	u8[2]	version	`00 01`: version 1, the only one
8	8	u64	root	the offset of the root group

A frozen byte of 00 means the writer did not finish, for example because the program stopped: the file is incomplete. The root offset is filled in when the file is closed, and the root group usually sits near the end.

00000000  4F 67 61 77 61 FF 00 01 F8 31 00 00 00 00 00 00

The header of a finished file whose root group is at offset 12,792 (0x31F8)

Groups

A group is a list of references to its children, each of which is another group or a data block.

Offset	Size	Type	Name	Description
0	8	u64	count	the number of children
8	8 × count	u64[]	children	one reference per child, in order

An empty group is written as eight zero bytes, a count of 0, and a reference to an empty group is simply 0.

Child references

Bits	Meaning
63	0: the child is a group; 1: the child is a data block
0–62	the offset of the child from the start of the file

A data reference with offset 0 (0x8000000000000000) is an empty data block of size 0, which is not stored. Two references can point at the same offset: Alembic uses this to store a repeated sample only once.

Data blocks

Offset	Size	Type	Name	Description
0	8	u64	size	the number of bytes that follow
8	size	bytes	data	the contents, which Ogawa does not interpret

Ogawa adds no padding or alignment between blocks.

Worked example

02 00 00 00 00 00 00 00 10 00 00 00 00 00 00 80
00 00 00 00 00 00 00 00

A group with two children: a data block at offset 16, and an empty group

00000010  04 00 00 00 00 00 00 00 D5 29 00 00

The data block at offset 16: a size of 4, then the 32-bit number 10,709, which is how Alembic 1.7.9 writes its library version

HDF5 files

Before Ogawa, Alembic stored the same tree in HDF5, a general scientific container, and such files start with the HDF5 signature 89 48 44 46 0D 0A 1A 0A. Alembic can still read them. Their layout is HDF5’s and is not described on this site’s Alembic pages.