pygmt.grdproject: Forward and inverse map transformation of grids

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the pygmt.grdproject function in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/grdproject.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/grdproject
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.grdproject.html

GMT Option Flags and Modifiers

☑️: Implemented; ⬜: To be implemented/discussed; Strikethrough: Won't implement.

• -C (center): Set projected coordinates relative to the projection center; optionally add false eastings/northings (dx/dy).
• -D (spacing): Set output grid node spacing dx[/dy].
• -E (dpi): Set output grid resolution in dots per inch.
• -F (scaling): Force 1:1 scaling in actual projected metres, or specify a length unit ("c", "i", "p", "e", "f", "k", "M", "n", "u").
• -G (outgrid): Output grid file path; if unset, returns an xarray.DataArray.
• -I (inverse): Perform the inverse transformation (rectangular → geographic) instead of the forward projection.
• -J (projection): Map projection to use (required).
• -M (unit): Set the projected length unit ("c" centimetres, "i" inches, "p" points).
• -R (region): Subsample or extend the input grid to this region before projecting.
• -V (verbose): Verbosity level.
• -X/-Y: Use Figure.shift_origin instead.
• -n (interpolation): Interpolation method and boundary condition flags.
• -r (registration): Set node registration ("gridline" or "pixel").
• --PAR=value: Use pygmt.config instead.

Notes on Input Formats

• grid: Accepts a file path or xarray.DataArray. For the forward projection, the input must be in geographic (lon/lat) coordinates.
• projection (-J) is required; omitting it raises GMTParameterError.
• unit and scaling are mutually exclusive; providing both raises GMTParameterError.
• Returns xarray.DataArray when outgrid is unset; returns None when outgrid is a file path.
• When neither spacing nor dpi is set, GMT selects a suitable output resolution automatically.

Linked Pull Requests

• Initial feature implementation
• Add inline docstring example
• Add a gallery or tutorial example demonstrating forward and inverse projection (e.g., projecting a global relief grid into a Mercator raster and back)

Related Issues and Discussions

• Complementary to pygmt.grdcut (spatial subsetting) and pygmt.grdsample (resampling on an existing layout).
• The forward projection is a key step when comparing satellite imagery (Cartesian) with geographic model output.
• The inverse option allows converting a Cartesian-coordinates grid (e.g., from a numerical model) back to geographic lon/lat nodes.