maplibre-gl 6.2.0 → 6.4.0

package/src/ui/handler_inertia.test.ts

@@ -0,0 +1,91 @@
+import {describe, beforeEach, afterEach, test, expect} from 'vitest';
+import Point from '@mapbox/point-geometry';
+import {DOM} from '../util/dom.ts';
+import {beforeMapTest} from '../util/test/util.ts';
+import {restoreNow, setNow} from '../util/time_control.ts';
+import {Map} from './map.ts';
+import type {EaseToOptions} from './camera.ts';
+import {HandlerInertia} from './handler_inertia.ts';
+
+type PanGesture = {
+    /**
+     * The pixels panned in each recorded frame, oldest first. `null` records a frame without
+     * any delta, which is what a terrain gesture does while the camera is not moving.
+     */
+    frames: Array<number | null>;
+    /**
+     * The milliseconds between the recorded frames.
+     */
+    frameTime?: number;
+    /**
+     * The milliseconds the gesture is held still between the last recorded frame and the release.
+     */
+    holdTime?: number;
+};
+
+/**
+ * Records a horizontal pan gesture and returns the inertial ease it produces, if any.
+ */
+function panAndRelease(inertia: HandlerInertia, {frames, frameTime = 16, holdTime = 0}: PanGesture) {
+    let time = 1000;
+    setNow(time);
+    for (const pixels of frames) {
+        setNow(time += frameTime);
+        inertia.record(pixels === null ? {} : {panDelta: new Point(pixels, 0)});
+    }
+    setNow(time + holdTime);
+    return inertia._onMoveEnd();
+}
+
+/**
+ * Returns the horizontal distance the map keeps panning after the gesture ended.
+ */
+function panOnDistance(ease: EaseToOptions) {
+    return (ease.offset as Point).x;
+}
+
+describe('HandlerInertia', () => {
+    let map: Map;
+    let inertia: HandlerInertia;
+
+    beforeEach(() => {
+        beforeMapTest();
+        map = new Map({container: DOM.create('div', '', window.document.body)});
+        inertia = new HandlerInertia(map);
+    });
+
+    afterEach(() => {
+        restoreNow();
+        map.remove();
+    });
+
+    test('pans on when the gesture is released while still moving', () => {
+        const ease = panAndRelease(inertia, {frames: [20, 20, 20, 20, 20]});
+
+        expect(panOnDistance(ease)).toBeGreaterThan(50);
+    });
+
+    test('barely pans on when the gesture is held still before being released', () => {
+        const ease = panAndRelease(inertia, {frames: [20, 20, 20, 20, 20], holdTime: 100});
+
+        expect(Math.abs(panOnDistance(ease))).toBeLessThan(5);
+    });
+
+    test('pans on at frame rates too low for two frames to fit into the velocity window', () => {
+        const ease = panAndRelease(inertia, {frames: [80, 80, 80], frameTime: 80});
+
+        expect(panOnDistance(ease)).toBeGreaterThan(20);
+    });
+
+    test('does not pan on when a single frame was recorded, twice in a row', () => {
+        expect(panAndRelease(inertia, {frames: [20]})).toBeUndefined();
+        // the frame left over by the first gesture must not be measured as part of the second
+        expect(panAndRelease(inertia, {frames: [20]})).toBeUndefined();
+    });
+
+    test('does not ease when the recorded frames hold no movement', () => {
+        const ease = panAndRelease(inertia, {frames: [20, 20, 20, null, null, null, null]});
+
+        expect(ease).toBeUndefined();
+    });
+});

package/src/ui/handler_inertia.ts

@@ -3,6 +3,7 @@ import {bezier, clamp, extend, evaluateZoomSnap} from '../util/util.ts';
 import Point from '@mapbox/point-geometry';
 
 import type {DragPanOptions} from './handler/shim/drag_pan.ts';
+import type {HandlerResult} from './handler_manager.ts';
 import type {EaseToOptions} from './camera.ts';
 import type {Map} from './map.ts';
 
