manpagez: man pages & more
man xyz2grd(1)
Home | html | info | man
xyz2grd(1)                            GMT                           xyz2grd(1)




NAME

       xyz2grd - Convert data table to a grid file


SYNOPSIS

       xyz2grd [ table ]  -Ggrdfile
        -Iincrement
        -Rregion         [          -A[d|f|l|m|n|r|S|s|u|z]         ]        [
       -D[+xxname][+yyname][+zzname][+sscale][+ooffset][+ninvalid][+tti-
       tle][+rremark]  ] [  -S[zfile] ] [  -V[level] ] [  -Z[flags] ] [ -bibi-
       nary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ]
       [ -r ] [ -:[i|o] ]

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


DESCRIPTION

       xyz2grd reads one or more z or xyz tables and  creates  a  binary  grid
       file.  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
       mean 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 num-
       ber of formats, see -Z below.)  Note: xyz2grd does not grid  the  data,
       it  simply  reformats existing data to a grid structure.  For gridding,
       see surface, greenspline, nearneighbor, or triangulate.


REQUIRED ARGUMENTS

       -Ggrdfile
              grdfile is the name of the binary output grid  file.  (See  GRID
              FILE FORMAT below.)

       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
              x_inc  [and  optionally  y_inc] is the grid spacing. Optionally,
              append a suffix modifier.  Geographical  (degrees)  coordinates:
              Append  m  to indicate arc minutes or s to indicate arc seconds.
              If one of the units e, f, k, M, n or u is appended instead,  the
              increment  is assumed to be given in meter, foot, km, Mile, nau-
              tical mile or US survey foot, respectively,  and  will  be  con-
              verted  to  the equivalent degrees longitude at the middle lati-
              tude of the region (the conversion depends  on  PROJ_ELLIPSOID).
              If  y_inc is given but set to 0 it will be reset equal to x_inc;
              otherwise it will be converted to degrees latitude. All  coordi-
              nates:  If +e is appended then the corresponding max x (east) or
              y (north) may be slightly adjusted  to  fit  exactly  the  given
              increment  [by default the increment may be adjusted slightly to
              fit the given domain]. Finally, instead of giving  an  increment
              you  may  specify the number of nodes desired by appending +n to
              the supplied integer argument; the increment  is  then  recalcu-
              lated  from  the  number  of nodes and the domain. The resulting
              increment value depends on whether you  have  selected  a  grid-
              line-registered  or  pixel-registered grid; see App-file-formats
              for details. Note: if -Rgrdfile is used then  the  grid  spacing
              has already been initialized; use -I to override the values.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
              Specify the region of interest.


OPTIONAL ARGUMENTS

       table  One  or  more  ASCII  [or  binary,  see  -bi] files holding z or
              (x,y,z) values. The xyz triplets  do  not  have  to  be  sorted.
              One-column z tables must be sorted and the -Z must be set.

       -A[d|f|l|m|n|r|S|s|u|z]
              By  default  we  will  calculate mean values if multiple entries
              fall on the same node. Use -A to change this behavior, except it
              is  ignored  if  -Z  is  given. Append f or s to simply keep the
              first or last data point that was assigned to each node.  Append
              l  or  u  or  d  to find the lowest (minimum) or upper (maximum)
              value or the difference between the maximum and miminum value at
              each  node,  respectively. Append m or r or S to compute mean or
              RMS value or standard  deviation  at  each  node,  respectively.
              Append  n  to  simply  count the number of data points that were
              assigned to each node (this only requires two  input  columns  x
              and  y  as  z is not consulted). Append z to sum multiple values
              that belong to the same node.

       -D[+xxname][+yyname][+zzname][+sscale][+ooffset][+ninvalid][+tti-
       tle][+rremark]
              Give one or more combinations for  values  xname,  yname,  zname
              (give  the  names of those variables and in square bracket their
              units, e.g., adistance [km]a), scale (to  multiply  grid  values
              after  read  [normally 1]), offset (to add to grid after scaling
              [normally 0]),  invalid  (a  value  to  represent  missing  data
              [NaN]),  title  (anything  you  like),  and remark (anything you
              like). Items not listed will remain  untouched.   Give  a  blank
              name  to  completely  reset  a particular string.  Use quotes to
              group texts with more than one word.  Note that  for  geographic
              grids (-fg) xname and yname are set automatically.

       -S[zfile]
              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[level] (more a|)
              Select verbosity level [c].

       -Z[flags]
              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 indicate that
              first element is at left or right end of row. Likewise for  col-
              umn  formats:  start  with  L or R to position first column, and
              then append T or B to position first element  in  a  row.  Note:
              These two row/column indicators are only required for grids; for
              other tables they do not apply. 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  or  the  words needs to be swapped, append w. Select
              one of several data types (all binary except a):

              A ASCII representation of one or more floating point values  per
              record

              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, signed 2-byte integer

              H uint16_t, unsigned 2-byte integer

              i int32_t, signed 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  input.  The  difference
              between  A  and  a is that the latter can decode both dateTclock
              and ddd:mm:ss[.xx] formats while the former is strictly for reg-
              ular floating point values.

       -bi[ncols][t] (more a|)
              Select  native  binary input. [Default is 3 input columns]. This
              option only applies to xyz input files; see -Z for z tables.

       -dinodata (more a|)
              Replace input columns that equal  nodata  with  NaN.  Also  sets
              nodes  with no input xyz triplet to this value [Default is NaN].

       -e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
              Skip or produce header record(s). Not used with binary data.

       -icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
              Select input columns and transformations (0 is first column).

       -r (more a|)
              Set pixel node registration [gridline].

       -:[i|o] (more a|)
              Swap 1st and 2nd column on input and/or output.

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

       -+ or just +
              Print  an extensive usage (help) message, including the explana-
              tion 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 all options, then exits.


