pygmt.grdproject(grid, *, center=None, spacing=None, dpi=None, scaling=None, outgrid=None, projection=None, inverse=None, unit=None, region=None, verbose=None, interpolation=None, registration=None, **kwargs)[source]

Change projection of gridded data between geographical and rectangular.

This method will project a geographical gridded data set onto a rectangular grid. If inverse is True, it will project a rectangular coordinate system to a geographic system. To obtain the value at each new node, its location is inversely projected back onto the input grid after which a value is interpolated between the surrounding input grid values. By default bi-cubic interpolation is used. Aliasing is avoided by also forward projecting the input grid nodes. If two or more nodes are projected onto the same new node, their average will dominate in the calculation of the new node value. Interpolation and aliasing is controlled with the interpolation parameter. The new node spacing may be determined in one of several ways by specifying the grid spacing, number of nodes, or resolution. Nodes not constrained by input data are set to NaN. The region parameter can be used to select a map region large or smaller than that implied by the extent of the grid file.

Full option list at


  • C = center

  • D = spacing

  • E = dpi

  • F = scaling

  • G = outgrid

  • I = inverse

  • J = projection

  • M = unit

  • R = region

  • V = verbose

  • n = interpolation

  • r = registration

  • grid (str or xarray.DataArray) – The file name of the input grid or the grid loaded as a DataArray.

  • outgrid (str or None) – The name of the output netCDF file with extension .nc to store the grid in.

  • inverse (bool) – When set to True transforms grid from rectangular to geographical [Default is False].

  • projection (str) – projcode[projparams/]width. Select map projection.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • center (str or list) – [dx, dy]. Let projected coordinates be relative to projection center [Default is relative to lower left corner]. Optionally, add offsets in the projected units to be added (or subtracted when inverse is set) to (from) the projected coordinates, such as false eastings and northings for particular projection zones [0/0].

  • spacing (str) –

    x_inc[+e|n][/y_inc[+e|n]]. x_inc [and optionally y_inc] is the grid spacing.

    • Geographical (degrees) coordinates: Optionally, append an increment unit. Choose among 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 +e 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 +n to the supplied integer argument; the increment is then recalculated from the number of nodes, the registration, and the domain. The resulting increment value depends on whether you have selected a gridline-registered or pixel-registered grid; see GMT File Formats for details.

    Note: If region=grdfile is used then the grid spacing and the registration have already been initialized; use spacing and registration to override these values.

  • dpi (int) – Set the resolution for the new grid in dots per inch.

  • scaling (str) – [c|i|p|e|f|k|M|n|u]. Force 1:1 scaling, i.e., output or output data are in actual projected meters [e]. To specify other units, append f (foot), k (km), M (statute mile), n (nautical mile), u (US survey foot), i (inch), c (cm), or p (point).

  • unit (str) – Append c, i, or p to indicate that cm, inch, or point should be the projected measure unit. Cannot be used with scaling.

  • verbose (bool or str) –

    Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

    • q - Quiet, not even fatal error messages are produced

    • e - Error messages only

    • w - Warnings [Default]

    • t - Timings (report runtimes for time-intensive algorithms)

    • i - Informational messages (same as verbose=True)

    • c - Compatibility warnings

    • d - Debugging messages

  • interpolation (str) –

    [b|c|l|n][+a][+bBC][+c][+tthreshold]. Select interpolation mode for grids. You can select the type of spline used:

    • b for B-spline

    • c for bicubic [Default]

    • l for bilinear

    • n for nearest-neighbor

  • registration (str) – g|p. Force gridline (g) or pixel (p) node registration. [Default is g(ridline)].


ret (xarray.DataArray or None) – Return type depends on whether the outgrid parameter is set:

  • xarray.DataArray if outgrid is not set

  • None if outgrid is set (grid output will be stored in file set by outgrid)


>>> import pygmt
>>> # Load a grid of @earth_relief_30m data, with an x-range of 10 to 30,
>>> # and a y-range of 15 to 25
>>> grid = pygmt.datasets.load_earth_relief(
...     resolution="30m", region=[10, 30, 15, 25]
... )
>>> # Create a new grid from the input grid, set the projection to
>>> # Mercator, and set inverse to "True" to change from "geographic"
>>> # to "rectangular"
>>> new_grid = pygmt.grdproject(grid=grid, projection="M10c", inverse=True)