Add polygon helper utilities

[lispandfound]

Adds some helper functions for plotting and labelling polygons on pygmt maps:

1. plot_geometry which (as the name suggests) plots any shapely.Geometry.
2. label_polygon_on_boundary which labels a polygon (only polygons, not linestrings or other shapely geometries) with a label. Label position is found dynamically by maximising distance from the plot boundaries.
3. label_geometry_inside which labels a geometry at a point guaranteed to be inside a given geometry (any geometry).
4. grid_scale_for_region which automatically infers a sensible grid-scale for a region. Used by default for create_grid.
5. clip_to_geometry which clips a grid to only points inside a geometry.

[gemini-code-assist]

Summary of Changes

Hello @lispandfound, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the pygmt_helper library by introducing a suite of new utilities for advanced geographical plotting and data handling. The primary focus is on providing robust functions for plotting and labeling shapely geometric objects, particularly polygons, on PyGMT maps. Additionally, it improves the create_grid functionality by enabling automatic inference of grid spacing based on the map region, streamlining the process of generating grids. These changes aim to make it easier for users to visualize complex spatial data and automate common mapping tasks.

Highlights

• Enhanced Polygon Plotting and Labeling: New functions plot_geometry, label_polygon_on_boundary, label_geometry_inside, and label_polygon_at have been added to facilitate the plotting and labeling of various Shapely geometric objects on PyGMT maps. This includes plotting polygons and linestrings, labeling polygons on their boundaries (with dynamic positioning), and labeling any geometry at an internal point.
• Automatic Grid Scale Inference: The create_grid function now supports automatic grid scale inference using the newly introduced grid_scale_for_region utility. This function calculates an appropriate grid resolution based on the map's geographical extent, simplifying grid generation for users.
• Coordinate Conversion Utilities: New coordinate conversion utilities, nztm_to_wgs_wraparound and polygon_nztm_to_pygmt, have been added to handle transformations from NZTM to WGS84 coordinates, specifically addressing the international date line wrapping for PyGMT compatibility.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a set of very useful helper functions for working with polygons in pygmt. The new functionalities for plotting and labeling shapely geometries are a great addition. The code is well-structured, and the inclusion of an example file is appreciated.

My review focuses on improving correctness, maintainability, and documentation. I've identified a few areas for improvement:

• A critical bug in create_grid where the automatic grid spacing is applied too late.
• A significant limitation in plot_geometry where polygons with holes are not handled correctly.
• An opportunity to simplify _point_on_polygon by using an existing shapely function.
• Minor issues in docstrings, including incorrect parameter documentation and a broken example.

Addressing these points will make these new utilities more robust and easier to use.

[lispandfound]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a valuable set of helper functions for working with polygons and geometries in pygmt. The new utilities for plotting, labeling, and transforming geometries are well-implemented and will be very useful. The automatic grid scaling is also a nice addition. My review includes a few suggestions to improve consistency in naming and type hinting for better clarity and maintainability.

[lispandfound]

For reference, here is the example labeling a polygon. I've included it in the repo. None of the labels required specifying any exact coordinates.

[claudio525]

Nice one!