GRID VALUES PRECISION

       Regardless of the precision of the input data, GMT programs that create
       grid  files  will  internally  hold  the grids in 4-byte floating point
       arrays. This is done to conserve memory and furthermore most if not all
       real  data  can be stored using 4-byte floating point values. Data with
       higher precision (i.e., double precision values) will lose that  preci-
       sion  once  GMT  operates on the grid or writes out new grids. To limit
       loss of precision when processing data you should always consider  nor-
       malizing the data prior to processing.


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 apackinga of grids, writing  out  floating  point
       data as 1- or 2-byte integers. To specify the precision, scale and off-
       set, the user should add the suffix  =ID[+sscale][+ooffset][+ninvalid],
       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  invalid  is the value used to indicate missing
       data. See grdconvert and Section grid-file-format of the GMT  Technical
       Reference and Cookbook for more information.

       When  writing  a  netCDF  file,  the grid is stored by default with the
       variable name aza. To specify another  variable  name  varname,  append
       ?varname to the file name. 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.


GEOGRAPHICAL AND TIME COORDINATES

       When the output grid type is netCDF, the coordinates  will  be  labeled
       alongitudea, alatitudea, or atimea based on the attributes of the input
       data or grid (if any) or on the -f or -R  options.  For  example,  both
       -f0x  -f1t  and  -R90w/90e/0t/3t  will result in a longitude/time grid.
       When the x, y, or z coordinate is time, it will be stored in  the  grid
       as  relative  time since epoch as specified by TIME_UNIT and TIME_EPOCH
       in the gmt.conf file or on the command  line.  In  addition,  the  unit
       attribute  of the time variable will indicate both this unit and epoch.


SWAPPING LIMITATIONS

       All data types can be read, even 64-bit integers, but internally  grids
       are  stored  using  floats.  Hence,  integer values exceeding the float
       typeas 23-bit mantissa may not be represented exactly. When -S is  used
       no  grids are implied and we read data into an intermediate double con-
       tainer. This means all but 64-bit integers can be represented using the
       double typeas 53-bit mantissa.


EXAMPLES

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

          gmt  xyz2grd hawaii_grv.xyz -D+xdegree+ydegree+zGal+taHawaiian Grav-
          itya+raGRS-80 Ellipsoid useda
                 -Ghawaii_grv_new.nc -R198/208/18/25 -I5m -V

       To  create  a grid file from the raw binary (3-column, single-precision
       scanline-oriented data raw.b, use
          gmt xyz2grd raw.b -D+xm+ym+zm -Graw.nc -R0/100/0/100 -I1 -V -Z -bi3f

       To  make  a grid file from the raw binary USGS DEM (short integer scan-
       line-oriented data topo30.b 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
          gmt xyz2grd topo30.b -D+xm+ym+zm -Gustopo.nc  -R234/294/24/50  -I30s
          -di-9999 -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
          gmt xyz2grd floats.bin -Snew_floats.bin -V -Zf


SEE ALSO

       gmt(1), grd2xyz(1), grdedit(1), grdconvert(1), greenspline(1),
       nearneighbor(1), surface(1), triangulate(1)


COPYRIGHT

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



5.4.2                            Jun 24, 2017                       xyz2grd(1)

gmt5 5.4.2 - Generated Thu Jun 29 19:10:46 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.