Skip to content

Add inverses for Aitoff, Winkel Tripel and Hammer; fail where there is none - #141

Merged
pomadchin merged 1 commit into
locationtech:masterfrom
SpaceOceanCorp:missing-inverses
Nov 14, 2026
Merged

pomadchin merged 1 commit into
locationtech:masterfrom
SpaceOceanCorp:missing-inverses

Conversation

@SpaceOceanCorp

Copy link
Copy Markdown
Contributor

Follow-up to the note at the end of #140.

Problem. Aitoff, Winkel Tripel and Hammer had no inverse, and Projection.projectInverse() returned its input unchanged, so inverseProject() on them (and on Airy, August, Boggs and the other projections without an inverse) passed projected coordinates off as radians. On a sphere of radius 6371000 m, the Hammer point x, y = (1060641.6, 2214667.4), which is (10, 20) degrees, came back as (9.54, 19.92).

Change

  • Aitoff: closed-form inverse, with atan2() for the latitude so it stays accurate near the poles. Points more than 180 degrees of arc from the centre throw a ProjectionException, as in PROJ.
  • Winkel Tripel: the Newton-Raphson inverse of PROJ (Bildirici, 2016), with the forms of Projections: fix precision loss and failures near the poles, the equator and the origin OSGeo/PROJ#4944 that stay accurate near the origin.
  • Hammer: closed-form inverse that takes +W and +M into account, accurate near the poles; points outside the ellipse throw.
  • The default projectInverse() now throws a ProjectionException instead of returning its input. LongLat, which relied on the identity, implements it. For projections where hasInverse() is false, inverseProject() therefore now throws, which is a change of behaviour worth a line under "Changed" in the CHANGELOG (I left the CHANGELOG to you, as you now group it by PR).

Tests. New InverseProjectionTest: forward and inverse against PROJ (cct) at five points per projection (Aitoff, Winkel Tripel, Hammer, and Hammer with +W=0.25 +M=2), round trips on a 7.5 degree grid, points outside the map, and that Airy throws. All 7 tests fail on master. mvn test passes for all modules (core 148 tests, GeoAPI 6).

This branch is based on master and touches different code from #140; the two merge without conflicts.

double cosAlpha = Math.cos(alpha);
// cos(phi) * sin(lam / 2) = halfX * k, sin(phi) = y * k, cos(phi) * cos(lam / 2) = cos(alpha)
lp.x = 2. * Math.atan2(halfX * k, cosAlpha);
lp.y = Math.atan2(y * k, Math.hypot(halfX * k, cosAlpha));

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤔 I would assume phi = atan2(y*k , hypot((x/2) * k , cos(alpha))) is the same as PROJs phi = asin(y*k)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, in exact arithmetic they are the same: with k = sin(alpha) / alpha, (x/2 * k)^2 + (y * k)^2 = sin(alpha)^2, so hypot(x/2 * k, cos(alpha)) = sqrt(1 - (y * k)^2) = cos(phi), and atan2(sin(phi), cos(phi)) = asin(sin(phi)).

They differ only in rounding close to the poles, where y * k is near 1 and asin() amplifies its last-bit error. Measured against a 50-digit evaluation on a sphere of the Moon's radius (1737400 m), 3000 random points per band:

asin(y * k) atan2
within 1e-6 degrees of a pole 3.0e-2 m 3.1e-10 m
within 0.01 degrees of a pole 1.9e-2 m 3.7e-10 m
latitudes 0 to 80 1.7e-9 m 3.6e-10 m

The atan2 form also cannot get an argument above 1 by rounding, so it needs no clamp. Happy to switch to PROJ's asin(y * k) if you prefer to match it exactly; the difference is only near the poles.

Paul S. Mamakos, Space Ocean Corp

}

@Test
public void testOutsideTheMap() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

only points far outside though?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, only points far outside, and that matches PROJ. Between the outline (longitude +/-180) and the edge of the inverse's mathematical domain, the formulas give a longitude beyond +/-180, which is then wrapped, so the point comes back as if it were on the other side of the map. PROJ does the same: its Aitoff inverse accepts the whole ellipse hypot(x/2, y) <= pi ("the sphere is double covered"; longitudes beyond +/-pi are kept only with +over), and its Hammer inverse has no outline check.

Measured on this branch, with points on the outline scaled by a factor f, 718 points per row:

f aitoff wintri hammer hammer +W=0.25 +M=2
1 - 1e-9 (inside) all returned, round trip 4e-9 m 4e-9 m 4e-9 m 1.5e-8 m
1.001 all returned (wrapped) all returned all returned all returned
1.1 all returned 108 rejected all returned all returned
1.5 all returned 368 rejected all rejected 72 rejected
3 all rejected 612 rejected all rejected all rejected

If you would rather reject everything outside the outline, it is a small change: throw when the computed |lam| > pi (plus a few ulps for points on the outline), and a test with points 1.001 times the outline. That would be stricter than PROJ, so it follows PROJ for now; happy to add it if you prefer.

Paul S. Mamakos, Space Ocean Corp

public ProjCoordinate projectInverse(double x, double y, ProjCoordinate lp) {
// Undo the M scaling of the forward: u = d * cos(phi) * sin(W * lam) and
// v = d * sin(phi), with d = sqrt(2 / (1 + cos(phi) * cos(W * lam)))
double u = x / mw;

@pomadchin pomadchin Nov 14, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

changed this one to be mw not w

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, that is the right change: since #143 keeps m as set and moves m / w into mw, the inverse has to undo mw. Checked on the rebased branch: with +W=0.25 +M=2, points just inside the outline round-trip within 1.5e-8 m, and testHammerWithWAndM (forward and inverse against PROJ) passes in CI.

Paul S. Mamakos, Space Ocean Corp

…s none

Aitoff, Winkel Tripel and Hammer had no inverse, and Projection.projectInverse
returned its input unchanged, so inverseProject() on these (and on Airy, August,
Boggs and the other projections without an inverse) silently passed projected
coordinates off as radians: on a sphere of radius 6371000 m, Hammer x, y =
(1060641.6, 2214667.4) came back as (9.54, 19.92) degrees instead of (10, 20).

- Aitoff: closed-form inverse, with atan2 for the latitude so it stays
  accurate near the poles.
- Winkel Tripel: the Newton-Raphson inverse of PROJ (Bildirici, 2016).
- Hammer: closed-form inverse that takes +W and +M into account (x is divided
  by mw = M / W, the factor the forward applies).
- The default projectInverse now throws a ProjectionException. LongLat, which
  relied on the identity, implements it.

InverseProjectionTest checks forward and inverse against PROJ (cct) at five
points per projection, round trips on a 7.5 degree grid, a point far outside
the map, and that Airy throws. All 7 tests fail before this change; the full
suite passes (154 tests).

Signed-off-by: SpaceOceanCorp <info@spaceoceancorp.com>

@pomadchin pomadchin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@pomadchin
pomadchin merged commit cc3d2af into locationtech:master Nov 14, 2026
2 checks passed
@SpaceOceanCorp
SpaceOceanCorp deleted the missing-inverses branch November 14, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants