merge3d

merge3d tiles or smoothly merges three-dimensional multiparameter NetCDF cubes. Horizontal support polygons (i.e., clip files) are extruded/extended through a selectable vertical interval, with independent x, y, and z windows and taper ratios.

Synopsis

gmt merge3d <cubes|mergefile> -Rregion -Iincrement -Tzmin/zmax/dz \
    -Goutput.nc [options]

Behavior

Output fields use (z,y,x) dimensions and geometry defined by -R, -I, and -T. Every input axis must be strictly increasing after its source transform. Input coordinate scaling does not reorder coordinates or cube data. A decreasing source axis can use a negative input scale to make it increase. Mergefile z supports and -T use this transformed system. Output -Z transforms only the completed output and may scale both coordinates and model fields without reordering them.

Direct cube lists tile values in availability order and retain the first available value by default. A mergefile enables primary and secondary pairing and contains records of the form:

primary [secondary] [polygon] [zlo/zhi] [xwindow/ywindow/zwindow] \
    [rx1/rx2/ry1/ry2/rz1/rz2]

Each non-comment record contains up to six 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 horizontal and vertical support and does not extend the primary availability beyond its domain. Use - for an unpaired fallback tile.

polygon

Optional xy polygon defining the horizontal support. The complete primary horizontal domain is used when it is omitted.

zlo/zhi

Optional vertical support in transformed source coordinates. The complete transformed primary z range is the default.

xwindow/ywindow/zwindow

BLEND window functions. One name applies to all axes. When two names are supplied, x also applies to z. Three names set x, y, and z. The default is cosine/cosine/cosine.

rx1/rx2/ry1/ry2/rz1/rz2

Dimensionless taper ratios in [0, 0.5). One value applies everywhere, three apply symmetrically to x, y, and z, and six control every side independently. rx1/rx2 apply at west/east (low/high x), ry1/ry2 at south/north (low/high y), and rz1/rz2 at zlo/zhi. 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 vertical support 0/40, rz1/rz2 = 0/0.2 disables the zlo taper and uses approximately the final 8 coordinate units for the zhi taper. 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, y, and z 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 the polygonal horizontal support, BLEND evaluates x and y tapers along local polygon cross-sections and adapts the transition width where a cross-section is too narrow for the nominal support-wide taper. The z taper uses the complete zlo/zhi support interval.

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,vs secondary.nc?p,s support.txt 0/40 cosine/cosine/cosine 0.2/0.2/0
secondary.nc?p,s - - - -

The polygon is extruded through its vertical support. Polygon validation and conversion with -ME or -MB follow merge2d.

NetCDF dimensions may appear in any order when x, y, and z coordinates can be identified from CF metadata or conventional names. All selected fields in one source must share those dimensions. Select fields with file.nc?field1,field2,.... If ? is omitted, the first eligible 3-D data variable is used. -F names output fields and 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. Without -F, output retains the first primary’s source field names and every source must use those same names.

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+z-1/1000+Zkm+v0.001,0.001+Vkm/s,km/s scales x and y in m to km, converts a source z axis of 4000 ... -16000 m to -4 ... 16 km without changing cube order, and scales both selected fields in m/s to km/s. Input transforms occur before interpolation, support polygon tests, and merging. Afterward, -Z+z-1000+Zm restores 4000 ... -16000 m without changing the output field or weight order.

Output -Z applies after merging. Its field scales and units follow -F order when supplied and selector order otherwise. 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+z-0.001+Zkm+v0.001,0.001+Vkm/s,km/s converts x and y in m to km, converts negative-down z in m to positive-down km, and converts both velocity fields in m/s to km/s without reordering the cube.

Aggregate weighting with -A, paired gap filling with -P, and the shared weight output follow the lower-dimensional merge modules. Only overlapping primaries must share the same secondary when using -A. Non-overlapping primaries may use different secondaries.

The -H option fills strictly internal horizontal holes in every native x-y layer before vertical interpolation, resampling, and merging. It matches merge2d: nearest neighbor (n), linear Delaunay (l), local weighted average (a), spline (s), and minimum curvature (m) are available, with linear Delaunay as the default. The +m<maxgap> modifier limits filling to holes whose x and y spans do not exceed the specified number of grid nodes. Original finite nodes and boundary-connected gaps are preserved. Input cubes used with -H must have regularly spaced x and y coordinates.

The -S option selects vertical interpolation: Akima (a), cubic (c), step-up (e), linear (l), nearest (n), or smoothing spline (s<p>) with non-negative fit parameter p. Linear (l) is the default. Vertical interpolation remains within contiguous non-missing runs by default. Appending +g bridges internal missing layers, optionally subject to a maximum z-coordinate distance. It does extrapolate beyond the available vertical range and does not bridge horizontal gaps.

After vertical interpolation, GMT -n controls horizontal resampling of each output z layer: nearest neighbor (-nn), bilinear (-nl), bicubic (-nc), or B-spline (-nb). Bicubic is the default. Regular horizontal grids use GMT’s two-dimensional interpolation and the selected -n modifiers. Cubes with irregular x or y coordinates use separable x-then-y GMT splines. In this fallback, -nb and -nc both use cubic interpolation.

The options do not conflict. Processing follows input scaling, -H filling of internal holes in native x-y layers, -S vertical interpolation to an output z layer, -n horizontal resampling to the -R/-I grid, and then merging. Without -H, -n resamples available values but does not deliberately fill internal horizontal holes. For example, -Hl -Sl+g -nl fills native x-y holes with linear Delaunay interpolation, bridges internal z gaps linearly, and resamples each output layer horizontally with bilinear interpolation.

Declared missing values, IEEE NaNs, selector +n sentinels, and -di are set to NaN. -W adds the shared variable weight with long_name="merging weight" and units 1. -W+o writes only the coordinates and weight. The implementation holds one input field at a time and writes completed output layers incrementally rather than retaining multiple data cubes in memory.

Usage

gmt merge3d [gq] 6.5.0 [64-bit] - Tile or smoothly merge three-dimensional multiparameter NetCDF
  cubes

