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

5.2.1                                           January 28, 2016                                  GRDBLEND(1gmt)