Appendix B-Overlay File Format

Overview

Overlay data files consist of one or more data sets. Each data set has two parts: a header and the data. The header contains information about the data such as when it was acquired, who produced it, and the amount and organization of the data.

Using the accompanying library of routines libov.a will make many of the details of the data format transparent to the programmer that needs to manipulate the data. See Appendix C for more information.

ID String

The ID string identifies this file as an overlay data file. It is a six-character string. Currently, the only valid string is OV90a followed by a NULL character. If this string is not present, the library routines that read overlay files won't recognize the file. The ID string is not considered part of the header structure, since there may be multiple headers in a file, but the ID string only precedes the first one. It must be the first thing in the file.

The Header

The information contained in the header is necessary to identify the data and interpret it correctly. Figure B.1 shows the structure of the header.

Header Size

The header size is the number of bytes in the entire header, excluding the ID string.

Version

This entry is the version of the header. The first version is 0. Presumably the header will be changed in the future to accommodate needs unforeseen in the original design of the header. If the header structure is changed, the version must be incremented. In addition, the ov_read() library routine must be amended to read the new format (as well as correctly reading all previous formats), and ov_write() must be changed so that it writes the most recent version.

ID

This ID uniquely identifies the source of the data. Values for this entry are not strictly defined at the current time. The user should use it consistently. This value is an integer.

Date

The date is three integers in the order: year, month, day. This is the day on which the data began being acquired.

Time

This entry is the time at which data acquisition began in milliseconds since midnight, GMT.

Type

The type, or format, of the data in the OV file. Currently, there are five types:OV_CONTOUR, OV_VECTOR, OV_OUTLINE, OV_UNGRIDDED_VECTOR, and OV_UNGRIDDED_SCALAR. These different types are discussed more fully a little later on.

Parameter ID

The parameter ID uniquely identifies the type of data contained in the file. There are currently values defined for temperature, geopotential height, wind vectors, humidity, and vertical velocity. This value can be used by programmers in any way they deem appropriate, so long as they are consistent in its interpretation.

Level

The level is an integer value in millibars that indicates the level at which the data compiled.

Minimum and Maximum Values

These values are the minimum and maximum values in the data. If the extreme values for a file are unknown, these values must be equal to each other. If they are equal, SatView (and other programs) will realize that the data must be scanned to establish the range.

Bad Value

This entry is the value used when a data point is missing or of questionable validity. It is usually something unreasonable like -9999999.9. If SatView comes across this value in the data, it will be ignored.

Beginning and Ending Coordinates

The next four values in the header are the starting latitude, the ending latitude, the starting longitude, and the ending longitude. These values identify the physical location of the first and last data values in the data set.

Latitude Increment

This value specifies the distance (in degrees) between two adjacent lines of the gridded overlay data.

Longitude Increment

This value specifies the distance (in degrees) between two adjacent columns of the gridded overlay data.

Number of Rows and Columns

The next two entries in the header state the number of rows and columns in the gridded data.

Comment Length

If a comment (arbitrary text describing the data) is included in the file, we must know how many characters are in it. This entry contains the number of bytes in the string. If this entry is zero, there is no comment field.

Title Length

The number of characters in the title string.

Units Length

The number of characters in the units string.

Parameter Description Length

The number of characters in the parameter description string.

Title String

A string to be used as a title by SatView or other display programs.

Units String

A string describing the units of the values contained in the data section.

Parameter Description String

A string describing the nature of the values in the data section.

Private Data Area Size

The private data area is provided to let people store information that was not foreseen in the design of this data format. It can be any size, but its size in bytes must be correctly represented in this header entry.

Reserved Area

This space is reserved for subsequent versions of the header.

Comment

This field is a string of arbitrary length. Programmers may put anything they want in it. It was included to let programmers describe exactly what is in the file. For instance, if the data in the file is the result of a lengthy series of transformations or filtering, the file history may be included in the comment.

Private Data

The private data is provided to let the user include data in the header that was not anticipated in the design, or is not of common interest. Its use is flexible. For instance, it can be used as an extra comment field if desired, or to hold results of an analysis. Naturally, the user should interpret it consistently. SatView ignores this data.

Overlay Types

Overlay files may contain data in several different formats, or types. Originally designed to contain only gridded data (contours or vectors), there are now overlay formats that permit ungridded lists of data points: vectors, scalars, or geographic locations.

Contour Type

When the type field of an OV header contains OV_CONTOUR, the data stored is gridded scalars for contouring. num_rows contains the number of rows (or latitudes) in the data, and num_columns contains the number of columns (or longitudes). start_lat and start_lon indicate the earth location of the first point in the file, and lat_increment and lon_increment contain the distance between adjacent rows and columns. This distance may be either degrees or kilometers, as indicated by the grid_type header element. Currently, SatView can only display contours with a grid increment in degrees. For this type of data, there is one array of dimension num_rows x num_columns following the header. This array contains the entire first row of data, followed by the entire second row, and so on.

Vector Type

This type of data is used to draw vector fields. SatView also permits you to display a contour field of either the u or v component contained in the file. The format of the file is identical to the format for contour data, except the header is followed by two arrays of dimension num_rows x num_columns instead of just one. The first array contains all of the u values, and the second array contains all of the v values.

