merge2d

merge2d tiles or smoothly merges two-dimensional multiparameterNetCDF grids. It supports polygonal supports (i.e., clip files) and direct layer selection from three-dimensional NetCDF cubes.

Synopsis

gmt merge2d <grids|mergefile> -Goutput.nc [-Rregion -Iincrement] [options]

Behavior

Listing at least two grids directly tiles values in availability order. The first available value is retained by default. A mergefile enables primary and secondary pairing and contains records of the form:

primary [secondary] [polygon] [xwindow/ywindow] [rx1/rx2/ry1/ry2]

Each non-comment record contains up to five whitespace-separated fields:

primary

Required NetCDF source providing the primary field or fields.

secondary

Optional source paired with the primary. Pairing applies only within the primary support and does not extend beyond the primary domain. Use - for an unpaired fallback tile.

polygon

Optional xy polygon defining the primary support. The complete primary-grid domain is used when the polygon is omitted.

xwindow/ywindow

BLEND window functions for the x and y dimensions. The default is cosine/cosine.

rx1/rx2/ry1/ry2

Dimensionless taper ratios in [0, 0.5). One value applies everywhere, two apply symmetrically to x and y, and four control each side independently. rx1/rx2 apply at west/east (low/high x), and ry1/ry2 apply at south/north (low/high y). Every ratio defaults to 0.2.

Each ratio sets the fraction of the corresponding support extent used by the transition at one boundary. For example, for a rectangular support 100 coordinate units wide, rx1 = 0.2 gives a west transition approximately 20 units wide. Within each transition, the selected window controls how the primary merging-weight factor changes between its boundary value and 1. The paired secondary receives the complementary weight. The x and y factors are multiplied. Larger ratios give broader transitions and a smaller full-primary interior. 0 disables the taper on that side. The boxcar window ignores taper ratios and has unit weight throughout the support.

For a polygon support, BLEND evaluates the x and y tapers along local cross-sections of the polygon and adapts the transition width where a cross-section is too narrow for the nominal support-wide taper.

Use - to skip an optional field when supplying a later field. Trailing optional fields may be omitted. Add a secondary as a later unpaired record when it should provide fallback values outside a paired primary domain. For example:

primary.nc?vp secondary.nc?p support.txt cosine/cosine 0.25/0.25/0.25/0.25
secondary.nc?p - - - -

-R and -I set the output geometry. When omitted, merge2d uses the union of the input domains and their common increments and registration. Specify -I when increments differ and -r when registrations differ. Inputs that are not co-registered with the output are resampled using GMT -n.

The optional polygon must be strictly xy-monotone after it is mapped to the output grid. -ME replaces a non-monotone polygon with its strict envelope, while -MB uses the best piecewise strict envelope. Appending +w writes the converted polygon with a _monotone suffix. -A combines positive weights where primary supports that share the same secondary source overlap. Non-overlapping supports may use different secondaries with this option. See BLEND for more information.

Select NetCDF fields by appending ? and a comma-separated list, such as model.nc?vp,vs. Selected fields must share the same horizontal coordinates. If ? is omitted, the default grid variable is used. The -F option names output variables. It does not select input fields. Source selectors map positionally to -F, so model1.nc?vp,vs,den and model2.nc?p,s,d can both map to vp,vs,rho with -Fvp,vs,rho. A single selected variable keeps its source name when -F is omitted. Without a selector or -F, the output field is named z.

A two-dimensional layer can be read directly from a three-dimensional variable from a NetCDF cube. Square brackets select a zero-based layer index, while parentheses select the layer nearest to a coordinate value without vertical interpolation:

model.nc?vp[3],vs[3]
model.nc?vp(20),vs(20)

Indices begin at zero. Parentheses select the nearest coordinate without vertical interpolation. Give one layer selector for every selected field. Coordinate scaling precedes coordinate-value selection, while index selection remains positional. Each selected layer is materialized temporarily as a 2-D grid and removed after processing.

Input modifiers follow the field list. +x, +y, and +z scale source coordinates. +v supplies one broadcast field scale or one scale per selected field. Uppercase counterparts set target-unit metadata. +n declares an additional missing-value sentinel. Use file.nc?<field1,field2,...>+<modifiers> for named fields or file.nc?+<modifiers> for the default field. For example, model.nc?vp,vs+x0.001+Xkm+y0.001+Ykm+v0.001,0.001+Vkm/s,km/s scales x and y in m to km and both selected fields in m/s to km/s. Input transforms occur before gap filling, resampling, and merging. Input coordinate scaling does not reorder grid data. GMT supplies the retained x and y axes in increasing order, so input +x and +y scales must be positive. Use output -Z when the completed grid should use a decreasing coordinate convention.

