Wrap clip

[maxrjones]

trafficstars

Description of proposed changes

Following a couple comments at https://github.com/GenericMappingTools/pygmt/pull/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[bot]]

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 5f67979baccb6d3715660e1b16c660c72f210bdb

[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 https://github.com/GenericMappingTools/gmt/issues/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 https://github.com/GenericMappingTools/gmt/pull/6450.