Chapter 7. The v5dimport Utility

Table of Contents
Using v5dimport's graphical interface
The v5dimport User Interface Embedded in Vis5D
Using v5dimport's text interface
Adding support for new file format
Notes on specific file formats

The v5dimport utility is a program for converting grid files to v5d format, combining multiple source files, resampling to new coordinate systems and culling variables and timesteps. It has both a graphical and command line user interface.

For example, you may use v5dimport to read 2 McIDAS GR3D files and a 2-D McIDAS GRID file, resample all the data to a Lambert Conformal projection, omit the CWAT and VORT variables and then write the data to a Vis5D file called lambert1.v5d.

The basic order of events when using v5dimport is:

  1. Read the input file(s).

  2. Select grids for output according to timestep, physical variable, map projection or vertical coordinate system.

  3. Setup a map projection and vertical coordinate system for the output file.

  4. Write the output file. Resampling is done at this time.

  5. Optionally, start Vis5D on the output file.

Currently, v5dimport can read the following file formats:

McIDAS GR3D and GRID files
Vis5D v5d and comp5d files
GRADS files
"UW vis" files (used at the University of Wisconsin)
EPA MM4 and RADM files (on Crays only)

Using v5dimport's graphical interface

Start v5dimport from your shell with

v5dimport [-path pathname] [files]

where [files] is an optional list of input files and [-path pathname] specifies that the directory named "pathname" is to be used as the default, in place of the current directory, for the input file browser and for making output files.

When v5dimport has started you'll see its main window appear. It consists of:

  1. a scrollable list of all grids scanned from the input files

  2. buttons used for selecting/culling grids according to variable name, timestep, projection or vertical coordinate system

  3. buttons and type-in fields for describing and creating the output file.

Reading input grids

You may read additional grid files into v5dimport at any time by clicking on the "Read file..." button. Use the file selector to locate your file and click on OK or CANCEL. It's best to read all input files right at the beginning because whenever a new file is read all grids are selected for output, overriding any selections you may have previously made.

The button labeled "Discard all grids" does exactly what it says. It's equivalent to exiting v5dimport and restarting it.

After reading each input file, the list of grids shown in the top half of the window, will be resorted by time then variable name.

The columns in this list are:

Grid grid number (no significant meaning)
YYDDD the year and date of the grid
HHMMSS the time of the grid in hours, minutes, and seconds
Variablethe variable name
Nr number of grid rows
Ncnumber of grid columns
Nlnumber of grid levels
Proj#the projection number (see "Select by projection..." window)
VCS#the vertical coordinate system number (see "Select by VCS...")
Filenamename of file the grid was found in

Selecting grids for output

It's often the case that one wants to discard some physical variables or timesteps from the input file so they aren't written to the output file. By default, all variables are selected for output.

To select/cull variables, click on the "Select by variable..." button. A pop-up window will appear which lists all the variables. The ones that are highlighted are selected for ouput. Click on variables names to select or deselect them.

Similarly, you can select timesteps via the "Select by time..." button. A pop-up window listing all time steps will appear. Use the mouse to select the time steps you want and unselect the timesteps you wish to omit. Note that you can select/deselect a number of timsteps by just dragging the mouse while holding down the button.

Finally, grids may be selected or discarded according to their map projection or vertical coordinate system (VCS) via the "Select by projectiion..." and "Select by VCS... buttons.

Note that as you select/deselect timesteps, variables, projections, or VCSs the effected grids will be high-lighted/unhigh-lighted in the main grid list.

The "Select All" and "Select None" buttons do just what they imply.

Defining the output file

The default parameters for the output file (grid size, projection, etc) are taken from the first file read in. You should always review these parameters before making your output file. It will often be necessary to change these values.

The number of rows, columns, and levels for the output file is specified by the type-in fields on the main window labeld "Rows", "Columns" and "Max Levels". Type in new values if the defaults are incorrect.

The map projection for the output file can be viewed and changed by clicking on the "Map projection..." button. In this pop-up window you'll be able to choose a map projection type then enter the specific projection parameters. There is also a "Guess" button which will attempt to find a reasonable output projection given the currently selected grid list. It's often helpful to have the "Select by Projection" pop-up window on-screen to compare the output projection to the input projections.

The vertical coordinate system for the output file can be viewed and changed by clicking on the "Vertical Coord System..." button. In this pop-up window you'll be able to choose a vertical coordinate system type and enter the specific parameters. This window also has a "Guess" button to try to find a reasonable default. Similarly, it's often helpful to have the "Select by VCS" pop-up window on-screen to compare the output VCS to the input VCSs.

Making the output file

Enter a filename for the output file in the type-in field at the bottom of the main window then click on "Make". Messages will be printed as the file conversion takes place. If there are any errors the process will halt. Note that generating the output file can be time-consuming if data must be resampled from the input grid's coordinate system to a new coordinate system for the output file.

If you click on "Visualize" this will make the file and then automatically start up Vis5D on that file (i.e., you don't need to click on "Make" first). If you type a filename in the type-in field, it wil use that name. Otherwise, it will use your login name followed by ".v5d". If you want command line options on the Vis5D command, put them in a file named vis5d_options. For example, -mbs 64.


An options window is available by clicking on the "Options..." button.

The first item controls the "combining of co-located data". It may be the case that several 3-D grids, selected for output, are co-located in space and time. When computing the value to put in the output file you can either choose the data value from the higher resolution grid at that location, or take the average of all grid values at that grid location.

The second item controls how grid data is compressed in the output file. By default, grid values are scaled down to 1-byte integers. Alternately, you can scale down to 2-byte integers for better resolution, or perform no compression/scaling by selecting 4-byte floating point values. This option respresents a tradeoff in file size and precision.