POC: Figure.clip: Clip paths by polygons, land or water

[seisman]

Description of proposed changes

This is an initial implementation of wrapping the clip method, based on the idea proposed in #1706 (comment), i.e., integrate all clipping functionalities (clip for clipping a polygon path, coast for clipping the land, water or dcw, and maybe more).

This PR almost works as expected, but I'm having difficulties adding Figure.clip into the documentation.

Syntax

import pygmt
fig = pygmt.Figure()
with fig.clip.land():
    # Plot data with land clipped
with fig.clip.water():
    # Plot data with water clipped
with fig.clip.polygon(...):
    # Plot data with polygons clipped
with fig.clip.dcw(...):
    # Plot data with clipping based on dcw

Example

import pygmt
from pygmt.datasets import load_earth_relief

grid = load_earth_relief()
fig = pygmt.Figure()
fig.basemap(region="g", projection="H15c", frame=["a", "+tClipping land"])
with fig.clip.land():
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(yshift=10)
fig.basemap(region="g", projection="H15c", frame=["a", "+tClipping water"])
with fig.clip.water():
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(yshift=-10, xshift=16)
fig.basemap(region="g", projection="H15c", frame=["a", "+tClipping polygon"])
with fig.clip.polygon(x=[60, 60, 150, 150], y=[-30, 60, 60, -30]):
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(yshift=10)
fig.basemap(region="g", projection="H15c", frame=["a", "+tMixed clipping"])
with fig.clip.polygon(x=[60, 60, 150, 150], y=[-30, 60, 60, -30]):
    with fig.clip.land():
        fig.grdimage(grid, cmap="geo")
with fig.clip.polygon(x=[200, 200, 250, 250], y=[-30, 60, 60, -30]):
    with fig.clip.water():
        fig.grdimage(grid, cmap="geo")

fig.show()

Supersedes PR #1779, #1706

Preview:

• https://pygmt-dev--3878.org.readthedocs.build/en/3878/api/index.html
• https://pygmt-dev--3878.org.readthedocs.build/en/3878/api/generated/pygmt.Figure.clip.html#pygmt.Figure.clip

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[yvonnefroehlich]

This PR almost works as expected, but I'm having difficulties adding Figure.clip into the documentation.

Hm. Maybe adding the method to doc/api/index.rst (https://github.com/GenericMappingTools/pygmt/blob/main/doc/api/index.rst?plain=1) is just missing?

[seisman]

This PR almost works as expected, but I'm having difficulties adding Figure.clip into the documentation.

Hm. Maybe adding the method to doc/api/index.rst (https://github.com/GenericMappingTools/pygmt/blob/main/doc/api/index.rst?plain=1) is just missing?

No, it won't work, because Figure.clip is not a class method, but an attribute.