1.. index:: ! grd2xyz 2.. include:: module_core_purpose.rst_ 3 4******* 5grd2xyz 6******* 7 8|grd2xyz_purpose| 9 10Synopsis 11-------- 12 13.. include:: common_SYN_OPTs.rst_ 14 15**gmt grd2xyz** *ingrid* 16[ |-C|\ [**f**\|\ **i**] ] 17[ |-L|\ [**c**\|\ **r**\|\ **x**\|\ **y**]\ *value* ] 18[ |SYN_OPT-R| ] 19[ |SYN_OPT-V| ] 20[ |-T|\ [**a**\|\ **b**][*base*] ] 21[ |-W|\ [**a**\ [**+u**\ *unit*]\|\ *weight*] ] [ |-Z|\ [*flags*] ] 22[ |SYN_OPT-bo| ] 23[ |SYN_OPT-d| ] 24[ |SYN_OPT-f| ] 25[ **-ho**\ [*n*] ] 26[ |SYN_OPT-o| ] 27[ |SYN_OPT-qo| ] 28[ |SYN_OPT-s| ] 29[ |SYN_OPT--| ] 30 31|No-spaces| 32 33Description 34----------- 35 36**grd2xyz** reads one or more binary 2-D grid files and writes out 37xyz-triplets in ASCII [or binary] format to standard output. Modify the 38precision of the ASCII output format by editing the 39:term:`FORMAT_FLOAT_OUT` parameter in your :doc:`gmt.conf` file or use 40**--FORMAT_FLOAT_OUT**\ =\ *format* on the command line, or choose binary 41output using single or double precision storage. As an option you may 42output z-values without the (x,y) coordinates (see **-Z** below) or you can 43save the grid in the STL format for 3-D printers. 44 45Required Arguments 46------------------ 47 48.. |Add_ingrid| replace:: Names of 2-D binary grid files to be converted. 49.. include:: explain_grd_inout.rst_ 50 :start-after: ingrid-syntax-begins 51 :end-before: ingrid-syntax-ends 52 53Optional Arguments 54------------------ 55 56.. _-C: 57 58**-C**\ [**f**\|\ **i**] 59 Replace the x- and y-coordinates on output with the corresponding 60 column and row numbers. These start at 0 (C-style counting); append 61 **f** to start at 1 (Fortran-style counting). Alternatively, append 62 **i** to write just the two columns *index* and *z*, where *index* 63 is the 1-D indexing that GMT uses when referring to grid nodes. 64 65.. _-L: 66 67**-L**\ **c**\|\ **r**\|\ **x**\|\ **y**]\ *value* 68 Limit the output of records to a single row or column. Identify the desired 69 vector either by *row* or *column* number (via directives **c** or **r**), or by the 70 constant *x* or *y* value (via directives **x** or **y**). If your selection is outside 71 the valid range then no output will result and a warning is issued. **Note**: For 72 directives **x** and **y** we find the nearest column or row, respectively. 73 74.. |Add_-R| replace:: Using the **-R** option will select a subsection of the grid. If this subsection exceeds the 75 boundaries of the grid, only the common region will be output. |Add_-R_links| 76.. include:: explain_-R.rst_ 77 :start-after: **Syntax** 78 :end-before: **Description** 79 80.. _-T: 81 82**-T**\ [**a**\|\ **b**][*base*] 83 Write STL triangulation for 3-D printing to standard output. By default (or via **-Ta**) we write an STL ASCII file. 84 Append **b** to instead write the STL binary (little-endian) format. For more information on STL, see the 85 `STL overview on Wikipedia <https://en.wikipedia.org/wiki/STL_(file_format)>`_. **Note**: All coordinates are 86 adjusted so that *xmin = ymin = zmin = 0*. For other adjustments, see :doc:`grdedit`, :doc:`grdproject` and :doc:`grdmath`. 87 Optionally, append a lower *base* other than the grid's minimum value [Default]. **Note**: The grid must be free 88 of NaN values. If your grid contains NaNs then we automatically replace these with the minimum value in the grid; 89 use :doc:`grdmath` to pre-process the grid if you wish to select another value. 90 91.. figure:: /_images/GMT_STL.jpg 92 :width: 600 px 93 :align: center 94 95 3-D print of Vailulu’u crater multibeam data (2006, R/V Kilo Moana off Samoa) via a GMT STL file. Original 96 multibeam data processed with `MB-System <https://www.mbari.org/products/research-software/mb-system>`_ seen 97 on the right. Photos courtesy of Jasper Konter, U of Hawaii at Manoa. 98 99.. |Add_-V| replace:: |Add_-V_links| 100.. include:: explain_-V.rst_ 101 :start-after: **Syntax** 102 :end-before: **Description** 103 104.. _-W: 105 106**-W**\ [**a**\ [**+u**\ *unit*]\|\ *weight*] 107 Write out *x,y,z,w*\ , where *w* is the supplied *weight* (or 1 if not 108 supplied) [Default writes *x,y,z* only]. Choose **-Wa** to compute 109 weights equal to the area each node represents. For Cartesian grids this 110 is simply the product of the *x* and *y* increments (except for 111 gridline-registered grids at all sides [half] and corners [quarter]). 112 For geographic grids we default to a length unit of **k** (hence area is in km^2). Change 113 this by appending **+u**\ *unit* (see `Units`_). For such grids, the area 114 varies with latitude and also sees special cases for gridline-registered layouts 115 at sides, corners, and poles. 116 117.. _-Z: 118 119**-Z**\ [*flags*] 120 Write a 1-column ASCII [or binary] table. Output will be organized 121 according to the specified ordering convention contained in *flags*. 122 If data should be written by rows, make *flags* start with 123 **T** (op) if first row is y = ymax or 124 **B** (ottom) if first row is y = ymin. Then, 125 append **L** or **R** to indicate that first element should start at 126 left or right end of row. Likewise for column formats: start with 127 **L** or **R** to position first column, and then append **T** or 128 **B** to position first element in a row. For gridline registered 129 grids: If grid is periodic in x but the written data should not 130 contain the (redundant) column at x = xmax, append **x**. For grid 131 periodic in y, skip writing the redundant row at y = ymax by 132 appending **y**. If the byte-order needs to be swapped, append 133 **w**. Select one of several data types (all binary except **a**): 134 135 * **a** ASCII representation of a single item per record 136 * **c** int8_t, signed 1-byte character 137 * **u** uint8_t, unsigned 1-byte character 138 * **h** int16_t, short 2-byte integer 139 * **H** uint16_t, unsigned short 2-byte integer 140 * **i** int32_t, 4-byte integer 141 * **I** uint32_t, unsigned 4-byte integer 142 * **l** int64_t, long (8-byte) integer 143 * **L** uint64_t, unsigned long (8-byte) integer 144 * **f** 4-byte floating point single precision 145 * **d** 8-byte floating point double precision 146 147 Default format is scanline orientation of ASCII numbers: **-ZTLa**. 148 149.. |Add_-bo| replace:: [Default is 3]. This option 150 only applies to xyz output; see **-Z** for z table output. 151.. include:: explain_-bo.rst_ 152 153.. |Add_-d| unicode:: 0x20 .. just an invisible code 154.. include:: explain_-d.rst_ 155 156.. |Add_-f| replace:: See also **TIME 157 COORDINATES** below. **-h** Output 1 header record based on 158 information in the first grid file header. Ignored if binary output 159 is selected. [Default is no header]. 160.. include:: explain_-f.rst_ 161 162.. |Add_-h| unicode:: 0x20 .. just an invisible code 163.. include:: explain_-h.rst_ 164 165.. include:: explain_-ocols.rst_ 166 167.. include:: explain_-qo.rst_ 168 169.. include:: explain_-s.rst_ 170 171.. include:: explain_help.rst_ 172 173.. include:: explain_distunits.rst_ 174 175.. include:: explain_precision.rst_ 176 177Non-equidistant x/y Coordinates 178------------------------------- 179 180In general, GMT modules cannot accept grids with variable *x* and/or *y* coordinates as most 181algorithms and plotting options expect equidistant grids. However, you can use **grd2xyz** 182to dump the original *x y z* triplets and then reprocess the data onto an equidistant 183lattice via :doc:`greenspline`, :doc:`nearneighbor` or :doc:`surface`, for instance. 184 185Time Coordinates 186---------------- 187 188Time coordinates in netCDF grids, be it the x, y, or z coordinate, will 189be recognized as such. The variable's **unit** attribute is parsed to 190determine the unit and epoch of the time coordinate in the grid. Values 191are then converted to the internal time system specified by 192:term:`TIME_UNIT` and :term:`TIME_EPOCH` in the 193:doc:`gmt.conf` file or on the 194command line. The default output is relative time in that time system, 195or absolute time when using the option **-f0T**, **-f1T**, or **-f2T** 196for x, y, or z coordinate, respectively. 197 198Row Order 199--------- 200 201The **-Lr** option allows you to output a specific row in the grid. Note that while 202a grid's y-coordinates are positive up, internal row numbers are scanline numbers 203and hence positive down. Therefore, the first row (0) coincides with the largest *y*-value. 204This means that **-Lr**\ *0* and **-Ly**\ *ymax* (for the correct maximum y-value) 205will yield the same result. In contrast, both *x* and column numbers are positive to the right, 206with **-Lc**\ *0* and **-Lx**\ *xmin* (for the correct minimum x-value) yielding the same output. 207 208Examples 209-------- 210 211To edit individual values in the 2' by 2' remote AFR.nc file, dump the .nc to ASCII:: 212 213 gmt grd2xyz @AFR.nc > AFR.xyz 214 215To write a single precision binary file without the x,y positions from 216the remote file @AFR.nc file, using scanline orientation, run:: 217 218 gmt grd2xyz @AFR.nc -ZTLf > AFR.b 219 220To write out *lon, lat, topo, area* from the @AFR.nc file, selecting meter^2 as the area unit, 221and where *area* reflects the size of each grid box, run:: 222 223 gmt grd2xyz @AFR.nc -Wa+ue > AFR.txt 224 225See Also 226-------- 227 228:doc:`gmt.conf`, :doc:`gmt`, 229:doc:`grdedit`, :doc:`grdconvert`, 230:doc:`xyz2grd` 231
