next up previous contents index
Next: 4.18 The NaN data Up: 4. General features Previous: 4.16 Character escape sequences   Contents   Index

4.17 Embedded grdfile format specifications

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

GMT netCDF 4-byte float format [Default]
Native binary single precision floats in scanlines with leading grd header
Native binary short integers in scanlines with leading grd header
8-bit standard Sun rasterfile (colormap ignored)
Native binary unsigned char in scanlines with leading grd header
Native binary bits in scanlines with leading grd header
Native binary ``surfer'' grid files
netCDF 1-byte byte format
netCDF 1-byte char format
netCDF 2-byte int format
netCDF 4-byte int format
netCDF 8-byte double format
NOAA/NGDC MGG grid format

In addition, users with some C-programming experience may add their own read/write functions 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:


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 .gmtdefaults4 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 as small as 1/32 the size of the corresponding grd format file.

next up previous contents index
Next: 4.18 The NaN data Up: 4. General features Previous: 4.16 Character escape sequences   Contents   Index
Paul Wessel 2004-10-01