Fixes wrong movement when inertia crosses the horizon (#6345)

* add failing unit test to demonstrate #6111

* Fix 6111 by reducing the ease offset so that it never crosses the horizon.

* update Changelog

* formatting

* increase inertia pan offset limit from 50% to 75% of distance to horizon.

---------

Co-authored-by: Harel M <harel.mazor@gmail.com>

Author: NathanMOlson

CHANGELOG.md

@@ -6,6 +6,7 @@
 ### 🐞 Bug fixes
 - Fix accuracy circle on locate user control ([#5432](https://github.com/maplibre/maplibre-gl-js/issues/5432))
 - Fix evaluating `global-state` in paint `...-pattern` properties ([6301](https://github.com/maplibre/maplibre-gl-js/pull/6301))
+- Fix pan moving in the wrong direction when map is pitched ([#6111](https://github.com/maplibre/maplibre-gl-js/issues/6111))
 - Fix evaluation of `text-color` when using `format` within `step` ([#5833](https://github.com/maplibre/maplibre-gl-js/issues/5432))
 - Fix regression in `mergeSourceDiffs`: handle add/remove/removeAll ([6342](https://github.com/maplibre/maplibre-gl-js/pull/6342))
 - Fix evaluating `global-state` in layout properties `icon-size` and `text-size` ([#6308](https://github.com/maplibre/maplibre-gl-js/issues/6308))

src/geo/projection/mercator_camera_helper.ts

@@ -3,7 +3,7 @@ import {LngLat, type LngLatLike} from '../lng_lat';
 import {cameraForBoxAndBearing, type CameraForBoxAndBearingHandlerResult, type EaseToHandlerResult, type EaseToHandlerOptions, type FlyToHandlerResult, type FlyToHandlerOptions, type ICameraHelper, type MapControlsDeltas, updateRotation, type UpdateRotationArgs} from './camera_helper';
 import {normalizeCenter} from '../transform_helper';
 import {rollPitchBearingEqual, scaleZoom, zoomScale} from '../../util/util';
-import {projectToWorldCoordinates, unprojectFromWorldCoordinates} from './mercator_utils';
+import {getMercatorHorizon, projectToWorldCoordinates, unprojectFromWorldCoordinates} from './mercator_utils';
 import {interpolates} from '@maplibre/maplibre-gl-style-spec';
 
 import type {IReadonlyTransform, ITransform} from '../transform_interface';
@@ -21,8 +21,14 @@ export class MercatorCameraHelper implements ICameraHelper {
         easingCenter: LngLat;
         easingOffset: Point;
     } {
+        // Reduce the offset so that it never goes past the horizon. If it goes past
+        // the horizon, the pan direction is opposite of the intended direction.
+        const offsetLength = pan.mag();
+        const pixelsToHorizon = Math.abs(getMercatorHorizon(transform));
+        const horizonFactor = 0.75; // Must be < 1 to prevent the offset from crossing the horizon
+        const offsetAsPoint = pan.mult(Math.min(pixelsToHorizon * horizonFactor / offsetLength, 1.0));
         return {
-            easingOffset: pan,
+            easingOffset: offsetAsPoint,
             easingCenter: transform.center,
         };
     }

src/ui/camera.test.ts

@@ -12,6 +12,8 @@ import {GlobeTransform} from '../geo/projection/globe_transform';
 import {getZoomAdjustment} from '../geo/projection/globe_utils';
 import {GlobeCameraHelper} from '../geo/projection/globe_camera_helper';
 import {MercatorCameraHelper} from '../geo/projection/mercator_camera_helper';
+import {getMercatorHorizon} from '../geo/projection/mercator_utils';
+import Point from '@mapbox/point-geometry';
 
 import type {GlobeProjection} from '../geo/projection/globe_projection';
 import type {Terrain} from '../render/terrain';
@@ -908,6 +910,24 @@ describe('easeTo', () => {
         expect(fixedLngLat(camera.getCenter())).toEqual({lng: 170.3125, lat: 0});
     });
 
+    test('offset computed from inertia (small) does not cross horizon when pitched', () => {
+        const camera = createCamera({pitch: 85, zoom: 10});
+        const easeOptions = camera.cameraHelper.handlePanInertia(new Point(0, 100), camera.transform);
+        expect(easeOptions.easingOffset.mag()).toBeLessThan(Math.abs(getMercatorHorizon(camera.transform)));
+    });
+
+    test('offset computed from inertia (large) does not cross horizon when pitched', () => {
+        const camera = createCamera({pitch: 85, zoom: 10});
+        const easeOptions = camera.cameraHelper.handlePanInertia(new Point(0, 500), camera.transform);
+        expect(easeOptions.easingOffset.mag()).toBeLessThan(Math.abs(getMercatorHorizon(camera.transform)));
+    });
+
+    test('offset computed from inertia (large) does not cross horizon when pitched and rotated', () => {
+        const camera = createCamera({pitch: 85, bearing: 135, zoom: 10});
+        const easeOptions = camera.cameraHelper.handlePanInertia(new Point(0, 500), camera.transform);
+        expect(easeOptions.easingOffset.mag()).toBeLessThan(Math.abs(getMercatorHorizon(camera.transform)));
+    });
+
     test('zooms with specified offset', () => {
         const camera = createCamera();
         camera.easeTo({zoom: 3.2, offset: [100, 0], duration: 0});
@@ -2917,6 +2937,24 @@ describe('easeTo globe projection', () => {
             expect(fixedLngLat(camera.getCenter())).toEqual({lng: -175.50457909, lat: 0});
         });
 
+        test('offset computed from inertia (small) does not cross horizon when pitched', () => {
+            const camera = createCameraGlobe({pitch: 85, zoom: 10});
+            const easeOptions = camera.cameraHelper.handlePanInertia(new Point(0, 100), camera.transform);
+            expect(easeOptions.easingOffset.mag()).toBeLessThan(Math.abs(getMercatorHorizon(camera.transform)));
+        });
+
+        test('offset computed from inertia (large) does not cross horizon when pitched', () => {
+            const camera = createCameraGlobe({pitch: 85, zoom: 10});
+            const easeOptions = camera.cameraHelper.handlePanInertia(new Point(0, 500), camera.transform);
+            expect(easeOptions.easingOffset.mag()).toBeLessThan(Math.abs(getMercatorHorizon(camera.transform)));
+        });
+
+        test('offset computed from inertia (large) does not cross horizon when pitched and rotated', () => {
+            const camera = createCameraGlobe({pitch: 85, bearing: 135, zoom: 10});
+            const easeOptions = camera.cameraHelper.handlePanInertia(new Point(0, 500), camera.transform);
+            expect(easeOptions.easingOffset.mag()).toBeLessThan(Math.abs(getMercatorHorizon(camera.transform)));
+        });
+
         test('zooms with specified offset', () => {
             const camera = createCameraGlobe();
             camera.easeTo({zoom: 3.2, offset: [100, 0], duration: 0});