@@ -43,12 +44,24 @@ export type InertiaOptions = {
     maxSpeed: number;
 };
 
+/**
+ * The maximum age of a recorded gesture update, in milliseconds.
+ */
+const BUFFER_CUTOFF = 160;
+
+/**
+ * The time window the gesture velocity is measured over, in milliseconds.
+ */
+const VELOCITY_WINDOW = 60;
+
+type InertiaBufferEntry = {
+    time: number;
+    settings: HandlerResult;
+};
+
 export class HandlerInertia {
     _map: Map;
-    _inertiaBuffer: Array<{
-        time: number;
-        settings: any;
-    }>;
+    _inertiaBuffer: InertiaBufferEntry[];
 
     constructor(map: Map) {
         this._map = map;
@@ -59,23 +72,54 @@ export class HandlerInertia {
         this._inertiaBuffer = [];
     }
 
-    record(settings: any): void {
+    record(settings: HandlerResult): void {
         this._drainInertiaBuffer();
         this._inertiaBuffer.push({time: now(), settings});
     }
 
     _drainInertiaBuffer(): void {
         const inertia = this._inertiaBuffer,
-            currentTime = now(),
-            cutoff = 160;   //msec
+            currentTime = now();
 
-        while (inertia.length > 0 && currentTime - inertia[0].time > cutoff)
+        while (inertia.length > 0 && currentTime - inertia[0].time > BUFFER_CUTOFF)
             inertia.shift();
     }
 
+    /**
+     * Returns the entries the velocity is measured from: everything recorded within
+     * {@link VELOCITY_WINDOW} before now, but never fewer than the last two, so that
+     * inertia also works below two recorded updates per window.
+     */
+    _getVelocityEntries(): InertiaBufferEntry[] {
+        const inertia = this._inertiaBuffer;
+        const windowStart = now() - VELOCITY_WINDOW;
+
+        let firstIndex = Math.max(0, inertia.length - 2);
+        while (firstIndex > 0 && inertia[firstIndex - 1].time >= windowStart) {
+            firstIndex--;
+        }
+
+        return inertia.slice(firstIndex);
+    }
+
+    /**
+     * Returns the ease which continues the gesture that has just ended.
+     *
+     * The velocity is measured over the time up to the release and not up to the last
+     * recorded movement, so that a gesture held still before being released has a lower
+     * velocity, down to no inertia at all. The delta of an entry happened before it was
+     * recorded, so the first entry only marks the start of the measured interval; anchors
+     * are the exception, as they describe the state at the moment of their entry.
+     *
+     * @param panInertiaOptions - overrides for the pan inertia defaults
+     * @returns the ease options, or `undefined` when the measured interval holds no
+     * movement, which terrain gestures produce by recording updates without any delta
+     */
     _onMoveEnd(panInertiaOptions?: DragPanOptions | boolean): EaseToOptions {
         this._drainInertiaBuffer();
-        if (this._inertiaBuffer.length < 2) {
+        const entries = this._getVelocityEntries();
+        if (entries.length < 2) {
+            this.clear();
             return;
         }
 
@@ -89,18 +133,25 @@ export class HandlerInertia {
             around: undefined
         };
 
-        for (const {settings} of this._inertiaBuffer) {
+        for (const {settings} of entries) {
+            if (settings.around) deltas.around = settings.around;
+            if (settings.pinchAround) deltas.pinchAround = settings.pinchAround;
+        }
+
+        for (const {settings} of entries.slice(1)) {
             deltas.zoom += settings.zoomDelta || 0;
             deltas.bearing += settings.bearingDelta || 0;
             deltas.pitch += settings.pitchDelta || 0;
             deltas.roll += settings.rollDelta || 0;
             if (settings.panDelta) deltas.pan._add(settings.panDelta);
-            if (settings.around) deltas.around = settings.around;
-            if (settings.pinchAround) deltas.pinchAround = settings.pinchAround;
         }
 
-        const lastEntry = this._inertiaBuffer[this._inertiaBuffer.length - 1];
-        const duration = (lastEntry.time - this._inertiaBuffer[0].time);
+        if (!deltas.pan.mag() && !deltas.zoom && !deltas.bearing && !deltas.pitch && !deltas.roll) {
+            this.clear();
+            return;
+        }
+
+        const duration = now() - entries[0].time;
 
         const easeOptions = {} as any;
 

package/src/ui/handler_manager.test.ts

@@ -8,15 +8,15 @@ import type {ICameraHelper, MapControlsDeltas} from '../geo/projection/camera_he
 import type {Terrain} from '../render/terrain.ts';
 import type {ITransform} from '../geo/transform_interface.ts';
 import {Event as MapEvent} from '../util/evented.ts';
-import {beforeMapTest, createMap} from '../util/test/util.ts';
+import {MercatorCoordinate} from '../geo/mercator_coordinate.ts';
+import {beforeMapTest, createMap, createTerrain} from '../util/test/util.ts';
+import simulate from '../../test/unit/lib/simulate_interaction.ts';
 
 let map: Map;
 let manager: HandlerManager;
 
 beforeEach(() => {
     beforeMapTest();
-    map = createMap();
-    manager = map._handlers;
 });
 
 afterEach(() => {
@@ -25,6 +25,11 @@ afterEach(() => {
 });
 
 describe('HandlerManager terrain scenarios', () => {
+    beforeEach(() => {
+        map = createMap();
+        manager = map._handlers;
+    });
+
     test('_handleMapControls keeps terrain movement disabled when terrain is not enabled', () => {
         const handleZoom = vi.fn();
         const handlePan = vi.fn();
@@ -291,3 +296,238 @@ function createEventInProgress(name: keyof EventsInProgress): EventInProgress {
         originalEvent: new MapEvent(`${String(name)}start`),
     };
 }
+
+describe('terrain gesture anchoring', () => {
+    async function setupGestureMap(pitch: number = 0): Promise<HTMLElement> {
+        map = createMap({interactive: true, zoom: 11, center: [7.5, 45.9], pitch, bearing: 0});
+        map.touchZoomRotate.disableRotation();
+        map._handlers._handlersById.tapZoom.disable();
+        map.touchPitch.disable();
+        await map.once('style.load');
+        return map.getCanvas();
+    }
+
+    function gestureStep(kind: 'touchstart' | 'touchmove', target: HTMLElement, positions: Point[]): void {
+        const touches = positions.map((p, i) => ({target, identifier: i + 1, clientX: p.x, clientY: p.y}));
+        simulate[kind](target, {touches});
+        map._renderTaskQueue.run();
+    }
+
+    function endGesture(target: HTMLElement): void {
+        simulate.touchend(target, {touches: []});
+        map._renderTaskQueue.run();
+        map._renderTaskQueue.run();
+    }
+
+    function pinchTouches(mid: Point, halfSpread: number): Point[] {
+        return [
+            new Point(mid.x, mid.y - halfSpread),
+            new Point(mid.x, mid.y + halfSpread),
+        ];
+    }
+
+    function slipOf(anchor: LngLat, expectedAt: Point): number {
+        return map.project(anchor).dist(expectedAt);
+    }
+
+    test('moving-centroid pinch with terrain keeps the grabbed terrain point under the fingers', async () => {
+        const target = await setupGestureMap();
+        const anchor = new LngLat(7.49, 45.905);
+        const anchorCoordinate = MercatorCoordinate.fromLngLat(anchor);
+        let raycastElevation = 1000;
+        map.terrain = {
+            ...createTerrain(),
+            pointCoordinate: () => new MercatorCoordinate(anchorCoordinate.x, anchorCoordinate.y, raycastElevation),
+        } as any as Terrain;
+
+        // Start the pinch with the finger midpoint exactly where the grabbed point renders
+        const start = map.project(anchor);
+        expect(start.x).toBeGreaterThan(20);
+        expect(start.x).toBeLessThan(180);
+        expect(start.y).toBeGreaterThan(20);
+        expect(start.y).toBeLessThan(180);
+
+        gestureStep('touchstart', target, pinchTouches(start, 30));
+        let mid = start;
+        let halfSpread = 30;
+        for (let step = 0; step < 3; step++) {
+            mid = mid.add(new Point(15, 10));
+            halfSpread += 10;
+            gestureStep('touchmove', target, pinchTouches(mid, halfSpread));
+            // terrain "loading" mid-gesture must not move the anchor plane
+            raycastElevation = 4000;
+        }
+
+        expect(map.getZoom()).toBeGreaterThan(11.5);
+        expect(map._handlers._terrainGestureAnchorElevation).toBe(1000);
+
+        const slip = slipOf(anchor, mid);
+        endGesture(target);
+        expect(slip).toBeLessThan(0.5);
+        expect(map._handlers._terrainGestureAnchorElevation).toBeNull();
+    });
+
+    test('pitched moving-centroid pinch with terrain keeps the grabbed terrain point under the fingers', async () => {
+        const target = await setupGestureMap(60);
+        const anchor = new LngLat(7.494, 45.904);
+        const anchorCoordinate = MercatorCoordinate.fromLngLat(anchor);
+        map.terrain = {
+            ...createTerrain(),
+            pointCoordinate: () => new MercatorCoordinate(anchorCoordinate.x, anchorCoordinate.y, 1000),
+        } as any as Terrain;
+
+        const start = map.project(anchor);
+        expect(start.x).toBeGreaterThan(20);
+        expect(start.x).toBeLessThan(180);
+        expect(start.y).toBeGreaterThan(20);
+        expect(start.y).toBeLessThan(180);
+
+        gestureStep('touchstart', target, pinchTouches(start, 25));
+        let mid = start;
+        let halfSpread = 25;
+        for (let step = 0; step < 3; step++) {
+            mid = mid.add(new Point(12, 8));
+            halfSpread += 8;
+            gestureStep('touchmove', target, pinchTouches(mid, halfSpread));
+        }
+
+        expect(map.getZoom()).toBeGreaterThan(11.5);
+
+        const slip = slipOf(anchor, mid);
+        endGesture(target);
+        expect(slip).toBeLessThan(0.5);
+    });
+
+    test('touch drag with terrain keeps a grabbed point elevated above the center plane under the finger', async () => {
+        const target = await setupGestureMap();
+        // a 2000 m ridge east of the center, with the center itself at 300 m
+        const ridgeStartLng = map.getCenter().lng + 0.003;
+        const elevationAt = (lngLat: LngLat) => lngLat.lng > ridgeStartLng ? 2000 : 300;
+        const anchor = new LngLat(map.getCenter().lng + 0.012, map.getCenter().lat);
+        const anchorCoordinate = MercatorCoordinate.fromLngLat(anchor);
+        map.terrain = {
+            ...createTerrain(),
+            getElevationForLngLat: (lngLat: LngLat) => elevationAt(lngLat),
+            getElevationForLngLatZoom: (lngLat: LngLat) => elevationAt(lngLat),
+            pointCoordinate: () => new MercatorCoordinate(anchorCoordinate.x, anchorCoordinate.y, 2000),
+        } as any as Terrain;
+        map._camera.transform.setElevation(300);
+
+        const start = map.project(anchor);
+        expect(start.x).toBeGreaterThan(20);
+        expect(start.x).toBeLessThan(180);
+
+        gestureStep('touchstart', target, [start]);
+        let finger = start;
+        for (let step = 0; step < 3; step++) {
+            finger = finger.add(new Point(-20, 0));
+            gestureStep('touchmove', target, [finger]);
+        }
+
+        expect(map.getCenter().lng).not.toBeCloseTo(7.5, 5);
+
+        const slip = slipOf(anchor, finger);
+        endGesture(target);
+        expect(slip).toBeLessThan(0.5);
+    });
+
+    test('center-anchored pinch over terrain still pans with the centroid', async () => {
+        const target = await setupGestureMap();
+        map.touchZoomRotate.enable({around: 'center'});
+        const anchor = new LngLat(7.49, 45.905);
+        const anchorCoordinate = MercatorCoordinate.fromLngLat(anchor);
+        map.terrain = {
+            ...createTerrain(),
+            pointCoordinate: () => new MercatorCoordinate(anchorCoordinate.x, anchorCoordinate.y, 1000),
+        } as any as Terrain;
+
+        const startCenter = map.getCenter();
+        const start = new Point(80, 90);
+        gestureStep('touchstart', target, pinchTouches(start, 30));
+        let mid = start;
+        let halfSpread = 30;
+        for (let step = 0; step < 3; step++) {
+            mid = mid.add(new Point(15, 10));
+            halfSpread += 10;
+            gestureStep('touchmove', target, pinchTouches(mid, halfSpread));
+        }
+
+        expect(map.getZoom()).toBeGreaterThan(11.5);
+        // center-anchored zoom keeps the center fixed, so only the pan moves it
+        const centerMovedPx = map.project(startCenter).dist(new Point(100, 100));
+        endGesture(target);
+        expect(centerMovedPx).toBeGreaterThan(20);
+    });
+
+    test('falls back to the center-elevation behavior when the terrain under the gesture is not loaded', async () => {
+        const target = await setupGestureMap();
+        map.terrain = {
+            ...createTerrain(),
+            pointCoordinate: () => null,
+        } as any as Terrain;
+
+        const startCenter = map.getCenter();
+        const start = new Point(80, 90);
+        gestureStep('touchstart', target, pinchTouches(start, 30));
+        let mid = start;
+        let halfSpread = 30;
+        for (let step = 0; step < 3; step++) {
+            mid = mid.add(new Point(15, 10));
+            halfSpread += 10;
+            gestureStep('touchmove', target, pinchTouches(mid, halfSpread));
+        }
+
+        // the gesture still zooms and pans sanely near where it started
+        expect(map.getZoom()).toBeGreaterThan(11.5);
+        expect(Math.abs(map.getCenter().lng - startCenter.lng)).toBeLessThan(0.5);
+        expect(Math.abs(map.getCenter().lat - startCenter.lat)).toBeLessThan(0.5);
+        endGesture(target);
+    });
+
+    test('falls back to the center-elevation behavior when the grabbed terrain point is above the camera altitude', async () => {
+        const target = await setupGestureMap();
+        map.terrain = {
+            ...createTerrain(),
+            pointCoordinate: () => new MercatorCoordinate(0.5, 0.35, 1e6),
+        } as any as Terrain;
+
+        const startCenter = map.getCenter();
+        const start = new Point(80, 90);
+        gestureStep('touchstart', target, pinchTouches(start, 30));
+        let mid = start;
+        let halfSpread = 30;
+        for (let step = 0; step < 3; step++) {
+            mid = mid.add(new Point(15, 10));
+            halfSpread += 10;
+            gestureStep('touchmove', target, pinchTouches(mid, halfSpread));
+        }
+
+        // the gesture still zooms and pans sanely near where it started
+        expect(map.getZoom()).toBeGreaterThan(11.5);
+        expect(Math.abs(map.getCenter().lng - startCenter.lng)).toBeLessThan(0.5);
+        expect(Math.abs(map.getCenter().lat - startCenter.lat)).toBeLessThan(0.5);
+        endGesture(target);
+    });
+
+    test('control: the same moving-centroid pinch without terrain keeps the grabbed point under the fingers', async () => {
+        const target = await setupGestureMap();
+
+        const start = new Point(67, 76);
+        const anchor = map.unproject(start);
+
+        gestureStep('touchstart', target, pinchTouches(start, 30));
+        let mid = start;
+        let halfSpread = 30;
+        for (let step = 0; step < 3; step++) {
+            mid = mid.add(new Point(15, 10));
+            halfSpread += 10;
+            gestureStep('touchmove', target, pinchTouches(mid, halfSpread));
+        }
+
+        expect(map.getZoom()).toBeGreaterThan(11.5);
+
+        const slip = slipOf(anchor, mid);
+        endGesture(target);
+        expect(slip).toBeLessThan(0.5);
+    });
+});

package/src/ui/handler_manager.ts

@@ -31,6 +31,12 @@ import type {Terrain} from '../render/terrain.ts';
 
 const isMoving = (p: EventsInProgress) => p.zoom || p.drag || p.roll || p.pitch || p.rotate;
 
+/**
+ * A terrain gesture's anchor plane must stay below this fraction of the camera's
+ * altitude over the center-elevation plane, or the ray-plane solve degenerates.
+ */
+const TERRAIN_ANCHOR_MAX_CAMERA_ALTITUDE_FRACTION = 0.9;
+
 class RenderFrameEvent extends Event {
     type: 'renderFrame';
     timeStamp: number;
@@ -162,6 +168,11 @@ export class HandlerManager {
     _updatingCamera: boolean;
     _changes: Array<[HandlerResult, EventsInProgress, {[handlerName: string]: Event}]>;
     _terrainMovement: boolean;
+    /**
+     * Elevation in meters of the terrain point grabbed at gesture start; kept for the
+     * same lifetime as the elevation freeze. Null when that terrain was not available.
+     */
+    _terrainGestureAnchorElevation: number | null = null;
     _zoom: {handlerName: string};
     _previousActiveHandlers: {[x: string]: Handler};
     _listeners: Array<[Window | Document | HTMLElement, string, {
@@ -542,17 +553,10 @@ export class HandlerManager {
         // stop any ongoing camera animations (easeTo, flyTo)
         this._camera.stop(true);
 
-        let {panDelta, zoomDelta, bearingDelta, pitchDelta, rollDelta, around, pinchAround} = combinedResult;
-
-        if (pinchAround !== undefined) {
-            around = pinchAround;
-        }
-
-        around ||= this._camera.transform.centerPoint;
+        const {panDelta, zoomDelta, bearingDelta, pitchDelta, rollDelta} = combinedResult;
 
-        if (terrain && !tr.isPointOnMapSurface(around)) {
-            around = tr.centerPoint;
-        }
+        let {around, aroundOnSurface} = this._resolveAround(combinedResult, terrain, tr);
+        const aroundElevation = terrain ? this._terrainGestureElevation(terrain, around, aroundOnSurface, tr, combinedEventsInProgress) : undefined;
 
         const deltasForHelper: MapControlsDeltas = {
             panDelta,
@@ -561,17 +565,14 @@ export class HandlerManager {
             pitchDelta,
             bearingDelta,
             around,
+            aroundElevation,
         };
 
         // Pre-zoom location under the mouse cursor is required for accurate mercator panning and zooming
         if (this._camera.cameraHelper.useGlobeControls && !tr.isPointOnMapSurface(around)) {
             around = tr.centerPoint;
         }
-        // If we are rotating about the center point, avoid numerical issues near the horizon by using the transform's
-        // center directly, instead of computing it from the screen point
-        const preZoomAroundLoc = around.distSqr(tr.centerPoint) < 1.0e-2 ?
-            tr.center :
-            tr.screenPointToLocation(panDelta ? around.sub(panDelta) : around);
+        const preZoomAroundLoc = this._computePreZoomAroundLoc(tr, around, panDelta, aroundElevation);
 
         this._handleMapControls({
             terrain,
@@ -590,6 +591,65 @@ export class HandlerManager {
 
     }
 
+    /**
+     * The gesture's anchor point: the pinch midpoint when pinching, otherwise the
+     * pan's anchor, clamped to the center point when it does not lie on the map.
+     */
+    _resolveAround(combinedResult: HandlerResult, terrain: Terrain | null, tr: ITransform): {around: Point; aroundOnSurface: boolean} {
+        let around = combinedResult.pinchAround !== undefined ? combinedResult.pinchAround : combinedResult.around;
+        around ||= this._camera.transform.centerPoint;
+        if (terrain && !tr.isPointOnMapSurface(around)) {
+            return {around: tr.centerPoint, aroundOnSurface: false};
+        }
+        return {around, aroundOnSurface: true};
+    }
+
+    /**
+     * The elevation of the plane a terrain gesture is solved on: the elevation of the
+     * terrain point grabbed at gesture start, captured here on the gesture's first
+     * frame. Undefined means the gesture is solved at the center's elevation instead —
+     * when the grabbed terrain is not loaded, the anchor is the center point (a
+     * center-point anchor is skipped by the camera helper and would lose the pan), or
+     * the anchor plane is too close to the camera for a stable ray-plane solve.
+     */
+    _terrainGestureElevation(terrain: Terrain, around: Point, aroundOnSurface: boolean, tr: ITransform, combinedEventsInProgress: EventsInProgress): number | undefined {
+        if (!aroundOnSurface) {
+            return undefined;
+        }
+        if (!this._terrainMovement && (combinedEventsInProgress.drag || combinedEventsInProgress.zoom)) {
+            const anchor = terrain.pointCoordinate(around);
+            this._terrainGestureAnchorElevation = anchor ? anchor.z : null;
+        }
+        if (this._terrainGestureAnchorElevation === null) {
+            return undefined;
+        }
+        const elevation = this._terrainGestureAnchorElevation;
+        if (around.distSqr(tr.centerPoint) < 1.0e-2) {
+            return undefined;
+        }
+        if (elevation - tr.elevation >= TERRAIN_ANCHOR_MAX_CAMERA_ALTITUDE_FRACTION * (tr.getCameraAltitude() - tr.elevation)) {
+            return undefined;
+        }
+        return elevation;
+    }
+
+    /**
+     * The location that was under `around` before this frame's deltas — the point the
+     * camera helper re-anchors after zooming — solved at `aroundElevation` when a
+     * terrain gesture provides one. When rotating about the center point, the
+     * transform's center is used directly to avoid numerical issues near the horizon.
+     */
+    _computePreZoomAroundLoc(tr: ITransform, around: Point, panDelta: Point | undefined, aroundElevation: number | undefined): LngLat {
+        if (around.distSqr(tr.centerPoint) < 1.0e-2) {
+            return tr.center;
+        }
+        const aroundPreviousPoint = panDelta ? around.sub(panDelta) : around;
+        if (aroundElevation !== undefined) {
+            return tr.screenPointToLocationAtElevation(aroundPreviousPoint, aroundElevation);
+        }
+        return tr.screenPointToLocation(aroundPreviousPoint);
+    }
+
     _handleMapControls({
         terrain,
         tr,
@@ -623,7 +683,9 @@ export class HandlerManager {
             return;
         }
 
-        if (combinedEventsInProgress.drag && this._terrainMovement && panDelta) {
+        if (deltasForHelper.aroundElevation === undefined &&
+            combinedEventsInProgress.drag && this._terrainMovement && panDelta) {
+            // no usable anchor: drag by pixel-delta on the center-elevation plane
             tr.setCenter(tr.screenPointToLocation(tr.centerPoint.sub(panDelta)));
             return;
         }
@@ -685,6 +747,7 @@ export class HandlerManager {
         if (finishedMoving && this._terrainMovement) {
             this._camera.elevationFreeze = false;
             this._terrainMovement = false;
+            this._terrainGestureAnchorElevation = null;
             const tr = this._camera.getTransformForUpdate();
             if (this._map.getCenterClampedToGround()) {
                 tr.recalculateZoomAndCenter(this._map.terrain);