grdblend
Blend several partially overlapping grids into one larger grid
Synopsis
gmt grdblend [ blendfile | grid1 grid2 … ] -Goutgrid -Iincrement -Rregion [ -Cf|l|o|u[+n|p] ] [ -Q ] [ -Zscale ] [ -V[level] ] [ -W[z] ] [ -dinodata[+ccol] ] [ -fflags ] [ -nflags ] [ -rreg ] [ --PAR=value ]
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
- 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 -rreg) will first be resampled via grdsample. Also, grids that are not in netCDF or native binary format will first be reformatted via grdconvert.
Each input grid has its full region (heavy line) and optionally an inner region (dashed line). The area between these bounds are subject to cosine tapering, where the weight will go from 0 to 1 (or the specified relative weight per grid). Any output grid node is then a weighted sum of the grids that overlap the node. Blue line shows a crossection of how the blending and tapering works.
- -Goutgrid
outgrid is the name of the binary output grid file. (See Grid File Formats). 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.
- -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
- -Cf|l|o|u[+n|p]
Clobber mode: Instead of blending, simply pick the value of one of the grids that covers a node. Select from the following directives:
f - Select the first grid to visit a node.
l - Select the grid with the lowest value.
o - Select the last grid to visit a node.
u - Select the grid with the uppermost value.
For directives 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. Optionally, append one of two modifiers. If given then we always initialize output to equal the first grid but then for subsequent grids we only consider them per node accordingly:
+n - Only consider a grid where the values are \(z \le 0\) (i.e., negative).
+p - Only consider a grid where the values are \(z \ge 0\) (i.e., positive).
Blending is just one option what happens in areas of overlap. The dashed lines indicates the “inner” regions where the relative weights are 1 and between the dashed lines and the grid borders the relative weights are cosine-tapered down to 0.
- -Q
Create plain header-less grid file (for use with external tools). Requires that the output grid file is a native format (i.e., not netCDF).
- -V[level]
Select verbosity level [w]. (See full description) (See technical reference).
- -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].
- -dinodata[+ccol] (more …)
Replace input columns that equal nodata with NaN. Also sets nodes with no input constraints to this value [Default is NaN].
- -f[i|o]colinfo (more …)
Specify data types of input and/or output columns.
- -n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more …)
Select interpolation mode for grids.
- -r[g|p] (more …)
Set node registration [gridline].
- -^ 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.
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
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 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.