usage: gmt merge3d [<mergefile> | <cube1> <cube2> ...] -R<w/e/s/n> -I<dx>[/<dy>] -T<zmin>/<zmax>/⏎
  …<dz> -G<output.nc> [-A] [-Cf|l|o|u[+n|p]] [-F<fields>] [-H[n|l|a|s|m[<arg>]][+m<maxgap>]] [-ME|⏎
  …B[+w]] [-P] [-Sa|c|e|l|n|s<p>[+g[<maxgap>]]] [-W[+o]]
  [-Z+x<sx>[+X<xunit>]+y<sy>[+Y<yunit>]+z<sz>[+Z<zunit>]+v<scales>[+V<units>]] [-V[q|e|w|t|i|c|d]]
  [-di<nodata>[+c<col>]] [-n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]]

  REQUIRED ARGUMENTS:

  <mergefile> | <cube1> <cube2> ...
     Supply one mergefile or list one or more NetCDF cubes 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 six 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 horizontal and vertical support
          and does not extend the primary domain.
       polygon: Optional xy polygon defining the horizontal primary support. Use '-' or omit it to
          use the complete primary horizontal domain.
       zlo/zhi: Optional vertical primary support in transformed input coordinates, with zlo < zhi.
          The default is the complete transformed primary z range.
       xwindow/ywindow/zwindow: BLEND window functions. One name applies to all axes. With two
          names, x also applies to z. Three names set x, y, and z. The default is cosine/cosine/⏎
          …cosine.
       rx1/rx2/ry1/ry2/rz1/rz2: Dimensionless taper ratios in [0, 0.5). One value applies
          everywhere, three apply symmetrically to x, y, and z, and six set every beginning and
          ending ratio independently. The default is 0.2 everywhere.
       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), ry1/ry2 at south/north (low/high
          y), and rz1/rz2 at zlo/zhi. For a vertical support 0/40, rz1/rz2 = 0/0.2 disables the zlo
          taper and uses approximately the final 8 coordinate units for the zhi taper.
       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, y, and z 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 the polygonal horizontal support, BLEND evaluates x and y tapers along local polygon
          cross-sections and adapts the transition width where a cross-section is too narrow for
          the nominal support-wide taper. The z taper uses the complete zlo/zhi support interval.
       Use '-' to skip an optional field when supplying a later field. Trailing optional fields may
          be omitted. Blank lines and text after '#' are ignored.
       Example mergefile:
        primary.nc?vp,vs secondary.nc?p,s support.txt 0/40 cosine/cosine/cosine 0.2/0.2/0
        secondary.nc?p,s - - - -
       Select NetCDF fields with file.nc?field1,field2,... . Selected fields must share the same
          x, y, and z coordinates. If ? is omitted, the first eligible three-dimensional data
          variable is used.
       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. and +n declares an additional missing-value sentinel. Input
          transforms are applied after NetCDF packing is decoded and before interpolation, support
          tests, and merging.
       Use file.nc?<field1,field2,...>+<modifiers> for named fields or file.nc?+<modifiers> to
          transform the default field without naming it.
       Input coordinate scaling does not reorder coordinates or cube data. Every transformed input
          axis must be strictly increasing. For a decreasing source axis, use a negative input
          scale to make it increase. use output -Z to restore a decreasing convention after
          merging.
       Example: model.nc?vp,vs+x0.001+Xkm+y0.001+Ykm+z-1/1000+Zkm+v0.001,0.001+Vkm/s,km/s selects
          vp and vs, scales x and y from m to km, converts a source z axis of 4000 ... -16000 m to
          -4 ... 16 km without reordering the cube, and scales both fields from m/s to km/s. Output
          -Z+z-1000+Zm restores the original z convention without reordering.

  -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 required horizontal output domain. It must overlap at least one input cube.

  -I<dx>[/<dy>]
     Set the required horizontal output increments. One value applies to x and y. Two values set
     them independently.

  -T<zmin>/<zmax>/<dz>
     Set the required regular output z axis. zmin must be less than zmax and dz is the increment.
     Values use the standardized coordinate system established by input +z transforms. The maximum
     is adjusted when necessary to fit dz.

  -G<output.nc>
     Write a NetCDF cube with every selected field sharing dimensions (z,y,x).

  OPTIONAL ARGUMENTS:

  -A
     Normalize positive weights where primary supports overlap. Only primaries that overlap must
     share the same secondary cube. 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 cube 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. Without -F, output retains the first
     primary's field names and every source must use those same names.

  -H[n|l|a|s|m[<arg>]][+m<maxgap>]
     Fill strictly internal horizontal missing-data holes in every native x-y layer before vertical
     interpolation, resampling, and merging. Original non-missing nodes and boundary-connected gaps
     are preserved. Without -H, horizontal holes are not filled. Use linear Delaunay interpolation
     when -H has no directive. Input cubes used with -H must have regularly spaced x and y
     coordinates.
       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 xy polygons with the strict envelope (E) or best piecewise envelope (B).
     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.

  -Sa|c|e|l|n|s<p>[+g[<maxgap>]]
     Choose GMT vertical interpolation: Akima (a), cubic (c), step-up (e), linear (l), nearest
     (n), or smoothing spline (s<p>) with non-negative fit parameter p. Linear (l) is the default.
     Interpolation remains within contiguous non-missing runs. Append +g to bridge internal missing
     layers, optionally only when the bracketing z-coordinate distance does not exceed maxgap.
     Values are not extrapolated outside the available vertical range.

  -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 coordinates and weight. All output fields use this same weight.

  -Z[+x<sx>][+X<xunit>][+y<sy>][+Y<yunit>][+z<sz>][+Z<zunit>][+v<scales>][+V<units>]
     Transform output coordinates and fields after merging. +x, +y, and +z scale output
     coordinates. +X, +Y, and +Z set coordinate units. +v supplies one broadcast scale or one scale
     per output field. and +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+z-0.001+Zkm+v0.001,0.001+Vkm/s,km/s converts
          x and y from m to km, converts a negative-down z axis in m to positive-down km, and
          converts vp and vs from m/s to km/s without reordering the cube.

  -di<nodata>[+c<col>] Replace any <nodata> values in input data with NaN.
       +c Append first column to be affected [2].

  -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].
     Control horizontal x-y interpolation after -S has interpolated each native vertical column to
     an output z layer. Use nearest neighbor (-nn), bilinear (-nl), bicubic (-nc), or B-spline (-
     nb). Bicubic is the default.
       Regular horizontal grids use GMT's two-dimensional interpolation and the selected -n
          modifiers. Cubes with irregular x or y coordinates use separable x-then-y GMT splines. In
          that fallback, -nb and -nc both use cubic interpolation.
       Option -n does not replace or conflict with -H. Processing follows input scaling, -H filling
          of internal holes in native x-y layers, -S vertical interpolation to an output z layer,
          -n horizontal resampling to the -R/-I grid, and then merging. Without -H, -n resamples
          available values but does not deliberately reconstruct internal horizontal holes.
       Example: -Hl -Sl+g -nl fills native x-y holes with linear Delaunay interpolation, bridges
          internal z gaps linearly, and resamples each output layer horizontally with bilinear
          interpolation.

  -^ (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 merge3d examples.

See also

merge2d, topobath, Scaling and Units