pygmt.project: Project data onto lines or great circles, or generate tracks

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the pygmt.project 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/project.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/project
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.project.html

GMT Option Flags and Modifiers

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

• ☑️ -A (azimuth): Azimuth of the projection in degrees clockwise from North (Definition 1).
• ☑️ -C (center): cx/cy. Origin of the projection.
• ☑️ -E (endpoint): bx/by. End point of the projection path (Definition 2).
• ☑️ -F (convention): Specify the desired output columns using any combination of xyzpqrs.
• ☑️ -G (generate): dist[/colat][+c|h]. Create (r, s, p) output at equal intervals along a profile.
• ☑️ -L (length): (lmin, lmax) or "limit". Project only data whose p coordinate lies within the given range.
• ☑️ -N (flat_earth): Make a Cartesian coordinate transformation in the plane.
• ☑️ -Q (unit): Set units for x, y, r, s to degrees and p, q distances to km.
• ☑️ -S (sort): Sort the output into increasing p order.
• ☑️ -T (pole): px/py. Set the position of the rotation pole of the projection (Definition 3).
• ☑️ -V (verbose): Verbosity level.
• ☑️ -W (width): (w_min, w_max). Project only data whose q coordinate lies within the given range.
• -X/-Y: Use Figure.shift_origin instead.
• ☑️ -Z (ellipse): major/minor/azimuth[+e|n]. Generate ellipse coordinates in combination with center and generate.
• ⬜ -b: Binary input/output.
• ⬜ -d: Replace NaN with a specified nodata value on input/output.
• ⬜ -e: Pattern matching to select input rows.
• ☑️ -f (coltypes): Column data types.
• ⬜ -g: Gap detection.
• ⬜ -h: Read/write header records.
• ⬜ -i: Select input columns.
• ⬜ -o: Select output columns.
• ⬜ -q: Select rows by row number or range.
• ⬜ -s: Skip rows containing NaN values.
• ⬜ -w: Wrap repeated cycles.
• --PAR=value: Use pygmt.config instead.

Notes on Input Formats

• data: Accepts a file path, 2-D numpy.ndarray, or pandas.DataFrame with at least 2 columns (x, y). Alternatively, provide x, y, and optionally z as separate 1-D arrays.
• output_type: "pandas" (default), "numpy", or "file". Use "file" together with outfile.
• When generate is set, no input data table is read; the data, x, y, and z arguments are ignored.
• Exactly one of azimuth, endpoint, or pole must be supplied to define the projection geometry.
• When generate is set, convention must not be specified; the output order is hardwired to rsp.

Linked Pull Requests

• Initial feature implementation – Wrap project #1122
• Add ellipse (-Z) parameter – Add function to load Blue Marble dataset #2235
• Add common data I/O options (-b, -d, -e, -g, -h, -i, -o, -q, -s, -w)
• Add a gallery or tutorial example (e.g., projecting ship-track data along a great-circle transect across a mid-ocean ridge)

Related Issues and Discussions

• pygmt.project is commonly used in marine geology to project scattered data (bathymetry, gravity, magnetics) along a great-circle transect for cross-sectional analysis.
• For forward/inverse map projections and datum conversions, use pygmt.mapproject instead.
• When using generate with pole to create a small circle, append +c to automatically compute the required colatitude for the small circle to pass through center.