xyz2grd

Convert data table to a grid

Synopsis

gmt xyz2grd [ table ] -Goutgrid -Iincrement -Rregion [ -A[d|f|l|m|n|r|S|s|u|z] ] [ -D[+xxname][+yyname][+zzname][+c[-|cpt]][+ddname][+sscale][+ooffset][+ninvalid][+ttitle][+rremark][+vvarname] ] [ -Jparameters ] [ -S[zfile] ] [ -V[level] ] [ -Z[flags] ] [ -bibinary ] [ -dinodata[+ccol] ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -qiflags ] [ -rreg ] [ -wflags ] [ -:[i|o] ] [ --PAR=value ]

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

Description

xyz2grd reads one or more x, y, z or z 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 organized in a number 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

table

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

-Goutgrid[=ID][+ddivisor][+ninvalid][+ooffset|a][+sscale|a][:driver[dataType][+coptions]]

Optionally, append =ID for writing a specific file format. The following modifiers are supported:

  • +d - Divide data values by given divisor [Default is 1].

  • +n - Replace data values matching invalid with a NaN.

  • +o - Offset data values by the given offset, or append a for automatic range offset to preserve precision for integer grids [Default is 0].

  • +s - Scale data values by the given scale, or append a for automatic scaling to preserve precision for integer grids [Default is 1].

Note: Any offset is added before any scaling. +sa also sets +oa (unless overridden). To write specific formats via GDAL, use =gd and supply driver (and optionally dataType) and/or one or more concatenated GDAL -co options using +c. See the “Writing grids and images” cookbook section for more details.

-Ix_inc[+e|n][/y_inc[+e|n]]

Set the grid spacing as x_inc [and optionally y_inc].

Geographical (degrees) coordinates: Optionally, append an increment unit. Choose among:

  • d - Indicate arc degrees

  • m - Indicate arc minutes

  • s - Indicate arc seconds

If one of e (meter), f (foot), k (km), M (mile), n (nautical mile) or u (US survey foot), the increment will be converted to the equivalent degrees longitude at the middle latitude of the region (the conversion depends on PROJ_ELLIPSOID). If y_inc is not given or given but set to 0 it will be reset equal to x_inc; otherwise it will be converted to degrees latitude.

All coordinates: The following modifiers are supported:

  • +e - Slightly adjust the max x (east) or y (north) to fit exactly the given increment if needed [Default is to slightly adjust the increment to fit the given domain].

  • +n - Define the number of nodes rather than the increment, in which case the increment is recalculated from the number of nodes, the registration (see GMT File Formats), and the domain. Note: If -Rgrdfile is used then the grid spacing and the registration have already been initialized; use -I and -R to override these values.

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See technical reference).

Optional Arguments

-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 a desired directive:

  • d: Find the difference between the maximum and minimum values at each node.

  • f: Simply keep the first data point that was assigned to each node.

  • l: Find the lowest (minimum) value at each node.

  • m: Compute the mean of all values falling to each node [Default].

  • n: Report 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).

  • r: Compute the rms of all values falling to each node.

  • S: Compute the standard deviation of all values falling to each node.

  • s: Simply keep the last data point that was assigned to each node.

  • u: Find the upper (maximum) value at each node.

  • z: Report sum of multiple values that belong to the same node.

-D[+xxname][+yyname][+zzname][+c[-|cpt]][+ddname][+sscale][+ooffset][+ninvalid][+ttitle][+rremark][+vvarname]

Control names and units of netCDF grid and cube meta-data. For dimensions with units, add the unit in square bracket (e.g., “distance [km]”). Select one or more of these modifiers:

  • +c - Append cpt to set a default CPT for this grid [turbo] or give - to remove any default CPT already set.

  • +d - Set dname, the data value name.

  • +n - Set the invalid number used to indicate a NaN or missing value.

  • +o - Set the offset to add to data after first scaling the data [0].

  • +r - Set a remark used for this grid (any sentence you prefer).

  • +s - Set the scale used fto multiply data values after they are read [1].

  • +t - Set a title used for this grid (any sentence you prefer).

  • +v - Append varname, the variable name of the data set.

  • +x - Append xname, the name of the x-coordinate (and optional unit in brackets).

  • +y - Append yname, the name of the y-coordinate (and optional unit in brackets).

  • +z - For 3-D cubes; append zname, the name of the z-coordinate (and optional unit in brackets).

Give a blank name to completely reset a particular string. Use quotes to group texts with more than one word. If any of your text contains plus symbols you need to escape them (place a backslash before each plus-sign) so they are not confused with the option modifiers. Alternatively, you can place the entire double-quoted string inside single quotes. If you have shell variables that contain plus symbols you cannot use single quotes but you can escape the plus symbols in a variable using constructs like ${variable/+/\+}. Note that for geographic grids and cubes (-fg), xname and yname are set automatically. Normally, the data netCDF variable is called “z” (grid) or “cube” (data cube). You can rename this netCDF variable via +v.

-Jparameters

Specify the projection. Use the -J syntax to save the georeferencing info as CF-1 compliant metadata in netCDF grids. Remember also that PROJ syntax can be used directly in -J. This referencing will be recognized by GDAL and increasingly also by GMT.

-S[zfile]

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

-V[level]

Select verbosity level [w]. (See full description) (See technical reference).

-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 column 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. The difference between A and a is that the latter can decode both dateTclock and ddd:mm:ss[.xx] formats but expects each input record to have a single value, while the former can handle multiple values per record but can only parse regular floating point values. Translate incoming z-values via the -i0 option and needed modifiers.

-birecord[+b|l] (more …)

Select native binary format for primary table input. [Default is 3 input columns]. This option only applies to x, y, z input files; see -Z for z tables.

-dinodata[+ccol] (more …)

Replace input columns that equal nodata with NaN. Also sets nodes with no input x, y, z triplet to this value [Default is NaN].

-e[~]“pattern” | -e[~]/regexp/[i] (more …)

Only accept data records that match the given pattern.

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

Skip or produce header record(s). Not used with binary data.

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …)

Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-qi[~]rows|limits[+ccol][+a|t|s] (more …)

Select input rows or data limit(s) [default is all rows].

-r[g|p] (more …)

Set node registration [gridline].

-wy|a|w|d|h|m|s|cperiod[/phase][+ccol] (more …)

Convert an input coordinate to a cyclical coordinate.

-:[i|o] (more …)

Swap 1st and 2nd column on input and/or output.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

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

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

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 precision once GMT operates on the grid or writes out new grids. To limit loss of precision when processing data you should always consider normalizing the data prior to processing.

Geographical And Time Coordinates

When the output grid type is netCDF, the coordinates will be labeled “longitude”, “latitude”, or “time” 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 type’s 23-bit mantissa may not be represented exactly. When -S is used no grids are implied and we read data into an intermediate double container. This means all but 64-bit integers can be represented using the double type’s 53-bit mantissa.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

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

gmt xyz2grd hawaii_grv.xyz -D+xdegree+ydegree+zGal+t"Hawaiian Gravity"+r"GRS-80 Ellipsoid used" \
            -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 scanline-oriented data topo30.b on the NCEI 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

To make a pixel node registrated tiff of the number of data points that is assigned to each node in a cartesian data set, use

gmt xyz2grd data.txt -R0/100/0/100 -r -I10 -An -Gnumber_of_points.tif=gd:GTiff

See Also

gmt, grd2xyz, grdedit, grdconvert, greenspline, nearneighbor, surface, triangulate