4.17 Embedded grdfile format specifications

GMT has the ability to read more than one grdfile format. As distributed, GMT now recognizes 12 predefined file formats. These are

0.

GMT netCDF 4-byte float format [Default]

1.

Native binary single precision floats in scanlines with leading grd header

2.

Native binary short integers in scanlines with leading grd header

3.

8-bit standard Sun rasterfile (colormap ignored)

4.

Native binary unsigned char in scanlines with leading grd header

5.

Native binary bits in scanlines with leading grd header

6.

Native binary ``surfer'' grid files

7.

netCDF 1-byte byte format

8.

netCDF 1-byte char format

9.

netCDF 2-byte int format

10.

netCDF 4-byte int format

11.

netCDF 8-byte double format

In addition, users with some C-programming experience may add their own read/write kernels and link them with the GMT library to extend the number of predefined formats. Technical information on this topic can be found in the source file gmt_customio.c.

Because of these new formats it is sometimes necessary to provide more than simply the name of the file on the command line. For instance, a short integer file may use a unique value to signify an empty node or NaN, and the data may need translation and scaling prior to use. Therefore, all GMT programs that read or write grdfiles will decode the given filename as follows:

name[=id[/scale/offset[/nan]]]

where everything in brackets is optional. If you only use the default netCDF file format then no options are needed: just continue to pass the name of the grdfile. However, if you use another format you must append the =id string, where id is the format id number listed above. In addition, should you want to multiply the data by a scale factor, then add a constant offset you may append the /scale/offset modifier. Finally, if you need to indicate that a certain data value should be interpreted as a NaN (not-a-number) you may append the /nan suffix to the scaling string (it cannot go by itself; note the nesting of the brackets!).

Some of the grd formats allow writing to standard output and reading from standard input which means you can connect GMT programs that operate on grdfiles with pipes, thereby speeding up execution and eliminating the need for large, intermediate grdfiles. You specify standard input/output by leaving out the filename entirely. That means the ``filename'' will begin with ``=id'' since the GMT default netCDF format does not allow piping (due to the design of netCDF).

Everything looks more obvious after a few examples:

1. To write a binary float grd file, specify the name as my_file.grd=1.

2. To read a short integer grd file, multiply the data by 10 and then add 32000, but first let values that equal 32767 be set to NaN, use the filename my_file.grd=2/10/32000/32767.

3. To read a 8-bit standard Sun rasterfile (with values in the 0-255 range) and convert it to a $\pm$1 range, give the name as rasterfile=3/7.84313725e-3/-1 (i.e., 1/127.5).

4. To write a short integer grd file to standard output after subtracting 32000 and dividing its values by 10, give filename as =2/0.1/-3200.

Programs that both read and/or write more than one grdfile may specify different formats and/or scaling for the files involved. The only restriction with the embedded grd specification mechanism is that no grdfiles may actually use the ``='' character as part of their name (presumably, a small sacrifice).

One can also define special file suffixes to imply a specific file format; this approach represents a more intuitive and user-friendly way to specify the various file formats. The user may create a file called .gmt_io in the home directory and define any number of custom formats. The following is an example of a .gmt_io file:

		# GMT i/o shorthand file 

# It can have any number of comment lines like this one anywhere 

# suffix 		 format_id 		 scale 		 offset 		NaN		Comments 


grd 		 0 		 - 		 - 		 - 		Default format 


b 		 1 		 - 		 - 		 - 		 Native binary floats 


i2 		 2 		 - 		 - 		 32767 		 2-byte integers 


ras 		 3 		 - 		 - 		 - 		 Sun rasterfiles 


byte 		 4 		 - 		 - 		 255 		 1-byte grids 


bit 		 5 		 - 		 - 		 - 		 0 or 1 grids 


mask 		 5 		 - 		 - 		 0 		 1 or NaN masks 


faa 		 2 		 0.1 		 - 		 32767 		 Gravity in 0.1 mGal

These suffices can be anything that make sense to the user. To activate this mechanism, set parameter GRIDFILE_SHORTHAND to TRUE in your .gmtdefaults file. Then, using the filename stuff.i2 is equivalent to saying stuff.i2=2/1/0/32767, and the filename wet.mask means wet.mask=5/1/0/0. For a file intended for masking, i.e., the nodes are either 1 or NaN, the bit or mask format file may be down to 1/32 the size of the corresponding grd format file.