Outline Type

If the type field of the OV file is OV_OUTLINE, the file contains a list of earth locations. Using SatView, you may either draw a `point' at each of these locations, or connect the points with lines. The u array contains the latitudes and the v array contains the longitudes. num_rows contains the total number of points, and num_columns is ignored. Likewise, start_lat, start_lon, end_lat, end_lon, lat_increment, and lon_increment do not apply.

Ungridded Scalars

If the type field of the OV header is OV_UNGRIDDED_SCALAR, the file contains a list of ScalarStruct structures, each of which contains a latitude, a longitude, and an intensity. This list of structures comprises the data portion of the file, and the data element is a pointer to an array of these structures. SatView will draw a uniform size marker of the appropriate color for every such data point in the file. This is a useful format for displaying data that is neither gridded nor scanned. All that is required is a position and an intensity. num_rows indicates the number of data points, and num_columns is not used.

Ungridded Vectors

Ungridded vectors are similar to ungridded scalars except each structure in the data area contains a u and v value along with a latitude and longitude. SatView will draw a vector of the appropriate direction and magnitude for each such structure in the file. See the definition of the VectorStruct in the following section.

OV Header Structure in C

The include file ov.h contains the C definition of the OverlayHdr structure. This is the data structure that contains all of the information included in a overlay file header. A pointer to such a structure is returned by ov_read().

#define OV_HDR_VERSION 2 
#define OV_ID_STRING "OV90a"
#define OV_CONTOUR 	1
#define OV_VECTOR 	2
#define OV_OUTLINE      3
#define OV_UNGRIDDED_VECTOR 4
#define OV_UNGRIDDED_SCALAR 5

/* include file for gridded data for contours and vector
fields. currently wind is the only vector field. There may be more
than one data set in a file. A data set consists of a complete header
and a data section. Vector fields have two-part data sections: all
the u-direction data, followed by all the v-direction
data. 


for instance: 
*-------------------------* 
| 	File ID string 	|
*-------------------------*
|	Header (contour)	|
*-------------------------*
|       data 	|
*-------------------------*
|	Header (contour) 	|
*-------------------------*
| 	data 	|
*-------------------------*
|	Header (vector) 	|
*-------------------------*
| 	u data 	|
*-------------------------*
| 	v data 	|
*-------------------------*
*/
typedef struct overlay_header
{
long header_size;		/* including preceding string */
long version;
long id; /* satellite id or source of data; ie ERBE, NOAA9, ECMWF*/
long year, month, day;
float time; /* milliseconds since midnight */
long term;
long type;	/* OV_CONTOUR, OV_VECTOR, etc*/
long param; /* which param type? wind, humidity, temp, etc */
long level;
float min,max; /* max and min values if file. ignored if max == min */
float bad_value; /* value to flag no data was available for a given sample*/
float start_lat,end_lat,start_lon,end_lon;
float lat_increment, lon_increment; /* distance in degrees between adjacent lines of the gridded data */
long num_rows, num_columns; /*redundant but convenient */
long comment_len; /* size in bytes of comment field */
long private_size; /* size in bytes of private data area */
IncrementType increment_type; /*lat,lon increment are in DEGREES or KM*/
long title_len;
long units_len;
long param_desc_len;
GridType grid_type;
char dum[VERSION_2_DUMSIZE];
char *comment; /* arbitrary text describing data */
char *private; /* pointer to private data */
char *title;
char *units;
char *param_desc;
float *lat, *lon; /* arrays of explicit lats & lons for irregular grids */
float *data,*vdata; /*data points to data array. For vector fields, data points to the u array, and vdata points to the v array*/
}OverlayHdr;
/* define a structure for ungridded vectors. *data array
 contains num_rows of these*/
typedef struct _vector_struct
{
float lat,lon,u,v;
}VectorStruct;
/* define a structure for ungridded scalars. *data array
 contains num_rows of these*/
typedef struct _scalar_struct
{
float lat,lon,val
}ScalarStruct;
OverlayHdr *ov_dup_header(), *ov_read();
OV Header Structure in Fortran

This is the text of the Fortran include file ovf.h. It defines the OverlayHdr structure.

c fortran include file for overlay files
c the difference between this and the C version is that this
one contains c no pointers to arrays comment, private, data and
vdata. Those are c referenced separately.

structure /OverlayHdr/
integer*4 header_size
integer*4 version
integer*4 id
integer*4 year,month,day
real*4 time
integer*4 term
integer*4 type
integer*4 param
integer*4 level
real*4 max,min
real*4 bad_value
real*4 start_lat,end_lat,start_lon,end_lon
real*4 lat_increment, lon_increment
integer*4 num_rows, num_columns
integer*4 comment_len
integer*4 private_size
integer*4 increment_type
integer*4 title_len
integer*4 units_len
integer*4 param_desc_len
integer*4 grid_type
byte dum(20)
integer*4 comment_ptr
integer*4 private_ptr
integer*4 title_ptr
integer*4 units_ptr
integer*4 param_desc_ptr
integer*4 lat_ptr
integer*4 lon_ptr
integer*4 data_ptr
integer*4 vdata_ptr
end structure