CGeo (version 7)

Overview

CGeo is an extensible file format for storing mesh data. It can be used to implement proxies or to communicate data between applications that support the Corona renderer.

A CGeo file consists of two main chunks, namely the header and the data. All binary data is little-endian.

In the documentation that follows, it is important to distinguish between an animation sample and an animation snapshot. The object stored within a CGeo file is represented as a series of animation snapshots, and a single snapshot consists of one or more animation samples. Samples represent subsamples between snapshots and can be used to store motion blur data.

General Layout

Header

Let's start with a sample:

<code data-v-c2b1f83f=""><span data-v-c2b1f83f="" class="line">Corona Renderer CGeo file.</span><span data-v-c2b1f83f="" class="line">This file contains an animated Mesh object.</span><span data-v-c2b1f83f="" class="line">This file is BINARY.</span><span data-v-c2b1f83f="" class="line">Version: 4</span><span data-v-c2b1f83f="" class="line">Date created: 2016-01-05/14:10:17</span><span data-v-c2b1f83f="" class="line">Number of faces: 12</span><span data-v-c2b1f83f="" class="line">Number of vertices: 8</span><span data-v-c2b1f83f="" class="line">Number of mapping channels: 2</span><span data-v-c2b1f83f="" class="line">Number of normals: 24</span><span data-v-c2b1f83f="" class="line">Bounding box size (original units) : 21.0804 26.3839 33.2031</span><span data-v-c2b1f83f="" class="line">Bounding box size (millimeters) : 210.804 263.839 332.031</span><span data-v-c2b1f83f="" class="line">Original material name: [none]</span><span data-v-c2b1f83f="" class="line">Original object name: Box001</span><span data-v-c2b1f83f="" class="line">Animation snapshot count: 1</span><span data-v-c2b1f83f="" class="line">Time per animation snapshot [microseconds]: 33333</span><span data-v-c2b1f83f="" class="line">Animation time start: 0</span><span data-v-c2b1f83f="" class="line">Scale: 0.1</span><span data-v-c2b1f83f="" class="line">Compressed: True</span></code>

The header is in plain text, so that it is possible to easily inspect the CGeo file in a text editor. It contains properties describing the data stored in the form:

<code data-v-c2b1f83f=""><span data-v-c2b1f83f="" class="line">PropertyName: PropertyValue</span></code>

Every property shall be on its own line with a line separator being \n. The header can contain an arbitrary number of properties, but there are properties that are mandatory (listed below). Besides properties, the header can contain arbitrary text. It's a good idea to at least state the origin of the file.

List of mandatory properties

Data Section

The data section contains animated mesh snapshots, along with precomputed auxiliary data such as bounding boxes and point clouds. Auxiliary data are usually smaller in memory footprint than the geometry data, which can be useful when displaying a proxy in the viewport of a 3d application, as we don't have to read a large amount of data from the disk. The format is extensible in the way that everything within the animation snapshot store has its own section. The only mandatory section is the one that holds geometry data; everything else can (but shouldn't) be missing and can be computed on the fly if necessary. The idea is that sections can be added in the future without breaking compatibility.

Tags

Tags are used to identify certain events within the data section. Every tag is a 4-byte integer. Following is the table of currently used tags and the rest of the documentation will be referencing them by their ids.

Layout

The following is the description of the layout of the data section.

Please note that the pair (TAG_ANIMATION_SNAPSHOT_START, TAG_ANIMATION_SNAPSHOT_END) will appear as many times as there are animation snapshots.

Flags

Sections

Every snapshot consists of one or more sections, and the offset stored in the offset table points to the first section! Every section begins with a 4-byte identifier and an 8-byte section size. Sections can be in arbitrary order, and the only required section is the one containing geometrical data (TAG_MESH_DATA). It's still recommended to store all documented sections within every animation snapshot. The following is the documentation of all currently supported sections.

Mesh Data - TAG_MESH_DATA

This section holds the geometry data and is the only one required. The first snapshot is always stored completely (including topology). Every subsequent snapshot that has the same topology as the first one is stored as the difference from the first; better compression is expected in such a case. The whole section is compressed.

The following is a description of the section's content when the snapshot is fully stored.

The following table describes how a single triangle is stored in CGEO version 7 and newer (Corona v2 and newer).

The following is a description of the section's content when the snapshot is stored as the difference from the first.

Bounding Box - TAG_BOUNDING_BOX

Compressed 6 IEEE754 single-precision floating-point numbers describing the bounding box of the snapshot. The order is: MinX, MinY, MinZ, MaxX, MaxY, MaxZ.

Point Cloud - TAG_POINTCLOUD

This section contains the point cloud that can be used to visualize the animation snapshot in the viewport. The whole section is compressed and contains the following: