maplibre-gl 6.2.0 → 6.4.0

package/src/geo/projection/camera_helper.ts

@@ -16,6 +16,11 @@ export type MapControlsDeltas = {
     pitchDelta: number;
     rollDelta: number;
     around: Point;
+    /**
+     * Elevation in meters of the terrain under `around` at gesture start; when set,
+     * pan and zoom keep the terrain at this elevation under `around`.
+     */
+    aroundElevation?: number;
 };
 
 export type CameraForBoxAndBearingHandlerResult = {

package/src/geo/projection/globe_transform.test.ts

@@ -4,11 +4,12 @@ import Point from '@mapbox/point-geometry';
 import {LngLat} from '../lng_lat.ts';
 import {GlobeTransform} from './globe_transform.ts';
 import {CanonicalTileID, OverscaledTileID, UnwrappedTileID} from '../../tile/tile_id.ts';
-import {angularCoordinatesRadiansToVector, mercatorCoordinatesToAngularCoordinatesRadians, sphereSurfacePointToCoordinates} from './globe_utils.ts';
+import {angularCoordinatesRadiansToVector, mercatorCoordinatesToAngularCoordinatesRadians, sphereSurfacePointToCoordinates, versorSetLocationAtPoint} from './globe_utils.ts';
 import {expectToBeCloseToArray} from '../../util/test/util.ts';
 import {MercatorCoordinate} from '../mercator_coordinate.ts';
 import {tileCoordinatesToLocation} from './mercator_utils.ts';
 import {MercatorTransform} from './mercator_transform.ts';
+import {differenceOfAnglesDegrees, MAX_VALID_LATITUDE} from '../../util/util.ts';
 
 function testPlaneAgainstLngLat(lngDegrees: number, latDegrees: number, plane: number[]) {
     const lat = latDegrees / 180.0 * Math.PI;
@@ -400,6 +401,31 @@ describe('GlobeTransform', () => {
                     expect(globeTransform.center.lat).toBeCloseTo(20.659450722109348, precisionDigits);
                 });
             });
+
+            test('ignores the elevation parameter when rendering the globe', () => {
+                const transform = createGlobeTransform();
+                transform.setZoom(1);
+                coords = new LngLat(5, 10);
+                point = new Point(320, 240);
+                transform.setLocationAtPoint(coords, point, 1000);
+                unprojected = transform.screenPointToLocationAtElevation(point, 1000);
+                expect(unprojected.lng).toBeCloseTo(coords.lng, precisionDigits);
+                expect(unprojected.lat).toBeCloseTo(coords.lat, precisionDigits);
+            });
+
+            test('solves on the plane at the given elevation when rendering mercator', () => {
+                const transform = createGlobeTransform();
+                transform.setZoom(5);
+                transform.setPitch(40);
+                transform.setTransitionState(0); // rendering mercator
+                coords = new LngLat(5, 10);
+                point = new Point(320, 200);
+                transform.setLocationAtPoint(coords, point, 500);
+                unprojected = transform.screenPointToLocationAtElevation(point, 500);
+                // exact up to the center-latitude change the solve itself causes (~1e-5 deg)
+                expect(unprojected.lng).toBeCloseTo(coords.lng, 3);
+                expect(unprojected.lat).toBeCloseTo(coords.lat, 3);
+            });
         });
     });
 
@@ -618,4 +644,131 @@ describe('GlobeTransform', () => {
         expect(globeTransform.center.lng).toBeCloseTo(originalLng, 10);
         expect(globeTransform.center.lat).toBeCloseTo(originalLat, 10);
     });
