Table of Contents

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


Byte IndexByte CountContent Description
01The binary magic number indicating cgeo file 0x43
14The size of the header H that follows represented as a binary 4 byte integer
5HThe header itself in human readable form (see the following description)
5 + HDetermined by the headerThe data section

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


NameDescription
“Version”Currently 7 for Corona v2
“Animation snapshot count”The number of animation snapshots stored in the data section
“Time per animation snapshot [microseconds]”As the name suggests
“Animation time start”In microseconds. Can be used to place the object correctly on the time line upon loading
“Scale”The scale of the data stored relative to millimeter (e.g. 10 if data are stored in centimeters). 0 if unknown
“Original material name”As the name suggests
“Original object name”As the name suggests
“Compressed”Can be one of {'True', 'False'}. The comparison is done case insensitive. If 'False' is specified then no section of the CGeo file is compressed. In other case sections of all snapshots in data section are compressed (see bellow). This property was added in version 5 and if it is missing then 'True' shall be assumed. If at any point in the documentation something is said to be compressed then it is only if the value of this property is 'True'.

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.

Tag IdTag Value
TAG_ANIMATION_SNAPHOT_START0xA3CDEF00
TAG_ANIMATION_SNAPHOT_END0xFED3BA11
TAG_ANIM_TABLE_START0xFAD0CCA1
TAG_ANIM_TABLE_END0xE580AC23
TAG_BOUNDING_BOX0x2F89A8B5
TAG_MESH_DATA0x35F71EA8
TAG_MESH_VERTICES_END0x42C342CC
TAG_MESH_NORMALS_END0xB00B06B0
TAG_MESH_MAP_COORDS_END0xCAAC04CA
TAG_POINTCLOUD0x1387EBEB

Layout


Following is the description of the layout of the data section.

ItemDescription
FlagsAn uncompressed 4 byte integer described later.
TAG_ANIM_TABLE_START
Offset TableUncompressed offset table. There is an entry for every animation snapshot and every entry is the 8 byte offset from the beginning of the file to the beginning of the snapshot's data
TAG_ANIM_TABLE_END
TAG_ANIMATION_SNAPSHOT_STARTTag indicating the beginning of an animation snapshot.
SectionsIndividual sections containing the data for the snapshot. Described later.
TAG_ANIMATION_SNAPSHOT_ENDTag indicating the end of an animation snapshot.


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

Flags


BitNameDescription
1Changing TopologyFlag indicates that every animation snapshot is stored compressed on it's own as the topology can change from snapshot to snapshot. In case this flag is not specified then it's expected that only the first snapshot contains topological information and all subsequent snapshots are only stored as compressed differences of positions, normals and texcoords from the first snapshot.

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.

ItemDescription
0x11 byte of value 0x1 indicating that this is a complete snapshot
Vertex Count4 byte integer
Normal Count4 byte integer
Map Channel Count4 byte integer indicating the number of mapping channels
Triangle Count4 byte integer
VerticesEvery vertex is represented by 3 IEEE754 single precision floating point numbers corresponding to X,Y,Z
TAG_MESH_VERTICES_END
NormalsEvery normal is represented by 3 IEEE754 single precision floating point numbers corresponding to X,Y,Z
TAG_MESH_NORMALS_END
Texture CoordinatesData for all mapping channels. The number of mapping channels is idicated by Map Coord Count. Every mapping channel data are given as 4 byte integer storing the number of texture coordinates followed by the coordinates itself. Each coordinate is represented by 3 IEEE754 single precision floating point numbers corresponding to U,V,W.
TAG_MESH_MAP_COORDS_END
Triangle DataDescribed bellow.


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

ItemDescription
Vertex Indices3 vertex indices. Every index is represented as a 4 byte integer.
Normal Indices3 normal indices. Every index is represented as a 4 byte integer.
Map Coordinates Indices3 indices are stored for each mapping channel and every index is represented as 4 byte integer.
Material ID2 byte material id.
Edge Visibility1 byte bitset. Bits 0, 1, 2 represents edges AB, BC, CA. When the corresponding bit for an edge is set the edge is visible.


Following is the decription of the section's content when the snapshot is stored as the difference from the first.

ItemDescription
0x01 byte of value 0x0 indicating that this is a difference from the first snapshot
Vertex DifferencesEvery difference is represented by 3 IEEE754 single precision floating point numbers corresponding to X,Y,Z
TAG_MESH_VERTICES_END
Normal DifferencesEvery difference is represented by 3 IEEE754 single precision floating point numbers corresponding to X,Y,Z
TAG_MESH_NORMALS_END
Texture Coordinate DifferencesEvery difference is represented by 3 IEEE754 single precision floating point numbers corresponding to U,V,W. The differences for all map channels are stored subsequently. The number of differences for each channel are given by the first snapshot which is stored completely.
TAG_MESH_MAP_COORDS_END

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:

ItemDescription
Point Count8 byte unsigned integer telling the number of points that follow.
PointsEvery point is represented by 3 IEEE754 single precision floating point numbers corresponding to X,Y,Z coordinates in that order.
Was this helpful?