Support polygon-based subsetting in grdcut -F with GeoDataFrame

[kshitijaucharmal]

Description of proposed changes

This PR enhances the pygmt.grdcut function to support polygon-based subsetting of grids using the -F option. Users can now provide polygons in three different formats:

• A geopandas.GeoDataFrame
• A shapely.geometry.Polygon
• A GMT ASCII polygon file

Additionally, a gallery example has been added to demonstrate all three methods and how they produce the same cropped grid. This improves PyGMT’s functionality for extracting regions of interest from raster grids and makes the workflow more Pythonic and flexible.

Fixes #1529 (implements rather)

Preview:
Users can crop grids using polygons without manually creating ASCII files.
Example figure showing original grid and cropped grids using all three polygon input methods.

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.

[welcome]

💖 Thanks for opening this pull request! 💖

Please make sure you read our contributing guidelines and abide by our code of conduct.

A few things to keep in mind:

• If you need help writing tests, take a look at the existing ones for inspiration. If you don't know where to start, let us know and we'll walk you through it.
• All new features should be documented. It helps to write the docstrings for your functions/classes before writing the code. This will help you think about your code design and results in better code.
• No matter what, we are really grateful that you put in the effort to do this! 🎉

[yvonnefroehlich]

Hey @kshitijaucharmal,

great that you started working on this quite old issue! And the PR looks already quite promising 🙂.
The team is currently working on finishing the release of v0.17.0 until the end of September, so I put this PR to v0.18.0.
Just two aspects for now:

• Looking at the upstream GMT docs at https://docs.generic-mapping-tools.org/dev/grdcut.html#f, we should also mention the +c and +i modifiers.
• Just wondering if there is a typo in the file name of the gallery example and it should be “grdpolygon” instead of “gdrpolygon”?

If I understood the Hacktoberfest correctly it’s fine to have the PR merged between October 1 and October 31, and we have to add the corresponding label so that this PR is considered.

[kshitijaucharmal]

Thanks for the suggestions @yvonnefroehlich !

The +c and +I options will need to be mentioned, I'll make sure to add that asap. And yeah the filename does contain a typo, don't know how I let it through, but will fix it right away!

Regarding Hacktoberfest, this PR won't be counted anyway as the creation time of the PR matters not the merging time, so the label isn't required. Wasn't sure how it worked before, I'll remove the request from the PR description as well

[seisman]

@kshitijaucharmal Thanks for your contribution. I noticed that you're pushing changes directly to your main branch. This is not a good practice and will definitely cause more troubles for you. Please create a separate branch next time.

[kshitijaucharmal]

@kshitijaucharmal Thanks for your contribution. I noticed that you're pushing changes directly to your main branch. This is not a good practice and will definitely cause more troubles for you. Please create a separate branch next time.

Yeah I should have created a new branch, I do accept the mistake on my part 😅

@yvonnefroehlich @seisman May I close this PR and reopen it when October starts as it's not going to be merged before then anyways?

[yvonnefroehlich]

May I close this PR and reopen it when October starts as it's not going to be merged before then anyways?

Well, I have no experience with this Hacktoberfest and how strict they are with the rules, but from my side, you can try this.

[kshitijaucharmal]

Thanks! I think it'll be worth a try, so I'll take down this PR for now.