maplibre-gl 6.2.0 → 6.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "maplibre-gl",
   "description": "BSD licensed community fork of mapbox-gl, a WebGL interactive maps library",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "module": "dist/maplibre-gl.mjs",
   "style": "dist/maplibre-gl.css",
   "license": "BSD-3-Clause",
@@ -51,7 +51,6 @@
     "@mapbox/mapbox-gl-rtl-text": "^0.4.0",
     "@mapbox/mvt-fixtures": "^4.0.0",
     "@stylistic/eslint-plugin": "^5.10.0",
-    "@types/benchmark": "^2.1.5",
     "@types/d3": "^7.4.3",
     "@types/earcut": "^3.0.0",
     "@types/eslint": "^9.6.1",
@@ -64,35 +63,32 @@
     "@types/offscreencanvas": "^2019.7.3",
     "@types/pixelmatch": "^5.2.6",
     "@types/pngjs": "^6.0.5",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
     "@types/request": "^2.48.13",
     "@types/shuffle-seed": "^1.1.3",
     "@types/window-or-global": "^1.0.6",
-    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/eslint-plugin": "^8.66.0",
     "@typescript-eslint/parser": "^8.59.3",
     "@typescript/native-preview": "beta",
     "@unicode/unicode-17.0.0": "^1.6.17",
     "@vitest/coverage-v8": "4.1.10",
-    "@vitest/eslint-plugin": "^1.6.24",
+    "@vitest/eslint-plugin": "^1.6.26",
     "@vitest/ui": "4.1.10",
     "address": "^2.0.3",
     "autoprefixer": "^10.5.4",
-    "benchmark": "^2.1.4",
     "canvas": "^3.2.3",
     "cross-env": "^10.1.0",
     "cspell": "^10.0.1",
-    "cssnano": "^8.0.2",
+    "cssnano": "^8.0.4",
     "d3": "^7.9.0",
     "d3-queue": "^3.0.7",
-    "devtools-protocol": "^0.0.1672245",
+    "devtools-protocol": "^0.0.1674729",
     "diff": "^9.0.0",
     "eslint": "^10.8.0",
     "eslint-plugin-html": "^8.1.4",
     "eslint-plugin-tsdoc": "0.5.2",
     "expect": "^30.4.1",
     "glob": "^13.0.6",
-    "globals": "^17.8.0",
+    "globals": "^17.9.0",
     "is-builtin-module": "^5.0.0",
     "jsdom": "^30.0.1",
     "minimist": "^1.2.8",
@@ -108,11 +104,9 @@
     "postcss-cli": "^11.0.1",
     "postcss-inline-svg": "^6.0.0",
     "pretty-bytes": "^7.1.1",
-    "puppeteer": "^25.4.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "puppeteer": "^25.5.0",
     "regenerate": "^1.4.2",
-    "rolldown": "^1.2.1",
+    "rolldown": "^1.2.3",
     "rolldown-plugin-dts": "^0.27.8",
     "rw": "^1.3.3",
     "semver": "^7.8.5",
@@ -125,7 +119,7 @@
     "typedoc": "^0.28.20",
     "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^6.0.3",
-    "vite": "^8.2.0",
+    "vite": "^8.2.1",
     "vitest": "^4.1.5",
     "vitest-webgl-canvas-mock": "^1.1.0"
   },
@@ -143,14 +137,11 @@
     "build-prod": "cross-env BUILD=production rolldown -c rolldown.config.ts",
     "build-css": "postcss -o dist/maplibre-gl.css src/css/maplibre-gl.css",
     "watch-css": "postcss --watch -o dist/maplibre-gl.css src/css/maplibre-gl.css",
-    "build-benchmarks": "npm run build-dev && rolldown -c test/bench/rolldown_config_benchmarks.ts",
-    "watch-benchmarks": "rolldown -c test/bench/rolldown_config_benchmarks.ts --watch",
     "spellcheck": "cspell",
     "docs": "npm run generate-docs && docker compose run --rm docs",
     "start-server": "st --no-cache -H localhost --port 9966 .",
     "start-docs": "docker compose run --rm -it --service-ports docs-serve",
     "start": "run-p watch-css watch-dev start-server",
-    "start-bench": "run-p watch-css watch-benchmarks start-server",
     "lint": "eslint",
     "lint-css": "stylelint **/*.css verbose",
     "test": "run-p lint lint-css test-render test-unit test-integration test-build",
@@ -164,8 +155,7 @@
     "test-render": "vitest test/integration/render/render.test.ts",
     "codegen": "run-p --print-label generate-style-code generate-unicode-data generate-struct-arrays generate-shaders && npm run generate-typings",
     "bench": "vitest bench --run --config vitest.config.bench.ts",
-    "benchmark": "node test/bench/run-benchmarks.ts",
-    "gl-stats": "node test/bench/gl-stats.ts",
+    "bench-e2e": "node test/bench/e2e/run.ts",
     "prepare": "npm run codegen",
     "typecheck": "tsgo --noEmit && tsgo --project tsconfig.dist.json"
   },

package/src/data/feature_index.bench.ts

@@ -0,0 +1,21 @@
+import {bench} from 'vitest';
+import {FeatureIndex} from './feature_index.ts';
+import {OverscaledTileID} from '../tile/tile_id.ts';
+
+import type {FeatureFilter} from '@maplibre/maplibre-gl-style-spec';
+import type {VectorTileFeatureLike, VectorTileLayerLike} from '@maplibre/vt-pbf';
+
+const layerCount = 100;
+const filter = {needGeometry: false} as FeatureFilter;
+
+const featureIndex = new FeatureIndex(new OverscaledTileID(0, 0, 0, 0, 0));
+featureIndex.bucketLayerIDs = [Array.from({length: layerCount}, (_, i) => `layer-${i}`)];
+featureIndex.vtLayers = {
+    '0': {feature: () => ({} as VectorTileFeatureLike)} as unknown as VectorTileLayerLike
+};
+
+const layerIdsToTest = new Set(Array.from({length: layerCount}, (_, i) => `non-existing-layer-${i}`));
+
+bench('FeatureIndex.loadMatchingFeature', () => {
+    featureIndex.loadMatchingFeature({}, 0, 0, 0, filter, layerIdsToTest, [], {}, {});
+});

package/src/data/segment.test.ts

@@ -4,13 +4,13 @@ import {SegmentVector} from './segment.ts';
 
 describe('SegmentVector', () => {
     test('constructor', () => {
-        expect(new SegmentVector() instanceof SegmentVector).toBeTruthy();
+        expect(new SegmentVector()).toBeInstanceOf(SegmentVector);
     });
 
     test('simpleSegment', () => {
         SegmentVector.MAX_VERTEX_ARRAY_LENGTH = 16;
         const segmentVector = SegmentVector.simpleSegment(0, 0, 10, 0);
-        expect(segmentVector instanceof SegmentVector).toBeTruthy();
+        expect(segmentVector).toBeInstanceOf(SegmentVector);
         expect(segmentVector.segments).toHaveLength(1);
         expect(segmentVector.segments[0].vertexLength).toBe(10);
     });

package/src/geo/edge_insets.test.ts

@@ -4,7 +4,7 @@ import {EdgeInsets} from '../geo/edge_insets.ts';
 describe('EdgeInsets', () => {
     describe('constructor', () => {
         test('creates an object with default values', () => {
-            expect(new EdgeInsets() instanceof EdgeInsets).toBeTruthy();
+            expect(new EdgeInsets()).toBeInstanceOf(EdgeInsets);
         });
 
         test('invalid initialization', () => {

package/src/geo/lng_lat.test.ts

@@ -3,7 +3,7 @@ import {LngLat} from '../geo/lng_lat.ts';
 
 describe('LngLat', () => {
     test('constructor', () => {
-        expect(new LngLat(0, 0) instanceof LngLat).toBeTruthy();
+        expect(new LngLat(0, 0)).toBeInstanceOf(LngLat);
 
         expect(() => {
             new LngLat(0, -91);
@@ -15,12 +15,12 @@ describe('LngLat', () => {
     });
 
     test('convert', () => {
-        expect(LngLat.convert([0, 10]) instanceof LngLat).toBeTruthy();
-        expect(LngLat.convert({lng: 0, lat: 10}) instanceof LngLat).toBeTruthy();
-        expect(LngLat.convert({lng: 0, lat: 0}) instanceof LngLat).toBeTruthy();
-        expect(LngLat.convert({lon: 0, lat: 10}) instanceof LngLat).toBeTruthy();
-        expect(LngLat.convert({lon: 0, lat: 0}) instanceof LngLat).toBeTruthy();
-        expect(LngLat.convert(new LngLat(0, 0)) instanceof LngLat).toBeTruthy();
+        expect(LngLat.convert([0, 10])).toBeInstanceOf(LngLat);
+        expect(LngLat.convert({lng: 0, lat: 10})).toBeInstanceOf(LngLat);
+        expect(LngLat.convert({lng: 0, lat: 0})).toBeInstanceOf(LngLat);
+        expect(LngLat.convert({lon: 0, lat: 10})).toBeInstanceOf(LngLat);
+        expect(LngLat.convert({lon: 0, lat: 0})).toBeInstanceOf(LngLat);
+        expect(LngLat.convert(new LngLat(0, 0))).toBeInstanceOf(LngLat);
     });
 
     test('wrap', () => {

package/src/geo/lng_lat_bounds.test.ts

@@ -336,25 +336,25 @@ describe('LngLatBounds', () => {
             test('point is in bounds', () => {
                 const llb = new LngLatBounds([-1, -1], [1, 1]);
                 const ll = {lng: 0, lat: 0};
-                expect(llb.contains(ll)).toBeTruthy();
+                expect(llb.contains(ll)).toBe(true);
             });
 
             test('point is not in bounds', () => {
                 const llb = new LngLatBounds([-1, -1], [1, 1]);
                 const ll = {lng: 3, lat: 3};
-                expect(llb.contains(ll)).toBeFalsy();
+                expect(llb.contains(ll)).toBe(false);
             });
 
             test('point is in bounds that spans dateline', () => {
                 const llb = new LngLatBounds([190, -10], [170, 10]);
                 const ll = {lng: 180, lat: 0};
-                expect(llb.contains(ll)).toBeTruthy();
+                expect(llb.contains(ll)).toBe(true);
             });
 
             test('point is not in bounds that spans dateline', () => {
                 const llb = new LngLatBounds([190, -10], [170, 10]);
                 const ll = {lng: 0, lat: 0};
-                expect(llb.contains(ll)).toBeFalsy();
+                expect(llb.contains(ll)).toBe(false);
             });
         });
     });

package/src/geo/mercator_coordinate.test.ts

@@ -4,8 +4,8 @@ import {MercatorCoordinate, mercatorScale} from './mercator_coordinate.ts';
 
 describe('LngLat', () => {
     test('constructor', () => {
-        expect(new MercatorCoordinate(0, 0) instanceof MercatorCoordinate).toBeTruthy();
-        expect(new MercatorCoordinate(0, 0, 0) instanceof MercatorCoordinate).toBeTruthy();
+        expect(new MercatorCoordinate(0, 0)).toBeInstanceOf(MercatorCoordinate);
+        expect(new MercatorCoordinate(0, 0, 0)).toBeInstanceOf(MercatorCoordinate);
     });
 
     test('fromLngLat', () => {

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

@@ -400,6 +400,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);
+            });
         });
     });
 

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/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.ts

@@ -2,7 +2,7 @@ import Point from '@mapbox/point-geometry';
 import {cameraBoundsWarning, type CameraForBoxAndBearingHandlerResult, type EaseToHandlerResult, type EaseToHandlerOptions, type FlyToHandlerResult, type FlyToHandlerOptions, type ICameraHelper, type MapControlsDeltas, updateRotation, cameraForBoxAndBearing} from './camera_helper.ts';
 import {LngLat, type LngLatLike} from '../lng_lat.ts';
 import {angularCoordinatesToSurfaceVector, computeGlobePanCenter, getGlobeRadiusPixels, getZoomAdjustment, globeDistanceOfLocationsPixels, interpolateLngLatForGlobe} from './globe_utils.ts';
-import {clamp, createVec3f64, differenceOfAnglesDegrees, MAX_VALID_LATITUDE, remapSaturate, rollPitchBearingEqual, scaleZoom, warnOnce, zoomScale} from '../../util/util.ts';
+import {clamp, createVec3f64, differenceOfAnglesDegrees, lerp, MAX_VALID_LATITUDE, remapSaturate, rollPitchBearingEqual, scaleZoom, warnOnce, zoomScale} from '../../util/util.ts';
 import {type mat4, vec3} from 'gl-matrix';
 import {normalizeCenter} from '../transform_helper.ts';
 import {interpolates} from '@maplibre/maplibre-gl-style-spec';
@@ -12,6 +12,45 @@ import type {CameraForBoundsOptions} from '../../ui/camera.ts';
 import type {LngLatBounds} from '../lng_lat_bounds.ts';
 import type {PaddingOptions} from '../edge_insets.ts';
 
+/**
+ * Zoom movement slowing starts when the mouse ray passes further than this above the planet surface,
+ * so a cursor off the globe does not move the map unnaturally. Globe radius is 1, so 0.3 is ~2000 km.
+ */
+const RAY_SURFACE_DISTANCE_FOR_SLOWING_START = 0.3;
+
+/** How sharply zoom movement slows as the mouse ray rises above the planet surface. Lower is more gradual. */
+const SLOWING_MULTIPLIER = 0.5;
+
+/** Longitude difference between zoom location and map center at which the blend from exact to heuristic zooming starts, in degrees. */
+const INTERPOLATE_TO_HEURISTIC_START_LNG = 45;
+
+/** Longitude difference at which the blend to heuristic zooming is complete, in degrees. */
+const INTERPOLATE_TO_HEURISTIC_END_LNG = 85;
+
+/** Exponent applied to the blend factor: below 1, so the blend leans towards heuristic zooming and flattens as it completes. */
+const INTERPOLATE_TO_HEURISTIC_EXPONENT = 0.25;
+
+/**
+ * Distance of the mouse ray from the globe center at which the blend from exact to heuristic zooming
+ * starts. Globe radius is 1, so 1 is a ray grazing the horizon.
+ */
+const INTERPOLATE_TO_HEURISTIC_START_HORIZON = 0.95;
+
+/** Ray distance at which the blend to heuristic zooming is complete. */
+const INTERPOLATE_TO_HEURISTIC_END_HORIZON = 0.999;
+
+/**
+ * Globe radius relative to the smaller viewport dimension below which zoom movement near the horizon
+ * starts being inhibited, avoiding unnatural movements when the map is zoomed out a lot.
+ */
+const SLOWING_RADIUS_START = 0.9;
+
+/** Globe radius relative to the smaller viewport dimension at which that inhibition is at full strength. */
+const SLOWING_RADIUS_STOP = 0.5;
+
+/** Fraction of the zoom movement that remains once the globe has shrunk to `SLOWING_RADIUS_STOP`. */
+const SLOWING_RADIUS_SLOW_FACTOR = 0.25;
+
 /**
  * @internal
  */
@@ -36,6 +75,13 @@ export class VerticalPerspectiveCameraHelper implements ICameraHelper {
         };
     }
 
+    /**
+     * Zooms around the pointer.
+     *
+     * `setLocationAtPoint` is exact but degenerates when called repeatedly for a
+     * location whose longitude is far from the center's, or one near the horizon,
+     * so those cases blend towards a heuristic.
+     */
     handleMapControlsRollPitchBearingZoom(deltas: MapControlsDeltas, tr: ITransform): void {
         const zoomPixel = deltas.around;
         const zoomLoc = tr.screenPointToLocation(zoomPixel);
@@ -51,28 +97,6 @@ export class VerticalPerspectiveCameraHelper implements ICameraHelper {
             return;
         }
 
-        // Problem: `setLocationAtPoint` for globe works when it is called a single time, but is a little glitchy in practice when used repeatedly for zooming.
-        // - `setLocationAtPoint` repeatedly called at a location behind a pole will eventually glitch out
-        // - `setLocationAtPoint` at location the longitude of which is more than 90° different from current center will eventually glitch out
-        // But otherwise works fine at higher zooms, or when the target is somewhat near the current map center.
-        // Solution: use a heuristic zooming in the problematic cases and interpolate to `setLocationAtPoint` when possible.
-
-        // Magic numbers that control:
-        // - when zoom movement slowing starts for cursor not on globe (avoid unnatural map movements)
-        // - when we interpolate from exact zooming to heuristic zooming based on longitude difference of target location to current center
-        // - when we interpolate from exact zooming to heuristic zooming based on globe being too small on screen
-        // - when zoom movement slowing starts for globe being too small on viewport (avoids unnatural/unwanted map movements when map is zoomed out a lot)
-        const raySurfaceDistanceForSlowingStart = 0.3; // Zoom movement slowing will start when the planet surface to ray distance is greater than this number (globe radius is 1, so 0.3 is ~2000km form the surface).
-        const slowingMultiplier = 0.5; // The lower this value, the slower will the "zoom movement slowing" occur.
-        const interpolateToHeuristicStartLng = 45; // When zoom location longitude is this many degrees away from map center, we start interpolating from exact zooming to heuristic zooming.
-        const interpolateToHeuristicEndLng = 85; // Longitude difference at which interpolation to heuristic zooming ends.
-        const interpolateToHeuristicExponent = 0.25; // Makes interpolation smoother.
-        const interpolateToHeuristicStartRadius = 0.75; // When globe is this many times larger than the smaller viewport dimension, we start interpolating from exact zooming to heuristic zooming.
-        const interpolateToHeuristicEndRadius = 0.35; // Globe size at which interpolation to heuristic zooming ends.
-        const slowingRadiusStart = 0.9; // If globe is this many times larger than the smaller viewport dimension, start inhibiting map movement while zooming
-        const slowingRadiusStop = 0.5;
-        const slowingRadiusSlowFactor = 0.25; // How much is movement slowed when globe is too small
-
         const dLngRaw = differenceOfAnglesDegrees(tr.center.lng, zoomLoc.lng);
         const dLng = dLngRaw / (Math.abs(dLngRaw / 180) + 1.0); // This gradually reduces the amount of longitude change if the zoom location is very far, eg. on the other side of the pole (possible when looking at a pole).
         const dLat = differenceOfAnglesDegrees(tr.center.lat, zoomLoc.lat);
@@ -87,15 +111,21 @@ export class VerticalPerspectiveCameraHelper implements ICameraHelper {
             rayDirection[1] * distanceToClosestPoint,
             rayDirection[2] * distanceToClosestPoint
         ]);
-        const distanceFromSurface = vec3.length(closestPoint) - 1;
-        const distanceFactor = Math.exp(-Math.max(distanceFromSurface - raySurfaceDistanceForSlowingStart, 0) * slowingMultiplier);
+        const rayDistanceFromGlobeCenter = vec3.length(closestPoint); // 0 for a ray straight under the camera, 1 for one grazing the horizon.
+        const distanceFromSurface = rayDistanceFromGlobeCenter - 1;
+        const distanceFactor = Math.exp(-Math.max(distanceFromSurface - RAY_SURFACE_DISTANCE_FOR_SLOWING_START, 0) * SLOWING_MULTIPLIER);
+
+        // Near the horizon a pixel is worth degrees of arc and `setLocationAtPoint` can have no solution at all.
+        const interpolationFactorHorizon = remapSaturate(rayDistanceFromGlobeCenter, INTERPOLATE_TO_HEURISTIC_START_HORIZON, INTERPOLATE_TO_HEURISTIC_END_HORIZON, 0, 1);
 
         // Slow zoom movement down if the globe is too small on viewport
-        const radius = getGlobeRadiusPixels(tr.worldSize, tr.center.lat) / Math.min(tr.width, tr.height); // Radius relative to larger viewport dimension
-        const radiusFactor = remapSaturate(radius, slowingRadiusStart, slowingRadiusStop, 1.0, slowingRadiusSlowFactor);
+        const radius = getGlobeRadiusPixels(tr.worldSize, tr.center.lat) / Math.min(tr.width, tr.height); // Radius relative to smaller viewport dimension
+        const radiusFactor = remapSaturate(radius, SLOWING_RADIUS_START, SLOWING_RADIUS_STOP, 1.0, SLOWING_RADIUS_SLOW_FACTOR);
+        // Globe size only stands in for how close the zoom location is to the horizon, so apply the slowdown where that is actually the case.
+        const slowingFactor = Math.min(distanceFactor, lerp(1.0, radiusFactor, interpolationFactorHorizon));
 
         // Compute how much to move towards the zoom location
-        const factor = (1.0 - zoomScale(-actualZoomDelta)) * Math.min(distanceFactor, radiusFactor);
+        const factor = (1.0 - zoomScale(-actualZoomDelta)) * slowingFactor;
 
         const oldCenterLat = tr.center.lat;
         const oldZoom = tr.zoom;
@@ -109,9 +139,8 @@ export class VerticalPerspectiveCameraHelper implements ICameraHelper {
         const exactCenter = tr.center;
 
         // Interpolate between exact zooming and heuristic zooming depending on the longitude difference between current center and zoom location.
-        const interpolationFactorLongitude = remapSaturate(Math.abs(dLngRaw), interpolateToHeuristicStartLng, interpolateToHeuristicEndLng, 0, 1);
-        const interpolationFactorRadius = remapSaturate(radius, interpolateToHeuristicStartRadius, interpolateToHeuristicEndRadius, 0, 1);
-        const heuristicFactor = Math.pow(Math.max(interpolationFactorLongitude, interpolationFactorRadius), interpolateToHeuristicExponent);
+        const interpolationFactorLongitude = remapSaturate(Math.abs(dLngRaw), INTERPOLATE_TO_HEURISTIC_START_LNG, INTERPOLATE_TO_HEURISTIC_END_LNG, 0, 1);
+        const heuristicFactor = Math.pow(Math.max(interpolationFactorLongitude, interpolationFactorHorizon), INTERPOLATE_TO_HEURISTIC_EXPONENT);
 
         const lngExactToHeuristic = differenceOfAnglesDegrees(exactCenter.lng, heuristicCenter.lng);
         const latExactToHeuristic = differenceOfAnglesDegrees(exactCenter.lat, heuristicCenter.lat);

package/src/geo/projection/vertical_perspective_transform.ts

@@ -662,7 +662,8 @@ export class VerticalPerspectiveTransform 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 {
+        // The elevation is ignored: this transform solves on the planet's surface.
         // This returns some fake coordinates for pixels that do not lie on the planet.
         // Whatever uses this `setLocationAtPoint` function will need to account for that.
         const pointLngLat = this.unprojectScreenPoint(point);
@@ -801,6 +802,11 @@ export class VerticalPerspectiveTransform implements ITransform {
         return this.screenPointToMercatorCoordinate(p, terrain)?.toLngLat();
     }
 
+    screenPointToLocationAtElevation(p: Point, _elevation: number): LngLat {
+        // No flat ground plane to intersect at an elevation: use the planet surface.
+        return this.screenPointToLocation(p);
+    }
+
     isPointOnMapSurface(p: Point, _terrain?: Terrain): boolean {
         const rayOrigin = this._cameraPosition;
         const rayDirection = this.getRayDirectionFromPixel(p);

package/src/geo/transform_interface.ts

@@ -204,8 +204,10 @@ interface ITransformMutators {
      * Set's the transform's center so that the given point on screen is at the given world coordinates.
      * @param lnglat - Desired world coordinates of the point.
      * @param point - The screen point that should lie at the given coordinates.
+     * @param elevation - Optional ground elevation in meters above sea level at `lnglat`,
+     * defaults to the elevation at the map's center. Ignored when rendering the globe.
      */
-    setLocationAtPoint(lnglat: LngLat, point: Point): void;
+    setLocationAtPoint(lnglat: LngLat, point: Point, elevation?: number): void;
 
     /**
      * Sets or clears the map's geographical constraints.
@@ -331,6 +333,16 @@ export interface IReadonlyTransform extends ITransformGetters {
      */
     screenPointToLocation(p: Point, terrain?: Terrain): LngLat;
 
+    /**
+     * @internal
+     * Given a point on screen, return its LngLat location assuming the ground there
+     * lies at the given elevation. When rendering the globe the elevation is ignored.
+     * @param p - screen point
+     * @param elevation - ground elevation in meters above sea level
+     * @returns lnglat location
+     */
+    screenPointToLocationAtElevation(p: Point, elevation: number): LngLat;
+
     /**
      * @internal
      * Given a point on screen, return its mercator coordinate.

package/src/index.ts

@@ -15,7 +15,7 @@ import {LngLat, type LngLatLike} from './geo/lng_lat.ts';
 import {LngLatBounds, type LngLatBoundsLike} from './geo/lng_lat_bounds.ts';
 import Point from '@mapbox/point-geometry';
 import {MercatorCoordinate} from './geo/mercator_coordinate.ts';
-import {Evented, ErrorEvent, Event, type Listener} from './util/evented.ts';
+import {Evented, ErrorEvent, Event, type ErrorEventType, type EventedParentData, type EventTypeMap, type Listener} from './util/evented.ts';
 import {type AddProtocolAction, config} from './util/config.ts';
 import {rtlMainThreadPluginFactory} from './source/rtl_text_plugin_main_thread.ts';
 import {now, setNow, restoreNow, isTimeFrozen} from './util/time_control.ts';
@@ -57,7 +57,7 @@ import type {Handler, HandlerResult} from './ui/handler_manager.ts';
 import type {Complete, Mat4f32, Mat4f64, RequireAtLeastOne, Subscription} from './util/util.ts';
 import type {CalculateTileZoomFunction, CoveringTilesOptions} from './geo/projection/covering_tiles.ts';
 import type {TransformConstrainFunction} from './geo/transform_interface.ts';
-import type {StyleImage, StyleImageData, StyleImageInterface, StyleImageMetadata, TextFit} from './style/style_image.ts';
+import type {StyleImage, StyleImageData, StyleImageInterface, StyleImageMetadata, StyleImageWebGLData, StyleImageWebGLTarget, TextFit} from './style/style_image.ts';
 import type {StyleLayer, PaintPropertyEntry} from './style/style_layer.ts';
 import type {Tile} from './tile/tile.ts';
 import type {GeoJSONFeatureDiff, GeoJSONFeatureId, GeoJSONSourceDiff} from './source/geojson_source_diff.ts';
@@ -297,6 +297,9 @@ export {
     type CanonicalTileRange,
     type Tile,
     type Listener,
+    type EventTypeMap,
+    type ErrorEventType,
+    type EventedParentData,
     type Coordinates,
     type ImageSourceImage,
     type UpdateImageOptions,
@@ -308,6 +311,8 @@ export {
     type GeolocateControlOptions,
     type LogoControlOptions,
     type StyleImageInterface,
+    type StyleImageWebGLData,
+    type StyleImageWebGLTarget,
     type AddLayerObject,
     type StyleSetterOptions,
     type CameraForBoundsOptions,