DOC: describe geometry_area_perimeter size limit concretely

[Htet-Kaung-San]

Closes #1592.

The note on Geod.geometry_area_perimeter said only:

There are a few limitations :

• only works with areas up to half the size of the globe ;
• certain large polygons may return negative values.

As #1592 points out, that doesn't say what "large" or "certain" mean — whether it's city-sized or continent-sized, and whether shape, poles or the antimeridian are involved.

Both bullets turn out to be the same rule. The area is reduced modulo the total area of the ellipsoid into (-A/2, A/2], so a region covering more than half the ellipsoid is reported as the negated area of its complement:

from pyproj import Geod
from shapely.geometry import Polygon

geod = Geod(ellps="WGS84")
nearly_global = Polygon([(-179, -89), (179, -89), (179, 89), (-179, 89)])
print(geod.geometry_area_perimeter(nearly_global)[0])
# -2833262901265.9062

That polygon is wound counter-clockwise and encloses 99.4% of the globe, but comes back as roughly -0.56% — the thin strip left outside it, negated.

So the answers to the two questions in the issue are concrete:

• "large" means precisely "encloses more than half the ellipsoid" — about 2.55e14 m² on WGS84.
• "certain" isn't about shape, proximity to a pole, or crossing the antimeridian. Size alone decides it.

I checked the (-A/2, A/2] bound holds across a grid of boxes spanning ±10° to ±179.9° longitude and ±10° to ±89.9° latitude.

The docstring already carries a separate warning that traversal direction is signed, CCW positive. That's the other reason a result can be negative, and unlike the size limit it applies at any size, so I cross-referenced the two rather than describing them independently.

Changes

• Replace the vague note with the modulo rule, the WGS84 numbers, and an explicit statement of what does not matter.
• Cross-reference the traversal-direction warning as the other, size-independent cause.
• Add doctests for the wraparound and for recovering the enclosed area by adding the total ellipsoid area back.
• Changelog entry.

Documentation only — no behavior change.

Testing

flake8, ruff and codespell are clean on the changed files, and blacken-docs --skip-errors leaves them unchanged. The docstring's doctests pass (14 examples, 0 failures), including the two new ones. The 99.4% figure is 99.4445% before rounding, so it isn't sitting on a rounding boundary.

[Htet-Kaung-San]

Gentle nudge on this one — it's a docs-only change and the workflow is sitting at "action_required" (the first-time-contributor gate), so it hasn't run since I pushed the fixup.

Two things to save a review round:

• The earlier CI failure was mine: the new examples are shapely-based, so on environments without shapely the doctest count went 6 → 10 and test_doctest_wrapper tripped. Fixed in 0db4de4 by trimming one example and updating the expected count to 8. Verified against a source build with PROJ 9.8.1 — passes at 8 without shapely, 0 with, and unmodified main still passes at 6.
• The Conda ubuntu-latest job fails on an EPSG-name mismatch (RGF93 v1 to WGS 84 (1) vs ETRS89-FRA…), which is the pre-existing TST Fix tests after PROJ 9.8.1 EPSG database revert #1588 breakage also red on main, not something from this PR.

Happy to rebase or adjust wording if you'd prefer.

[djhoese]

I just rebased your branch (be careful pulling locally, may need git reset --hard origin/geometry-area-perimeter-limits. This rebase should have pulled in the latest CI fixes and kept the git history pretty clean.

[djhoese]

This looks reasonable to me. We'll wait for CI. Thanks!

Note: I won't pretend to fully understand the details here so if another maintainer wants to comment on this it would be appreciated.

[jorisvandenbossche]

I think this reads very difficult (at least for the non-native speaker that I am), what does "reduced modulo" mean?

[jorisvandenbossche]

I think there is no need to refer to "large" and explaining what it means, since the actual text using that word has now been removed (this now rather makes it confusing)

[jorisvandenbossche]

This is not actually a "nearly global" polygon in practice, because for geodesic edges, it takes the shortest path on the sphere, so this is actually connecting -179 to 179 crossing the anti-meridian, i.e. an edge of 2 degrees long, and not 358 degrees long. As a consequence of that interpretation, this polygon is actually oriented clock-wise (although shapely, which is not using geodesic logic, will indicate this is CCW), and that is the reason this is giving a negative result