Converting Your Data to v5d Format

Files in the v5d format are created with functions from the v5d library. We've included four sample conversion programs which outline how to make a v5d file. They are located in the convert/ subdirectory. You can choose which one to use as a template for your data converter:

In any case, each conversion program uses three functions to write the v5d file: v5dCreate (or v5dCreateSimple), v5dWrite, and v5dClose. v5dCreateSimple is used to create v5d files that only specify the most basic parameters. v5dCreate allows more complicated parameters. There are versions of these functions for C and Fortran programs.

Here are the descriptions of the v5dCreate and v5dCreateSimple functions in a format similar to man page documentation. C programmers should note that in the argument descriptions we describe arrays by Fortran convention, i.e. A(1) is the first element of A, whereas in C this would be A[0].

Fortran-callable functions:

integer function v5dcreatesimple( name, numtimes, numvars, nr, nc, nl, varname, timestamp, datestamp, northlat, latinc, westlon, loninc, bottomhgt, hgtinc ) character* (*) name integer numtimes integer numvars integer nr integer nc integer nl character*10 varname(MAXVARS) integer timestamp(*) integer datestamp(*) real northlat real latinc real westlon real loninc real bottomhgt real hgtinc integer function v5dcreate( name, numtimes, numvars, nr, nc, nl, varname, timestamp, datestamp, compress, projection, proj_args, vertical, vert_args ) character* (*) name integer numtimes, numvars integer nr integer nc integer nl(*) character*10 varname(MAXVARS) integer timestamp(*) integer datestamp(*) integer compress integer projection real proj_args(*) integer vertical real vert_args(*)

C-callable functions:

int v5dCreateSimple( name, numtimes, numvars, nr, nc, nl, varname, timestamp, datestamp, northlat, latinc, westlon, loninc, bottomhgt, hgtinc ) char *name; int numtimes; int numvars; int nr, nc, nl; char varname[MAXVARS][10]; int timestamp[], datestamp[]; float northlat, latinc; float westlon, loninc; float bottomhgt, hgtinc; int v5dCreate( name, numtimes, numvars, nr, nc, nl, varname, timestamp, datestamp, compress, projection, proj_args, vertical, vert_args ) char *name; int numtimes, numvars; int nr, nc, nl[]; char varname[MAXVARS][10]; int timestamp[], datestamp[]; int compress; int projection; float proj_args[]; int vertical; float vert_args[];

The v5dWrite function is used to write a single 3-D grid of data to a v5d file. The grid is identified by a timestep and physical variable number. Here is the synopsis of v5dWrite:

Fortran-callable function:

integer function v5dwrite( time, var, data ) integer time integer var real data(*)

C-callable function:

int v5dWrite( time, var, data ) int time; int var; float data[];

The v5dClose function closes the v5d file after the last grid has been written. No arguments are needed. Here is the synpsis of v5dClose:

Fortran-callable function:

integer function v5dclose

C-callable function:

int v5dClose()

Each of the create functions returns 1 when successful and 0 when an error occurs.

Looking at any of the example data conversion programs, you'll see that there are variables which directly correspond to the arguments to v5dCreate/v5dCreateSimple. It is up to you to initialize these variables. For example, you'll have to assign to numtimes the number of timesteps in your dataset, assign to numvars the number of variables in your dataset, etc. After you've initialized all these variables, the v5dCreate (or v5dCreateSimple) call will create the v5d file. If you've failed to initialize any of the variables you will see an appropriate error message.

Next, the conversion program will enter a nested loop inside of which you must insert the code to read your data for the appropriate time step and physical variable number. Read your data into the array specified. The v5dWrite call will then compress and write the data to the v5d file. Finally, the v5dClose function will be called after all the data has been written.

After you've written and compiled your file converter, you should test it with one of your data files then check that it worked by running the v5dinfo and v5dstats utility programs on the v5d file. If everything looks OK, try running vis5d.

Here is an example of typical values that might be assigned to each variable if one were using the foo_to_v5d.f program:

The product of the number of rows, columns, levels, timesteps, and variables is the total number of data points. In this example: 30*40*20*5*4 = 480,000. A real dataset may be 100 rows by 100 columns by 20 levels, have 50 timesteps, and 10 variables for a total of 100,000,000 data points.

The difference between the foo_to_v5d program (which uses v5dCreateSimple), and the foo2_to_v5d program (which uses v5dCreate), is the later allows you to specify any map projection, vertical coordinate system, a different number of grid levels for each physical variable, and to control data compression. To specify a map projection, you must set the value of projection to 0,1,2 or 3 to indicate which projection, then specify the projection-dependent parameters in the proj_args arrray. Specifying the vertical coordinate system is done similarly.

It is sometimes useful to specify a different number of grid levels for each variable. For example, suppose most of your variables have 30 grid levels but a some variables have fewer grid levels, perhaps only one. Prior to version 4.0 of Vis5D, you would have had to fill in the extra levels with redundant, missing or dummy data values. With the v5dCreate function you can specify how many grid levels are present for each individual physical variable with the nl array parameter. Be aware that the amount of data passed to the v5dWrite call will depend on which variable you're writing. For example, if your grid has C columns and R rows then the number of values in the data array passed to v5dWrite for variable V must equal C*R*nl(V).

By default, the bottom-most grid level of each variable is displayed at the bottom of the 3-D box; each grid extends upward for how ever many levels are present. Sometimes, however, the bottom-most grid level of a particular variable should be positioned higher up. An example of this is a combined ocean/atmosphere dataset. There may be a total of 18 grid levels: the bottom 8 grid levels being ocean data and the top 10 grid levels being atmospheric data. In this case, the bottom of the atmospheric data should be offset or shifted upward by 8 grid levels.

Elaborating on the ocean/atmosphere example, suppose we have 2 ocean variables named S (salinity) and T (temperature) and 2 atmosphere variables named P (pressure) and T1 (temperature). There are 8 layers of ocean data and 10 layers of atmospheric data. Here is a summary showing how the lowlev array is the solution to this situation:

The lowlev array is not specified in the v5dCreate function because it was developed after the v5dCreate function was well established. Instead, the new v5dSetLowLev function is called with the lowlev array. This separate function was added to extend the functionality of v5dCreate without changing its calling sequence. Here is the synopsis of v5dSetLowLev:

Fortran-callable function:

integer function v5dsetlowlev( lowlev ) integer lowlev(*)

C-callable function:

int v5dSetLowLev( lowlev ) int lowlev[];

Argument description:

lowlev: Specifies the vertical offset, in grid levels, for each variable.

lowlev(1) = offset for first variable

lowlev(2) = offset for second variable ... = ... lowlev(numvars) = offset for last variable

v5dSetLowLev may be called at any point between v5dCreate and v5dClose.

The v5dCreate and v5dcreate functions allow you to control how the grid data are compressed. The default is for grid values to be linearly scaled to one byte integers. This works very well for most data sets, since the scaling factors are chosen independently for each combination of time step, variable and vertical level. Furthermore, the compression to one byte per grid point enables Vis5D's high degree of interactivity, since compression allows entire data sets to be resident in memory. However, the compress argument of the v5dCreate and v5dcreate functions lets you pick whether grid point values are scaled to 1-byte integers, scaled to 2-byte integers, or left as 4-byte floating point values (no compression).

Vis5D version 4.2 and later allow you to specify the physical units for each variable in your dataset. The v5dSetUnits() function takes two arguments: a variable number and a units character string. If the first variable in your file is P and the units are millibars then you can specify that with:

C: v5dSetUnits( 1, "millibars" )

Fortran: call v5dsetunits( 1, "millibars" )

The units will be displayed by the v5dinfo program and in Vis5D when using the probe.

To compile your program which uses v5dCreate, v5dWrite, and v5dClose you must link with the src/v5d.o and src/binio.o files. Alternatively, link with -lv5d to link with the installed libv5d library. See the makefiles in the convert/ directory for examples.

Finally, if your data is generated by an atmospheric or oceanic model, you may want to consider modifying your model to generate v5d files directly using the v5dCreate, v5dWrite, and v5dClose functions. Look at the sample data conversion programs for ideas.