WMS:Binary Dataset Files

From XMS Wiki
Revision as of 16:45, 17 February 2014 by Jcreer (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Datasets can be stored to either ASCII or binary files. Compared to ASCII files, binary files require less memory and can be imported to WMS more quickly. The disadvantages of binary files are that they are not as portable and they cannot be viewed with a text editor.

The binary dataset file format is shown in Figure 1. The binary format is patterned after the ASCII format in that the data are grouped into "cards". However, the cards are identified by a number rather than a card title.

Card Item Size Description
  version 4 byte integer The WMS binary dataset file format version. value = 3000.
100 objecttype 4 byte integer Identifies the type of objects that the datasets in the file are associated with. Options are as follows:
  &nbsp
1 TINs
2 Boreholes
3 2D meshes
4 2D grids
5 2D scatter points = 6 3D meshes
7 3D grids
8 3D scatter points
110 SFLT 4 byte integer The number of bytes that will be used in the remainder of the file for each floating point value (4, 8, or 16).
120 SFLG 4 byte integer The number of bytes that will be used in the remainder of the file for status flags.
130 or 140 BEGSCL or BEGVEC   Marks the beginning of a set of cards defining a scalar or vector dataset.
150 VECTYPE 4 byte integer (0 or 1) In the case of vector dataset files, indicates whether the vectors will be applied at the nodes/gridnodes or the elements/cells.
160 OBJID 4 byte integer The id of the associated object. Value is ignored for grids and meshes.
170 NUMDATA 4 byte integer The number of data values that will be listed per time step. This number should correspond to the number of vertices, nodes, cell centers (cell-centered grid), cell corners (mesh-centered grid) or scatter points.
180 NUMCELLS 4 byte integer This number should correspond to the number of elements (meshes) or the number of cells (mesh-centered grids). Value is ignored for other object types.
190 NAME 40 bytes The name of the dataset. Use one character per byte. Mark the end of the string with the ‘\0’ character.
200 TS   Marks the beginning of a time step.
  ISTAT SFLG integer (0 or 1) Indicates whether or not status flags will be included in the file.
  TIME SFLT real Time corresponding to the time step.
  statflag1 SFLG integer Status flag (0 or 1) for node 1
  statflag2 SFLG integer Status flag (0 or 1) for node 2
  ....    
  val1 SFLT real Scalar value for item 1
  val2 SFLT real Scalar value for item 2
  ....    
      Repeat card 200 for each timestep in the dataset.
210 ENDDS   Signal the end of a set of cards defining a dataset.

Figure 1. The Binary Scalar or Vector Dataset File Format.


The cards in the binary dataset file are as follows:

Card Type VERSION
Card ID 3000
Description File type identifier. No fields.
Required YES


Card Type OBJTYPE
Card ID 100
Description Identifies the type of objects that the datasets in the file are associated with.
Required YES. If card does not exist, the file can only be read through the Data Browser. The datasets would then be assigned to the objects corresponding to the active module.
Field Variable Size Value Description
1 id 4 byte int
1
2
3
4
5
6
7
8
TINs
Boreholes
2D meshes
2D grids
2D scatter points
3D meshes
3D grids
3D scatter points


Card Type SFLT
Card ID 110
Description Identifies the number of bytes that will be used in the remainder of the file for each floating point value (4, 8, or 16).
Required YES
Field Variable Size Value Description
1 sizefloat 4 byte int 4, 8, or 16 Number of bytes


Card Type SFLG
Card ID 120
Description Identifies the number of bytes that will be used in the remainder of the file for status flags (1, 2, or 4).
Required YES
Field Variable Size Value Description
1 sizeflag 4 byte int 1, 2, or 4 Number of bytes


Card Type BEGSCL
Card ID 130
Description Marks the beginning of a set of cards defining a scalar dataset.
Required YES


Card Type BEGVEC
Card ID 140
Description Marks the beginning of a set of cards defining a vector dataset.
Required YES



Card Type VECTYPE
Card ID 150
Description Identifies the type of vector data that will be read and where to apply it.
Required This card is only required if the vector data is associated with elements/cells. If this card is not present, it is assumed that the data are associated with nodes/gridnodes.
Field Variable Size Value Description
1 type 4 byte int
0
1
The vectors will be applied to the nodes/gridnodes.
The vectors will be applied to the elements/cells.



Card Type OBJID
Card ID 160
Description The id of the associated object.
Required This card is required in the case of TINs, 2D scatter points, and 3D scatter points. With each of these objects, multiple objects may be defined at once. Hence the id is necessary to relate the dataset to the proper object.
Field Variable Size Value Description
1 id 4 byte int + The id of the object.



Card Type NUMDATA
Card ID 170
Description The number of data values that will be listed per time step. This number should correspond to the number of vertices, nodes, cell centers (cell-centered grid), cell corners (mesh-centered grid), maximum node id (meshes) or scatter points.
Required YES
Field Variable Size Value Description
1 numdata 4 byte int + The number of items. At each time step, numdata are listed.



Card Type NUMCELLS
Card ID 180
Description This number should correspond to the element id (meshes) or the number of cells (grids).
Required YES
Field Variable Size Value Description
1 numcells 4 byte int + The number of elements or cells.



Card Type NAME
Card ID 190
Description The name of the dataset.
Required YES
Field Variable Size Value Description
1 name 40 bytes str The name of the dataset. Use one character per byte. Mark the end of the string with the ‘\0’ character.



Card Type TS
Card ID 200
Description Defines the set of scalar values associated with a time step. Should be repeated for each time step.
Required YES
Field Variable Size Value Description
1 istat SFLG int
0
1
Use status flags from previous time step. For the first time step, this value indicates that all cells are active.
Status flags will be listed.
2 time SFLT int + The time step value. This number is ignored if there is only one time step.
  stat SFLG int
0
1
Inactive
Active
One status flag should be listed for each cell or element.
These flags are included only when istat = 1.
  val SFLT real ± The scalar values


Card Type ENDDS
Card ID 210
Description Signals the end of a set of cards defining a dataset
Required YES