Add enclose_poles to antimeridian module

[gadomski]

Related Issue(s):

• Required for Update Sentinel-5P microsoft/planetary-computer-tasks#167

Description:
Items whose assets include data over the poles can be hard to represent in WGS84, which is required for their geometries. This PR adds a new function, stactools.core.utils.antimeridian.enclose_poles, that modifies geometries that cross the antimerdian to enclose the polar regions.

Explanation

Here's some sentinel5p data:

As you can see, the data encloses both the north and the south poles. A simple geometry will follow the boundary of the data, but doesn't display (or really make sense at all) on a map:

To solve the problem, we can "box" the poles by detecting antimeridian crossings and adding points to cover the polar regions in WGS84:

This last image shows a geometry created with enclose_poles.

PR checklist:

• Code is formatted (run scripts/format).
• Code lints properly (run scripts/lint).
• Tests pass (run scripts/test).
• Documentation has been updated to reflect changes, if applicable.
• Changes are added to the CHANGELOG.

[TomAugspurger]

Looks good, thanks.

One request for an additional test, which I think is important.

Only other question would be whether we want a test that verifies we raise a ValueError when the polygon has an interior ring. I'm not 100% sure why that matters (and am OK remaining ignorant here), so I'll let you judge whether a test for that case is important.

[gadomski]

Only other question would be whether we want a test that verifies we raise a ValueError when the polygon has an interior ring. I'm not 100% sure why that matters (and am OK remaining ignorant here), so I'll let you judge whether a test for that case is important.

I don't think its particularly necessary, as this is more of a one-off utility rather than a foundational API function. I'm sure there's plenty of other edge cases that would blow this function up that aren't tested.

That being said, I have a thought about one more edge case we could test for -- the case where there's more than two antimeridian crossings (e.g. a swath over the Pacific). I'm going to convert to draft until I can cook up a test case (or better yet, a real-world example) of that and see if we can handle it.

[gadomski]

@TomAugspurger I've added code and tests (and comments, because it's reasonably complex code) to handle multiple crossings. Ready for re-review, thanks.

[TomAugspurger]

Looks good, thanks!

[jlaura]

Just a quick kudos post @gadomski. This functionality works wonderfully on some Mars polar data!

Before:

After: