VIS-5D

Also Known As: Visualization-5D, McIDAS, Grid File Format


Type Vector
Colors NA
Compression Uncompressed
Maximum Image Size Unlimited
Multiple Images Per File No
Numerical Format Big- and little-endian
Originator University of Wisconsin - Madison
Platform UNIX
Supporting Applications VIS-5D, McIDAS
See Also None

Usage
Designed to support the VIS-5D application by providing for the storage of multi-dimensional data.

Comments
Although VIS-5D was designed to support scientific applications, multi-dimensional data visualization is a growing area. This format may become more important outside of scientific circles in the future.

Vendor specifications are available for this format.

Code fragments are available for this format.


The VIS-5D (Visualization-5D) format is the native file format of the VIS-5D scientific visualization UNIX application. VIS-5D is used to store a 3D rendering of numerical data. Such data is typically acquired from scientific sources such as weather data and topographical measurements. Because the numerical data often contains a time component, VIS-5D file data may be animated to show changes over time, such as the movements of cloud patterns.

Contents:
File Organization
File Details
For Further Information

The VIS-5D application is actually a stand-alone subsystem of the proprietary McIDAS (Man-computer Interactive Data Access System) system maintained by the Space Science and Engineering Center of the University of Wisconsin at Madison. McIDAS also uses the VIS-5D format to store data, and users of both systems often refer to VIS-5D files as "McIDAS 5D grid files", or simply as "grid files."

Because the VIS-5D system is distributed under the GNU public license, it is freely available with full source code. This makes the VIS-5D distribution itself your best source of information for this file format.

File Organization

All VIS-5D files contain three sections of data:

The file header contains information about the contents of the entire file. The grid information headers are a directory of the grid data sequences stored in the file. The data is a sequence of one or more 3D grids, each of which defines a coordinate point in the numerical data.

There is one 3D grid information header per grid stored in the file. The information header stores the size and location, time and date stamp, variable name, and unit description of a grid or grid point. Each grid point is constructed of five floating-point values referred to as a five-dimensional data set. The five values stored are the three coordinate locations of the grid point, a time step value, and the physical variable name of the grid point.

The three coordinate locations store the spatial dimensions of latitude, longitude, and altitude (rows, columns, and levels) of a point in the 3D grid data set. The time step value indicates the moment in time that the point exists. The variable name is the label used to refer to the point.

Grid points are divided into logical groupings called grid sequences. A grid sequence is one or more grid points that all exist in the same moment in time. A grid sequence is and similar to a single still-image frame in an animation. Displaying the grid sequences in their orderly succession causes the numerical data to become animated.

The duration of time between each grid sequence is called a time step. The time step increments may be as short as one second or as long as years. All of the time steps in a grid data set are the same length of time, and the rate at which the data is displayed by an application may or may not depend on the size of these increments.

Time step values are derived from the time and date stamp data associated with each grid. Time stamps are constructed using the familiar HHMMSS (hours, minutes, seconds) format. For example, 183426 would be 6:34 p.m. and 26 seconds. Date stamps are constructed using the less familiar YYDDD format, where YY is the last two digits of the year and DDD is the number of the day of the year. For example, June 20th is the 171st day of the year 1994 and would be represented by the date format 94171.

In the following hypothetical example, we have a data set containing 20 grid points. Each point is identified by an integer starting with 1. The data set contains five grid sequences, each containing four grid points. There are five time steps, one per grid sequence, starting on April 7, 1994 at 11:00 p.m. and advancing in 30-minute increments. Each time step is composed of four grid points using the physical variable names A, B, C, and D. Each grid contains data in all three spatial dimensions:

Grid

Seq.

Date

Time

Var.

Latitude

Longitude

Altitude

1

1

94097

230000

A

34076.67

123543.90

4365.7

2

1

94097

230000

B

29086.56

135789.74

4405.6

3

1

94097

230000

C

32567.67

129086.56

4445.5

4

1

94097

230000

D

16095.34

116865.91

4495.4

5

2

94097

233000

A

34184.22

123543.90

4375.7

6

2

94097

233000

B

29006.56

135789.75

4415.6

7

2

94097

233000

C

32567.67

129186.56

4455.5

8

2

94097

233000

D

16567.34

115765.91

4505.4

9

3

94098

000000

A

34262.47

123543.90

4385.7

10

3

94098

000000

B

29008.22

135789.76

4425.6

11

3

94098

000000

C

32567.67

129286.56

4465.5

12

3

94098

000000

D

16456.34

114365.91

4515.4

13

4

94098

003000

A

34666.14

123543.90

4395.7

14

4

94098

003000

B

28055.46

135789.77

4435.6

15

4

94098

003000

C

32567.67

129386.56

4475.5

16

4

94098

003000

D

16234.34

112165.91

4525.4

17

5

94098

010000

A

34776.20

123543.90

4405.7

18

5

94098

010000

B

28006.01

135789.78

4445.6

19

5

94098

010000

C

32567.67

129486.56

4485.5

20

5

94098

010000

D

16123.34

120486.91

4535.4

As you can see, this data is animated by displaying each successive grid sequence as a frame in a movie. In this example, the four grid points are displayed in sequence and would appear to move as their position changes over time.

Although it is possible to construct a simple data set consisting of one dimension, no time dynamic, and only one variable, it is more likely that data stored using the VIS-5D format will use all five dimensions.

Grid files are typically named using file mask GR3Dnnnn, where nnnn is a zero-padded number in the range of 0001 to 9999. This number is referred to as the grid file number and is used to sequence and identify grid files associated with a project. Grid files typically do not use a file extension.

A single grid file may contain a maximum of 100,000,000 grid points, which is 400 megabytes of data. If this is not enough for your application, VIS-5D allows single data sets to span multiple disk files.

File Details

All VIS-5D files begin with a 256-byte header in the following format:

typedef struct _Vis5DHeader
{
    CHAR  Identifier[32];    /* File description field */
    LONG  ProjectNumber;     /* Project number */
    LONG  CreationDate;      /* Date file was created */
    LONG  MaximumSize;       /* No. of data points in largest 3D grid */
    LONG  NumberOfGrids;     /* No. of 3D grids in the data */
    LONG  FirstGrid;         /* Location of first grid */
    LONG  Padding[51];       /* Alignment padding */
} VIS5DHEADER;

Identifier is a 32-byte field used to store a NULL-terminated character string which is used to identify the file and its contents. This field, when blank, may be filled with all NULL (00h) or SPACE (20h) characters.

ProjectNumber is a user-defined value used to identify the project to which a VIS-5D file belongs. If a project number is not required, this value may then equal the grid file number used to construct the file name, or may be set to 00h.

CreationDate is the date the VIS-5D file was created in YYDDD format. A value of 01h indicates that no creation date was specified.

MaximumSize is the number of data points in the largest 3D grid. This value is the product of the number of rows, columns, and levels in the largest grid.

NumberOfGrids is the total number of 3D grids in the data. This value is the product of the number of time steps and parameters in the data.

FirstGrid is the offset location of the first grid in the data. This offset value is the number of 4-byte LONG values from the first grid to the beginning of the file. The first grid usually follows the last 3D grid information header in the file.

Padding is 204 bytes of filler used to pad the header out to a length of 256 bytes. This field is set to a value of 00h.

Following the header is a sequence of 3D grid information headers. Each header may be thought of as an entry in a directory of grid point data found in a grid file. There will be one information header per grid point stored in the file, and the number of grids is equal to the product of the number of time steps and physical parameters.

All 3D grid information headers are 256 bytes in length and have the following format:

