3DSoftware.com: File Formats

3DSoftware.com > Programming > File Formats > GSHHS

GSHHS (WVS)
File Format Changes

June 2007

GSHHS (Global Self-consistent Hierarchical High-resolution Shoreline) is a global-level data set consisting of the WVS data set (World Vector Shorelines) corrected with the WDB-II data set (World Data Bank). GSHHS can be downloaded from:

ftp://ftp.soest.hawaii.edu/pwessel/gshhs/

When this article was written (June 2007) the current GSHHS version was 1.5/1.8 (version 1.5 of the data, and version 1.8 of the sample source code that extracts the data). By the time you read this, a newer version may be available at the link above.

This article begins with a reminder that binary data files must be opened in binary mode, and then covers the difference between version 1.5/1.8 and the earlier version 1.3/1.5.

Binary Mode

The GSHHS data files must be opened in binary mode, not in text mode. The C language source code (in gshhs.c) opens the data file in binary mode:

if ((fp = fopen (argv[1], "rb")) == NULL ) {
fprintf (stderr,
"gshhs: Could not find file %s.\n",
argv[1]);
exit (EXIT_FAILURE);
}

fopen is called with mode "rb" which specifies the file will be opened for reading in binary mode. The mode must be "rb", not simply "r".

If the mode is "r" (instead of "rb") then the data file will open in text mode instead of binary mode, causing data corruption. When using fopen (or equivalent library function) to read a binary file, make sure the mode is "rb", not "r".

Data Structure

The GSHHS data file consists of blocks of data without a file header. Each data block has its own header.

Each data block stores the vertices of a polygon. The polygon is the coastline of a land mass or water body. The version 1.3/1.5 polygon header record (declared in gshhs.h) is:

struct GSHHS {
int id;
int n;
int level;
int west, east, south, north;
int area;
int version;
short int greenwich;
short int source;
};

The newer version 1.5/1.8 polygon header record is:

struct GSHHS {
int id;
int n;
int flag;
int west, east, south, north;
int area;
};

The new variable flag replaces the struct elements level, version, greenwich and source, each of which become a byte in the new 4-byte flag. Those 4 variables are now declared and assigned outside the struct:

int level, version, greenwich, src;
struct GSHHS h;
//...
fread ((void *)&h,
(size_t)sizeof (struct GSHHS),
(size_t)1, fp);
//...
level = h.flag & 255;
version = (h.flag >> 8) & 255;
greenwich = (h.flag >> 16) & 255;
src = (h.flag >> 24) & 255;

We recommend inserting a version check where these 4 variables are assigned, to make sure the binary file being read is not for a different GSHHS binary format:

level = h.flag & 255;
version = (h.flag >> 8) & 255;
if (version != GSHHS_DATA_VERSION) {
fprintf (stderr, "Error\n" );
exit (EXIT_FAILURE);
}
greenwich = (h.flag >> 16) & 255;
src = (h.flag >> 24) & 255;

That would be the second version check. The first version check, earlier in the source code, checks for the need to do byte swapping. In that check, if the version is incorrect, it is assumed that byte swapping is needed. The second check would occur after performing byte swapping (if needed) of the struct elements.

Thursday, 20-Nov-2008 13:37:20 GMT