A VN Field file is line-oriented
Lines consist of items separated by commas; an item is a name (a control word) followed by a (possibly empty) set of values separated by spaces; the values can be separated from the name by space(s), colon or equal sign
In the description, [.....] indicate optional data, <...|...> indicate alternatives.
Control words can be abbreviated, minimal abbreviation is indicated in bold.
Only string values (names, file names) are case-sensitive.
If a string contains one of the following characters: ','(comma) ',' (blank) ':'(colon) or '=' (equal sign) it must be enclosed in “” (quotation marks)
# character begins a comment (all characters up to the end of the line are ignored
#VisNow regular field (This is the necessary first line)
Data components description section
[field name,] dimensions d1 [d2 [d3]] [,coordinates] [,mask]
[<affine field description | extents description>]
[tiling description]
d1,d2 and d3 are field dimensions (integers)
coordinates indicates that node coordinates will be read from a file (the field will be located in 3D space, the coordinates not read will be set to 0)
If neither coordinates nor the affine/rectangular description section is present, node indices will be used as coordinates
mask indicates that a boolean array indicating which node data are valid will be read
origin x0 x1 x2 #float coordinates of the node with zero indices
v0 x0 x1 x2 #float components of the first cell vector
[v1 x0 x1 x2 #float components of the second cell vector
[v2 x0 x1 x2]] #float components of the third cell vector
Example:
#VisNow regular field
field test,dim 65 101 255, mask
orig -32 -25 -127
v0 1 0 0
v1 0 0.5 0
v2 0 0 0.5
x x_min x_max #data box x range
[y y_min y_max #data box y range
[z z_min z_max]] #data box z range
Example:
#VisNow regular field
field test,dim 65 101 255, mask
x -32 32
y -50 50
z -127 127
tile_x from:to [from:to ...] #integers indicating tile boundaries along axes (ranges are inclusive and may overlap)
[tile_y from:to [from:to ...]]
[tile_z from:to [from:to ...]]
Example:
#VisNow regular field
field test,dim 65 101 257
tile_x 0:32 32:64
tile_y 0:50 50:100
tile_z 0:64 64:128 128:192 192:256
indicates a regular field with a 2x2x4 grid of tiles of dimensions 33x51x65 overlapping along common boundaries.
The tiles can then be read from different files and file sections.
Note: Tiles can extend outside of the field area – this feature can be used to read only portions of the data contained in data files. For example,
#VisNow regular field
field test,dim 30 50
tile_x -8:37
tile_y -8:57
will read only a central rectangle leaving aside margins of the width 8.
component name boolean|byte|short|integer|float|real|double|string, [vector|veclen|vlen veclen,]|[, array d0 [d1 ...][, symmetric]][, unit unit][, min min, max max][,user user data]
...(for each component)
The name string can not contain space, period or comma;
veclen is the number of data at each node, default 1;
float and real are synonyms;
if arr field is
present, data at each node will be interpreted as a matrix of given
dimensions (veclen will be d0 * d1 *... or d*(d+1)/2 if symmetric
is present);
if symmetric is present, data at each node will be interpreted as the upper triangle of a symmetric d0xd0 matrix stored in row order
unit is a string determining physical units units for this component, e.g. m/sec, Mpa, etc.;
it could be used for graph or colormap legends and in the future could be used in vnScript programs
min and max can be ysed in the case of byte or short data to indicate pthysical data range compressed to unsigned byte 0-255 or short -32556-32555 range
user data is a sequence of space-separated strings that can be used as a comment or for any user defined purposes
component velocity float, vector 3, unit m/sec
component pressure float, unit PSI
comp Hessian double, arr 3, symmetric, user “symmetric matrix of the second derivative of pressure”
VisNow can read both ASCII/UTF-8 and binary files.
The first line of a file description contains overall description of the file.
The following lines contain the information about subsequent file sections (parsing rules and the list of data contained in the file section).
file name binary [little|big] #file description
[timestep t[ dt]]
[skip skip,][stride stride,][tile x [y [z]] | tile x0:x1 [y0:y1 [z0:z1]],] component[.coordinate] offset[,... for each component read from this file section] #section content (can be repeated)
[end|repeat n]
The file must conform to the IEEE 754 interchange standard for float (32 bit) or double (64 bit) data
boolean data are stored as zero (false) non-zero (true) bytes
strings cannot be read from binary data files
little|big indicates endianness of the file; default – big endian
the optional timestep entry indicates that the data read in in the section will be added as time step data for the moment t.
skip is the number of bytes to be skipped from the beginning of the file or from the end of the previous section
stride is the number of bytes from the beginning of data for i-th node to the beginning of data for the node i+1
x [y [z]] are indices of the tile to be read in from the current file section, x0:x1 [y0:y1 [z0:z1]] are extents of the tile read in
in the case when the timestep entry is present, the end entry will indicate the end of a single timestep section, the repeat entry will indicate that n subsequent timesteps will be read in for timesteps t, t+dt, t+2*dt, ... t + (n-1)* dt.
file ../data/test.bin binary l,
skip 1024, stride 13, mask 0, velocity.0 1, velocity.1 5, velocity.2 9
skip 0, stride 4, temperature 0
will describe a file written e.g. on an Intel computer with two data sections:
the first section starts with 1024 irrelevant bytes and contains dim0*dim1*dim2 13-byte groups with mask[i] at the first byte followed by three float coordinates of the v[i] component;
the second section contains dim0*dim1*dim2 4-byte groups containing temperature data (one float per node)
Simplifications:
skip = 0 can be omitted
if the offset of the first item is 0 or if the offset of the i-th item is equal to
the offset of i-1-th item plus i-1-th item length (in bytes) then this offset can be omitted
if all coordinates of a component occupy a continuous chunk of bytes, one can write simply component [offset];
if, in addition, last offset + last data length = stride, stride can be omitted
Therefore, our example can be abbreviated to
file ../data/test.bin binary l
skip 1024, mask, velocity
temperature
file ../data/test.bin binary
skip 1024, tile 0 1 2, temperature
alternative tile description:
file ../data/test.bin bin
skip 1024, tile 0:32 50:100 128:192, temperature
file 2011Dec02_00/16222_2011120200+00250000C3sl000000000000000 binary
timestep 25
tile -8:439 -8:606, pressure_at_mean_sea_level
end
Three types of files are available.
Boolean values can be written as true/false or 1/0 in ASCII/UTF-8 files
Strings containing any separator character must be enclosed in “ “ to be read properly
ASCII column file:
file name column [,decimal decimal separator]
[timestep t[ dt]]
[skip skip,][separator "separator_string",][ tile x [y [z]] | x0:x1 [y0:y1 [z0:z1]],] component[.coordinate] column[,... for each component read from this section]#section content (can be repeated)
[end|repeat n]
name is a valid file pathname (either absolute or relative to the field file directory)
skip is the number of lines to be skipped from the beginning of the file or from the end of the previous section
separator_string is a string containing non-blank characters that can be used to separate the columns (example: ",;" will indicate that the columns can be separated by comma or semicolon in addition to blank characters - empty columns can occur: e.g. in a line like 1,,2,,,5 the columns 1,3,4 are empty). Note: since the separator string can contain a comma used as item separator, it has to be enclosed by “”)
x [y [z]] are indices of the tile to be read in from the current file section, x0-x1 [y0-y1 [z0-z1]] are extents of the tile read in
component is the name of currently read component, coords when coordinates are read in or mask when the node validity mask is read
in the case when the component is not scalar (veclen > 1) coordinate is a number of currently read coordinate of the component
column indicates the column holding the data (column numbers start from 0)
file ../data/test.txt column,
skip 10, separator ",", mask 0, v.0 1, v.1 2, v.2 3
skip 0, temperature 0
will describe a file with 10 irrelevant lines, a section of text organized in 4 or more columns separated by commas or blanks with mask[i] at the first columns followed by three float coordinates of the v component. The next section contains the temperature data at the first column.
Simplifications:
if the first item is read from the column 0 or if the i-th item is next to the column of i-1-th item then this column number can be omitted
if all coordinates of a component occupy a continuous sequence, one can write simply component [column];
Therefore, our example can be abbreviated to
file ../data/test.bin col,
skip 10, separator ",", mask, velocity
temperature
ASCII character column file:
file name fixed column[,skip skip][,decimal decimal separator]
[timestep t[ dt]]
[skip skip,][ tile x [y [z]] | x0-x1 [y0-y1 [z0-z1]],]component[.coordinate] char-char[,... # for each component read from this file]
[end|repeat n]
name is a valid file pathname (either absolute or relative to the field file directory)
skip is the number of lines to be skipped from the beginning of the file or from the end of the previous section
component is the name of currently read component, coords when coordinates are read in or mask when the node validity mask is read
in the case when the component is not scalar (veclen > 1) coordinate is a number of currently read coordinate of the component
char-char is the range of character columns holding the data for current item
x [y [z]] are indices of the tile to be read in from the current file section, x0-x1 [y0-y1 [z0-z1]] are extents of the tile read in
file ../data/test.txt fix
skip 10, mask 0-1, v.0 2-10, v.1 11-19, v.2 20-28
will describe a file with 10 irrelevant lines followed by a sequence of dim0*dim1*dim2 lines with mask[i] written at first 2 chars of the line and followed by three float coordinates of the velocity components at the node written at the subsequent 9-char chunks.
ASCII continuous file:
file name ASCII[,separator separator_string][,length length][,decimal decimal separator]
[timestep t[ dt]]
[skip skip],[stride stride,] [ tile x [y [z]] | x0-x1 [y0-y1 [z0-z1]], component[.coordinate] offset[,... # for each component read from this file]
[end|repeat n]
No line structure is assumed – data are read continuously from the file. If no separator string is given, data items are separated by any combination of white characters (spaces, tabs and newlines)
name is a valid file pathname (either absolute or relative to the field file directory)
skip is the number of items from the beginning of the file to be skipped (this is different from the ascii column type input where skip denotes the number of lines to be skipped)
component is the name of currently read component, coords when coordinates are read in or mask when the node validity mask is read
in the case when the component is not scalar (veclen > 1) coordinate is a number of currently read coordinate of the component
stride is the number of items form the beginning of data for i-th node to the beginning of data for the node i+1
separator_string is a string containing non-blank characters that can be used to separate the data items
length length can be used when all data entries are of the same length and there are no separators
x [y [z]] are indices of the tile to be read in from the current file section, x0-x1 [y0-y1 [z0-z1]] are extents of the tile read in
Example:
1:
file ../data/test.txt ascii
skip 1, stride 5, pressure 0, v.0 1, v.1 2, v.2 3
skip 1, stride 1, temperature 0
will describe a file with one header line followed by 5-element groups with pressure[i] at the first item followed by three float coordinates of the velocity components and one unread item at the i-th node for i = 0,...,dim0*dim1*dim2-1. The next section of the file starts with one header line and contains only temperature data.
2.
file ../data/test.txt ascii, len 1
skip 1, stride 1, mask
will describe a file with one header line followed by mask data, one character per node e.g.
Mask
00011111100111111
00111111111111110
00011111111111101
...
Simplifications:
if the offset of the first item is 0 or if the offset of the i-th item is equal to the offset of i-1-th item plus i-1-th item length (in bytes) then this offset can be omitted
if all coordinates of a component occupy a continuous chunk of bytes, one can write simply component [offset];
if stride is equal to the number of data items, it can be omitted
Therefore, our first example can be abbreviated to
file ../data/test.txt ascii
skip 1, stride 5, pressure, velocity
skip 1, temperature