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