typedef struct _3DGridInformationHeader
{
    LONG  Size;                /* Number of data points */
    LONG  NumberOfRows;        /* Number of rows */
    LONG  NumberOfColumns;     /* Number of columns */
    LONG  NumberOfLevels;      /* Number of levels */
    LONG  DataLocation;        /* Location of grid data */
    LONG  Date;                /* Grid date stamp */
    LONG  Time;                /* Grid time stamp */
    LONG  Padding1;            /* Alignment padding */
    CHAR  ParamName[4];        /* 4-character variable or parameter name */
    CHAR  UnitsDesc[4];        /* 4-character units description */
    LONG  Padding2[11];        /* Alignment padding */
    LONG  IType;               /* Always 04h */
    LONG  NorthLatitude;       /* North latitude * 10000 */
    LONG  WestLongitude;       /* West longitude * 10000 */
    LONG  LatitudeIncrement;   /* Latitude increment * 10000 */
    LONG  LongitudeIncrement;  /* Longitude increment * 10000 */
    LONG  Padding3[4];         /* Alignment padding */
    LONG  IhType;              /* Always 01h */
    LONG  TopAltitude;         /* Top altitude * 1000 */
    LONG  AltitudeIncrement;   /* Altitude increment * 1000 */
    LONG  Padding4[31];        /* Alignment padding */
} 3DGRIDINFOHEADER;

Size is equal to the number of 4-byte data points in the grid. This value is always equal to NumberOfRows * NumberOfColumns * NumberOfLevels.

NumberOfRows, NumberOfColumns, and NumberOfLevels are the number of rows, columns, and levels, respectively, in the grid data.

DataLocation is the location of the grid data in the file stored as the number of 4-byte LONG values from the beginning of the file.

Date is the date stamp of the grid data in YYDDD format.

Time is the time stamp of the grid in HHMMSS format.

Padding1 is four bytes of filler used to align the first seven fields of the header on a 32-byte boundary. This field is set to a value of 00h.

ParamName is a 4-character ASCII string which is the physical variable name used to represent the grid point. This field is not NULL-terminated and is padded with SPACE (20h) characters if needed.

UnitsDesc is a 4-character ASCII string which describes the unit of measure used by the grid point. This field is not NULL-terminated and is padded with SPACE (20h) characters if needed.

Padding2 is 44 bytes of filler used to align the previous ten fields. This field is set to a value of 00h.

IType is always set to the value 04h.

NorthLatitude is the northernmost latitude in the grid data multiplied by 10000.

WestLongitude is the westernmost longitude in the grid data multiplied by 10000.

LatitudeIncrement is the latitude increment multiplied by 10000.

LongitudeIncrement is the longitude increment multiplied by 10000.

Padding3 is 16 bytes of filler used to align the previous 16 fields. This field is set to a value of 00h.

IhType is always set to the value 01h.

TopAltitude is the highest altitude multiplied by 1000.

AltitudeIncrement is the altitude increment multiplied by 1000.

Padding4 is 124 bytes of filler used to pad the information header out to a length of 256 bytes. This field is set to a value of 00h.

The actual grid data is a five-dimensional array of floating-point values:

FLOAT GridArray[TimeSteps][Parameters][Levels][Columns][Rows];

TimeSteps is the number of time steps in this grid data set.

Parameters is the number of physical parameters used by the grid data set.

Levels is the number of levels (altitude).

Columns is the number of columns (longitude).

Rows is the number of rows (latitude).

An array containing only one grid using one time step and one variable would be declared as:

FLOAT GridArray[1][1][1][1][1];

while an array containing 1644 grids using 12 parameters and 137 time steps in each sequence would be declared as:

FLOAT GridArray[137][12][1644][1644][1644];

The Northwest-bottom corner of the data set is:

GridArray[TimeSteps][Parameters][0][0][0];

The Southeast-top corner is:

GridArray[TimeSteps][Parameters][Levels - 1][Columns - 1][Rows - 1];

Empty or missing data in a grid element is indicated by a value of 1.0e35.

For Further Information

For further information about VIS-5D, see the documentation and sample code on the CD-ROM. For additional information or to be added to the VIS-5D mailing list, contact:

Space Science and Engineering Center
Attn: Bill Hibbard or Brian Paul
University of Wisconsin--Madison
1225 West Dayton Street
Madison, WI 53706
Bill Hibbard: whibbard@macc.wisc.edu
Brian Paul: brianp@ssec.wisc.edu
WWW: http://java.meteor.wisc.edu/

The VIS-5D distribution is available via FTP at the following site:

ftp://iris.ssec.wisc.edu/pub/vis5d/

There is no official VIS-5D file format specification, but the files README and util/sample.c (included on the CD-ROM) should be of special interest.



Copyright © 1996, 1994 O'Reilly & Associates, Inc. All Rights Reserved.