grd2xyz

grd2xyz(cmd0::String="", arg1=nothing, kwargs...)

keywords: GMT, Julia, grid

Convert grid to data table

Description

Reads a grid (from file or a Grid type object) and writes out xyz-triplets in ASCII [or binary] format to file or return them as a Julia variable. Modify the precision of the ASCII output format by editing the FORMAT_FLOAT_OUT parameter in your gmt.conf file or use par=(FORMATFLOATOUT=format,) or choose binary output using single or double precision storage. As an option you may output z-values without the (x,y) coordinates (see onecol below) or you can save the grid in the STL format for 3-D printers.

Required Arguments

ingrid : – A grid file name or a Grid type

Optional Arguments

• C or rowcol or row_col : – rowcol=true | rowcol=:f|:i
  Replace the x- and y-coordinates on output with the corresponding column and row numbers. These start at 0 (C-style counting); use rowcol=:f to start at 1 (Fortran-style counting). Alternatively, use rowcol=: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.

• L or hvline : – hvline=:c|:r|:x|:yvalue
  Limit the output of records to a single row or column. Identify the desired vector either by row or column number (via directives :c or :r), or by the constant x or y value (via directives :x or :y). If your selection is outside the valid range then no output will result and a warning is issued. Note: For directives :x and :y we find the nearest column or row, respectively.

• R or region or limits : – limits=(xmin, xmax, ymin, ymax) | limits=(BB=(xmin, xmax, ymin, ymax),) | limits=(LLUR=(xmin, xmax, ymin, ymax),units="unit") | ...more
  Specify the region of interest. More at limits. For perspective view view, optionally add zmin,zmax. This option may be used to indicate the range used for the 3-D axes. You may ask for a larger w/e/s/n region to have more room between the image and the axes.

• T or stl or STL : – STL=true | STL=[:b][base]
  Write STL triangulation for 3-D printing to standard output. By default we write an STL ASCII file. Append b to instead write the STL binary (little-endian) format. For more information on STL, see the STL overview on Wikipedia. Note: All coordinates are adjusted so that xmin = ymin = zmin = 0. For other adjustments, see grdedit and grdproject Optionally, append a lower base other than the grid's minimum value [Default]. Note: The grid must be free of NaN values. If your grid contains NaNs then we automatically replace these with the minimum value in the grid.

• V or verbose : – verbose=true | verbose=level
  Select verbosity level. More at verbose

• W or weight : – weight=true | weight=:a[+uunit] | weight=weight
  Write out x,y,z,w, where w is the supplied weight (or 1 if not supplied) [Default writes x,y,z only]. Choose weight=:a to compute weights equal to the area each node represents. For Cartesian grids this is simply the product of the x and y increments (except for gridline-registered grids at all sides [half] and corners [quarter]). For geographic grids we default to a length unit of k (hence area is in km^2). Change this by appending +uunit (see Units). For such grids, the area varies with latitude and also sees special cases for gridline-registered layouts at sides, corners, and poles.

• Z or onecol or one_col : – onecol="flags"
  Write (or return) a 1-column 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: **onecol=:TLa**. **NOTE**, to write on a disk file one must use the **save="file"** option, otherwise data is return to Julia and the type options above are ignored. In that case, data is always Float64.

• name or save : – save="file"
  Save data to disk file with save="file".

• bo or binary_out : – binary_out=??
  Select native binary format for table output. More at

• di or nodata_in : – nodata_in=??
  Substitute specific values with NaN. More at

• f or colinfo : – colinfo=??
  Specify the data types of input and/or output columns (time or geographical data). More at

• h or header : – header=??
  Specify that input and/or output file(s) have n header records. More at

• o or outcol : – outcol=??
  Select specific data columns for primary output, in arbitrary order. More at

• q or inrows : – inrows=??
  Select specific data rows to be read and/or written. More at

• s or skiprows or skip_NaN : – skip_NaN=true | skip_NaN="<cols[+a][+r]>"
  Suppress output of data records whose z-value(s) equal NaN. More at

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default unless stated otherwise], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

Non-equidistant x/y Coordinates

In general, GMT modules cannot accept grids with variable x and/or y coordinates as most algorithms and plotting options expect equidistant grids. However, you can use grd2xyz to dump the original x y z triplets and then reprocess the data onto an equidistant lattice via greenspline, nearneighbor or surface, for instance.

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 colinfo="0T", colinfo="1T", or colinfo="2T" for x, y, or z coordinate, respectively.

Row Order

The hvline=:r option allows you to output a specific row in the grid. Note that while a grid's y-coordinates are positive up, internal row numbers are scanline numbers and hence positive down. Therefore, the first row (0) coincides with the largest y-value. This means that hvline=:r0 and hvline=:y<ymax> (for the correct maximum y-value) will yield the same result. In contrast, both x and column numbers are positive to the right, with hvline=:c0 and hvline=:x<xmin> (for the correct minimum x-value) yielding the same output.

Examples

To edit individual values in the 2' by 2' remote AFR.nc file, dump the .nc to Dataset type. That is, return data in a Julia variable, do

D = grd2xyz("@AFR.nc")

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

grd2xyz("@AFR.nc", onecol=:TLf, save="AFR.b")

To write out lon, lat, topo, area from the @AFR.nc file, selecting meter^2 as the area unit, and where area reflects the size of each grid box, run:

grd2xyz("@AFR.nc", weight="a+ue", save="AFR.txt")

See Also

grdedit, grdconvert, xyz2grd