4.17 Grdfile format specifications
Keywords: GMT_Docs

Next: 4.18 Options for COARDS-compliant Up: 4. General features Previous: 4.16 Character escape sequences Contents Index

#
4.17 Grdfile format specifications

GMT has the ability to read and write grids using more than one gridfile format (see Table 4.9 for supported format and their IDs). For reading, GMT will automatically determine the format of grid files, while for writing you will normally have to append =ID to the filename if you want GMT to use a different format than the default.

By default, GMT will create new gridfiles using the nf format; however, this behavior can be overridden by setting the GRID_FORMAT defaults parameter to any of the other recognized values (or by appending =ID).

GMT can also read netCDF gridfiles produced by other software packages, provided the grid files satisfy the COARDS and Hadley Centre conventions for NetCDF grids. Thus, products created under those conventions (provided the grid is 2- or 3-, or 4-dimensional) can be read directly by GMT and the netCDF grids written by GMT can be read by other programs that conform to those conventions. Two such programs are ncview and ncBrowse; others can be found on the NetCDF website.

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.

Table 4.9: GMT grid file formats.
ID | GMT 4 netCDF standard formats
nb | GMT netCDF format (byte) (COARDS-compliant)
ns | GMT netCDF format (short) (COARDS-compliant)
ni | GMT netCDF format (int) (COARDS-compliant)
nf | GMT netCDF format (float) (COARDS-compliant)
nd | GMT netCDF format (double) (COARDS-compliant)
ID | GMT 3 netCDF legacy formats
cb | GMT netCDF format (byte) (depreciated)
cs | GMT netCDF format (short) (depreciated)
ci | GMT netCDF format (int) (depreciated)
cf | GMT netCDF format (float) (depreciated)
cd | GMT netCDF format (double) (depreciated)
ID | GMT native binary formats
bm | GMT native, C-binary format (bit-mask)
bb | GMT native, C-binary format (byte)
bs | GMT native, C-binary format (short)
bi | GMT native, C-binary format (int)
bf | GMT native, C-binary format (float)
bd | GMT native, C-binary format (double)
ID | Miscellaneous gridformats
rb | SUN rasterfile format (8-bit standard)
rf | GEODAS grid format GRD98 (NGDC)
sf | Golden Software Surfer format 6 (float)
sd | Golden Software Surfer format 7 (double)
af | Atlantic Geoscience Center AGC (float)

Because some formats have limitations on the range of values they can store it is sometimes necessary to provide more than simply the name of the file and its ID on the command line. For instance, a native 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 are reading a grid then no options are needed: just continue to pass the name of the grdfile. However, if you write another format you must append the =ID string, where ID is the format code listed above. In addition, should you want to (1) multiply the data by a scale factor, and (2) add a constant offset you must 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 must append the /nan suffix to the scaling string (it cannot go by itself; note the nesting of the brackets!).

Some of the grid 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 no GMT netCDF format allow piping (due to the design of netCDF).

Everything looks more obvious after a few examples:

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

2. To read a native 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=bs/10/32000/32767.

3. To read a Golden Software ``surfer'' format 6 grd file, just pass the file name, e.g., my_surferfile.grd.

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

5. To write a native binary short integer grd file to standard output after subtracting 32000 and dividing its values by 10, give filename as =bs/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 current directory, home directory or in the directory /.gmt 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 		 nf 		 - 		 - 		 - 		Default format

    b 		 bf 		 - 		 - 		 - 		 Native binary floats

    i2 		 bs 		 - 		 - 		 32767 		 2-byte integers with NaN value

    ras 		 rb 		 - 		 - 		 - 		 Sun rasterfiles

    byte 		 bb 		 - 		 - 		 255 		 Native binary 1-byte grids

    bit 		 bm 		 - 		 - 		 - 		 Native binary 0 or 1 grids

    mask 		 bm 		 - 		 - 		 0 		 Native binary 1 or NaN masks

    faa 		 bs 		 0.1 		 - 		 32767 		 Native binary gravity in 0.1 mGal

These suffices can be anything that makes 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=bs/1/0/32767, and the filename wet.mask means wet.mask=bm/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 as small as 1/32 the size of the corresponding grd float format file.

Next: 4.18 Options for COARDS-compliant Up: 4. General features Previous: 4.16 Character escape sequences Contents Index