ANTz000x.csv

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

Also see:
[Table_B.2] for node Field Descriptions.

---

Appendix B Node State File - .CSV

---

B.1 Node State File Overview

The scene 'State' file is written in CSV format (Comma Separated Values). The first line contains the field names for the columns. Individual node records start on the second line and continue with one node per line until the last node is reached. The file is terminated with an extra line return at the end, (the last line is blank.) All values are either 32bit signed integers or 32bit signed floats.

---

B.1.1 Tree Hierarchy

CSV files are written such that the nodes are grouped by root tree, child nodes are sorted using a recursive algorithm. It is not usually necessary to understand (or retain) the node ordering in the CSV file. However, for those who want to know.... The file write process iterates through all root nodes sequentially. First writes the root-node, then recursively calls itself for all child nodes. The parent node is always written before its child nodes. After the last child branch is traversed, the process starts over on the next root-node.

The CSV Read process is agnostic to node ordering within the file, the only parameter that defines the hierarchy is the 'parent_id'. Orphan nodes that are out of order in the file are sorted and attached to there parents after reading the entire file.

---

id (node ID)

The 'id' field is used to build the topo tree hierarchy and link to additional node type specific data. The node ID is only unique within the file. Whenever a file is opened (or imported,) a new set of IDs are generated. This allows for merging multiple files that contain overlapping node IDs without any contention.

An exception is the primary Root-Camera and Root-Grid which are always overwritten. This is also true for the first 4 child cams at branch level 1. All others nodes are created as 'New' and are assigned session unique IDs.

Note that if you save a file, then read it back in, delete and/or add some nodes, then re-save, you will get a different set of IDs. Use the 'record_id' to keep track of nodes over time (throughout multiple sessions.)

---

parent_id

The parent ID determines the tree hierarchy. Root-Nodes are set to zero, all child nodes must specify the 'parent_id', which is the only parameter used to build the hierarchy.

---

branch_level

Root-Nodes have 'branch_level' = 0. The first child, such as a primary torus is set to 1, each additional sub-child adds one. So a child of a primary torus is 'branch_level' = 2, and so on.... The 'branch_level' is automatically set during the node creation process and the CSV value ignored. It is included in the CSV file for convenience of 3rd party analysis.

---

record_id

Because the node 'id' is subject to automatic re-assignment by the app, the 'record_id' is provided for the user to keep track of the record that the node represents. It is retained by the node and is not modified by the application. This may be used to reference the original DB record that the node was based on.

---

child_count - the number of child nodes directly attached to the node at the current 'branch_level'. Does not count the sub-children of the attached child nodes. The 'child_count' is automatically set during node creation and is provided for convenience of 3rd party analysis.

---

child_index - Specifies which child node that is actively selected, used mostly for keyboard navigation of the tree topology. Basically this allows the application to remember which child branch was last active.

---

B.1.2 Position & Coordinates

Position is based on translation, rotation and scale (of the parent.) Root nodes are relative to the global origin. Child node coordinates are relative to (or inherent) there parents position and topo type.

'topo' types include default, cube, sphere, torus, surface, pin and grid. Each defines a coordinate system with a unique set of operations that transform the position, orientation and scale of any attached child nodes.

Some topo types, (such as a 'cube') have multiple local coordinate systems. The child node 'facet' value tracks which system, (or cube side to use.)
See 'Cube - Key Table' appendix and 'Coordinates & Topologies' section.

Radial offset is 'translate_z' for a torus.

Translational velocity is set by 'translate_rate_x/y/z' and is the delta distance applied per cycle, (typically 60 cycles per second.) Nodes may be restricted (or wrapped) by both local node limits imposed and/or the parent topo type limits.

Typically you do not assign a 'translate_rate' to a root-node as it will continue to move until it disappears by leaving the scene boundaries, (at the clipping planes.) However, child nodes will typically limit or wrap there coordinates when boundaries are hit, (depends on parent topo type.)

The following table describes the coordinate system for a KML based Sphere in comparison to a Torus. The range for the two are the same, except for translate_y where the Torus has a range of -180 to 180 latitude vs KML -90 to +90 deg. Cube and Grid topo coordinates are the same as a Torus. Latitude values greater then +/- 90 degrees are wrapped onto the Sphere, (causes upside down object.) For detail see 'Topologies & Coordinates' section.

order	field_name	kml_name	kml_lo	kml_hi	torus_lo	torus_hi
1	translate_x	longitude	-180	180	-180	180
2	translate_y	latitude	-90	90	-180	180
3	translate_z	altitude	0	none	none	none
4	rotate_y	heading	0	360	0	360
5	rotate_x	tilt	0	180	0	180
6	rotate_z	roll	-180	180	-180	180

---

Rotation

The 'rotate_x/y/z' sets the node orientation with units in degrees. Order of operation is:

1st rotate about z-axis by the Heading, rotate_y
2nd rotate about x-axis by the Tilt, rotate_x
3rd rotate about z-axis(again) Roll, rotate_z

Camera 'Tilt' differs from all other objects in that the 'rotate_x' axis is inverted. A value of 0 results in a view looking straight down the -z axis, basically looking straight down on a map. At x = 90 deg the cam will rotate CCW about the x-axis and look at the horizon towards North (with Heading rotate_y = 0.) Effectively this is a 'Right-Handed' coordinate system for rotation, (with an inverted up vector.) Translation is still a 'Left-Handed' coordinate system. Compatible with the google KML '<Camera>' standard.

Objects (other then the camera) use a 'Left-Handed' coordinate system for rotation (and translation.) An object with zero Tilt will be upright. At rotate_x = 45 deg the object will lean towards North, (with Heading = 0).

rotate_y Heading range is 0 to 360 deg, North = 0, E=90, S=180, W=270.
rotate_z Roll range is -180 to +180 deg.

'x' axis of a child node can be used to set the spacing of toroids around there parent. 'y' axis will spin the torus, not very noticeable unless it has a texture map or is assigned a different primitive.

Rotational velocity is set by 'rotate_rate_x/y/z' and is applied (added) to the 'rotate' orientation every cycle.

Orientation and position of nodes, (other then the camera,) are compatible with the google KML '<Model>' specification. The altitude units are not the same. Instead of feet (or meters) altitude is specified relative to the circumference, altitude units are 1 to 1 with translate_x at the equator.

Cameras use the '<Camera>' KML coordinate system which differs in that the 'Tilt' x-axis is inverted, (and camera up vector.) See 'Camera Position” in this appendix for further detail.

---

Camera Position

Position is set using 'translate_x/y/z' and 'rotate_x/y/z' for orientation.

Tilt is 'rotate_x', straight down is 0.0 deg, horizon is 90 deg, up is 180.
Heading is 'rotate_y', North is 0.0 deg, E 90, S 180, W 270.
Roll is 'rotate_z', CW is 0 to 180 deg and CCW is 0 to -180.0 deg.

Note that the x-axis 'tilt' is essentially a flipped axis, and is therefore a right-handed coordinate system. This is an exception, the rest of the coordinates are all left-handed systems.

Note that the 'rotateVec_x/y/z/s' parameter should be ignored, it is a unit vector calculated from 'rotate' and is automatically updated.

There are multiple cameras available to the user. There is a single root camera that all other cameras are attached to as child nodes. New child camera's may be created or existing child cams may be deleted. The Root-Camera is locked and cannot be deleted. By default there are four child cams attached to the Root-Camera.

The coordinate system is designed to be compatible with the Google KML standard for a '<Camera>', not to be confused with '<LookAt>'. For detail see 'Topology & Coordinates' section in this document.

Also see the '<Camera>' specification in the Google KML docs:

http://code.google.com/apis/kml/documentation/kmlreference.html

*At this time, all cameras coordinates are relative to the World Origin, which is flat cartesian space, (non-spherical coordinates.) Future updates will allow for attaching a camera to any node. Attaching a camera to a parent with a Sphere topo type would result in polar coordinates.

---

Scaling

Object size is set by 'scale_x/y/z'. A scale value of 0.5 is equivalent to a 50% reduction, default is 1.0 which results in no change in size. Valid scale values can be very small or large. A negative value results in an inversion of the geometry, including all child nodes of the current node. For uniform scaling the x, y and z values must be identical. Individual axes may have different scale values. This results in non-uniform scaling which causes an object to appear stretched or squished.

In general 'scale_rate_x/y/z' is used internally by the application but is not practical if set to a value other then zero. Otherwise continuos scaling will occur and an object will typically become far too large.

---

Ratio (torus inner radius)

The 'ratio' sets the inner radius of a torus relative to its size. Range is between 0.01 and 1.0, where 1.0 is a donut with no hole and 0.01 is a very thin donut. The default ratio is 0.1 which is equivalent to 10% of the outer radius. Nodes attached to a parent of Torus topo type are positioned relative to the surface, so scale and ratio (inner radius) effect the position.

*Ratio may effect other characteristics depending on geometry and topo type.

---

B.1.3 Texture Maps & Color

'texture_id' specifies which texture map to apply. When texture_id = 0 the texture map is disabled, zero is the default for most objects. The root-grid has a default textureID = 1 that is loaded from 'map00001.jpg'. For detail see 'File - Texture Maps' section.

'color_r/g/b/a' sets the RGBA of a node and is usually based on the 'color_index' that maps to a palette of colors, default palette has 20 colors, larger index numbers are mapped into the palette range. T

'color_a' sets the alpha transparency and is not set by the 'color_index'. Texture maps can be RGBA with per pixel alpha values.

Note that you may set the color to any custom RGBA you choose, but if the user changes the color, the custom color will be lost. In general, match the RGB values to the 'color_index - key table' in the appendix.