The -Z option independently transforms the completed output. It scales coordinates and fields in place and does not reorder coordinates, fields, or weight. A negative axis scale therefore produces a decreasing output axis. For example, with -Fvp,vs, -Z+x0.001+Xkm+y0.001+Ykm+v0.001,0.001+Vkm/s,km/s converts x and y in m to km and both velocity fields in m/s to km/s.

-H fills strictly internal input holes before resampling and merging. The available methods are nearest neighbor (n), linear Delaunay (l), local weighted average (a), spline (s), and minimum curvature (m). Linear Delaunay (l) is the default. A maximum gap span can limit filling. Original values and missing regions connected to an input boundary are preserved. -P can then fill remaining primary NaNs from non-missing paired secondary values. Primary NaNs are preserved by default.

Declared NetCDF missing values, IEEE NaNs, selector +n sentinels, and -di are set to NaN. -W adds the fixed variable weight with long_name="merging weight" and units 1. -W+o writes only the coordinates and weight. All selected fields use the same weight. Processing is row-oriented so large output grids do not require every input field to be simultaneously held in memory.

Usage

gmt merge2d [gq] 6.5.0 [64-bit] - Tile or smoothly merge two-dimensional multiparameter NetCDF
  grids

usage: gmt merge2d [<mergefile> | <grid1> <grid2> ...] -G<output.nc> [-R<west>/<east>/<south>/⏎
  …<north>[+r]] [-I<xinc>[+e|n][/<yinc>[+e|n]]] [-A] [-Cf|l|o|u[+n|p]] [-F<fields>] [-H[n|l|a|s|⏎
  …m[<arg>]][+m<maxgap>]] [-ME|B[+w]] [-P] [-V[q|e|w|t|i|c|d]] [-W[+o]]
  [-Z+x<sx>[+X<xunit>]+y<sy>[+Y<yunit>]+v<scales>[+V<units>]] [-di<nodata>[+c<col>]] [-f[i|⏎
  …o]<colinfo>] [-n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]] [-r[g|p]] [--PAR=<value>]

  REQUIRED ARGUMENTS:

  <mergefile> | <grid1> <grid2> ...
     Supply one mergefile or list at least two NetCDF grids directly. Omit the input argument to
     read a mergefile from standard input. Direct inputs tile values in availability order and use
     first-value clobbering by default.
       Each non-comment mergefile record contains up to five whitespace-separated fields:
       primary: Required NetCDF source providing the primary field or fields.
       secondary: Optional NetCDF source paired with primary for merging. Use '-' for an unpaired
          fallback tile. Pairing is valid only within the primary support and does not extend the
          primary domain.
       clipfile: Optional xy polygon defining the primary support. Use '-' or omit it to use the
          complete primary-grid domain.
       xwindow/ywindow: BLEND window functions for the x and y dimensions. The default is cosine/⏎
          …cosine.
       rx1/rx2/ry1/ry2: Dimensionless taper ratios in [0, 0.5). One value applies to all sides, two
          values apply symmetrically to x and y, and four set the beginning and ending ratios
          independently. The default is 0.2 on every side.
       Each ratio sets the fraction of the corresponding support extent used by the transition at
          one boundary: rx1/rx2 apply at west/east (low/high x), and ry1/ry2 apply at south/north
          (low/high y). For a rectangular support 100 coordinate units wide, rx1 = 0.2 gives a west
          transition approximately 20 units wide.
       Within each transition, the selected window controls how the primary merging-weight factor
          changes between its boundary value and 1. The paired secondary receives the complementary
          weight. The x and y factors are multiplied. Larger ratios give broader transitions and a
          smaller full-primary interior. 0 disables the taper on that side. Boxcar ignores taper
          ratios and has unit weight throughout the support.
       For a polygon support, BLEND evaluates the x and y tapers along local cross-sections of the
          polygon and adapts the transition width where a cross-section is too narrow for the
          nominal support-wide taper.
       Use '-' to skip an optional field when supplying a later field. Trailing optional fields may
          be omitted. Blank and comment records are ignored.
       Example mergefile:
        primary.nc?vp secondary.nc?p support.txt cosine/cosine 0.25/0.25/0.25/0.25
        secondary.nc?p - - - -
       Select NetCDF fields with file.nc?field1,field2,... . Selected fields must share the same
          horizontal coordinates. If ? is omitted, the default grid variable is used.
       Select a layer from a 3-D variable with model.nc?vp[<index>] or model.nc?vp(<level>).
          Indices are zero-based. A coordinate value selects the nearest layer without vertical
          interpolation. Specify one layer selector for every selected field.
       Append input modifiers after the field list. +x, +y, and +z scale source coordinates. +v
          supplies one broadcast field scale or one scale per selected field. +X, +Y, +Z, and +V
          set target-unit metadata. +n declares an additional missing-value sentinel. Coordinate-
          value layer selection occurs after +z scaling, while index selection remains positional.
       Use file.nc?<field1,field2,...>+<modifiers> for named fields or file.nc?+<modifiers> to
          transform the default field without naming it. Input transforms are applied before gap
          filling, resampling, and merging.
       Input coordinate scaling does not reorder grid data. Unchanged x and y axes must remain
          strictly increasing after scaling. Because GMT supplies them in increasing order, input
          +x and +y scales must be positive. Use output -Z to write a decreasing final axis if
          desired.
       Example: model.nc?vp,vs+x0.001+Xkm+y0.001+Ykm+v0.001,0.001+Vkm/s,km/s selects vp and vs,
          scales x and y from m to km, and scales both fields from m/s to km/s.

  -G<output.nc>
     Write the final NetCDF grid. Multiparameter output stores all selected fields on the same
     coordinates.

  OPTIONAL ARGUMENTS:

  -R<west>/<east>/<south>/<north>[+r]
     Specify the min/max coordinates of your data region in user units. Use dd:mm[:ss] for regions
     given in arc degrees, minutes [and seconds]. Use -R<xmin>/<xmax>/<ymin>/<ymax>[+u<unit>] for
     regions given in projected coordinates, with <unit> selected from e|f|k|M|n|u [Default: e]. If
     +u is set, projected regions centered on (0,0) may be set via -R<halfwidth>[/⏎
     …<halfheight>]+u<unit>, where <halfheight> defaults to <halfwidth> if not given. Use
     [yyyy[-mm[-dd]]]T[hh[:mm[:ss[.xxx]]]] format for time axes. Append +r if -R specifies the
     coordinates of the lower left and upper right corners of a rectangular area.
     Alternatively, use -R<code><x0>/<y0>/<n_columns>/<n_rows> for origin and grid dimensions,
     where <code> is a 2-char combo from [T|M|B][L|C|R] (top/middle/bottom/left/center/right) and
     grid spacing must be specified via -I<dx>[/<dy>] (also see -r).
     Set the output region. If -R is omitted, use the union of the input-grid domains.

  -I<xinc>[+e|n][/<yinc>[+e|n]]
     Specify increment(s) and optionally append units or modifiers. For geographic regions in
     degrees you can optionally append units from this list: (d)egree [Default], (m)inute,
     (s)econd, m(e)ter, (f)oot, (k)ilometer, (M)ile, (n)autical mile, s(u)rvey foot.
       +e Adjust the region to fit increments [Adjust increment to fit domain].
       +n Increment specifies the number of nodes instead. Then, the actual increments are
          calculated from the given domain and node-registration settings (see Appendix B for
          details).
     Note: If -R<grdfile> was used then -I (and -R and maybe -r) have been set; use -I to override
     those increments.
     Set the output increments. If -I is omitted, use the common input increments. Specify -I when
     input increments differ and -r when input registrations differ. Inputs not co-registered with
     the output geometry are resampled using GMT -n.

  -A
     Normalize positive weights where primary supports overlap. Only primaries that overlap must
     share the same secondary. A later record for that secondary starts a lower-priority layer.
     Non-overlapping primaries may use different secondaries, and unpaired records remain fallback
     tiles.

  -Cf|l|o|u[+n|p]
     Select clobber/tiling mode instead of weighted merging:
       f: Keep the first available value. This is the default for direct grid lists.
       l: Keep the lowest available value.
       o: Keep the last available value.
       u: Keep the highest available value.
       +n: Only consider non-positive values for clobbering.
       +p: Only consider non-negative values for clobbering.

  -F<field1,field2,...>
     Set NetCDF output variable names. -F does not select source variables: fields selected with ?
     map positionally to -F. Thus model1.nc?vp,vs,den and model2.nc?p,s,d may be merged with -Fvp,⏎
     …vs,rho when the differently named fields are equivalent.

  -H[n|l|a|s|m[<arg>]][+m<maxgap>]
     Fill strictly internal missing-data holes in every input field before resampling and merging.
     Original non-missing nodes and boundary-connected gaps are preserved. Without -H, internal
     holes are not filled. Use linear Delaunay interpolation when -H has no directive.
       Nearest neighbor (n). Optionally append a search radius in grid nodes.
       Linear Delaunay interpolation (l). This is the default.
       Local weighted average (a). Append <radius>[/<sectors>] in grid nodes. The default is 3/4.
       Spline interpolation (s). Optionally append tension in the range 0-1. The default is 0.
       Minimum-curvature interpolation (m). Optionally append tension in the range 0-1. The default
          is 0.
       +m Only fill holes whose horizontal and vertical spans are both no larger than <maxgap> grid
          nodes. The default is to fill all internal holes.

  -ME|B[+w]
     Convert non-monotone clip polygons to strict xy-monotone supports using the envelope (E) or
     best-piecewise envelope (B) method. Append +w to write a converted polygon with a _monotone
     suffix. Without -M, supplied polygons must already be strictly xy-monotone.

  -P
     Fill primary values that remain missing after interpolation from their non-missing paired
     secondary values. By default, primary NaNs are preserved.

  -V[q|e|w|t|i|c|d]
     Change the verbosity level (currently w). Choose among 7 levels; each level adds more detailed
     messages:
       q: Quiet, not even fatal error messages.
       e: Error messages only.
       w: Warnings [Default when no -V is given].
       t: Timings (time-intensive operations only).
       i: Informational messages (or just -V with no level appended).
       c: Compatibility warnings.
       d: Debugging messages.

  -W[+o]
     Include the shared NetCDF variable weight with long_name='merging weight' and units='1'.
     Append +o to write only the coordinates and weight. All output fields use this same weight.

  -Z[+x<sx>][+X<xunit>][+y<sy>][+Y<yunit>][+v<scales>][+V<units>]
     Transform output coordinates and fields after merging. +x and +y scale output coordinates. +X
     and +Y set coordinate units. +v supplies one broadcast scale or one scale per output field. +V
     sets field units. Field lists follow -F order when -F is used and selector order otherwise. -Z
     scales output coordinates and fields in place and does not reorder coordinates, fields, or
     weight. A negative axis scale therefore produces a decreasing output axis. Weight is not
     scaled.
       Example: with -Fvp,vs, -Z+x0.001+Xkm+y0.001+Ykm+v0.001,0.001+Vkm/s,km/s converts x and y
          from m to km and converts vp and vs from m/s to km/s.

  -di<nodata>[+c<col>] Replace any <nodata> values in input data with NaN.
       +c Append first column to be affected [2].
     Also sets value for nodes without constraints. The default is NaN.

  -f[i|o]<colinfo>
     Indicate content of input/output columns. Optionally append i(nput) or o(utput) [Default is
     both]. Append <colinfo> as one or more comma-separated groups of <cols><type>, where <cols> is
     a column (or column ranges) and <type> is the column type, chosen from T (Calendar format), t
     (time relative to TIME_EPOCH), f (floating point), x (longitude), y (latitude), or d
     (dimension). You may also use s (string) to indicate the start column of trailing text.
     Shortcuts: -f[i|o]g means -f[i|o]0x,1y (geographic, i.e., lon/lat coordinates), -f[i|o]c means
     -f[i|o]0:1f (Cartesian coordinates), while -fp[<unit>] means input x,y are already in
     projected coordinates in <unit> [e].

  -n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]
     Specify a grid interpolation directive:
       b: B-spline.
       c: Bicubic spline [Default].
       l: Bilinear spline.
       n: Nearest-neighbor value, i.e., no spline at all.
     Optional modifiers:
       +a Switch off anti-aliasing (except for linear) [Default is ON].
       +b Change boundary conditions, where <BC> can be either g for geographic, p for periodic, or
          n for natural boundary conditions. For p and n you may optionally append x or y [Default
          is both]: x for periodic boundary conditions on x, y for periodic boundary conditions on
          y [Default is Natural conditions, unless grid is known to be geographic].
       +c Clip interpolated grid to input z-min/max [Default may exceed limits].
       +t Change the minimum weight in vicinity of NaNs. A <threshold> of 1.0 requires all nodes
          involved in interpolation to be non-NaN; 0.5 will interpolate about half way from a non-
          NaN to a NaN node [Default is 0.5].
     (-n is passed to grdsample if grids are not co-registered).

  -r[g|p]
     Set (g)ridline- or (p)ixel-registration (-r with no argument sets pixel registration). If -r
     is not given then we default to gridline registration.

  -^ (or -) Print short synopsis message.
  -+ (or +) Print longer synopsis message.
  -? (or no arguments) Print this usage message.
  --PAR=<value> Temporarily override GMT default setting(s) (repeatable).
     (See gmt.conf documentation for GMT default parameters).

Examples

See merge2d examples.

See also

merge1d, merge3d, NetCDF Variable Selection, Scaling and Units