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