File_Types

[Home] - [User_Manual] - hosted at openANTz.com

ANTz supports a variety of file types. The internal data structure that generates the scene can be saved and loaded using a combination of data files (ANTZ...csv) and auxiliary content such as texture map images.

---

ANTz Data Files:

[ANTz000x.csv] - the Node State File, stores all node attributes.

[ANTzTag000x.csv] - text tags with 'title' and 'description' associated using record_id

[ANTzCh000x.csv] - channel track data, n tracks with n samples.
[ANTzChMap000x.csv] - maps tracks to node parameters (node channel stored in the ANTz000x.csv)
[ANTzChMeta000x.csv] - track metadata, sample rate, time-stamp, source type, etc...

*ANTzChMeta... is not yet implemented

Planned ANTz Data Files:

[ANTzTableMap000x.csv] - nodes and channels have table_id to map the source file or DB.
[ANTzFormat000x.csv] - combines record_id with table_id to translate an external DB record (non ANTz format)
[antzglobals.csv] - stores global parameters such as background color, transparency mode, etc....
[ANTzLog000x.csv]

CSV formatting:

• DOS-style line-ends (CRLF)
• First record(row) is a header (this helps with import/export to DB).
• Each record must contain the same number of comma-separated fields.
• A (double) quote character in a field must be represented by two double quote characters.
• Fields containing a line-break, double-quote, and/or commas must be quoted.
• Delimiter is comma (,) and double quotes for text strings ("My Text").

*Reading is tolerant to different line endings CRLF(MSW), CR(OSX) and LF(Linux). Writes using CRLF.

For general CSV discussion see the section "Towards standardization" on wikipedia CSV page:
http://en.wikipedia.org/wiki/Comma-separated_values

---

Texture Mapping:

We use the SOIL library which supports a variety of image formats. Currently the file loading routine is relatively crude. It only scans for images named map00001.jpg to map00256.jpg in the folder 'antzmaps\'.

Strangely enough, you can load different image file types including PNG files with alpha transparency (RGBA) but you will need to rename them to map0000x.jpg (this works because SOIL detects the file type regardless of the extension.)

---

!!! Below is copied from the user guide and needs to be merged/updated with information above !!!

---

Section 7: File Types

This section is designed to be an overview of the file types supported by the application. Please see the appendix on information on how CSV files are formatted. The 'Commands' section explains how to Load and Save the CSV files. Texture Maps are loaded at application launch.

The primary file type is the State File, it is used to store and retrieve the entire state of the current scene.

The secondary data file type is the Channels file which allows for data that changes over time, such as audio, EEG, position, etc.... It is used to animate object parameters.

Additionally, various image formats are supported for texture mapping.

File Name Conventions:

State antz000x.CSV
Channels TNG00001.CSV
Event Log log0000x.CSV
Texture Maps map0000x.JPG3DS geo0000x.3DS

*An Event Log file is planned.

*Support for 3DS files to load custom 3D models is planned.

---

7.1 State - .CSV

**image of dataset loaded in from a CSV file.

The antz000x.CSV is a snapshot of the entire scene. It contains all information needed to represent the spatial characteristics of the scene at the specific moment the file is generated. However, some global parameters are not stored in the file, such as window position, Alpha Mode (transparency type), and grid spacing....

The State File also stores velocity rates that result in animation. However, the data that changes over time (per cycle) is stored in the Channels file.

It is possible to merge scenes from multiple files. This can be done by the user at runtime or at launch by passing in multiple file names.

See the 'Commands – State File' section on how to Load and Save files. Also 'Commands – Command Line' on how to load files upon application launch.

See the Appendix for file formatting and parameter descriptions.

---

7.2 Channels - .CSV

The 'antzch000x.CSV' contains time based channel information. The channels can be used to modulate (animate) objects position, scale and color. Each object has up to 3 channels assigned to it. To change the assigned channel use the '<' and '>' keys, applies the currently active axes, ('X' key.)

Channels effect different parameters based on the object type. For root pins the X and Y channels effect the X and Y position and Z effects the color. For children, X is rotation around the parent, Y is scale, and Z is color.

See the 'Command' section on how to Load the Channels file or the appendix on how to format the file.

*Future support to include mapping channels to more parameters.

---

7.3 *Event Log

*Event log records all user commands and other specified triggers.

---

7.4 Texture Map - .JPG, .TGA...

Up to 256 textures can be loaded for use in the scene. The textures are located in a sub-folder of the main application named "maps\". The texture maps need to be sequentially numbered to be properly organized, starting with 'map00001.jpg' on up to 'map00256.jpg'.

By default the grid uses 'map00001.jpg', this can be changed. See the 'Commands - Keyboard - Texture Maps' section for information on how to assign the textures to objects.

Be aware that non-sequential texture names can be used, but there numbers will not correspond to the textureID stored in the CSV State file. (Also they must be named with the ".JPG" extension, but do NOT need to be a JPEG format... A variety of image types can be read in, but they must have the names specified. Yes it's strange to rename a PNG image to 'map00008.jpg', but it will work.)

The textures are automatically loaded at launch and may cause a significant delay if they are numerous and large. Note that the application will appear to not be responding until all textures are loaded (can be minutes.)

The GPU memory determines the total size of the textures loaded. Maximum texture size depends on GPU hardware, however the user does not need to be concerned as the loading routine will down-convert large textures (if required by the hardware.) A typical GPU today will support maximum size of either 1024x1024 or 2048x2048, some support 4096x4096. Power of 2 sizes are also no longer required in most hardware, the texture loader will handle any necessary scaling.

All textures are converted to 8-bits per channel. Both RGB and RGBA with alpha channel is supported.

Readable Image Formats:

BMP - non-1bpp, non-RLE (from stb_image documentation)
PNG - non-interlaced (from stb_image documentation)
JPG - JPEG baseline (from stb_image documentation)
TGA - greyscale or RGB or RGBA or indexed, uncompressed or RLE
DDS - DXT1/2/3/4/5, uncompressed, cubemaps (can't read 3D DDS)
PSD - (from stb_image documentation)
HDR - converted to LDR, unless loaded with *HDR* functions (RGBE or
    RGBdivA or RGBdivA2)

*Future Feature - Allow for selecting a specific texture map with any name and file path. The path will be stored in the CSV Table Map file and/or DB.

*Future Feature – Use an image sequence for video playback.

---

7.5 *3DS Models

*Future support for 3DS models will allow for adding custom geometry to the scene for use as root pin, child node objects, or grid geometry.