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:
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 range, give the name as
rasterfile=3/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 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.