pygmt.grd2xyz: Convert grid to data table

[seisman]

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

GMT Option Flags and Modifiers

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

• ☑️ -C (cstyle): Replace x/y coordinates with column/row numbers (C-style; append "f" for Fortran-style, or "i" for 1-D index + z).
• ☑️ -R (region): Extract only the nodes within the specified subregion.
• ☑️ -V (verbose): Verbosity level.
• ☑️ -W (weight): Append a weight column; use "a" to compute area-based weights per node.
• ☑️ -Z (convention): Write a 1-column table ordered by row/column convention flags (e.g., "TLa" for ASCII scanline).
• ☑️ -b (binary): Select binary output.
• ☑️ -d (nodata): Substitute a specific value for NaN on output.
• ☑️ -f (coltypes): Specify column data types (e.g., geographic coordinates).
• ☑️ -h (header): Write/read a header record.
• ☑️ -o (outcols): Select specific output columns.
• ☑️ -s (skiprows): Skip rows with NaN values.
• -X/-Y: Use Figure.shift_origin instead.
• --PAR=value: Use pygmt.config instead.

Notes on Input Formats

• grid: Accepts a file path or xarray.DataArray. All non-NaN nodes within the (optionally restricted) region are output.
• output_type: "pandas" (default) returns a DataFrame; "numpy" returns an ndarray; "file" writes to outfile.
• When output_type="pandas" and the input is an xarray.DataArray, column names are inferred from the DataArray's dimension names and variable name (e.g., lon, lat, z).
• outcols (-o) cannot be combined with output_type="pandas" because column selection changes the number/order of columns, making named-column output ambiguous.
• The -Z (convention) option writes a single-column table, useful for interoperability with tools that expect scanline-ordered binary arrays.

Linked Pull Requests

• Initial feature implementation – Wrap grd2xyz #1284
• Improve performance by storing output in virtual files – pygmt.grd2xyz: Improve performance by storing output in virtual files #3097
• Add inline docstring example – Add inline example for grd2xyz #1713
• Add a gallery or tutorial example (e.g., extracting xyz triplets from a relief grid and using them for further analysis or scatter plotting)

Related Issues and Discussions

• The complement of pygmt.xyz2grd, which converts a scatter of xyz points back to a grid.
• For tabular output of grid metadata (extent, increments, registration), see pygmt.grdinfo.