|
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). When reading grid files, GMT can automatically determine which one of the many netCDF formats has been used, but for all other formats the user must append the appropriate =ID specification.
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-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.
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 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 only use the default grid 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 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 range, give the name as
rasterfile=rb/7.84313725e-3/-1 (i.e., 1/127.5).
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 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.