## NAME

           xyz2grd - Converting an ASCII or binary table to grd file format

## SYNOPSIS

           xyz2grd        xyzfile        -Ggrdfile       -Ix_inc[m|c][/y_inc[m|c]]
           -Rwest/east/south/north[r]     [     -A[n|z|u|l]     ]     [      -Dxu-
           nit/yunit/zunit/scale/offset/title/remark ] [ -F ] [ -H[nrec] ] [ -Nno-
           data ] [ -S[zfile] ] [ -V ] [ -Z[flags] ]  [  -:  ]  [  -bi[s][n]  ]  [
           -f[i|o]colinfo ]

## DESCRIPTION

           xyz2grd  reads  a  z or xyz table and creates a binary grdfile. xyz2grd
           will report if some of the nodes are not  filled  in  with  data.  Such
           unconstrained  nodes  are set to a value specified by the user [Default
           is NaN].  Nodes with more than one value will be  set  to  the  average
           value. As an option (using -Z), a 1-column z-table may be read assuming
           all nodes are present (z-tables can be in organized in a number of for-
           mats, see -Z below.)

           [xy]zfile
                  ASCII [or binary] file holding z or (x,y,z) values. xyz triplets
                  do not have to be sorted (for binary triplets, see -b). 1-column
                  z tables must be sorted and the -Z must be set).

           -G     grdfile is the name of the binary output grdfile.

           -I     x_inc  [and  optionally  y_inc] is the grid spacing. Append m to
                  indicate minutes or c to indicate seconds.

           -R     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
                  geographic  regions,  these  limits  correspond  to  west, east,
                  south, and north and you may specify them in decimal degrees  or
                  in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
                  and upper right map coordinates are given instead of  wesn.  The
                  two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
                  -180/+180 in longitude respectively, with -90/+90 in  latitude).
                  For  calendar time coordinates you may either give relative time
                  (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
                  TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
                  [date]T[clock] (append T to -JX|x). At least  one  of  date  and
                  clock must be present; the T is always required. The date string
                  must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
                  yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
                  be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
                  type  and  positions must be as indicated (however, input/output
                  and plotting formats are flexible).

## OPTIONS

           -A     Add up multiple values that belong to the  same  node  (same  as
                  -Az).   Append  n to simply count the number of data points that
                  were assigned to each node.  Append l or u to  find  the  lowest
                  (minimum)  or  upper (maximum) value at each node, respectively.
                  [Default (no -A option) will calculate mean value].  Ignored  if
                  -Z is given.

           -D     Give  values  for xunit, yunit, zunit, scale, offset, title, and
                  remark.  To leave some of these values untouched, specify  =  as
                  the value.

           -F     Force pixel registration [Default is grid registration].

           -H     Input file(s) has Header record(s). Number of header records can
                  be changed by editing your  .gmtdefaults4  file.  If  used,  GMT
                  default  is  1  header record. Use -Hi if only input data should
                  have header records [Default will write out  header  records  if
                  the input data have them].  Not used with binary data.

           -N     No  data.  Set  nodes  with  no  input xyz triplet to this value
                  [Default is NaN]. For z-tables, this option is used  to  replace
                  z-values that equal nodata with NaN.

           -S     Swap the byte-order of the input only. No grid file is produced.
                  You must also supply the -Z option. The  output  is  written  to
                  zfile (or stdout if not supplied).

           -V     Selects verbose mode, which will send progress reports to stderr
                  [Default runs "silently"].

           -Z     Read a 1-column ASCII [or binary] table. This assumes  that  all
                  the nodes are present and sorted according to specified ordering
                  convention contained in  flags.   If  incoming  data  represents
                  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  indi-
                  cate that first element is 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 data are periodic  in  x  but  the
                  incoming data do not contain the (redundant) column at x = xmax,
                  append x. For data periodic in y without redundant row  at  y  =
                  ymax,  append  y.  Append sn to skip the first n number of bytes
                  (probably a header). If the  byte-order  needs  to  be  swapped,
                  append  w.  Select  one of several data types (all binary except
                  a):

                          a ASCII representation
                          c signed 1-byte character
                          u unsigned 1-byte character
                          h short 2-byte integer
                          i 4-byte integer
                          l long (4- or 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 input.

           -:     Toggles  between  (longitude,latitude)  and (latitude,longitude)
                  input and/or output. [Default is (longitude,latitude)].   Append
                  i  to  select  input  only  or o to select output only. [Default
                  affects both].

           -bi    Selects binary input. Append s for single precision [Default  is
                  double].   Append  n  for  the  number  of columns in the binary
                  file(s).
                  [Default is 3 input columns]. This option only  applies  to  xyz
                  input files; see -Z for z tables.

           -f     Special  formatting  of  input  and output columns (time or geo-
                  graphical data) Specify i(nput) or  o(utput)  [Default  is  both
                  input  and output].  Give one or more columns (or column ranges)
                  separated by commas.  Append T (Absolute calendar time), t (time
                  relative  to  chosen TIME_EPOCH), x (longitude), y (latitude), g
                  (geographic coordinate), or f (floating point) to each column or
                  column range item.

## EXAMPLES

           To create a grdfile from the ASCII data in hawaii_grv.xyz, use

           xyz2grd    hawaii_grv.xyz    -Ddegree/degree/mGal/1/0/"Hawaiian   Grav-
           ity"/"GRS-80 Ellipsoid used" -Ghawaii_grv_new.grd -R198/208/18/25  -I5m
           -V

           To  create  a  grdfile from the raw binary (3-column, single-precision)
           scanline-oriented data raw.b, use

           xyz2grd raw.b -Dm/m/m/1/0/=/= -Graw.grd -R0/100/0/100 -I1 -V -Z -b3

           To make a grdfile from the raw binary USGS DEM  (short  integer)  scan-
           line-oriented  data topo30. on the NGDC global relief Data CD-ROM, with
           values of -9999 indicate missing data, one must on some machine reverse
           the byte-order. On such machines (like Sun), use

           xyz2grd  topo30.  -Dm/m/m/1/0/=/=  -Gustopo.grd  -R234/294/24/50  -I30c
           -N-9999 -V -ZTLhw

           Say you have received a binary file with 4-byte  floating  points  that
           were  written  on a machine of different byte-order than yours. You can
           swap the byte-order with

           xyz2grd floats.bin -Snew_floats.bin -V -Zf

## SEE ALSO

           gmt(l), grd2xyz(l), grdedit(l)

    GMT4.0                            1 Oct 2004                        XYZ2GRD(l)