Wrap clip

[maxrjones]

Description of proposed changes

Following a couple comments at #1706, this PR suggests an implementation of GMT's clip module using a with statement/context manager. It uses the same style as the subplot and inset methods of pygmt.Figure. Here is an example:

import pygmt
x = [1, 1, 2, 3, 3, 1]
y = [1, 2, 2, 3, 1, 1]
fig = pygmt.Figure()
# Plot the original data
fig.plot(data="@tut_data.txt", style="c0.5c", color="red", frame=True, region=[0, 6, 0, 6], projection="X5c")
# Setup a clip path
with fig.clip(x=x, y=y, pen="1p"):
    # Plot the data with a green fill
    fig.plot(data="@tut_data.txt", style="c0.5c", color="green")
fig.show()

To do:

• Decide whether this function should remain as a context manager
• Decide how to organize this function relative to other clipping modules in GMT
• Add more robust tests (e.g., multiple clipping paths, geodataframe input, ogrfile, polygon clip + coast clip)

Fixes #

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 commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_clip.png

Image diff(s)

Added images

• pygmt/tests/baseline/test_clip.png

Modified images

Path	Old	New

Report last updated at commit 5f67979

[seisman]

The -C documentation says

Remember to supply -X and -Y settings if you have moved since the clip started.

How can we revert the -X and -Y setttings in a context manager?

[maxrjones]

The -C documentation says

Remember to supply -X and -Y settings if you have moved since the clip started.

How can we revert the -X and -Y setttings in a context manager?

Possibly we could use GMT_Get_Common on entry and exit to keep track of the -X -Y settings. But I wonder if in modern mode GMT could keep track of these settings internally. I will open an issue in the GMT repository for discussion.

[maxrjones]

How can we revert the -X and -Y setttings in a context manager?

We might not have to do anything about this. See discussion/confusion at GenericMappingTools/gmt#6406.

[maxrjones]

The -C documentation says "Remember to supply -X and -Y settings if you have moved since the clip started." How can we revert the -X and -Y setttings in a context manager?

Paul and I could not figure out what this is in reference to and suspect it relates to obsolete behavior, so I removed this statement from the docs in GenericMappingTools/gmt#6450.