grdsample(cmd0::String="", arg1=nothing, kwargs...)

keywords: GMT, Julia, grid resample


Read a grid file and interpolates it to create a new grid file with either: a different registration (reg or toggle); or, a new grid-spacing or number of nodes (inc), and perhaps also a new sub-region (region). A bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation is used; see interp for settings. Note that using region only is equivalent to grdcut or grdedit-S. grdsample safely creates a fine mesh from a coarse one; the converse may suffer aliasing unless the data are filtered using grdfft or grdfilter.

When the region is omitted, the output grid will cover the same region as the input grid. When inc is omitted, the grid spacing of the output grid will be the same as the input grid. Either reg or toggle can be used to change the grid registration. When omitted, the output grid will have the same registration as the input grid.

Required Arguments

The 2-D gridded data set to be contoured.

Optional Arguments

  • G or save or outgrid or outfile : – save=file_name.grd
    Write one or more fields directly to grids on disk or return them to the Julia REPL as grid objects. If more than one field is specified via fields then file_name must contain the format flag %s so that we can embed the field code in the file names.

  • I or inc or increment or spacing : – inc=x_inc | inc=(xinc, yinc) | inc="xinc[+e|n][/yinc[+e|n]]"
    Specify the grid increments or the block sizes. More at spacing

  • R or region or limits : – limits=(xmin, xmax, ymin, ymax) | limits=(BB=(xmin, xmax, ymin, ymax),) | limits=(LLUR=(xmin, xmax, ymin, ymax),units="unit") | ...more
    Specify the region of interest. More at limits. For perspective view view, optionally add zmin,zmax. This option may be used to indicate the range used for the 3-D axes. You may ask for a larger w/e/s/n region to have more room between the image and the axes.

  • T or toggle : toggle=true
    Translate between grid and pixel registration; if the input is grid-registered, the output will be pixel-registered and vice-versa. This is a destructive grid change; see Switching registrations.

  • V or verbose : – verbose=true | verbose=level
    Select verbosity level. More at verbose

  • f or colinfo : – colinfo=??
    Specify the data types of input and/or output columns (time or geographical data). More at

  • n or interp or interpol : – interp=params
    Select interpolation mode for grids. More at interp

// Couldn't find a file when trying to resolve an input request with relative path: `common_opts/opt_r`. //

// Couldn't find a file when trying to resolve an input request with relative path: `common_opts/opt_x`. //

Grid Values Precision

Regardless of the precision of the input data, GMT programs that create grid files will internally hold the grids in 4-byte floating point arrays. This is done to conserve memory and furthermore most if not all real data can be stored using 4-byte floating point values. Data with higher precision (i.e., double precision values) will lose that precision once GMT operates on the grid or writes out new grids. To limit loss of precision when processing data you should always consider normalizing the data prior to processing.

Consequences of grid resampling

Resample or sampling of grids will use various algorithms (see interp) that may lead to possible distortions or unexpected results in the resampled values. One expected effect of resampling with splines is the tendency for the new resampled values to slightly exceed the global min/max limits of the original grid. If this is unacceptable, you can impose clipping of the resampled values values so they do not exceed the input min/max values by adding +c to your interp option.


If an interpolation point is not on a node of the input grid, then a NaN at any node in the neighborhood surrounding the point will yield an interpolated NaN. Bicubic interpolation [default] yields continuous first derivatives but requires a neighborhood of 4 nodes by 4 nodes. Bilinear interpolation [interp] uses only a 2 by 2 neighborhood, but yields only zero-order continuity. Use bicubic when smoothness is important. Use bilinear to minimize the propagation of NaNs.


As an alternative to bicubic spline, linear spline or nearest neighbor interpolation one can instead send the entire dataset through surface for re-gridding. This approach allows more control on aspects such as tension but it also leads to a solution that is not likely to have fully converged. The general approach would be something like

grd2xyz old.grd | gmt surface -Rold.grd -Inewinc -Gnew.grd [other options]

For moderate data set one could also achieve an exact solution with greenspline, such as

grd2xyz old.grd | gmt greenspline -Rold.grd -Inewinc -Gnew.grd [other options]


To resample a sub-region of the 5 x 5 minute remote grid earthrelief05m onto a 1 minute grid::

grdsample @earth_relief_05m -R0/20/0/20 -I1m

To translate the gridline-registered remote grid earthrelief05m to pixel registration while keeping the same region and grid interval::

grdsample @earth_relief_05m -T

See Also