pygmt.grd2cpt: Make linear or histogram-equalized color palette table from grid

[seisman]

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

GMT Option Flags and Modifiers

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

• -B: Not applicable (no map/figure output).
• ☑️ -A (transparency): Set a constant transparency level (0–100) for all color slices; append +a to also affect B/F/N colors.
• ☑️ -C (cmap): Select the master CPT to use for interpolation.
• ☑️ -D (background): Match background/foreground colors to lowest/highest z-values in the output (or input with "i") CPT.
• ☑️ -E (nlevels): Create a linear CPT using the grid's z-range, or resample into nlevels equidistant slices.
• ☑️ -F (color_model): Force output CPT to use r/g/b, h/s/v, or c/m/y/k codes; optionally write categorical format with +c.
• ☑️ -G (truncate): Truncate the incoming CPT to zlow/zhigh before resampling.
• ☑️ -H (output): Write the CPT to a file instead of storing it as the session-level CPT.
• ☑️ -I (reverse): Reverse the sense of color progression ("c") or the sign of z-values ("z").
• ☑️ -L (limit): Limit range of CPT to zmin/zmax.
• ☑️ -M (overrule_bg): Overrule B/F/N colors in the master CPT with the values from pygmt.config.
• ☑️ -N (no_bg): Do not write out background, foreground, and NaN-color fields.
• ☑️ -Q (log): Logarithmic interpolation scheme; input z-values are log₁₀(z).
• ☑️ -R (region): Subsample the grid to this region before computing the CDF.
• ☑️ -T (series): Define the range of the new CPT (min/max/inc, list, or file).
• ☑️ -V (verbose): Verbosity level.
• ☑️ -W (categorical): Do not interpolate; pick colors sequentially from the master CPT.
• ☑️ -Ww (cyclic): Produce a wrapped (cyclic) CPT.
• -X/-Y: Use Figure.shift_origin instead.
• --PAR=value: Use pygmt.config instead.
• ☑️ -Z (continuous): Force a continuous CPT when building from a list of colors and z-values.

Notes on Input Formats

• grid: Accepts a file path or xarray.DataArray. The CDF is computed over all non-NaN grid values within the (optionally subsetted) grid.
• output: If None or False (default), the CPT is stored at the current session/figure/subplot/panel/inset level (GMT modern mode hierarchical CPT). Otherwise, provide a .cpt file path.
• truncate: A 2-element sequence (zlow, zhigh). Use float("nan") for either end to leave it unchanged.
• categorical and cyclic are mutually exclusive.

Linked Pull Requests

• Initial feature implementation – Wrap grd2cpt #803
• Simplify CPT output logic – pygmt.grd2cpt & pygmt.makecpt: Simplify the logic for dealing with CPT output #3334
• Add inline docstring example – Add inline example for grd2cpt #2145
• Add a dedicated gallery or tutorial example showing CPT customization with grd2cpt (e.g., comparing histogram-equalized vs. linear CPTs on a relief grid)

Related Issues and Discussions

• Closely related to pygmt.makecpt, which creates CPTs from data ranges rather than from a grid's CDF.
• Works naturally in combination with Figure.grdimage, Figure.grdview, and Figure.colorbar.