Figure.hlines/Figure.vlines: Plot horizontal/vertical lines

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the hlines and vlines methods 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/plot.html
• PyGMT hlines: https://www.pygmt.org/dev/api/generated/pygmt.Figure.hlines.html
• PyGMT vlines: https://www.pygmt.org/dev/api/generated/pygmt.Figure.vlines.html

Parameters

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

Figure.hlines and Figure.vlines are high-level PyGMT wrappers around Figure.plot (which internally uses GMT's plot module). They expose the following subset of Figure.plot parameters:

• -B: frame
• -J: projection
• -N: no_clip
• -R: region
• -U: Use Figure.timestamp instead.
• -V: verbose
• -W: pen
• -X/-Y: Use Figure.shift_origin instead.
• -c: panel Figure.hlines/Figure.vlines: Add the parameter 'panel' #4892
• -l: label
• -p: perspective
• -t: transparency
• --PAR=value: Use pygmt.config instead.

Notes

Figure.hlines plots horizontal lines at specified Y-coordinates; Figure.vlines plots vertical lines at specified X-coordinates. Both methods internally call Figure.plot with straight_line="x" or straight_line="y" respectively, and resample to at least 4 points to support geographic/polar projections.

The term "horizontal"/"vertical" differs by coordinate system:

• Cartesian: straight lines
• Polar: arcs along constant radius / straight lines along constant azimuth
• Geographic: arcs along parallels (constant latitude) / meridians (constant longitude)

Linked Pull Requests

• Initial feature implementation
• Add a tutorial or gallery example

Related Issues and Discussions

• Convenient methods to plot horizontal and vertical lines #670 — original request for hlines/vlines convenience methods
• Higher-level plotting methods for Figure.plot and Figure.plot3d #2797 — higher-level plotting methods discussion