B.2.1 NetCDF files

By default, GMT stores 2-D grids as COARDS-compliant netCDF files. COARDS (Cooperative Ocean/Atmosphere Research Data Service) is a convention used by many agencies distributing gridded data for ocean and atmosphere research. Sticking to this convention allows GMT to read gridded data provided by other institutes and other programs. Conversely, other general domain programs will be able to read grids created by GMT.

The netCDF grdfile in GMT has several attributes (See Table B.1) to describe the content. The routine that deals with netCDF grdfiles is sufficiently flexible so that grdfiles slightly deviating from the standards used by GMT can also be read.

Table B.1: Attributes of default GMT gridded file in COARDS-compliant netCDF format.

Attribute	Description
Global attributes
Conventions	COARDS (optional)
title	Title (optional)
source	How file was created (optional)
node_offset	0 for grid line registration (default), 1 for pixel registration
$x$- and $y$-variable attributes
long_name	Variable name (and unit) (default: ``x'' and ``y'')
actual_range	Minimum and maximum $x$ and $y$ of region; if absent
(or valid_range)	the first and last $x$- and $y$-values are queried
$z$-variable attributes
long_name	Variable name (and unit) (default: ``z'')
scale_factor	Factor to multiply $z$ with (default: 1)
add_offset	Offset to add to scaled $z$ (default: 0)
actual_range	Minimum and maximum $z$ (optional)
_FillValue	Value associated with missing data points; if absent an
(or missing_value)	approriate default value is assumed, depending on data type.

By default, the first 2-D or 3-D variable in a netCDF file will by read as the $z$ variable and the coordinate axes $x$ and $y$ will be determined from the dimensions of the $z$ variable. GMT will recognise whether the $y$ (latitude) variable increases or decreases. Both forms of data storage are handled appropriately. When the $z$ variable is 3-dimensional, such as is the case of longitude-latitude-depth grids, only the first ``layer'' will be loaded. For more information on the use of COARDS-compliant netCDF files, read Section 4.18.

GMT also allows other formats to be read. In addition to the default netCDF format it can use binary floating points, short integers, bytes, and bits, as well as 8-bit Sun rasterfiles (colormap ignored). Additional formats may be used by supplying read/write functions and linking these with the GMT libraries. The source file gmt_customio.c has the information that programmers will need to augment GMT to read custom grdfiles. We anticipate that the number of pre-programmed formats will increase as enterprising users implement what they need. See Section 4.17 for more information.