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 Corona renderer.

CGeo file consist of two main chunks, namely header and data. All binary data are little-endian.

In the documentation that follows it is important to distinguish between animation sample and animation snapshot. The object stored within a CGeo file is represented as a series of animation snapshots and a single snapshot consist 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:

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

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

PropertyName: PropertyValue

Every property shall be on it's own line with line separator being \n. The header can contain arbitrary number of properties, but there are properties that are mandatory (listed bellow). Beside 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 snaphots itself together with some precomputed auxilary data like bounding boxes and point clouds. Auxilary data are usualy smaller in memory footprint than the geometry data which can be usefull when displaying proxy in the viewport of 3d application as we don't have to read large amount of data from the disk. The format is extensible in the way that everything within the animation snaphot store has it's 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

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 consist of one or more sections and the offset stored in the offset table points to the first section! Every section begins with 4 byte identifier and 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. 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 allways 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 case. The whole section is compressed.

Following is the decription of the section's content when the snapshot is stored completely.

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

Following is the decription 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 following: