File Format Summary

Manual
Licensing

Basics
Intro
Data Order
Tags
Data Section
Version Section
Basic File Structure
Data Section Items  
User Interact Item deprecated
Reset View Item deprecated
Grab Image Item deprecated
Grab Frame Item deprecated 
Data Section Subsections
Image Setup Section - More info not implemented
Movie Setup Section - More info not implemented
Scene Section - More info (over 10 tags)
View Section - More info (over 30 tags)
Example

Basics

Intro

When building a file for this viewer, one thing to keep in mind is the file is read sequentially. So, all "instructions" are carried out in the order that they are specified, and are not looped (or anything else resembling intelligence).

The file format for the viewer is divided into different sections. These sections can have items in them or even other subsections. As an analogy, the format of a viewer file can be compared to that of a directory structure.

Data Order

Different processors have different bit/byte orders, and this causes problems when sharing files across systems. To counter this, all files must start with an unsigned long of value DATA_ORDER_CHECK. The value is defined in cuvtags.h, and the viewer will figure out what byte order to use from how this is written (do not alter the value in any way--just write an unsigned long of that value).

Tags

All sections and items are identified by unsigned chars, known as tags. Besides starting a section with a tag, the section also has to be terminated by another tag. The values of those unsigned char tags are defined in cuvtags.h, which should be included in all file creation programs. (* for programming purposes, an unsigned char by definition is 8 bits = 1 byte =>  with a number range of 0 to 255; the ASCII character set uses only about half the range).

Data Section

Everything within a viewer file is within the Data Section (except data order)--the top-level directory in the analogy. The Data Section is started by the tag called BEGIN_DATA, and is ended by either END_DATA_STAY or END_DATA_EXIT. END_DATA_STAY will close the file, and leave the viewer open for the user, while END_DATA_EXIT will close the viewer when it is reached (useful for batching).

Version Section

Another section that is always in existence is the Version Section. This section allows the viewer to deal with different versions, and it also contains a human-readable string in it so the file format is easy to determine when viewing the file as text. It is started by the BEGIN_VERSION tag, and ended by the END_VERSION tag. The data between the two tags is always VERSION_STRING.

Basic File Structure

Other sections and/or items occur between the end of the version, and the end of the data. This is the space where all the 3D info goes.

Visually, the file should look like:

DATA_ORDER_CHECK

BEGIN_DATA

BEGIN_VERSION
VERSION_STRING
END_VERSION

(Other sections/items)

END_DATA_STAY or END_DATA_EXIT

Data Section Items

User Interact Item (USER_INTERACT tag)

deprecated

This item will pause the reading of the file, and allow for user interaction. This is useful when creating a movie, and the user needs to interactively alter the environment, or just to peek at the scene to make sure your movie is going as planned. It can also be used for a "slide show" to advance to the next part of the file once the user has had enough time to view and manipulate the scene. To let the viewer go back to reading the file, the space bar must be hit by the user.

Reset View Item (RESET_VIEW tag) 

deprecated

This is the same as the 'r' key. It resets all the viewing variables to the defaults (see the interactive reset view command for more info).

Grab Image Item (GRAB_IMAGE tag)

deprecated

This is the same as the 'e' key. The current export options are used to create an image on disk (see the interactive export image command for more info).

Grab Frame Item (GRAB_FRAME tag)

deprecated

This is the same as the 'm' key. The current movie options are used to add a frame to the current movie (see the interactive add a frame to the movie command for more info).

Data Section Subsections

Image Setup Section (BEGIN_IMG_SET and END_IMG_SET tags) 

not implemented

This section is used to set the default image export options. More info

Movie Setup Section (BEGIN_MOV_SET and END_MOV_SET tags)

not implemented

 This section is used to set the default movie options. More info

Scene Section (BEGIN_SCENE and END_SCENE tags)

This section is where all the 3D objects are defined. Over 10 tags defined: More info

View Section (BEGIN_VIEW and END_VIEW tags)

This section is where all the view's properties can be altered. Over 30 tags defined: More info

Example

The following example file creates a blue sphere, radius = 1 at the origin, then goes to preset view 0 and lets the user interact with it. Following that, the image is saved to disk, and a red sphere is saved to the disk using the same environment. The bin palette information corresponding to the lowest and highest values on the palette are written, in units of Celcius. The file is then closed, and the program is instructed to remain open.

BEGIN_DATA

BEGIN_VERSION
VERSION_STRING
END_VERSION

BEGIN_SCENE

SSPHERE
unsigned char = 0x01 (filled)
float [3] = {0.0, 0.0, 0.0} (position)
float = 1.0 (radius)
float [3] = {0.0, 0.0, 1.0} (color)
END_SCENE

BEGIN_VIEW

VPRESET_VIEW
unsigned char = 0x00 (preset view 0)

VBIN_PAL_MIN_MAX
float = 1.31
float = 253.22
VBIN_PAL_TYPE
"Celcius\0"
END_VIEW

USER_INTERACT

GRAB_IMAGE

BEGIN_SCENE

SSPHERE
unsigned char = 0x01 (filled)
float [3] = {0.0, 0.0, 0.0} (position)
float = 1.0 (radius)
float [3] = {1.0, 0.0, 0.0} (color)
END_SCENE

GRAB_IMAGE

END_DATA_STAY