1.. _grd_inout_full:
2
3Grid File Formats
4-----------------
5
6By default GMT writes out grids as single precision floats in a COARDS-complaint
7netCDF file format. However, GMT is able to produce and read grid files in many
8other commonly used grid file formats and also facilitates so called "packing"
9of grids, writing out floating point data as 1- or 2-byte integers. To specify
10the precision, scale and offset, the user should add the suffix
11[**=**\ *ID*][**+d**\ *divisor*][**+n**\ *invalid*][**+o**\ *offset*][**+s**\ *scale*], where
12*ID* is a two-letter identifier of the grid type and precision, and the
13*scale* (or *divisor*), *offset* and *invalid* are the arguments of optional modifiers to be applied
14to all grid values,  Here, *invalid* is the value used to indicate missing
15data. In case the *ID* is not provided, as in **+s**\ *scale*, then a
16*ID*\ **=**\ *nf* is assumed. When reading grids, the format is generally
17automatically recognized from almost all of those formats that GMT and GDAL
18combined offer. If not, the same suffix can be added to input grid file names.
19If reading an image as a grid you can select the band via **+b**.
20See :doc:`grdconvert </grdconvert>` and Section :ref:`grid-file-format`
21of the GMT Technical Reference and Cookbook for more information regarding GDAL settings.
22
23When reading a netCDF file that contains multiple grids, GMT will
24read, by default, the first 2-dimensional grid that it can find in that
25file. To coax GMT into reading another multi-dimensional variable in
26the grid file, append **?**\ *varname* to the file name, where *varname*
27is the name of the variable. Note that you may need to escape the
28special meaning of **?** in your shell program by putting a backslash in
29front of it, or by placing the filename and suffix between quotes or
30double quotes. The **?**\ *varname* suffix can also be used for output
31grids to specify a variable name different from the default: "z". See
32:doc:`grdconvert </grdconvert>` and Sections :ref:`modifiers-for-CF` and
33:ref:`grid-file-format` of the GMT Technical Reference and Cookbook for more
34information, particularly on how to read slices of 3-, 4-, or 5-dimensional grids.
35
36When writing a netCDF file, the grid is stored by default with the
37variable name "z". To specify another variable name *varname*, append
38**?**\ *varname* to the file name. Note that you may need to escape the
39special meaning of **?** in your shell program by putting a backslash in
40front of it, or by placing the filename and suffix between quotes or
41double quotes.
42
43.. description-ends
44.. ingrid-syntax-begins
45
46*ingrid*\ [=\ *ID*\|\ ?\ *varname*][**+b**\ *band*][**+d**\ *divisor*][**+n**\ *invalid*]
47[**+o**\ *offset*][**+s**\ *scale*]
48
49    |Add_ingrid| Optionally, append =\ *ID* for reading a specific file
50    format [Default is =\ *nf*] or ?\ *varname* for a specific netCDF variable
51    [Default is the first 2-D grid found by GMT]
52    (:ref:`See full description <grd_inout_full>`). The following modifiers are
53    supported:
54
55       - **+b** - Select a *band* (for images only) [Default is 0].
56       - **+d** - Divide data values by the given *divisor* [Default is 1].
57       - **+n** - Replace data values matching *invalid* with NaN.
58       - **+o** - Offset data values by the given *offset* [Default is 0].
59       - **+s** - Scale data values by the given *scale* [Default is 1].
60
61    Note: Any offset is added after any scaling.
62
63.. ingrid-syntax-ends
64.. outgrid-syntax-begins
65
66**-G**\ *outgrid*\ [=\ *ID*][**+d**\ *divisor*][**+n**\ *invalid*]
67[**+o**\ *offset*\|\ **a**][**+s**\ *scale*\|\ **a**]
68[:*driver*\ [*dataType*][**+c**\ *options*]]
69
70    |Add_outgrid| Optionally, append =\ *ID* for writing a specific file format
71    (:ref:`See full description <grd_inout_full>`). The following modifiers are
72    supported:
73
74        - **+d** - Divide data values by given *divisor* [Default is 1].
75        - **+n** - Replace data values matching *invalid* with a NaN.
76        - **+o** - Offset data values by the given *offset*, or append **a** for
77          automatic range offset to preserve precision for integer grids
78          [Default is 0].
79        - **+s** - Scale data values by the given *scale*, or append **a** for
80          automatic scaling to preserve precision for integer grids [Default
81          is 1].
82
83    Note: Any offset is added before any scaling. **+sa** also sets **+oa**
84    (unless overridden). To write specific formats via GDAL, use = *gd*
85    and supply *driver* (and optionally *dataType*) and/or one or more
86    concatenated GDAL **-co** options using **+c**. See
87    the :ref:`"Writing grids and images" cookbook section <Write-grids-images>`
88    for more details.
89
90.. outgrid-syntax-ends
91