Ubuntu Manpage: grdblend - Blend several partially over-lapping grids into one large grid

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

NAME

       grdblend - Blend several partially over-lapping grids into one large grid

SYNOPSIS

       grdblend  [  blendfile  | grid1 grid2 ... ] outgrid [ increment ] [ region ] [ f|l|o|u ] [
       nodata ] [  ] [ scale ] [ [level] ] [ [z] ] [ -f<flags> ] [ -r ]

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

DESCRIPTION

       grdblend reads a listing of grid files and blend parameters and creates a binary grid file
       by  blending  the  other grids using cosine-taper weights. grdblend 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
       weighted average value. Any input grid that does not share the final  output  grid's  node
       registration  and  grid  spacing  will  automatically be resampled via calls to grdsample.
       Note: Due to the row-by-row i/o nature of operations  in  grdblend  we  only  support  the
       netCDF and native binary grid formats for both input and output.

REQUIRED ARGUMENTS

       -Goutgrid
              outgrid  is the name of the binary output grid file. (See GRID FILE FORMATS below).
              Only netCDF and native binary grid formats  are  can  be  written  directly.  Other
              output  format  choices will be handled by reformatting the output once blending is
              complete.

       -Ixinc[unit][=|+][/yinc[unit][=|+]]
              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, nautical
              mile or US survey foot, respectively, and  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 given but set to 0 it will be reset equal  to  x_inc;
              otherwise  it  will  be  converted  to  degrees  latitude. All coordinates: If = 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  +  to the supplied integer
              argument; the increment is then recalculated from  the  number  of  nodes  and  the
              domain.  The  resulting  increment  value  depends  on  whether you have selected a
              gridline-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.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest.

OPTIONAL ARGUMENTS

blendfile
ASCII file with one record per grid file to include in the blend. Each record may
contain up to three items, separated by spaces or tabs: the gridfile name
(required), the -R-setting for the interior region (optional), and the relative
weight wr (optional). In the combined weighting scheme, this grid will be given
zero weight outside its domain, weight = wr inside the interior region, and a 2-D
cosine-tapered weight between those end-members in the boundary strip. However, if
a negative wr is given then the sense of tapering is inverted (i.e., zero weight
inside its domain). If the inner region should instead exactly match the grid
region then specify a - instead of the -R-setting, or leave it off entirely.
Likewise, if a weight wr is not specified we default to a weight of 1. If the
ASCII blendfile file is not given grdblend will read standard input. Alternatively,
if you have more than one grid file to blend and you wish (a) all input grids to
have the same weight (1) and (b) all grids should use their actual region as the
interior region, then you may simply list all the grids on the command line instead
of providing a blendfile. You must specify at least 2 input grids for this
mechanism to work. Any grid that is not co-registered with the desired output
layout implied by -R, -I (and -r) will first be resampled via grdsample. Also,
grids that are not in netCDF or native binary format will first be reformatted via
grdconvert.

-C Clobber mode: Instead of blending, simply pick the value of one of the grids that
covers a node. Select from the following modes: f for the first grid to visit a
node; o for the last grid to visit a node; l for the grid with the lowest value,
and u for the grid with the uppermost value. For modes f and o the ordering of
grids in the blendfile will dictate which grid contributes to the final result.
Weights and cosine tapering are not considered when clobber mode is active.

-Nnodata
No data. Set nodes with no input grid to this value [Default is NaN].

-Q Create a header-less grid file suitable for use with grdraster. Requires that the
output grid file is a native format (i.e., not netCDF).

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

-W[z] Do not blend, just output the weights used for each node [Default makes the blend].
Append z to write the weight*z sum instead.

-Zscale
Scale output values by scale before writing to file. [1].

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

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

-^ 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.

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.  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  "z".  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 "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.

TAPERING

       While the weights computed are tapered from 1 to 0, we are computing weighted averages, so
       if there is only a single grid given then the weighted output will  be  identical  to  the
       input.   If  you  are  looking  for  a  way  to  taper your data grid, see grdmath's TAPER
       operator.

EXAMPLES

       To create a grid file from the four grid files piece_?.nc, giving them each the  different
       weights, make the blendfile like this

              piece_1.nc -R<subregion_1> 1
              piece_2.nc -R<subregion_2> 1.5
              piece_3.nc -R<subregion_3> 0.9
              piece_4.nc -R<subregion_4> 1

       Then run

              gmt grdblend blend.job -Gblend.nc -R<full_region> -I<dx/dy> -V

       To blend all the grids called MB_*.nc given them all equal weight, try

              gmt grdblend MB_*.nc -Gblend.nc -R<full_region> -I<dx/dy> -V

WARNING ON LARGE FILE SETS

       While  grdblend can process any number of files, it works by keeping those files open that
       are being blended, and close files as soon  as  they  are  finished.   Depending  on  your
       session,  many  files may remain open at the same time.  Some operating systems set fairly
       modest default limits on how many concurrent files can be open, e.g.,  256.   If  you  run
       into  this problem then you can change this limit; see your operating system documentation
       for how to change system limits.

COPYRIGHT

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