Appendix A: Satellite Image File Format

Overview

Satellite image data files consist of two parts: a header and the data. The header contains information about the data such as when it was acquired, which satellite produced it, the amount and organization of the data, and the name of the latitude/longitude file that applies to it.

The user is given the option of including the latitude/longitude data within the satellite image file, or putting it in a separate file, and referencing this separate file through the header. Latitude/longitude data tends to be large and is often common to multiple data sets. Putting it in a separate file is a good way to save disk space.

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

The Header

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

ID String

The ID string identifies this file as a satellite image file. It is a six-character string. Currently, the only valid string is "SI90a" followed by a NULL character. If this string is not present, the library routines that read satellite image files won't recognize the file.

Header Size

The header size is the number of bytes in the entire header, including the ID string. Think of it as the distance from the beginning of the file to the first data point.

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 si_open() library routine must be amended to read the new format (as well as correctly reading all previous formats), and si_write() must be changed so that it writes the most recent version.

Satellite ID

The satellite ID uniquely identifies the satellite that acquired the data. Currently defined IDs exist for GOES, ERBE, GMS, NOAA9, and SSMI data. This value is an integer.

Date

The date is three integers in the order of: year, month, day. Clearly, 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.

Time Flag

If this flag is set, then each scanline of data is preceded by the time at which the scan began.

Parameter ID

The parameter ID uniquely identifies the type of data the satellite gathered. For instance, longwave data has an ID of 1, and shortwave data has an ID of 2. This value can be used by programmers in any way they deem appropriate, so long as they are consistent in its interpretation.

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. When rendering the satellite image, SatView will map its coolest color to the minimum value, and its warmest color to the maximum value.

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.

Latitude/Longitude File Name Length

If a separate latitude/longitude file accompanies this data file, its name must be included in the header. In order to read it in, the number of characters in the file name must be known. If this value is zero, it is assumed the latitude/longitude data is included within the image file.

Number of Scan Lines

Presumably the image in the data file is a series of scans of a satellite image. The assumption is made that scan lines adjacent in the file are adjacent in space. This value is simply the number of scans comprising an image.

Samples Per Scan Line

To interpret the data correctly, it must be known how many values are in each scan line. If all scan lines contain the same number of samples, this header entry should contain that number. If each scan line contains a different number of samples, this entry should be set to -1, and each scan line must be preceded by the number of samples in that scan line.

Comment Length

If a comment (arbitrary text describing the data) is included in the file, it must be known 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.

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.

Latitude/Longitude File Name

This string is a relative or absolute pathname to the file that contains the latitude/longitude data relevant to the data contained herein. If the pathname is relative, it is assumed to be relative to the directory that this file (the satellite image file) is in. The correct length of this string must also be stored in the header.

Comment

This field is a string of arbitrary length. The programmer may put anything he wants in it. It was included to let him 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's 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.

si.h

The include file si.h contains the definition of the SatImageHdr structure. This is the data structure that contains all of the information included in a satellite image file header. A pointer to such a structure is returned by si_open().

#define HDR_VERSION 0
#define LONGWAVE 0
#define SHORTWAVE 1
#define ALBEDO 1
#define FILES_ONLY 1
#define DIRS_ONLY 2
#define ID_STRING "SI90a"      

/* satellite image file header */ 
/* this header structure will appear at the beginning of each
satellite data file with the following differences:
  1. The character pointers will not appear. They would have no meaning in a file. In their place will be the corresponding character arrays each of whose length is stated in other header elements (i.e., there will be a character array of exactly `lat_lon_filename_len' bytes (no terminating NULL) which comprise the filename). The order of the character string is unchanged.
  2. The file descriptors fd and ll_fd are for program use only and are not included in the file. The read_header() routine will fill these in as appropriate in the header it passes back.
    typedef struct sat_image_hdr
    {
    char id_string[6];/* must be `SI90a\0' to identify this as an si file */
    int header_size; /* including preceding string */
    int version;
    int id;	/* satellite id; ie ERBE, NOAA9, etc */
    int year,month,day;
    float time; /* milliseconds since midnight */
    int time_flag; /* TRUE if each scanline is preceded by it's time */
    int parameter; /* longwave, shortwave, etc */
    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*/
    int lat_lon_filename_len; /* 0 if latlon is included in this file */
    int num_scans; /* number of scanlines */
    int samps_per_scan; /* samples per scanline. -1 if variable */
    int comment_len; /* arbitrary text describing data */
    int private_size; /* size in bytes of private data area */
    char dum[40];
    char *lat_lon_filename; /* pathname of latlon file */
    char *comment;
    char *private; /* pointer to private data */
    int fd, ll_fd; /* file descriptors for param file and latlon file */
    }SatImageHdr;
    /*the data is coded scanline by scanline. It looks like this:
    *--------------------------------*
    | time (one float) 	| <-- optional (time_flag == TRUE)
    *--------------------------------*
    | num samps (one int) 	| <-- optional(samps_per_scan== -1)
    *--------------------------------*
    | one scanline of satellite data 	|
    *--------------------------------*
    | one scanline of latitude data	| <-- optional(lat_lon_filename_len>0)
    *--------------------------------*
    | one scanline of longitude data 	| <-- optional(lat_lon_filename_len>0)
    *--------------------------------*
    */
    SatImageHdr *si_create_header(), *si_dup_header();