xenial (1) grd2xyz.1gmt.gz

Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       grd2xyz - Convert grid file to data table

SYNOPSIS

       grd2xyz  grid  [ [f|i] ] [ region ] [ [level] ] [ [weight] ] [ [flags] ] [ -bo<binary> ] [ -d<nodata> ] [
       -f<flags> ] [ -ho[n] ] [ -o<flags> ] [ -s<flags> ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       grd2xyz reads one or more binary 2-D grid files and writes out xyz-triplets in ASCII [or  binary]  format
       to  standard  output.  Modify  the  precision  of the ASCII output format by editing the FORMAT_FLOAT_OUT
       parameter in your gmt.conf file or use --D_FORMAT=format on the command line,  or  choose  binary  output
       using  single  or  double  precision  storage.  As  an  option  you may output z-values without the (x,y)
       coordinates; see -Z below.

REQUIRED ARGUMENTS

       grid   Names of 2-D binary grid files to be converted. (See GRID FILE FORMATS below.)

OPTIONAL ARGUMENTS

       -C[f|i]
              Replace the x- and y-coordinates on output with the corresponding column and  row  numbers.  These
              start  at  0  (C-style  counting); append f to start at 1 (Fortran-style counting). Alternatively,
              append i to write just the two columns index and z, where index is the 1-D indexing that GMT  uses
              when referring to grid nodes.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify  the region of interest. Using the -R option will select a subsection of the grid. If this
              subsection exceeds the boundaries of the grid, only the common region will be output.

       -V[level] (more ...)
              Select verbosity level [c].

       -W[weight]
              Write out x,y,z,w, where w is the supplied weight (or 1 if not  supplied)  [Default  writes  x,y,z
              only].

       -Z[flags]
              Write  a  1-column  ASCII  [or  binary] table. Output will be organized according to the specified
              ordering convention contained in flags.  If data should be written by rows, make flags start  with
              T  (op)  if  first  row  is y = ymax or B (ottom) if first row is y = ymin. Then, append L or R to
              indicate that first element should start at left or right end of row. Likewise for column formats:
              start  with L or R to position first column, and then append T or B to position first element in a
              row. For gridline registered grids: If grid is periodic in x  but  the  written  data  should  not
              contain  the  (redundant)  column  at x = xmax, append x. For grid periodic in y, skip writing the
              redundant row at y = ymax by appending y. If the byte-order needs to be swapped, append w.  Select
              one of several data types (all binary except a):

              • a ASCII representation of a single item per record

              • c int8_t, signed 1-byte character

              • u uint8_t, unsigned 1-byte character

              • h int16_t, short 2-byte integer

              • H uint16_t, unsigned short 2-byte integer

              • i int32_t, 4-byte integer

              • I uint32_t, unsigned 4-byte integer

              • l int64_t, long (8-byte) integer

              • L uint64_t, unsigned long (8-byte) integer

              • f 4-byte floating point single precision

              • d 8-byte floating point double precision

              Default  format  is  scanline  orientation  of ASCII numbers: -ZTLa.  Note that -Z only applies to
              1-column output.

       -bo[ncols][type] (more ...)
              Select native binary output. [Default is 3]. This option only applies to xyz output; see -Z for  z
              table output.

       -d[i|o]nodata (more ...)
              Replace input columns that equal nodata with NaN and do the reverse on output.

       -f[i|o]colinfo (more ...)
              Specify  data  types  of input and/or output columns. See also TIME COORDINATES below. -h Output 1
              header record based on information in the first grid file header.  Ignored  if  binary  output  is
              selected. [Default is no header].

       -ocols[,...] (more ...)
              Select output columns (0 is first column).

       -s[cols][a|r] (more ...)
              Set handling of NaN records.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).

       -+ or just +
              Print  an  extensive usage (help) message, including the explanation of any module-specific option
              (but not the GMT common options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation of options, then exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

ASCII FORMAT PRECISION

       The ASCII output formats of numerical data are controlled by parameters in your gmt.conf file.  Longitude
       and  latitude  are formatted according to FORMAT_GEO_OUT, whereas other values are formatted according to
       FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in the  output,  which
       can  lead  to  various  problems downstream. If you find the output is not written with enough precision,
       consider  switching  to  binary  output  (-bo  if  available)  or  specify  more   decimals   using   the
       FORMAT_FLOAT_OUT setting.

GRID FILE FORMATS

       By  default  GMT  writes  out  grid  as single precision floats in a COARDS-complaint netCDF file format.
       However, GMT is able to produce grid files in many  other  commonly  used  grid  file  formats  and  also
       facilitates  so  called  "packing" of grids, writing out floating point data as 1- or 2-byte integers. To
       specify the precision, scale and offset, the user should add the suffix  =id[/scale/offset[/nan]],  where
       id  is  a  two-letter  identifier of the grid type and precision, and scale and offset are optional scale
       factor and offset to be applied to all grid values, and nan is the value used to indicate  missing  data.
       In  case  the  two  characters  id  is not provided, as in =/scale than a id=nf is assumed.  When reading
       grids, the format is generally automatically recognized. If not, the same suffix can be  added  to  input
       grid  file names. See grdconvert and Section grid-file-format of the GMT Technical Reference and Cookbook
       for more information.

       When reading a netCDF  file  that  contains  multiple  grids,  GMT  will  read,  by  default,  the  first
       2-dimensional  grid  that  can  find  in  that  file.  To coax GMT into reading another multi-dimensional
       variable in the grid file, append ?varname to the file name, where varname is the name of  the  variable.
       Note that you may need to escape the special meaning of ? in your shell program by putting a backslash in
       front of it, or by placing the filename and suffix between quotes or double quotes. The  ?varname  suffix
       can  also  be  used  for  output  grids  to  specify a variable name different from the default: "z". See
       grdconvert and Sections modifiers-for-CF and grid-file-format of the GMT Technical Reference and Cookbook
       for more information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.

TIME COORDINATES

       Time  coordinates  in  netCDF  grids,  be  it  the x, y, or z coordinate, will be recognized as such. The
       variable's unit attribute is parsed to determine the unit and epoch of the time coordinate in  the  grid.
       Values  are  then  converted  to  the  internal  time system specified by TIME_UNIT and TIME_EPOCH in the
       gmt.conf file or on the command line. The default output  is  relative  time  in  that  time  system,  or
       absolute time when using the option -f0T, -f1T, or -f2T for x, y, or z coordinate, respectively.

EXAMPLES

       To edit individual values in the 5' by 5' hawaii_grv.nc file, dump the .nc to ASCII:

              gmt grd2xyz hawaii_grv.nc > hawaii_grv.xyz

       To  write  a single precision binary file without the x,y positions from the file raw_data.nc file, using
       scanline orientation, run

              gmt grd2xyz raw_data.nc -ZTLf > hawaii_grv.b

SEE ALSO

       gmt.conf, gmt, grdedit, grdconvert, xyz2grd

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe