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).

Method	Activate	Deactivate
Figure.clip.land()	coast -G	coast -Q
Figure.clip.water()	coast -S	coast -Q
Figure.clip.polygon()	clip	clip -C
Figure.clip.mask()	mask	mask -C
Figure.clip.dcw()	coast -E+c	coast -Q
Figure.clip.solar()	solar -G	clip -C

TODO

• Figure.clip.land()
• Figure.clip.water()
• Figure.clip.polygon()
• Figure.clip.mask()
• Figure.clip.dcw()
• Figure.clip.solar() Figure.solar: Plot day-night terminators and other sunlight parameters. #4110

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="H10c", frame=["a", "+tFigure.clip.land()"])
with fig.clip.land():
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(xshift=11)
fig.basemap(region="g", projection="H10c", frame=["a", "+tFigure.clip.water()"])
with fig.clip.water():
    fig.grdimage(grid, cmap="geo")

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

fig.shift_origin(xshift=11)
fig.basemap(region="g", projection="H10c", frame=["a", "+tFigure.clip.solar()"])
with fig.clip.solar(terminator="civil"):
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(xshift=-33, yshift=8)

fig.basemap(region="g", projection="H10c", frame=["a", "+tFigure.clip.dcw()"])
with fig.clip.dcw(code="AU"):
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(xshift=11)
fig.basemap(region="g", projection="H10c", frame=["a", "+tFigure.clip.dcw()"])
with fig.clip.dcw(code=["US", "CA"]):
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(xshift=11)
fig.basemap(region="g", projection="H10c", frame=["a", "+tFigure.clip.mask()"])
with fig.clip.mask(x=[180] * 5, y=[-50, -20, 0, 20, 50], spacing="30m", radius="30d"):
    fig.grdimage(grid, cmap="geo")

fig.shift_origin(xshift=-22, yshift=8)
fig.basemap(region="g", projection="H10c", frame=["a", "+tMixed clip 1"])
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.shift_origin(xshift=11)
fig.basemap(region="g", projection="H10c", frame=["a", "+tMixed clip 2"])

with fig.clip.water():
    with fig.clip.solar(terminator="civil"):
        with fig.clip.polygon(x=[200, 200, 250, 250], y=[-30, 60, 60, -30]):
            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.