+
+    describe('versorSetLocationAtPoint', () => {
+        const precisionDigits = 4;
+        const globeTransform = createGlobeTransform();
+        globeTransform.setZoom(1);
+        globeTransform.setTransitionState(1);
+        let coords: LngLat;
+        let point: Point;
+        let unprojected: LngLat;
+
+        test('round-trip accuracy', () => {
+            coords = new LngLat(20, 30);
+            point = new Point(280, 200);
+            versorSetLocationAtPoint(globeTransform, coords, point, undefined, false);
+            unprojected = globeTransform.screenPointToLocation(point);
+            expect(unprojected.lng).toBeCloseTo(coords.lng, precisionDigits);
+            expect(unprojected.lat).toBeCloseTo(coords.lat, precisionDigits);
+        });
+
+        test('round-trip accuracy at center', () => {
+            coords = new LngLat(10, 15);
+            point = new Point(320, 240);
+            versorSetLocationAtPoint(globeTransform, coords, point);
+            unprojected = globeTransform.screenPointToLocation(point);
+            expect(unprojected.lng).toBeCloseTo(coords.lng, precisionDigits);
+            expect(unprojected.lat).toBeCloseTo(coords.lat, precisionDigits);
+        });
+
+        test('near-pole panning stays finite', () => {
+            globeTransform.setCenter(new LngLat(0, 80));
+            coords = new LngLat(10, 85);
+            point = new Point(300, 230);
+            versorSetLocationAtPoint(globeTransform, coords, point);
+            expect(isNaN(globeTransform.center.lng)).toBe(false);
+            expect(isNaN(globeTransform.center.lat)).toBe(false);
+            expect(isNaN(globeTransform.bearing)).toBe(false);
+        });
+
+        test('identical source and target points leave the center unchanged', () => {
+            const centerBefore = globeTransform.center;
+            point = new Point(320, 240);
+            coords = globeTransform.screenPointToLocation(point);
+            versorSetLocationAtPoint(globeTransform, coords, point);
+            expect(globeTransform.center.lng).toBeCloseTo(centerBefore.lng, precisionDigits);
+            expect(globeTransform.center.lat).toBeCloseTo(centerBefore.lat, precisionDigits);
+        });
+
+        test('bearing changes when panning off-center without a fixed bearing', () => {
+            const bearingBefore = globeTransform.bearing;
+            coords = new LngLat(20, 30);
+            point = new Point(250, 180);
+            versorSetLocationAtPoint(globeTransform, coords, point, undefined, false);
+            expect(globeTransform.bearing).not.toBeCloseTo(bearingBefore, 1);
+        });
+
+        test('target points that miss the globe are ignored without a pan delta', () => {
+            const freshTransform = createGlobeTransform();
+            freshTransform.setZoom(1);
+            freshTransform.setTransitionState(1);
+            freshTransform.setCenter(new LngLat(5, 10));
+            const lngBefore = freshTransform.center.lng;
+            const latBefore = freshTransform.center.lat;
+            const bearingBefore = freshTransform.bearing;
+            point = new Point(620, 240);
+            expect(freshTransform.isPointOnMapSurface(point)).toBe(false);
+            coords = freshTransform.screenPointToLocation(point);
+            versorSetLocationAtPoint(freshTransform, coords, point);
+            expect(freshTransform.center.lng).toBe(lngBefore);
+            expect(freshTransform.center.lat).toBe(latBefore);
+            expect(freshTransform.bearing).toBe(bearingBefore);
+        });
+
+        test('panning continues once the cursor leaves the globe', () => {
+            const freshTransform = createGlobeTransform();
+            freshTransform.setZoom(1);
+            freshTransform.setTransitionState(1);
+            freshTransform.setCenter(new LngLat(5, 10));
+            const lngBefore = freshTransform.center.lng;
+            const bearingBefore = freshTransform.bearing;
+            point = new Point(620, 240);
+            expect(freshTransform.isPointOnMapSurface(point)).toBe(false);
+            coords = freshTransform.screenPointToLocation(point);
+            versorSetLocationAtPoint(freshTransform, coords, point, new Point(20, 0));
+            expect(freshTransform.center.lng).not.toBe(lngBefore);
+            expect(isNaN(freshTransform.center.lng)).toBe(false);
+            expect(isNaN(freshTransform.center.lat)).toBe(false);
+            expect(freshTransform.bearing).toBe(bearingBefore);
+        });
+
+        test('panning does not freeze near a centred pole', () => {
+            // With the pole centred the dial supplies all of the longitude change, and the center
+            // latitude is already clamped, so if the dial gives up the drag stops moving entirely.
+            const tr = createGlobeTransform();
+            tr.setZoom(1);
+            tr.setTransitionState(1);
+            tr.setCenter(new LngLat(0, MAX_VALID_LATITUDE));
+            const pole = tr.locationToScreenPoint(new LngLat(0, 90));
+            const cursor = new Point(pole.x + 10, pole.y);
+            const panDelta = new Point(0, 8); // tangential, so it sweeps around the pole
+            const lngBefore = tr.center.lng;
+            const location = tr.screenPointToLocation(cursor.sub(panDelta));
+            versorSetLocationAtPoint(tr, location, cursor, panDelta);
+            expect(Math.abs(differenceOfAnglesDegrees(lngBefore, tr.center.lng))).toBeGreaterThan(1);
+        });
+
+        test('panning off the globe is slower than on it', () => {
+            const travel = (screenPoint: Point) => {
+                const tr = createGlobeTransform();
+                tr.setZoom(1);
+                tr.setTransitionState(1);
+                tr.setCenter(new LngLat(0, 0));
+                const panDelta = new Point(20, 0);
+                const location = tr.screenPointToLocation(screenPoint.sub(panDelta));
+                versorSetLocationAtPoint(tr, location, screenPoint, panDelta);
+                return Math.abs(differenceOfAnglesDegrees(0, tr.center.lng));
+            };
+            const onGlobe = new Point(340, 240);
+            const offGlobe = new Point(620, 240);
+            const reference = createGlobeTransform();
+            reference.setZoom(1);
+            reference.setTransitionState(1);
+            reference.setCenter(new LngLat(0, 0));
+            expect(reference.isPointOnMapSurface(onGlobe)).toBe(true);
+            expect(reference.isPointOnMapSurface(offGlobe)).toBe(false);
+            expect(travel(offGlobe)).toBeLessThan(travel(onGlobe));
+        });
+    });
 });

package/src/geo/projection/globe_transform.ts

@@ -411,13 +411,13 @@ export class GlobeTransform implements ITransform {
      * Note: automatically adjusts zoom to keep planet size consistent
      * (same size before and after a {@link setLocationAtPoint} call).
      */
-    setLocationAtPoint(lnglat: LngLat, point: Point): void {
+    setLocationAtPoint(lnglat: LngLat, point: Point, elevation?: number): void {
         if (!this.isGlobeRendering) {
-            this._mercatorTransform.setLocationAtPoint(lnglat, point);
+            this._mercatorTransform.setLocationAtPoint(lnglat, point, elevation);
             this.apply(this._mercatorTransform, false);
             return;
         }
-        this._verticalPerspectiveTransform.setLocationAtPoint(lnglat, point);
+        this._verticalPerspectiveTransform.setLocationAtPoint(lnglat, point, elevation);
         this.apply(this._verticalPerspectiveTransform, false);
         return;
     }
@@ -434,6 +434,10 @@ export class GlobeTransform implements ITransform {
         return this.currentTransform.screenPointToLocation(p, terrain);
     }
 
+    screenPointToLocationAtElevation(p: Point, elevation: number): LngLat {
+        return this.currentTransform.screenPointToLocationAtElevation(p, elevation);
+    }
+
     isPointOnMapSurface(p: Point, terrain?: Terrain): boolean {
         return this.currentTransform.isPointOnMapSurface(p, terrain);
     }

package/src/geo/projection/globe_utils.ts

@@ -1,8 +1,9 @@
-import {type ReadonlyVec4, vec3} from 'gl-matrix';
-import {clamp, createVec3f64, lerp, MAX_VALID_LATITUDE, mod, remapSaturate, scaleZoom, wrap} from '../../util/util.ts';
+import {quat, type ReadonlyVec4, vec3} from 'gl-matrix';
+import {clamp, createVec3f64, createVec4f64, lerp, MAX_VALID_LATITUDE, mod, remapSaturate, scaleZoom, wrap} from '../../util/util.ts';
 import {LngLat} from '../lng_lat.ts';
 import {EXTENT} from '../../data/extent.ts';
 import type Point from '@mapbox/point-geometry';
+import type {ITransform} from '../transform_interface.ts';
 
 export function getGlobeCircumferencePixels(transform: {worldSize: number; center: {lat: number}}): number {
     const radius = getGlobeRadiusPixels(transform.worldSize, transform.center.lat);
@@ -107,6 +108,192 @@ export function sphereSurfacePointToCoordinates(surface: vec3): LngLat {
     }
 }
 
+/**
+ * Returns the globe orientation quaternion for the given map center and bearing.
+ * The inverse of {@link lngLatBearingFromOrientation}.
+ */
+export function orientationFromLngLatBearing(lngLat: LngLat, bearing: number): quat {
+    return quat.fromEuler(createVec4f64(), -lngLat.lng, -lngLat.lat, bearing);
+}
+
+/**
+ * Given a globe orientation quaternion, returns the corresponding map center and bearing.
+ * The inverse of {@link orientationFromLngLatBearing}.
+ */
+export function lngLatBearingFromOrientation(q: quat): { lng: number; lat: number; bearing: number } {
+    const x = q[0], y = q[1], z = q[2], w = q[3];
+    const lng = -Math.atan2(2 * (w * x + y * z), 1 - 2 * (x * x + y * y)) * 180 / Math.PI;
+    const lat = -Math.asin(clamp(2 * (w * y - z * x), -1, 1)) * 180 / Math.PI;
+    const bearing = Math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z)) * 180 / Math.PI;
+    return {lng, lat, bearing};
+}
+
+/**
+ * How much of the angle between the view axis and the horizon is given over to easing off, measured
+ * inward from the horizon. Only the outermost sliver of the globe is affected, where a pixel is
+ * already worth degrees of arc.
+ *
+ * This is the one number here open to taste, and it sets two things at once: narrowing it keeps the
+ * drag exact over more of the globe, and, since the exact curve steepens towards tangency, hands
+ * over at a higher rate too. Bell has no such freedom, as a hyperbola of the fixed form `k/d` meets
+ * a sphere in both value and slope at exactly one radius.
+ */
+const PAN_FALLOFF_BAND = 0.1;
+
+/**
+ * Radius around the pole's screen position, in pixels, within which the cursor's sweep around it
+ * stops being trusted at face value: the angle a given drag subtends grows without bound as the
+ * cursor closes on the pole, and at the pole itself there is no angle at all.
+ */
+const DIAL_MIN_RADIUS_PIXELS = 20;
+
+/** Kept just below a half turn so the center cannot land exactly on the far side of the globe. */
+const PAN_MAX_ANGLE = Math.PI * 0.98;
+
+/**
+ * Returns the point on the globe that a drag towards `point` should aim at.
+ *
+ * Exact tracking breaks down at the silhouette: the ray meets the globe at `asin(D sin a) - a`,
+ * whose slope runs away to infinity as the ray goes tangent, and past it there is no intersection
+ * at all. So the exact curve is left {@link PAN_FALLOFF_BAND} early and continued with a hyperbola
+ * matching it in value and slope, easing off and saturating short of the far side. Bell's virtual
+ * trackball takes the same idea of easing a sphere into a hyperbola before the rim, though it fits
+ * the curve differently: SGI's `trackball.c`, described in Henriksen, Sporring and Hornbæk,
+ * "Virtual Trackballs Revisited", IEEE TVCG 10(2):206-216, 2004.
+ *
+ * The angle comes from atan2, so a ray pointing away from the globe is a wide angle the falloff
+ * saturates rather than a case to reject.
+ * @param tr - The transform being dragged.
+ * @param point - The cursor position.
+ */
+function panSurfaceLocation(tr: ITransform, point: Point): LngLat {
+    const origin = tr.cameraPosition;
+    const distance = vec3.length(origin);
+    if (distance <= 1) {
+        return tr.screenPointToLocation(point);
+    }
+
+    const u = createVec3f64();
+    vec3.normalize(u, origin);
+    const direction = tr.getRayDirectionFromPixel(point);
+    const c = -vec3.dot(direction, u);
+    const lateral = createVec3f64();
+    vec3.scaleAndAdd(lateral, direction, u, c);
+    const s = vec3.length(lateral);
+    if (s < 1e-9) {
+        return tr.screenPointToLocation(point);
+    }
+
+    const angle = Math.atan2(s, c);
+    const horizonAngle = Math.asin(1 / distance);
+    const handoverAngle = horizonAngle * (1 - PAN_FALLOFF_BAND);
+    if (angle < handoverAngle) {
+        return tr.screenPointToLocation(point);
+    }
+
+    const sinHandover = distance * Math.sin(handoverAngle);
+    const targetAtHandover = Math.asin(clamp(sinHandover, -1, 1)) - handoverAngle;
+    const slopeAtHandover = distance * Math.cos(handoverAngle) / Math.sqrt(Math.max(1 - sinHandover * sinHandover, 1e-12)) - 1;
+    const room = PAN_MAX_ANGLE - targetAtHandover;
+    const excess = angle - handoverAngle;
+    const target = targetAtHandover + room * (slopeAtHandover * excess) / (room + slopeAtHandover * excess);
+
+    const e = createVec3f64();
+    vec3.scale(e, lateral, 1 / s);
+    const surface = createVec3f64();
+    vec3.scale(surface, u, Math.cos(clamp(target, 0, PAN_MAX_ANGLE)));
+    vec3.scaleAndAdd(surface, surface, e, Math.sin(clamp(target, 0, PAN_MAX_ANGLE)));
+    vec3.normalize(surface, surface);
+    return sphereSurfacePointToCoordinates(surface);
+}
+
+/**
+ * Rotates the globe so that the given location appears at the given screen point, by composing
+ * versors, the unit quaternions that represent rotations. Unlike the bearing-preserving
+ * {@link ITransform.setLocationAtPoint}, this stays smooth near and across the poles, and keeps
+ * panning once the cursor leaves the globe.
+ *
+ * Note: the delta rotation's axis is in the surface-vector frame of
+ * {@link angularCoordinatesToSurfaceVector}, while the orientation quaternion uses the Euler frame
+ * of {@link orientationFromLngLatBearing}, hence the component swizzle where they combine. Zoom is
+ * adjusted to keep the planet the same size, as `setLocationAtPoint` does.
+ * @param tr - The transform to rotate.
+ * @param lnglat - The location to bring under `point`.
+ * @param point - The screen point that `lnglat` should appear at.
+ * @param panDelta - The drag's pixel delta. Used to re-derive the previous cursor location through
+ * {@link panSurfaceLocation}, since both ends of the rotation must come from the same mapping.
+ * @param fixedBearing - Applies the swing only, keeping the bearing fixed, which is what dragging
+ * the globe does. Pass `false` to apply the twist about the view axis as well, so that the grabbed
+ * location tracks the cursor exactly and the bearing drifts with it.
+ */
+export function versorSetLocationAtPoint(tr: ITransform, lnglat: LngLat, point: Point, panDelta?: Point, fixedBearing = true): void {
+    const pointLngLat = panSurfaceLocation(tr, point);
+    let sourceLngLat = lnglat;
+    if (panDelta) {
+        sourceLngLat = panSurfaceLocation(tr, point.sub(panDelta));
+    } else if (!tr.isPointOnMapSurface(point)) {
+        return;
+    }
+
+    const vecToPixelCurrent = angularCoordinatesToSurfaceVector(pointLngLat);
+    const vecToTarget = angularCoordinatesToSurfaceVector(sourceLngLat);
+    const centerQuat = orientationFromLngLatBearing(tr.center, tr.bearing);
+    const w = vec3.cross(createVec3f64(), vecToTarget, vecToPixelCurrent);
+    const l = Math.sqrt(vec3.dot(w, w));
+    const t = Math.acos(clamp(vec3.dot(vecToTarget, vecToPixelCurrent), -1, 1)) / 2;
+    const s = Math.sin(t);
+    const delta = l ? quat.fromValues((w[1] / l) * s, (-w[0] / l) * s, (w[2] / l) * s, Math.cos(t)) : quat.fromValues(0, 0, 0, 1);
+    const newCenterQuat = quat.multiply(createVec4f64(), centerQuat, delta);
+    const {lng: newCenterLng, lat: newCenterLat, bearing: newBearing} = lngLatBearingFromOrientation(newCenterQuat);
+
+    const oldLat = tr.center.lat;
+    const finalLat = clamp(newCenterLat, -90, 90);
+    const finalLng = fixedBearing ? fixedBearingLongitude(tr, point, panDelta, newCenterLng) : newCenterLng;
+
+    tr.setCenter(new LngLat(wrap(finalLng, -180, 180), finalLat));
+    if (!fixedBearing) {
+        tr.setBearing(newBearing);
+    }
+    tr.setZoom(tr.zoom + getZoomAdjustment(oldLat, tr.center.lat));
+}
+
+/**
+ * Returns the center longitude for a bearing-preserving drag.
+ *
+ * The swing longitude becomes ill-conditioned near the pole and the grabbed location slips away
+ * from the cursor, so within the last ~12 degrees of latitude the cursor is treated as turning a
+ * dial around the pole, blended in with a smoothstep anchored on {@link MAX_VALID_LATITUDE}, the
+ * highest latitude the center can reach. The sweep comes from the raw pixel delta rather than a
+ * round-tripped previous cursor position, which would lose its sign to cancellation at the pole,
+ * and is damped within {@link DIAL_MIN_RADIUS_PIXELS} so it eases to nothing there instead of
+ * being dropped, which would leave a spot where the drag could not move at all.
+ * @param tr - The transform being dragged.
+ * @param point - The cursor position.
+ * @param panDelta - The drag's pixel delta, or undefined to use the swing longitude only.
+ * @param newCenterLng - The swing target longitude.
+ * @returns the center longitude to apply.
+ */
+function fixedBearingLongitude(tr: ITransform, point: Point, panDelta: Point | undefined, newCenterLng: number): number {
+    const oldLng = tr.center.lng;
+    const oldLat = tr.center.lat;
+    const poleLat = oldLat >= 0 ? 90 : -90;
+    const polePoint = tr.locationToScreenPoint(new LngLat(0, poleLat));
+    const rx = point.x - polePoint.x, ry = point.y - polePoint.y;
+    const r2 = rx * rx + ry * ry;
+
+    const tRamp = clamp(1 - (MAX_VALID_LATITUDE - Math.abs(oldLat)) / 12, 0, 1);
+    const dial = tRamp * tRamp * (3 - 2 * tRamp);
+    const dLngSwing = mod(newCenterLng - oldLng + 180, 360) - 180;
+
+    let dLngDial = 0;
+    if (dial > 0 && panDelta) {
+        const dTheta = (rx * panDelta.y - ry * panDelta.x) / Math.max(r2, DIAL_MIN_RADIUS_PIXELS * DIAL_MIN_RADIUS_PIXELS);
+        dLngDial = (poleLat > 0 ? 1 : -1) * dTheta * 180 / Math.PI;
+    }
+
+    return oldLng + (1 - dial) * dLngSwing + dial * dLngDial;
+}
+
 /**
  * Given a normalized horizon plane in Ax+By+Cz+D=0 format, compute the center and radius of
  * the circle in that plain that contains the entire visible portion of the unit sphere from horizon

package/src/geo/projection/mercator_camera_helper.ts

@@ -47,7 +47,7 @@ export class MercatorCameraHelper implements ICameraHelper {
         if (deltas.around.distSqr(tr.centerPoint) < 1.0e-2) {
             return;
         }
-        tr.setLocationAtPoint(preZoomAroundLoc, deltas.around);
+        tr.setLocationAtPoint(preZoomAroundLoc, deltas.around, deltas.aroundElevation);
     }
 
     cameraForBoxAndBearing(options: CameraForBoundsOptions, padding: PaddingOptions, bounds: LngLatBounds, bearing: number, tr: IReadonlyTransform): CameraForBoxAndBearingHandlerResult {

package/src/geo/projection/mercator_transform.ts

@@ -308,10 +308,18 @@ export class MercatorTransform implements ITransform {
         this._helper.recalculateZoomAndCenter(elevation);
     }
 
-    setLocationAtPoint(lnglat: LngLat, point: Point): void {
-        const z = mercatorZfromAltitude(this.elevation, this.center.lat);
+    /**
+     * Moves the center so that `lnglat`, on the ground at `elevation` meters, renders
+     * at the screen `point`. Both rays are cast through the same inverse pixel matrix
+     * so its inversion error cancels out of their difference; the current-center ray
+     * must be intersected at the center's own elevation (z=0) — intersecting it with
+     * the elevated plane would land `(elevation - centerElevation)·tan(pitch)` away
+     * from the center and make repeated calls drift.
+     */
+    setLocationAtPoint(lnglat: LngLat, point: Point, elevation: number = this.elevation): void {
+        const z = elevation - this.elevation;
         const a = this.screenPointToMercatorCoordinateAtZ(point, z);
-        const b = this.screenPointToMercatorCoordinateAtZ(this.centerPoint, z);
+        const b = this.screenPointToMercatorCoordinateAtZ(this.centerPoint, 0);
         const loc = MercatorCoordinate.fromLngLat(lnglat);
         const newCenter = new MercatorCoordinate(
             loc.x - (a.x - b.x),
@@ -332,6 +340,10 @@ export class MercatorTransform implements ITransform {
         return this.screenPointToMercatorCoordinate(p, terrain)?.toLngLat();
     }
 
+    screenPointToLocationAtElevation(p: Point, elevation: number): LngLat {
+        return this.screenPointToMercatorCoordinateAtZ(p, elevation - this.elevation)?.toLngLat();
+    }
+
     screenPointToMercatorCoordinate(p: Point, terrain?: Terrain): MercatorCoordinate {
         // get point-coordinate from terrain coordinates framebuffer
         if (terrain) {
@@ -343,10 +355,14 @@ export class MercatorTransform implements ITransform {
         return this.screenPointToMercatorCoordinateAtZ(p);
     }
 
-    screenPointToMercatorCoordinateAtZ(p: Point, mercatorZ?: number): MercatorCoordinate {
+    /**
+     * Intersects the ray through a screen point with the horizontal plane at `z`,
+     * given in meters relative to the plane at the center's elevation (not mercator units).
+     */
+    screenPointToMercatorCoordinateAtZ(p: Point, z?: number): MercatorCoordinate {
 
         // calculate point-coordinate on flat earth
-        const targetZ = mercatorZ ? mercatorZ : 0;
+        const targetZ = z ? z : 0;
         // since we don't know the correct projected z value for the point,
         // unproject two points to get a line and then find the point on that
         // line with z=0

package/src/geo/projection/vertical_perspective_camera_helper.test.ts

@@ -0,0 +1,24 @@
+import {describe, expect, test} from 'vitest';
+import Point from '@mapbox/point-geometry';
+import {LngLat} from '../lng_lat.ts';
+import {GlobeTransform} from './globe_transform.ts';
+import {VerticalPerspectiveCameraHelper} from './vertical_perspective_camera_helper.ts';
+import {type MapControlsDeltas} from './camera_helper.ts';
+
+describe('VerticalPerspectiveCameraHelper.handleMapControlsPan', () => {
+    test('preserves bearing away from the poles', () => {
+        const tr = new GlobeTransform();
+        tr.resize(512, 512);
+        tr.setZoom(4);
+        tr.setCenter(new LngLat(0, 20));
+        tr.setTransitionState(1);
+        const helper = new VerticalPerspectiveCameraHelper();
+
+        helper.handleMapControlsPan(
+            {panDelta: new Point(50, 30), around: tr.centerPoint} as MapControlsDeltas,
+            tr, tr.center);
+
+        expect(tr.bearing).toBe(0);
+        expect(tr.center.lat).not.toBe(20);
+    });
+});